Skip to main content

Articles

note

This guide assumes familiarity with the Spring Framework.
If you are new to Spring, we recommend starting with their official guides to get up to speed.

The Article is the primary content type in Singularity for managing editorial and blog-style content. It is engineered to fully utilize and extend the core Content Management System (CMS) architecture.

The Kotlin data class Article implements two foundational architectural interfaces:

  1. ContentDocument<Article>: Provides the base for security, access control, and tag management.
  2. Translatable<ArticleTranslation>: Enables the article to store content in multiple languages.

The Article Model Structure​

The Article document stores both core CMS fields and specialized article metadata. The model's power comes from its structure, which separates editorial content (translations) from workflow and display metadata (state, colors).

FieldTypeDescription
key, access, tags, trusted(Inherited)Core content features (Security, Ownership, Tagging) from ContentDocument.
translationsMap<Locale, ArticleTranslation>Stores localized fields (title, content, summary).
publishedAtInstant?The timestamp of when the article was formally published.
pathStringThe unique, URL-friendly slug for the article (e.g., /guides/my-new-article).
stateArticleStateThe current workflow state, such as DRAFT, PUBLISHED, or ARCHIVED.
imageKeyString?The FileMetadataDocument key linking to the article's primary image/rendition set.
colorsArticleColorsOptional metadata for frontend styling (text and background hex codes).

Specialized Article Sub-Models​

ArticleState​

This enum defines the formal state of the article, which is crucial for controlling public visibility and editorial workflows.

StateDescriptionUsage Context
DRAFTThe article is currently being edited and is not publicly visible.Development, Review
PUBLISHEDThe article is live and accessible according to its ContentAccessDetails.Production, Public Access
ARCHIVEDThe article is no longer active but is retained for historical purposes.Historical records, Internal only

ArticleTranslation​

This structure holds the actual, localized editorial content fields that are expected to change per language.

FieldTypeDescription
titleStringThe title of the article.
summaryStringA brief description or snippet used for overview pages.
contentStringThe full body content of the article.

ArticleColors​

This model provides simple thematic styling control, which can be useful for frontend rendering, like custom branding on a news feed.

FieldTypeDefaultDescription
textString?"white"The color used for the article's primary text.
backgroundString?"#00008B"The background color (e.g., used for card backgrounds).

Key Advantages​

1. Robust Multilingual Support (i18n)​

By implementing the Translatable interface, Articles store all editorial text in a nested translations map, allowing for robust internationalization out-of-the-box.

Translations

You can learn more about translations here.

Deep Localization

When retrieving or searching Articles, the system automatically uses the requested Locale to focus on the ArticleTranslation fields. Search queries for title or content are language-specific, ensuring accurate results for the current user's language preference.

2. Integrated Publishing Workflow​

The Article model uses the ArticleState enum and the dedicated changeState endpoint to manage a formal editorial lifecycle.

Controlled State Transitions

The endpoint PUT /api/content/articles/{key}/state is restricted to users with at least the EDITOR role. This separation ensures that only authorized personnel can move an article from DRAFT to PUBLISHED, providing essential governance over content release.

3. Advanced, Localized Search & Filtering​

The API for querying Articles (GET /api/content/articles) offers highly granular search capabilities through its comprehensive set of query parameters.

Comprehensive Filtering

The ArticleController allows filtering by numerous criteria, including:

  • Localized text (title, content)
  • Date ranges (createdAt, updatedAt, publishedAt)
  • Workflow State (state)
  • Roles: The roles parameter allows users to filter the results to only include Articles for which they have a specific access level.

4. Inherited Security Model and Customization​

As an implementation of ContentDocument, the Article automatically inherits the system's robust security framework.

Access

You can learn more about access here.

Secure Access by Default

An Article is never accessible unless granted permission via its ContentAccessDetails. This includes:

  1. Being set to PUBLIC visibility.
  2. Explicitly sharing with a User or Group with a role of VIEWER or higher (defined in ContentAccessPermissions.kt).
  3. The user possessing the global ADMIN role.

The trusted flag, also inherited from ContentDocument, provides an extra layer of integrity control for critical assets.

Configuration​

Articles are enabled by default. You can disable it by changing the following property:

PropertyTypeDescriptionDefault value
singularity.content.articles.enableBooleanEnable article management.true

Management​

Creating Articles​

New articles can be created through the endpoint:

Finding Articles​

info

These endpoints return only the articles that are accessible by the requester. You can learn more here.

Updating Articles​

Title, Content, Summary, Colors​

You can update the title, content, summary, tags and colors of an article with given key through the endpoint:

Locale

The locale specifies which translation should be updated. The locale query parameter specifies which translation should be returned.

State​

You can update the article's state through the endpoint:

Image​

You can update the article's image through the endpoint:

Owner​

The owner of an article with given key can be updated through the endpoint:

Access​

The access can be updated through the endpoint:

Trusted State​

The trusted state can be updated through the endpoint

Deleting Articles​

An article with given key can be deleted through the endpoint: