README

🇩🇪 German Version

The SuluArticleConfigurationBundle extends Sulu 3.0 Articles with a comprehensive "Configuration" tab. It allows managing additional display options, features, and publication settings directly on the article.

✨ Features

📋 Display Options

Layout Style - Choose between Default, Wide, Full Width, or Narrow (Reading Mode)
Sidebar - Enable/disable sidebar and set position (Left/Right)
Show Elements - Table of Contents (TOC), Reading Time, Author Box, Related Articles

⚙️ Functions & Features

Interactions - Share Buttons
Tools - Print Function

🚀 Publication Settings

Metadata - Hide Publish Date

🎨 Styling & Advanced

Design - Custom CSS classes

🔄 Default-Configuration

Inheritance System - Set a configuration as default for all articles of the same template key
3-Tier Cascade - Article-specific → Template key specific → default values
Automatic Template Detection - The template key is automatically detected and stored

📋 Prerequisites

PHP 8.2 or higher
Sulu CMS 3.0 or higher

👩🏻‍🏭 Installation

Step 1: Install the package

Add the repository to your composer.json (if local) or install directly:

composer require manuxi/sulu-article-configuration-bundle

If you are not using Symfony Flex, add the bundle to config/bundles.php:

return [
    //...
    Manuxi\SuluArticleConfigurationBundle\SuluArticleConfigurationBundle::class => ['all' => true],
];

Step 2: Configure routes

Add the following to config/routes.yaml to load the Admin API routes:

sulu_article_configuration_api:
    resource: '@SuluArticleConfigurationBundle/Resources/config/routes_admin.yaml'

Step 3: Update the database

Create the required ar_article_configuration table:

# Check what will be created
php bin/console doctrine:schema:update --dump-sql

# Execute migration
php bin/console doctrine:schema:update --force

🎣 Usage

Admin Interface

Navigate to Articles in the Sulu admin navigation.
Open an existing article or create a new one.
Click on the Configuration tab.
Select the desired options (e.g., "Enable Sidebar", "Layout Style").
Save the config.

Template Defaults

You can set a configuration as default for all articles with the same template:

Open an article with the desired template (e.g., "Blog Post").
Go to the Configuration tab.
Configure all settings as desired.
Enable "Use as default" in the "Default Configuration" section.
Save the config.

Now all other articles with this template will automatically use these settings - unless they have their own configuration.

How the cascade works:

1. Article has own configuration? → Use it
2. Default config for that template exists? → Use it
3. Neither? → Use default values

Frontend Usage (Twig)

The bundle provides a Twig function to access the resolved configuration in your twig templates:

{# Get configuration #}
{% set articleConfig = article_configuration(uuid, template) %}

{# Or use shortcut/alias #}
{% set articleConfig = article_config(uuid, template) %}

{# Use the configuration values #}
<article class="article article--{{ articleConfig.layoutStyle }}{% if articleConfig.customCssClass %} {{ articleConfig.customCssClass }}{% endif %}">
    
    {% if articleConfig.showReadingTime %}
        <span class="reading-time">{{ reading_time }} min read</span>
    {% endif %}
    
    {% if articleConfig.showToc %}
        <nav class="table-of-contents">
            {# ... TOC content ... #}
        </nav>
    {% endif %}
    
    <div class="article__content">
        {{ content|raw }}
    </div>
    
    {% if articleConfig.showAuthorBox %}
        <div class="author-box">
            {# ... Author info ... #}
        </div>
    {% endif %}
    
    {% if articleConfig.showRelated %}
        <section class="related-articles">
            {# ... Related articles ... #}
        </section>
    {% endif %}
    
    {% if articleConfig.enableShareButtons %}
        <div class="share-buttons">
            {# ... Share buttons ... #}
        </div>
    {% endif %}
    
</article>

{# Check where the config came from #}
{% if articleConfig.configSource == 'template_default' %}
    <!-- Using template default from article {{ articleConfig.templateDefaultArticleId }} -->
{% endif %}

Available configuration values:

Property	Type	Default	Description
`layoutStyle`	string	`'fullwidth'`	`default`, `wide`, `fullwidth`, `narrow`
`enableSidebar`	bool	`true`	Show sidebar
`sidebarPosition`	string	`'right'`	`left`, `right`
`showToc`	bool	`true`	Show table of contents
`showReadingTime`	bool	`true`	Show reading time
`showAuthorBox`	bool	`true`	Show author box
`showRelated`	bool	`true`	Show related articles
`enableShareButtons`	bool	`true`	Show share buttons
`enablePrint`	bool	`true`	Show print button
`hidePublishDate`	bool	`false`	Hide publish date
`customCssClass`	string	`null`	Custom CSS class
`configSource`	string	-	`article`, `template_default`, `hardcoded`

Example: Conditional sidebar layout

{% set articleConfig = article_config(uuid, template) %}

<div class="layout layout--{{ articleConfig.layoutStyle }}">
    {% if articleConfig.enableSidebar %}
        <div class="layout__sidebar layout__sidebar--{{ articleConfig.sidebarPosition }}">
            {% if articleConfig.showToc %}
                {{ render_toc(content) }}
            {% endif %}
        </div>
    {% endif %}
    
    <main class="layout__main">
        {{ content|raw }}
    </main>
</div>

Example: Custom CSS class

{% set articleConfig = article_configuration(article.id, article.templateKey) %}

<header class="article-header{% if articleConfig.customCssClass %} {{ articleConfig.customCssClass }}{% endif %}">
    <h1>{{ article.title }}</h1>
</header>

Resolving an Article's Template by URL

article_configuration/article_config need the article's own templateKey, which is trivial to pass when you are already rendering that article's own page. It is not reachable through Sulu's properties mapping on a smart_content/selection list, though (the field lives in the resource's internal "view" data, which recursivelyMapProperties() never maps) -- for example an "articles" collection field on a page or a different article, where each item is only a title/subtitle/url/image, would always miss it.

article_template_key(url, locale) resolves it from the article's frontend URL instead (via the route table), so it works from exactly that situation. Returns null if the URL does not resolve to a live article.

{% set templateKey = article_template_key(item.url, app.request.locale) %}
{% if templateKey %}
    <span class="badge">{{ templateKey }}</span>
{% endif %}

Combine with your own template-to-color/label mapping (e.g. a project-level color palette) to badge articles by their template in a list -- the bundle only resolves the key, it has no opinion on colors or labels.

⬆️ Upgrading from 1.x

2.0 removes the PDF switches (enableDownloadPdf, pdfShowCaptions, pdfShowAuthor, pdfShowModified, pdfShowOnlineLink, pdfCompanyData) from the "Configuration" tab. They now live in the excerpt tab of the article, provided by manuxi/sulu-pdf-bundle (1.3+) - per language and with the draft/publish workflow:

sulu_pdf:
    excerpt:
        articles: true

Replace articleConfig.enableDownloadPdf in your templates with sulu_pdf_available('articles', uuid, app.request.locale), run bin/adminconsole doctrine:schema:update --force to drop the columns and set the switches again in the excerpt tab.

🗄️ Database Schema

The bundle creates the following table:

CREATE TABLE ar_article_configuration (
    id INT AUTO_INCREMENT PRIMARY KEY,
    article_id VARCHAR(36) UNIQUE NOT NULL,
    template_key VARCHAR(128) DEFAULT NULL,
    is_default TINYINT(1) DEFAULT 0 NOT NULL,
    layout_style VARCHAR(32) DEFAULT 'default' NOT NULL,
    enable_sidebar TINYINT(1) DEFAULT 1 NOT NULL,
    sidebar_position VARCHAR(16) DEFAULT 'right' NOT NULL,
    show_toc TINYINT(1) DEFAULT 1 NOT NULL,
    show_reading_time TINYINT(1) DEFAULT 1 NOT NULL,
    show_author_box TINYINT(1) DEFAULT 1 NOT NULL,
    show_related TINYINT(1) DEFAULT 1 NOT NULL,
    enable_share_buttons TINYINT(1) DEFAULT 1 NOT NULL,
    enable_print TINYINT(1) DEFAULT 1 NOT NULL,
    hide_publish_date TINYINT(1) DEFAULT 0 NOT NULL,
    custom_css_class VARCHAR(128) DEFAULT NULL,
    INDEX idx_template_default (template_key, is_default)
);

🧪 Testing

composer test

📄 License

This bundle is under the MIT license. See the complete license in the bundle: LICENSE

👤 Author

Manuel Bertrams

GitHub: @manuxi

manuxi / sulu-article-configuration-bundle

Package info

Security

Statistics