Developer Information

The Visual CMS can be extended by adding further widgets.

The editor creates short codes from all widgets (similar to BBCode), which it then saves as content. In the frontend these short codes are parsed again, and the corresponding classes are triggered.

Even the usage of custom grid systems is possible. As default, the module uses a slimmed down version of the Bootstrap grid system.

Theme Integration

Visual CMS is compatible with Wave and apex themes. For other themes, minor adjustments may be necessary.

The following information refers to the Twig template engine. If Smarty is used, this information can be found in the documentation for Visual CMS 3.6.

Content Pages

When needed, the two themes content.html.twig and content_plain.html.twig must be extended by two requests (see comment inside the source code: “Customization: …”):

content.html.twig

{% capture append = "oxidBlock_content" %}
    {% set oContent = oView.getContent() %}
    {% set tpl = oViewConf.getActTplName() %}
    {% set oxloadid = oViewConf.getActContentLoadId() %}
    {% set template_title = oView.getTitle() %}

    <div class="container-xxl">
        {% if not oContent.oxcontents__ddhidetitle.value %}
            <h1>{{ template_title }}</h1>
        {% endif %}
        <article class="cmsContent pb-5">
            {{ oView.getParsedContent()|raw }}
        </article>
    </div>
    {{ insert_tracker({title: template_title}) }}
{% endcapture %}
{% include "layout/page.html.twig" %}

{# Customization: Checking the display of the sidebar #}
{% if sidebar %}
    {% include "layout/page.html.twig" %}
{% else %}
    {% include "layout/page.html.twig" with {sidebar: "Left"} %}
{% endif %}

content_plain.html.twig

{% capture append = "oxidBlock_content" %}
    {% set oContent = oView.getContent() %}
    {% set template_title = oView.getTitle() %}
    {% set tpl = oViewConf.getActTplName() %}
    {% set oxloadid = oViewConf.getActContentLoadId() %}

    {# Customization: Checking the display of the heading #}
    {% if not oContent.oxcontents__ddhidetitle.value %}
        <h1>{{ template_title }}</h1>
    {% endif %}

    {{ oView.getParsedContent() }}
    {{ insert_tracker({title: template_title}) }}
{% endcapture %}
{% include "layout/popup.html.twig" %}

Widget Creation

In your own module, in the services.yaml the shortcode must be made available as follows:

modules/ddoe/visualcms/Core/shortcodes/
modules/*/visualcms/shortcodes/

Following Namespace is always needed:

use OxidEsales\VisualCmsModule\Application\Model\VisualEditorShortcode;

A short-code class is structured as follows:

class Article extends BaseShortCode
{

The class name consists of a file name (without a file extension).
The class should always extend the class BaseShortCode, so that standard attributes and methods are made available.

Attributes

Next, attributes can be defined:

protected string $title = 'DD_VISUAL_EDITOR_SHORTCODE_ARTICLE';
protected string $backgroundColor = '#e74c3c';
protected string $icon = 'fa-newspaper-o';

$title: Title of the widget (Lang-String)
$backgroundColor: Color of the widget in the back end
$icon: CSS-class for the icon of the widget in the back end (s. http://fontawesome.io/icons/)
$shortCode: Short-code name

setInterfaceOptions()-Method

The setInterfaceOptions() method is called when initializing the widgets in the administration area.
Subsequently, the widget options or input fields are set in the administration area.

public function setInterfaceOptions(): void
{
    $oLang = Registry::getLang();

    $this->setOptions([
        'id' => new SelectFromDataOption(
            // Label Bezeichnung
            label: $oLang->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE'),
            // Legt eine Methode fest, welche bei einer Livesuche angesprochen wird
            data: 'searchArticle',
            // Platzhalter Bezeichnung
            placeholder: $oLang->translateString('DD_VISUAL_EDITOR_WIDGET_CHOOSE_ARTICLE'),
            // Felder die bei einer Auswahl ebenfalls berücksichtigt werden (nur bei Typ "select")
            dataFields: ['name' => 'label']
        ),
        'articletype' => new SelectOption(
            label: $oLang->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE'),
            values: [
                'grid' => $oLang->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE_GRID'),
                'line' => $oLang->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE_LINE'),
            ],
            defaultValue: 'grid'
        ),
        'name' => new HiddenOption()
    ]);
}

prepareTemplateParams()-Method

The prepareTemplateParams() method is executed when the shortcode is read in the frontend.
The $content parameter is reserved for the content widget option.
All other values are passed in the array of the second parameter.

public function prepareTemplateParams(string $content, array $params): array
{
    $frontendController = oxNew(FrontendController::class);

    $listType = $frontendController->getListDisplayType();
    $viewConfig = Registry::get('oxViewConfig');

    if (!$params['articletype']) {
        if (Registry::getConfig()->getTopActiveView()->getClassKey() == 'start') {
            if (($sStartType = $viewConfig->getViewThemeParam('sStartPageListDisplayType'))) {
                $listType = $sStartType;
            }
        }
    } else {
        $listType = $params['articletype'];
    }

    $params = array_merge($params, [
        'listType' => $listType
    ]);

    return parent::prepareTemplateParams($content, $params);
}

A text widget configured via the admin is stored in oxcontent as follows:

[text background_color="#875c5c" background_image="vcms_Car_03_Mood_1.png" background_fixed="1" fullwidth="" class=""]some text widget contents[/text].

While parsing this part for the frontend, the BaseShortCode::prepareTemplateParams method is called. It receives the contents of the text widget as $content and other parameters:

array(5) {
    ["background_color"]=>
    string(7) "#875c5c"
    ["background_image"]=>
    string(22) "vcms_Car_03_Mood_1.png"
    ["background_fixed"]=>
    string(1) "1"
    ["fullwidth"]=>
    string(0) ""
    ["class"]=>
    string(0) ""
}

The “shortcode” and “content” keys come from BaseShortCode::prepareTemplateParams.

The information can be used in the text widget template to include user information or respond to previous user actions. It is also possible to include services in the shortcodes, but the BaseShortCode constructor should be called to handle the initialization of the management interface parameters:

public function __construct(
     protected categories $categoriesService
 ) {
     parent::__construct();
 }

The two methods and above properties are enough to create a widget or shortcode. Everything else depends on the complexity of the widget.

… note:: All included widgets are open source in the module folder of VisualCMS under Core/shortcodes and can be used as examples.

Custom Grid System

In order to use your own custom grid system, only a few changes in the settings are necessary.

Please navigate in the admin area of the eShop to Extensions ‣ Modules ‣ Visual CMS ‣ Settings
Activate the checkbox Use custom grid. This checkbox is located under the point Front end
Enter the prefixes of CSS-classes for your grid system
Enter the maximum number of columns of the grid system
Save

After that, offsets and column widths can no longer be adjusted by Layout settings of the widget, but must be made by dragging and dropping them on the CMS page.

Examples

Foundation

960 Grid System

Note

The grid system of your choice has to have been included into the theme.