Technical reference
The Sitemap plugin generates XML sitemaps for published Brightspot content. It supports standard, news, and video sitemap types, manages sitemap generation through configurable background tasks, and organizes output into partitions to keep individual files within search-engine size limits.
Installation
Requirements
Requires Brightspot 4.5 or later.
- Maven
- Gradle
- Gradle (Kotlin DSL)
<dependency>
<groupId>com.brightspot.sitemap</groupId>
<artifactId>sitemap</artifactId>
<version>1.0.1</version>
</dependency>
implementation 'com.brightspot.sitemap:sitemap:1.0.1'
implementation("com.brightspot.sitemap:sitemap:1.0.1")
API reference
Content type interfaces
To include a content type in a sitemap, implement the appropriate interface on any class that also extends Content and implements Directory.Item.
| Interface | Method | Description |
|---|---|---|
SiteMapItem | getSiteMapEntries(Site site) | Returns entries for the standard sitemap. |
NewsSiteMapItem | getNewsSiteMapEntries(Site site) | Returns entries for the news sitemap (news-sitemap.xml). |
VideoSiteMapItem | getSiteMapEntries(Site site) | Returns entries for the video sitemap (video-sitemap.xml). |
All three extend GlobalSiteMapItem, which extends Recordable.
SiteMapEntry
SiteMapEntry represents a single <url> element in the sitemap XML. Return one per URL the content type resolves to across all sites.
| Method | Type | Required | Description |
|---|---|---|---|
setPermalink(String) | String | Yes | Full URL, including protocol and domain. Non-ASCII characters are percent-encoded automatically. |
setUpdateDate(Date) | Date | No | Last-modified date. Maps to <lastmod>. |
setChangeFrequency(SiteMapChangeFrequency) | enum | No | Hint to search engines about how often the URL changes. Maps to <changefreq>. |
setPriority(Double) | Double | No | Relative priority within the site, from 0.0 to 1.0. Maps to <priority>. |
setImages(List<SiteMapImage>) | List | No | Image extension data. Maps to <image:image> elements. |
setVideos(List<SiteMapVideo>) | List | No | Video extension data. Maps to <video:video> elements. |
setNews(List<SiteMapNews>) | List | No | News extension data. Maps to <news:news> elements. |
SiteMapChangeFrequency
| Value | Description |
|---|---|
ALWAYS | Content changes every time it is accessed. |
HOURLY | Content changes approximately every hour. |
DAILY | Content changes approximately once a day. |
WEEKLY | Content changes approximately once a week. |
MONTHLY | Content changes approximately once a month. |
YEARLY | Content changes approximately once a year. |
NEVER | Archived content that will not change. |
SiteMapImage
Attach one or more SiteMapImage instances to a SiteMapEntry to populate <image:image> elements.
| Method | Type | Required | Description |
|---|---|---|---|
setUrl(String) | String | Yes | Full URL to the image. |
setTitle(String) | String | No | Image title. |
setCaption(String) | String | No | Image caption. |
setGeoLocation(String) | String | No | Geographic location where the image was taken. |
setLicense(String) | String | No | URL of the image license. |
SiteMapVideo
Attach one or more SiteMapVideo instances to a SiteMapEntry to populate <video:video> elements.
| Method | Type | Required | Description |
|---|---|---|---|
setThumbnailLoc(String) | String | Yes | URL to the video thumbnail image. |
setTitle(String) | String | Yes | Video title. |
setDescription(String) | String | Yes | Video description. |
setContentLoc(String) | String | No | Direct URL to the video file. Either contentLoc or playerLoc must be set. |
setPlayerLoc(String) | String | No | URL of the video player page. Either contentLoc or playerLoc must be set. |
setPlayerLocAllowEmbed(Boolean) | Boolean | No | Whether the player can be embedded on other pages. |
setPlayerLocAutoplay(String) | String | No | Autoplay parameter appended to the player URL. |
setDuration(Long) | Long | No | Duration in seconds. |
setExpirationDate(Date) | Date | No | Date after which the video is no longer available. |
setRating(Double) | Double | No | Rating from 0.0 to 5.0. |
setViewCount(Long) | Long | No | Number of views. |
setPublicationDate(Date) | Date | No | Date the video was first published. |
setTags(List<String>) | List | No | Descriptive tags for the video. |
setCategory(String) | String | No | Single category describing the video's topic. |
setFamilyFriendly(Boolean) | Boolean | No | Whether the video is suitable for all audiences. |
setRestriction(String) | String | No | Space-delimited ISO 3166 country codes. Use with setRestrictionRelationship. |
setRestrictionRelationship(SiteMapRelationship) | enum | No | Whether the restriction list is an allowlist or a blocklist. |
setGalleryLoc(String) | String | No | URL of a gallery page associated with the video. |
setGalleryLocTitle(String) | String | No | Title of the gallery page. |
setPrice(Double) | Double | No | Price to view the video. Use with setPriceCurrency. |
setPriceCurrency(String) | String | No | ISO 4217 currency code for the price (for example, USD). |
setRequiresSubscription(Boolean) | Boolean | No | Whether viewing requires a subscription. |
setUploader(String) | String | No | Display name of the video uploader. |
setUploaderInfo(String) | String | No | URL with more information about the uploader. |
setLive(Boolean) | Boolean | No | Whether the video is a live stream. |
SiteMapRelationship
Used with SiteMapVideo#setRestrictionRelationship(SiteMapRelationship).
| Value | Description |
|---|---|
ALLOW | Video is available only in the specified countries. |
DENY | Video is not available in the specified countries. |
SiteMapNews
Attach a SiteMapNews instance to a SiteMapEntry to populate <news:news> elements.
| Method | Type | Required | Description |
|---|---|---|---|
setName(String) | String | Yes | Publication name. Maps to <news:publication><news:name>. |
setLanguage(String) | String | Yes | BCP 47 language code (for example, en). Maps to <news:publication><news:language>. |
setPublicationDate(Date) | Date | Yes | Date the article was published. Maps to <news:publication_date>. |
setTitle(String) | String | Yes | Article title. Maps to <news:title>. |
setGenres(List<String>) | List | No | Publication genres (for example, Blog, Opinion). Rendered as a comma-delimited value in <news:genres>. |
setGeoLocations(String) | String | No | Geographic locations the article relates to. Maps to <news:geo_locations>. |
setKeywords(List<String>) | List | No | Keywords describing the topic. Rendered as a comma-delimited value in <news:keywords>. |
setStockTickers(List<String>) | List | No | Stock tickers referenced in the article. Rendered as a comma-delimited value in <news:stock_tickers>. |
SiteMapConfig
SiteMapConfig controls how the sitemap background tasks run. The plugin discovers a concrete implementation at run time using ClassFinder. Implement this interface to customize task scheduling, content age limits, partition strategies, or file size constraints.
| Method | Default | Description |
|---|---|---|
isAllowedToRun() | — | Required. Return true only on the designated task host. As a best practice, call TaskUtils.isRunningOnTaskHost(). |
getSiteMapTypes(Site site) | — | Required. Return the SiteMapType instances to enable for the given site. |
getMaximumContentAgeDays(Site, SiteMapType<?>) | type default | Maximum age of content included in partitioned sitemaps. |
getMaximumLatestContentAgeDays(Site, SiteMapType<?>) | type default | Maximum age of content included in the dynamic sitemap-latest.xml file. |
getPartitionStrategy(Site, SiteMapType<?>) | type default | Partition strategy to use for the given site and type. |
getMaximumSiteMapEntries() | 50000 | Maximum number of <url> elements per sitemap file. |
getMaximumLatestSiteMapEntries() | 1000 | Maximum entries in the sitemap-latest.xml file. |
getMaximumSiteMapFileSize() | 10485760 | Maximum file size in bytes (10 MB). |
shouldRepartition(SiteMapPartitionConfiguration) | hourly | Return true when partitions should be reconfigured. |
getFetchSize() | 400 | Query fetch size for sitemap content queries. Override the default via the setting key cms/siteMap/queryOptionsFetchSize. |
shouldFormatXml() | true | Whether to format generated XML with indentation. |
SiteMapType
SiteMapType<T> defines a category of sitemap and maps content types to sitemap entries. Implement this interface to create a custom sitemap type beyond the three built-in types.
| Method | Default | Description |
|---|---|---|
getPrefix() | — | Required. File name prefix. An empty string produces sitemap.xml; "news-" produces news-sitemap.xml. Each implementation must use a unique prefix. |
getSiteMapItemClass() | — | Required. The content type interface this sitemap type handles. |
getEntries(T item, Site site) | — | Required. Returns the sitemap entries for a given item and site. |
getSitemapItemQuery() | Query.from(getSiteMapItemClass()).where("* matches *") | Query used to retrieve all sitemap candidates. |
updateSiteMapMap(Map<String, Object>) | no-op | Hook to inject XML namespace declarations into the root sitemap element. |
getDefaultMaximumContentAgeDays() | 7300 (~20 years) | Maximum age of content included in this sitemap type. |
getDefaultMaximumLatestContentAgeDays() | 2 | Maximum age of content included in sitemap-latest.xml. |
getLabel() | derived from class name | Display name for the sitemap type. |
getPartitionStrategy() | YearMonthPartitionStrategy | Default partition strategy for this type. |
PartitionStrategy
PartitionStrategy controls how the sitemap task divides content across sitemap files and determines when each file needs to be regenerated. Implement this interface to create a custom partitioning scheme.
| Method | Description |
|---|---|
updatePartitions(SiteMapConfig, Site, SiteMapType<?>) | Required. Create, update, or delete SiteMapPartition records for the given site and type. |
shouldUpdateSitemap(SiteMapConfig, Site, SiteMapType<?>, SiteMapPartition) | Required. Return true when the sitemap for the given partition needs to be regenerated. |
partitionContentQuery(SiteMapConfig, Site, SiteMapType<T>, SiteMapPartition) | Required. Return the content query scoped to a specific partition. |
latestContentQuery(SiteMapConfig, Site, SiteMapType<T>, SiteMapPartition) | Returns a query for content published more recently than the partition's last successful run, up to getMaximumLatestContentAgeDays. Has a default implementation. |
Built-in implementations
Sitemap types
| Class | Prefix | Content interface | Default max content age |
|---|---|---|---|
StandardSiteMapType | "" | SiteMapItem | ~20 years |
NewsSiteMapType | "news-" | NewsSiteMapItem | 2 days |
VideoSiteMapType | "video-" | VideoSiteMapItem | ~20 years |
Partition strategies
YearMonthPartitionStrategy organizes content into monthly buckets based on publication date. It creates one SiteMapPartition per year-month combination in which published content exists, and determines regeneration frequency by partition age.
| Partition age | Regeneration frequency |
|---|---|
| Within the last month | Daily |
| One to six months old | Weekly |
| Six months to two years old | Monthly |
| Older than two years | Every 180 days |
SinglePartitionStrategy maintains a single partition regardless of content volume, regenerating it every six hours. It is used by NewsSiteMapType to keep news sitemaps current.