metatag.api.php 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  1. <?php
  2. /**
  3. * @file
  4. * API documentation for the Metatag module.
  5. */
  6. /**
  7. * To enable Metatag support in custom entities, add 'metatags' => TRUE to the
  8. * entity definition in hook_entity_info(), e.g.:
  9. *
  10. * /**
  11. * * Implements hook_entity_info().
  12. * *
  13. * * Taken from the Examples module.
  14. * * /
  15. * function entity_example_entity_info() {
  16. * $info['entity_example_basic'] = array(
  17. * 'label' => t('Example Basic Entity'),
  18. * 'controller class' => 'EntityExampleBasicController',
  19. * 'base table' => 'entity_example_basic',
  20. * 'uri callback' => 'entity_example_basic_uri',
  21. * 'fieldable' => TRUE,
  22. * 'metatags' => TRUE,
  23. * 'entity keys' => array(
  24. * 'id' => 'basic_id' , // The 'id' (basic_id here) is the unique id.
  25. * 'bundle' => 'bundle_type' // Bundle will be determined by the 'bundle_type' field
  26. * ),
  27. * 'bundle keys' => array(
  28. * 'bundle' => 'bundle_type',
  29. * ),
  30. * 'static cache' => TRUE,
  31. * 'bundles' => array(
  32. * 'first_example_bundle' => array(
  33. * 'label' => 'First example bundle',
  34. * 'admin' => array(
  35. * 'path' => 'admin/structure/entity_example_basic/manage',
  36. * 'access arguments' => array('administer entity_example_basic entities'),
  37. * ),
  38. * ),
  39. * ),
  40. * 'view modes' => array(
  41. * 'tweaky' => array(
  42. * 'label' => t('Tweaky'),
  43. * 'custom settings' => FALSE,
  44. * ),
  45. * )
  46. * );
  47. *
  48. * return $info;
  49. * }
  50. *
  51. * The definition of each bundle may be handled separately, thus support may be
  52. * disabled for the entity as a whole but enabled for individual bundles. This
  53. * is handled via the 'metatags' value on the bundle definition, e.g.:
  54. *
  55. * 'bundles' => array(
  56. * 'first_example_bundle' => array(
  57. * 'label' => 'First example bundle',
  58. * 'metatags' => TRUE,
  59. * 'admin' => array(
  60. * 'path' => 'admin/structure/entity_example_basic/manage',
  61. * 'access arguments' => array('administer entity_example_basic entities'),
  62. * ),
  63. * ),
  64. * ),
  65. */
  66. /**
  67. * Provides a default configuration for Metatag intances.
  68. *
  69. * This hook allows modules to provide their own Metatag instances which can
  70. * either be used as-is or as a "starter" for users to build from.
  71. *
  72. * This hook should be placed in MODULENAME.metatag.inc and it will be auto-
  73. * loaded. MODULENAME.metatag.inc *must* be in the same directory as the
  74. * .module file which *must* also contain an implementation of
  75. * hook_ctools_plugin_api, preferably with the same code as found in
  76. * metatag_ctools_plugin_api().
  77. *
  78. * The $config->disabled boolean attribute indicates whether the Metatag
  79. * instance should be enabled (FALSE) or disabled (TRUE) by default.
  80. *
  81. * @return
  82. * An associative array containing the structures of Metatag instances, as
  83. * generated from the Export tab, keyed by the Metatag config name.
  84. *
  85. * @see metatag_metatag_config_default()
  86. * @see metatag_ctools_plugin_api()
  87. */
  88. function hook_metatag_config_default() {
  89. $configs = array();
  90. $config = new stdClass();
  91. $config->instance = 'config1';
  92. $config->api_version = 1;
  93. $config->disabled = FALSE;
  94. $config->config = array(
  95. 'title' => array('value' => '[current-page:title] | [site:name]'),
  96. 'generator' => array('value' => 'Drupal 7 (http://drupal.org)'),
  97. 'canonical' => array('value' => '[current-page:url:absolute]'),
  98. 'shortlink' => array('value' => '[current-page:url:unaliased]'),
  99. );
  100. $configs[$config->instance] = $config;
  101. $config = new stdClass();
  102. $config->instance = 'config2';
  103. $config->api_version = 1;
  104. $config->disabled = FALSE;
  105. $config->config = array(
  106. 'title' => array('value' => '[user:name] | [site:name]'),
  107. );
  108. $configs[$config->instance] = $config;
  109. return $configs;
  110. }
  111. /**
  112. * Internal hook for adding further configuration values in bundled submodules.
  113. *
  114. * The defaults provided by the main Metatag module need to be extended by the
  115. * bundled submodules before they are presented to other modules for altering
  116. * via hook_metatag_config_default_alter(), in case differences in module
  117. * weights and loading priorities cause the submodules' settings to run after
  118. * those of any custom modules.
  119. *
  120. * @see hook_metatag_config_default()
  121. * @see hook_metatag_config_default_alter()
  122. */
  123. function hook_metatag_bundled_config_alter(&$config) {
  124. }
  125. /**
  126. *
  127. */
  128. function hook_metatag_config_default_alter(&$config) {
  129. }
  130. /**
  131. *
  132. */
  133. function hook_metatag_config_delete($entity_type, $entity_ids, $revision_ids, $langcode) {
  134. }
  135. /**
  136. *
  137. */
  138. function hook_metatag_config_insert($config) {
  139. }
  140. /**
  141. *
  142. */
  143. function hook_metatag_config_instance_info() {
  144. return array();
  145. }
  146. /**
  147. *
  148. */
  149. function hook_metatag_config_instance_info_alter(&$info) {
  150. }
  151. /**
  152. *
  153. */
  154. function hook_metatag_config_load() {
  155. }
  156. /**
  157. *
  158. */
  159. function hook_metatag_config_load_presave() {
  160. }
  161. /**
  162. *
  163. */
  164. function hook_metatag_config_presave($config) {
  165. }
  166. /**
  167. *
  168. */
  169. function hook_metatag_config_update($config) {
  170. }
  171. /**
  172. * Definition of the meta tags and groups.
  173. *
  174. * @return array
  175. * A nested array of 'tags' and 'groups', each keyed off the machine name for
  176. * their respective structure type, with the following values:
  177. * Tags:
  178. * 'label' - The name for this meta tag.
  179. * 'description' - An explanation of what this meta tag is used for and what
  180. * values are permissible.
  181. * 'class' - The class name that controls this meta tag.
  182. * 'weight' - Used to sort the meta tags during output.
  183. * 'group' - The machine name of a group this meta tag will be contained
  184. * within.
  185. * 'context' - Optionally control the type of configuration the meta tag
  186. * will be available from. Possible values are:
  187. * [empty] - All meta tags apply to all possible objects, by default.
  188. * 'global' - This will make it only show in the global meta tag
  189. * configuration form.
  190. * [entity type] - Makes the meta tag only show for specific entity types.
  191. * 'header' - Optionally output the meta tag as an HTTP header value.
  192. * 'element' - Optional attributes for rendering the meta tag. Should
  193. * contain the following:
  194. * '#theme' - The theming function used to render the meta tag.
  195. * 'replaces' - An optional array of meta tags that this meta tag replaces.
  196. * Used to indicate that these deprecated meta tags will be replaced by
  197. * this newer one, their values will be used, upon the next object save
  198. * the deprecated tag will be entirely replaced by the new meta tag. While
  199. * one meta tag can replace several others, only one of the possible
  200. * values will be used, the others will be silently purged upon the next
  201. * configuration/object save.
  202. * 'form' - Optional items to be passed directly to the form; uses standard
  203. * Form API values.
  204. * 'devel_generate' - Optional values to be passed to the Devel Generate
  205. * submodule. Should be an array containing one of the following values:
  206. * 'type' - One of the following:
  207. * 'canonical' - The token for the absolute URL for the current page.
  208. * 'email' - An email address randomly generated at the site's hostname.
  209. * 'float' - A random floating point number between 0.0 and 999.999.
  210. * 'image' - A randomly generated image.
  211. * 'integer' - A random integer between 0 and 999.
  212. * 'phone' - A phone number in the format 999-999-9999.
  213. * 'select' - A value randomly selected from the available form options.
  214. * 'text' - Random text string.
  215. * 'twitter' - A Twitter username.
  216. * 'url' - A randomly generated URL on this site.
  217. * 'maxlength' - The maximum length / number of iterations of this value,
  218. * defaults to 10.
  219. * 'dependencies' - Optional nested array of values to indicate other meta
  220. * tags that must be present in order for this meta tag to be visible. See
  221. * The Open Graph and Twitter Cards submodules for example usage. Each
  222. * dependency must contain the following elements:
  223. * 'dependency' - The name of the meta tag that is required.
  224. * 'attribute' - The name of the other meta tag that is to be checked,
  225. * most meta tags use "value" as the attribute name.
  226. * 'condition' - The state condition to be checked against, e.g. "filled"
  227. * to check text values, "checked" for a checkbox, "value" to compare
  228. * the raw selection; see https://api.drupal.org/drupal_process_states
  229. * for more details.
  230. * 'value' - The field value to check the 'condition' against. see
  231. * https://api.drupal.org/drupal_process_states for further details.
  232. * Groups:
  233. * 'label' - The name for this group.
  234. * 'description' - A detailed explanation of these meta tags.
  235. * 'form' - Additional items to be passed directly to the form.
  236. * Note: 'label', 'description', and any text strings passed in 'form', should
  237. * be translated.
  238. *
  239. * @see metatag_metatag_info().
  240. */
  241. function hook_metatag_info() {
  242. return array();
  243. }
  244. /**
  245. *
  246. */
  247. function hook_metatag_info_alter(&$info) {
  248. }
  249. /**
  250. *
  251. */
  252. function hook_metatag_load_entity_from_path_alter(&$path, $result) {
  253. }
  254. /**
  255. * Alter metatags before being cached.
  256. *
  257. * This hook is invoked prior to the meta tags for a given page are cached.
  258. *
  259. * @param array $output
  260. * All of the meta tags to be output for this page in their raw format. This
  261. * is a heavily nested array.
  262. * @param string $instance
  263. * An identifier for the current page's page type, typically a combination
  264. * of the entity name and bundle name, e.g. "node:story".
  265. * @param array $options
  266. * All of the options used to generate the meta tags.
  267. */
  268. function hook_metatag_metatags_view_alter(&$output, $instance, $options) {
  269. if (isset($output['description']['#attached']['drupal_add_html_head'][0][0]['#value'])) {
  270. $output['description']['#attached']['drupal_add_html_head'][0][0]['#value'] = 'O rly?';
  271. }
  272. }
  273. /**
  274. *
  275. */
  276. function hook_metatag_page_cache_cid_parts_alter(&$cid_parts) {
  277. }
  278. /**
  279. *
  280. */
  281. function hook_metatag_presave(&$metatags, $entity_type, $entity_id, $revision_id, $langcode) {
  282. }
  283. /**
  284. * Allows modules to alter the defined list of tokens available
  285. * for metatag patterns replacements.
  286. *
  287. * By default only context (for example: global, node, etc...)
  288. * related tokens are made available to metatag patterns replacements.
  289. * This hook allows other modules to extend the default declared tokens.
  290. *
  291. * @param array $options
  292. * (optional) An array of options including the following keys and values:
  293. * - token types: An array of token types to be passed to theme_token_tree().
  294. * - context: An identifier for the configuration instance type, typically
  295. * an entity name or object name, e.g. node, views, taxonomy_term.
  296. *
  297. * @see metatag_config_edit_form()
  298. * @see metatag_field_attach_form()
  299. */
  300. function hook_metatag_token_types_alter(&$options) {
  301. // Watchout: $options['token types'] might be empty
  302. if (!isset($options['token types'])) {
  303. $options['token types'] = array();
  304. }
  305. if ($options['context'] == 'config1'){
  306. $options['token types'] += array('token_type1','token_type2');
  307. }
  308. elseif ($options['context'] == 'config2'){
  309. $options['token types'] += array('token_type3','token_type4');
  310. }
  311. }
  312. /**
  313. * Allows modules to alter defined token patterns and values before replacement.
  314. *
  315. * The metatag module defines default token patterns replacements depending on
  316. * the different configuration instances (contexts, such as global, node, ...).
  317. * This hook provides an opportunity for other modules to alter the patterns or
  318. * the values for replacements, before tokens are replaced (token_replace).
  319. *
  320. * See facetapi and facetapi_bonus modules for an example of implementation.
  321. *
  322. * @param $pattern
  323. * A string potentially containing replaceable tokens. The pattern could also
  324. * be altered by reference, allowing modules to implement further logic, such
  325. * as tokens lists or masks/filters.
  326. * @param $types
  327. * Corresponds to the 'token data' property of the $options object.
  328. * (optional) An array of keyed objects. For simple replacement scenarios
  329. * 'node', 'user', and others are common keys, with an accompanying node or
  330. * user object being the value. Some token types, like 'site', do not require
  331. * any explicit information from $data and can be replaced even if it is
  332. * empty.
  333. * @param string $tag_name
  334. * The name of the meta tag being altered.
  335. *
  336. * @see DrupalTextMetaTag::getValue()
  337. */
  338. function hook_metatag_pattern_alter(&$pattern, &$types, $tag_name) {
  339. if (strpos($pattern, 'token_type1') !== FALSE) {
  340. $types['token_type1'] = "data to be used in hook_tokens for replacement";
  341. }
  342. if (strpos($pattern, 'token_type2') !== FALSE) {
  343. // Load something or do some operations.
  344. $types['token_type2'] = array("Then fill in the array with the right data");
  345. // $pattern could also be altered, for example, strip off [token_type3].
  346. $pattern = str_replace('[token_type3]', '', $pattern);
  347. }
  348. }