www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/simple_sitemap/README.md

   1 CONTENTS OF THIS FILE
   2 ---------------------
   3
   4  * Introduction
   5  * Installation
   6  * Configuration
   7  * Usage
   8  * Extending the module
   9  * How Can You Contribute?
  10  * Maintainers
  11
  12
  13 INTRODUCTION
  14 ------------
  15
  16 Author and maintainer: Pawel Ginalski (gbyte.co)
  17 https://www.drupal.org/u/gbyte.co
  18
  19 The module generates a multilingual XML sitemap which adheres to Google's new
  20 hreflang standard. Out of the box the sitemap is able to index most of Drupal's
  21 content entity types including:
  22
  23  * nodes
  24  * taxonomy terms
  25  * menu links
  26  * users
  27  * ...
  28
  29 Contributed entity types like commerce products or media entities can be indexed
  30 as well. On top of that custom links can be added to the sitemap.
  31
  32 To learn about XML sitemaps, see https://en.wikipedia.org/wiki/Sitemaps.
  33
  34
  35 INSTALLATION
  36 ------------
  37
  38 See https://www.drupal.org/documentation/install/modules-themes/modules-8
  39 for instructions on how to install or update Drupal modules.
  40
  41
  42 CONFIGURATION
  43 -------------
  44
  45 The module permission 'administer sitemap settings' can be configured under
  46 /admin/people/permissions.
  47
  48 Initially only the home page is indexed in the sitemap. To include content into
  49 the sitemap, visit /admin/config/search/simplesitemap/entities to enable support
  50 for entity types of your choosing. Entity types which feature bundles can then
  51 be configured on a per-bundle basis, e.g.
  52
  53  * /admin/structure/types/manage/[content type] for nodes
  54  * /admin/structure/taxonomy/manage/[taxonomy vocabulary] for taxonomy terms
  55  * /admin/structure/menu/manage/[menu] for menu items
  56  * ...
  57
  58 When including an entity type or bundle into the sitemap, the priority setting
  59 can be set which will set the 'priority' parameter for all entities of that
  60 type. Same goes for the 'changefreq' setting. All Images referenced by the
  61 entities can be indexed as well. See https://en.wikipedia.org/wiki/Sitemaps to
  62 learn more about these parameters.
  63
  64 Inclusion settings of bundles can be overridden on a per-entity
  65 basis. Just head over to a bundle instance edit form (e.g. node/1/edit) to
  66 override its sitemap settings.
  67
  68 If you wish for the sitemap to reflect the new configuration instantly, check
  69 'Regenerate sitemap after clicking save'. This setting only appears if a change
  70 in the settings has been detected.
  71
  72 As the sitemap is accessible to anonymous users, bear in mind that only links
  73 will be included which are accessible to anonymous users. There are no access
  74 checks for links added through the module's hooks (see below).
  75
  76 To include custom links into the sitemap, visit
  77 /admin/config/search/simplesitemap/custom.
  78
  79 The settings page can be found under admin/config/search/simplesitemap.
  80 Here the module can be configured and the sitemap can be manually regenerated.
  81
  82
  83 USAGE
  84 -----
  85
  86 The sitemap is accessible to the whole world under /sitemap.xml.
  87
  88 If the cron generation is turned on, the sitemap will be regenerated according
  89 to the 'Sitemap generation interval' setting ranging from 'On every cron run' to
  90 'Once a week'.
  91
  92 A manual generation is possible on admin/config/search/simplesitemap.
  93
  94 The sitemap can be also generated via drush: Use the command
  95 'drush simple_sitemap-generate'.
  96
  97
  98 EXTENDING THE MODULE
  99 --------------------
 100
 101 It is possible to hook into link generation by implementing
 102 hook_simple_sitemap_links_alter(&$links){} in a custom module and altering the
 103 link array shortly before it is transformed to XML.
 104
 105 Adding arbitrary links is possible through the use of
 106 hook_simple_sitemap_arbitrary_links_alter(&$arbitrary_links){}. There are no
 107 checks performed on these links (i.e. if they are internal/valid/accessible)
 108 and parameters like priority/lastmod/changefreq have to be added manually.
 109
 110 Altering sitemap attributes and sitemap index attributes is possible through the
 111 use of hook_simple_sitemap_attributes_alter(&$attributes){} and
 112 hook_simple_sitemap_index_attributes_alter(&$index_attributes){}.
 113
 114 Altering URL generator plugins is possible through
 115 the use of hook_simple_sitemap_url_generators_alter(&$generators){}.
 116
 117 In case this module's URL generators do not cover your use case, it is possible
 118 to implement new generator plugins in a custom module. To do it, simply extend
 119 the Drupal\simple_sitemap\Plugin\simple_sitemap\UrlGenerator\UrlGeneratorBase
 120 class. See the generator plugins included in this module and check the API docs
 121 (https://www.drupal.org/docs/8/api/plugin-api/plugin-api-overview) to learn how
 122 to implement plugins.
 123
 124 Overwriting the default EntityUrlGenerator for a single entity type is possible
 125 through the flag "overrides_entity_type" = "[entity_type_to_be_overwritten]" in
 126 the settings array of the new generator plugin's annotation. See how the
 127 EntityUrlGenerator is overwritten by the EntityMenuLinkContentUrlGenerator to
 128 facilitate a different logic for menu links.
 129
 130 There are API methods for altering stored inclusion settings, status queries and
 131 programmatic sitemap generation. These include:
 132
 133  * getSetting()
 134  * saveSetting()
 135  * getSitemap()
 136  * generateSitemap()
 137  * getGeneratedAgo()
 138  * enableEntityType()
 139  * disableEntityType()
 140  * setBundleSettings()
 141  * getBundleSettings()
 142  * setEntityInstanceSettings()
 143  * getEntityInstanceSettings()
 144  * removeEntityInstanceSettings()
 145  * bundleIsIndexed()
 146  * entityTypeIsEnabled()
 147  * addCustomLink()
 148  * getCustomLinks()
 149  * getCustomLink()
 150  * removeCustomLink()
 151  * removeCustomLinks()
 152
 153 These service methods can be chained like so:
 154
 155 \Drupal::service('simple_sitemap.generator')
 156   ->saveSetting('remove_duplicates', TRUE)
 157   ->enableEntityType('node')
 158   ->setBundleSettings('node', 'page', ['index' => TRUE, 'priority' = 0.5])
 159   ->removeCustomLinks()
 160   ->addCustomLink('/some/view/page', ['priority' = 0.5])
 161   ->generateSitemap();
 162
 163
 164 HOW CAN YOU CONTRIBUTE?
 165 -----------------------
 166
 167  * Report any bugs, feature or support requests in the issue tracker, if
 168    possible help out by submitting patches.
 169    http://drupal.org/project/issues/simple_sitemap
 170
 171  * Do you know a non-English language? Help translating the module.
 172    https://localize.drupal.org/translate/projects/simple_sitemap
 173
 174  * If you would like to say thanks and support the development of this module, a
 175    donation is always appreciated.
 176    https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5AFYRSBLGSC3W
 177
 178
 179 MAINTAINERS
 180 -----------
 181
 182 Current maintainers:
 183  * Pawel Ginalski (gbyte.co) - https://www.drupal.org/u/gbyte.co