README.txt 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319
  1. Metatag
  2. -------
  3. This module allows you to automatically provide structured metadata, aka "meta
  4. tags", about your website and web pages.
  5. In the context of search engine optimization, providing an extensive set of
  6. meta tags may help improve your site's & pages' ranking, thus may aid with
  7. achieving a more prominent display of your content within search engine
  8. results. Additionally, using meta tags can help control the summary content
  9. that is used within social networks when visitors link to your site,
  10. particularly the Open Graph submodule for use with Facebook, Pinterest,
  11. LinkedIn, etc (see below).
  12. This version of the module only works with Drupal 7.28 and newer.
  13. Features
  14. ------------------------------------------------------------------------------
  15. The primary features include:
  16. * The current supported basic meta tags are ABSTRACT, DESCRIPTION, CANONICAL,
  17. GENERATOR, IMAGE_SRC, KEYWORDS, PUBLISHER, REVISIT-AFTER, RIGHTS, ROBOTS,
  18. SHORTLINK and the page's TITLE tag.
  19. * Multi-lingual support using the Entity Translation module.
  20. * Translation support using the Internationalization (i18n) module.
  21. * Full support for entity revisions and workflows based upon revision editing,
  22. including compatibility with the Revisioning and Workbench Moderation modules.
  23. * Per-path control over meta tags using the "Metatag: Context" submodule
  24. (requires the Context module).
  25. * Integration with the Views module allowing meta tags to be controlled for
  26. individual Views pages, with each display in the view able to have different
  27. meta tags, by using the "Metatag: Views" submodule.
  28. * Integration with the Panels module allowing meta tags to be controlled for
  29. individual Panels pages, by using the "Metatag: Panels" submodule.
  30. * The fifteen Dublin Core Basic Element Set 1.1 meta tags may be added by
  31. enabling the "Metatag: Dublin Core" submodule.
  32. * The Open Graph Protocol meta tags, as used by Facebook, Pinterest, LinkedIn
  33. and other sites, may be added by enabling the "Metatag: Open Graph" submodule.
  34. * The Twitter Cards meta tags may be added by enabling the "Metatag: Twitter
  35. Cards" submodule.
  36. * Certain meta tags used by Google+ may be added by enabling the "Metatag:
  37. Google+" submodule.
  38. * Facebook's fb:app_id and fb:admins meta tags may be added by enabling the
  39. "Metatag: Facebook" submodule. These are useful for sites which are using
  40. Facebook widgets or are building custom integration with Facebook's APIs,
  41. but they are not needed by most sites and have no bearing on the Open Graph
  42. meta tags.
  43. * The App Links meta tags may be added by enabling the Metatag: App Links
  44. submodule.
  45. * Site verfication meta tags can be added, e.g. as used by the Google search
  46. engine to confirm ownership of the site; see the "Metatag: Verification"
  47. submodule.
  48. * An API allowing for additional meta tags to be added, beyond what is provided
  49. by this module - see metatag.api.php for full details.
  50. * Support for the Migrate module for migrating data from another system - see
  51. metatag.migrate.inc for full details.
  52. * Support for the Feeds module for importing data from external data sources or
  53. file uploads.
  54. * Integrates with Devel_Generate, part of the Devel module, to automatically
  55. generate meta tags for generated nodes, via the Metatag:Devel submodule.
  56. * Integrates with Workbench Moderation (both v1 and v2) allowing meta tags on
  57. nodes to be managed through the workflow process.
  58. * The Transliteration and Imagecache Token modules (see below) are highly
  59. recommended when using image meta tags, e.g. og:image.
  60. * Several advanced options may be controlled via the Advanced Settings page.
  61. Configuration
  62. ------------------------------------------------------------------------------
  63. 1. On the People Permissions administration page ("Administer >> People
  64. >> Permissions") you need to assign:
  65. - The "Administer meta tags" permission to the roles that are allowed to
  66. access the meta tags admin pages to control the site defaults.
  67. - The "Edit meta tags" permission to the roles that are allowed to change
  68. meta tags on each individual page (node, term, etc).
  69. 2. The main administrative page controls the site-wide defaults, both global
  70. settings and defaults per entity (node, term, etc), in addition to those
  71. assigned specifically for the front page:
  72. admin/config/search/metatags
  73. 3. In order to provide a specific configuration per entity bundle (content
  74. type, vocabulary, etc), click "Add a Metatag default".
  75. 4. Each supported entity object (nodes, terms, users) will have a set of meta
  76. tag fields available for customization on their respective edit page, these
  77. will inherit their values from the defaults assigned in #2 above. Any
  78. values that are not overridden per object will automatically update should
  79. the defaults be updated.
  80. 5. As the meta tags are output using Tokens, it may be necessary to customize
  81. the token display for the site's entities (content types, vocabularies,
  82. etc). To do this go to e.g., admin/structure/types/manage/article/display,
  83. in the "Custom Display Settings" section ensure that "Tokens" is checked
  84. (save the form if necessary), then to customize the tokens go to:
  85. admin/structure/types/manage/article/display/token
  86. Internationalization: i18n.module
  87. ------------------------------------------------------------------------------
  88. All default configurations may be translated using the Internationalization
  89. (i18n) module. The custom strings that are assigned to e.g., the "Global: Front
  90. page" configuration will show up in the Translate Interface admin page
  91. (admin/config/regional/translate/translate) and may be customized per language.
  92. Fine Tuning
  93. ------------------------------------------------------------------------------
  94. All of these may be controlled from the advanced settings page:
  95. admin/config/search/metatags/settings
  96. * It is possible to "disable" the meta tags provided by Drupal core, i.e.
  97. "generator", "canonical URL" and "shortlink", though it may not be completely
  98. obvious. Metatag takes over the display of these tags, thus any changes made
  99. to them in Metatag will supercede Drupal's normal output. To hide a tag, all
  100. that is necessary is to clear the default value for that tag, e.g. on the
  101. global settings for nodes, which will result in the tag not being output for
  102. those pages.
  103. * By default Metatag will load the global default values for all pages that do
  104. not have meta tags assigned via the normal entity display or via Metatag
  105. Context. This may be disabled by setting the variable 'metatag_load_all_pages'
  106. to FALSE through one of the following methods:
  107. * Use Drush to set the value:
  108. drush vset metatag_load_all_pages FALSE
  109. * Hardcode the value in the site's settings.php file:
  110. $conf['metatag_load_all_pages'] = FALSE;
  111. To re-enable this option simply set the value to TRUE.
  112. * By default users will be able to edit meta tags on forms based on the 'Edit
  113. meta tags' permission. The 'metatag_extended_permissions' variable may be set
  114. to TRUE to give each individual meta tag a separate permission. This allows
  115. fine-tuning of the site's editorial control, and for rarely-used fields to be
  116. hidden from most users. Note: The 'Edit meta tags' permission is still
  117. required otherwise none of the meta tag fields will display at all. The
  118. functionality may be disabled again by either removing the variable or
  119. setting it to FALSE.
  120. * It's possible to disable Metatag integration for certain entity types or
  121. bundles using variables. To disable an entity just assigning a variable
  122. 'metatag_enable_{$entity_type}' or 'metatag_enable_{$entity_type}__{$bundle}'
  123. the value FALSE, e.g.:
  124. // Disable metatags for file_entity.
  125. $conf['metatag_enable_file'] = FALSE;
  126. // Disable metatags for carousel nodes.
  127. $conf['metatag_enable_node__carousel'] = FALSE;
  128. To enable the entity and/or bundle simply set the value to TRUE or remove the
  129. settings.php line. Note that the Metatag cache will need to be cleared after
  130. changing these settings, specifically the 'info' records, e.g., 'info:en'; a
  131. quick version of doing this is to clear the site caches using either Drush,
  132. Admin Menu (flush all caches), or the "Clear all caches" button on
  133. admin/config/development/performance.
  134. * By default Metatag will not display meta tags on admin pages. To enable meta
  135. tags on admin pages simply set the 'metatag_tag_admin_pages' variable to TRUE
  136. through one of the following methods:
  137. * Use Drush to set the value:
  138. drush vset metatag_tag_admin_pages TRUE
  139. * Hardcode the value in the site's settings.php file:
  140. $conf['metatag_tag_admin_pages'] = TRUE;
  141. To re-enable this option simply set the value to FALSE or delete the
  142. settings.php line.
  143. * When loading an entity with multiple languages for a specific language the
  144. meta tag values saved for that language will be used if they exist, otherwise
  145. values assigned to the entity's default language will be used. This
  146. may be disabled using the enabling the "Don't load entity's default language
  147. values if no languages match" option on the Advanced Settings page, which will
  148. cause default values to be used should there not be any values assigned for
  149. the current requested language.
  150. * When using Features to export Metatag configurations, it is suggested to
  151. override all of the default configurations and then disable the default
  152. configurations via the advanced settings page; doing so will avoid potential
  153. conflicts of the same configurations being loaded by both the Metatag module
  154. and the new Features-based modules.
  155. Developers
  156. ------------------------------------------------------------------------------
  157. Full API documentation is available in metatag.api.php.
  158. To enable Metatag support in custom entities, add 'metatag' => TRUE to either
  159. the entity or bundle definition in hook_entity_info(); see metatag.api.php for
  160. further details and example code.
  161. The meta tags for a given entity object (node, etc) can be obtained as follows:
  162. $metatags = metatags_get_entity_metatags($entity_id, $entity_type, $langcode);
  163. The result will be a nested array of meta tag structures ready for either output
  164. via drupal_render(), or examining to identify the actual text values.
  165. Troubleshooting / Known Issues
  166. ------------------------------------------------------------------------------
  167. * Image fields do not output very easily in meta tags, e.g. for og:image,
  168. without use of the Imagecache Token module (see below). This also provides a
  169. way of using an image style to resize the original images first, rather than
  170. requiring visitors download multi-megabyte original images.
  171. * When using custom page template files, e.g., page--front.tpl.php, it is
  172. important to ensure that the following code is present in the template file:
  173. <?php render($page['content']); ?>
  174. or
  175. <?php render($page['content']['metatags']); ?>
  176. Without one of these being present the meta tags will not be displayed.
  177. * An alternative method to fixing the missing-tags problem is to change the page
  178. region used to output the meta tags. The region used may be controlled from
  179. the settings page, it is recommended to test different options to identify the
  180. one that works best for a specific site.
  181. * Versions of Drupal older than v7.17 were missing necessary functionality for
  182. taxonomy term pages to work correctly.
  183. * Using Metatag with values assigned for the page title and the Page Title
  184. module simultaneously can cause conflicts and unexpected results.
  185. * When customizing the meta tags for user pages, it is strongly recommended to
  186. not use the [current-user] tokens, these pertain to the person *viewing* the
  187. page and not e.g., the person who authored a page.
  188. * Certain browser plugins, e.g., on Chrome, can cause the page title to be
  189. displayed with additional double quotes, e.g., instead of:
  190. <title>The page title | My cool site</title>
  191. it will show:
  192. <title>"The page title | My cool site"</title>
  193. The solution is to remove the browser plugin - the page's actual output is not
  194. affected, it is just a problem in the browser.
  195. * Drupal core versions before v7.33 had a bug which caused validation problems
  196. in the Open Graph output if the RDF module was also enabled. The solution is
  197. to update to core v7.33 or newer.
  198. * If the Administration Language (admin_language) module is installed, it is
  199. recommended to disable the "Force language neutral aliases" setting on the
  200. Admin Language settings page, i.e. set the "admin_language_force_neutral"
  201. variable to FALSE. Failing to do so can lead to data loss in Metatag.
  202. Related modules
  203. ------------------------------------------------------------------------------
  204. Some modules are available that extend Metatag with additional functionality:
  205. * Image URL Formatter
  206. https://www.drupal.org/project/image_url_formatter
  207. Provides a formatter for file and image fields to output the raw URL, and
  208. optionally pass it through an image style. Useful for getting an image
  209. field's token to output correctly for use in a meta tag.
  210. * Imagecache Token
  211. https://www.drupal.org/project/imagecache_token
  212. Provides additional tokens for image fields that can be used in e.g. the
  213. og:image meta tag; ultimately makes it possible to actually use image meta
  214. tags without writing custom code.
  215. * Transliteration
  216. https://drupal.org/project/transliteration
  217. Tidies up filenames for uploaded files, e.g. it can remove commas from
  218. filenames that could otherwise break certain meta tags.
  219. * Alternative hreflang
  220. https://www.drupal.org/project/hreflang
  221. Output <link rel="alternate" hreflang="x" href="http://" /> meta tags for
  222. each language available on the site.
  223. * Domain Meta Tags
  224. https://drupal.org/project/domain_meta
  225. Integrates with the Domain Access module, so each site of a multi-domain
  226. install can separately control their meta tags.
  227. * Select or Other
  228. https://drupal.org/project/select_or_other
  229. Enhances the user experience of the metatag_opengraph submodule by allowing
  230. the creation of custom Open Graph types.
  231. * Node Form Panes
  232. https://drupal.org/project/node_form_panes
  233. Create custom node-edit forms and control the location of the Metatag fields.
  234. * Textimage
  235. https://drupal.org/project/textimage
  236. Supports using Textimage's custom tokens in meta tag fields.
  237. * Field Multiple Limit
  238. https://drupal.org/project/field_multiple_limit
  239. Allows control over how many items are output in a multi-item field, useful
  240. with meta tags that only allow for one item but which are assigned from fields
  241. which accept multiple items, e.g. og:audio and og:video.
  242. Credits / Contact
  243. ------------------------------------------------------------------------------
  244. Currently maintained by Damien McKenna [1] and Dave Reid [2]; all initial
  245. development was by Dave Reid.
  246. Ongoing development is sponsored by Mediacurrent [3] and Lullabot [4]. All
  247. initial development was sponsored by Acquia [5] and Palantir.net [6].
  248. The best way to contact the authors is to submit an issue, be it a support
  249. request, a feature request or a bug report, in the project issue queue:
  250. https://www.drupal.org/project/issues/metatag
  251. References
  252. ------------------------------------------------------------------------------
  253. 1: https://www.drupal.org/u/damienmckenna
  254. 2: https://www.drupal.org/u/dave-reid
  255. 3: http://www.mediacurrent.com/
  256. 4: http://www.lullabot.com/
  257. 5: http://www.acquia.com/
  258. 6: http://www.palantir.net/