Proposal for Documentation Improvement: Configuration of Article Types

[Stolidbug]

Q	A
Bug?	no
New Feature?	no
SuluArticleBundle Version	2.6.3

Actual Behavior

In the current documentation of the SuluArticleBundle, there is a lack of detailed guidance regarding the configuration required when creating a new article type. Specifically, the necessity of creating a corresponding XML file and configuring it is not adequately covered. This omission might confuse developers, especially those new to Sulu or the ArticleBundle, as it is a crucial step to ensure proper functionality.

Expected Behavior

The documentation should include a section titled Configuration of Article Types that provides detailed, step-by-step instructions to configure a new article type, including the creation of an XML file and updating the necessary configurations. This will help developers understand the process more clearly and avoid common pitfalls.

Steps to Reproduce

1. Follow the current documentation to create a new article type.
2. Observe that the necessity of creating an XML file and the corresponding configurations is not mentioned.
3. Attempt to use the new article type without the XML configuration and experience issues with recognition or rendering.

Possible Solutions

Add the following section to the documentation:

Configuration of Article Types

When creating a new article type, for example, my_article_type, it is crucial to properly configure a corresponding template file. This file is necessary for Sulu to recognize and render the new article type correctly.

Step 1: Create the XML File

You need to create a specific XML file in the config/templates/articles/ directory. The filename must match the identifier of your article type, followed by the .xml extension. For instance, for an article type named my_article_type, create a file named:

config/templates/articles/my_article_type.xml

Step 2: Minimal Content of the XML File

Below is an example of minimal content for the XML file:

<?xml version="1.0"?>
<template xmlns="http://schemas.sulu.io/template/template"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">

    <key>my_article_type</key>
    <view>articles/my-article-type</view>
    <controller>Sulu\Bundle\ArticleBundle\Controller\ArticleController::indexAction</controller>
    
    <meta>
        <title lang="en">my-article-type</title>
        <title lang="fr">my-article-type</title>
    </meta>
  
    <tag name="sulu_article.type" type="my-article-type"/>

    <properties>
        <property name="title" type="text_line">
            <meta>
                <title>Title</title>
            </meta>
        </property>
    </properties>
</template>

Step 3: Final Configuration and Translations

After creating the XML file, ensure that your new article type is properly declared in config/packages/sulu_article.yaml. Additionally, provide translations for the article type in the Sulu-Admin UI.

Configuration in config/packages/sulu_article.yaml:

sulu_article:
    types:
        my_article_type:
            translation_key: "app.article_types.my_article_type"

Adding Translations:

The translation_key can then be used in your translation files. For example, add the following entry to translations/admin.en.json:

{
    "app.article_types.my_article_type": "My Article Type"
}