Developer Information

Important

The English version of this Visual CMS documentation serves only as a basis and for developers and does not contain all details. More comprehensive documentation can be found in the German documentation.

The Visual CMS can be extended by adding further widgets.

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

Theme Integration

The Visual CMS shortcode widgets currently supplied are compatible with the APEX theme. For other themes, minor adjustments may be necessary.

The following information refers to the Twig template engine.

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" %}

More information about Twig in modules can be found here in the developer documentation.

Widget Creation

In case of creating your own shortcode, make sure the one:

  • Registered in the services.yaml as a separate service

  • Has a shortcode special tag in service description: ‘visualcms.shortcode.tag.twig’

  • Implements the OxidEsales\VisualCmsModule\ShortCode\ShortCodeInterface

  • Has unique value set for shortCodeTag of shortcode Metadata - the identifier of the shortcode, like “carousel”, “image”, “hero”. You can check example shortcode GoogleMap in vcms-example repository.

OxidEsales\VcmsExamples\ShortCode\GoogleMap:
  class: OxidEsales\VcmsExamples\ShortCode\GoogleMap
  tags: [ 'visualcms.shortcode.tag.twig' ]

BaseShortCode usage

The BaseShortCode abstract class provides basic implementation of some OxidEsales\VisualCmsModule\ShortCode\ShortCodeInterface methods.

ShortCodeInterface interface

The interface implementation is a requirement for your shortcode to work with the VisualCms module.

  • public function getMetadata(): ShortCodeMetadataInterface;

    The method should return main information about your shortcode. The ShortCodeMetadataInterface implemented object should be returned. The OxidEsales\VisualCmsModule\DataType\ShortCodeMetadata class can be used.

  • public function getTemplate(): string;

    The pointer(path) to the shortcode template. Make sure you are using your module id in the path, like used in one of our examples: @ddoevisualcms/shortcodes/visualcms_shortcode_tabs

  • public function getOptions(): OptionList;

    List of options wrapped in OxidEsales\VisualCmsModule\DataType\OptionList object. The OptionList ensures options array have more standard contents, and will not allow to break everything through simple missconfiguration.

    Example:

    public function getOptions(): OptionList
{
    $shopLanguage = Registry::getLang();

    return new OptionList([
        'id' => new SelectFromDataOption(
            // Label name
            label: $shopLanguage->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE'),
            // Specifies a method which will be used for a live search
            data: 'searchArticle',
            // placeholder name
            placeholder: $shopLanguage->translateString('DD_VISUAL_EDITOR_WIDGET_CHOOSE_ARTICLE'),
            // fields that are also taken into account for a selection (only for type "select")
            dataFields: ['name' => 'label']
        ),
        'articletype' => new SelectOption(
            label: $shopLanguage->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE'),
            values: [
                'grid' => $shopLanguage->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE_GRID'),
                'line' => $shopLanguage->translateString('DD_VISUAL_EDITOR_WIDGET_ARTICLE_TYPE_LINE'),
            ],
            defaultValue: 'grid'
        ),
        'name' => new HiddenOption()
    ]);
}

    Note

    Please note, the OptionList() class consumes the array of OxidEsales\\VisualCmsModule\\Option\\ShortCodeOptionInterface objects. Our currently provided options should cover most of the cases you may need to configure your widgets. If not, feel free adding your own Options, and using them directly in your shortcode initialization.

  • public function prepareTemplateParams(GridItemInterface $gridItem): array;

    This method is the entry point for your imagination and the place where you can prepare variables for your shortcode template. The result of this method is “extracted” as variables for your widget template. Read more in next sections.

ShortCodeMetadataInterface interface

The ShortCodeMetadata class takes those parameters during object creation:

  • shortCodeTag

    Short-code tag - the identifier of the shortcode, like “carousel”, “image”, “hero”. This one should be unique.

  • isWidget

    Boolean - Can this shortcode be directly included into the content or not? (in other words - is there a button for this shortcode?)

  • title

    Title of the widget (Lang-String)

  • previewOptionKey

    Special attribute which describes which Option data will be used for a preview text in the content grid admin interface for this widget. As a value, Option key should be set here, ex: we have “content” option in the Text widget, so values for that option are shown in the grid.

  • backgroundColor

    Color of the widget in the content grid admin interface (html format, like ‘#ccbbaa’)

  • icon

    CSS-class for the icon of the widget in the back end (s. http://fontawesome.io/icons/)

Example:

public function getMetadata(): ShortCodeMetadataInterface
{
    return new ShortCodeMetadata(
        shortCodeTag: 'text',
        isWidget: true,
        title: 'DD_VISUAL_EDITOR_SHORTCODE_TEXT',
        previewOptionKey: 'content',
        backgroundColor: '#3498db',
        icon: 'fa-align-left'
    );
}

prepareTemplateParams()-Method

The following describes the general process for all widgets, but using Text widget code as example.

When saving a CMS content in the administration area, every widget’s layout configuration and structure is saved in the ddoevisualcms_tree_nodes table in JSON format. The individual options data of each widget is stored in the ddoevisualcms_shortcode_data table as JSON as well. Also, a hook for widget tree rendering is added to the oxcontent field of oxcontents table. On page loading, the custom Twig function vetree then triggers nested rendering of configured widgets tree.

  • The prepareTemplateParams() method is executed for every widget before rendering, and the result is extracted to template as variables.

  • You can access this widget’s option values from the $gridItem object.

public function prepareTemplateParams(GridItemInterface $gridItem): array
{
    $params = parent::prepareTemplateParams($gridItem);

    // TODO: Remove duplication for Text, Hero and Column shortcodes
    if (!empty($params['background_image'])) {
        $params['background_image'] = $this->mediaService->getUrlByMediaPath($params['background_image']);
    }

    if (!empty($params['content'])) {
        $params['content'] = $this->templateRenderer->renderFragment($params['content'], md5($params['content']));
    }

    return $params;
}

{"content":"some example text","background_color":"#ef9d9dff","background_image":"237-536x354.jpg","background_fixed":"","fullwidth":"","class":""}

When rendering process is triggered, the prepareTemplateParams method is triggered and you can get widget’s configured option values $gridItem->getShortCodeConfiguration()->getOptionValues().

The data will be already available as an array:

[
    'content' => "some  example text",
    'background_color' => "#ef9d9dff",
    'background_image' => "237-536x354.jpg",
    'background_fixed' => "",
    'fullwidth' => "",
    'class' => ""
]

You will notice, that in the template you usually have some more variables available: * shortcode - calculated by the BaseShortCode if you are extending one * calculatedClasses - calculated by the ColumnLayoutTemplateParamsDecorator * oView and oViewConf - added with the ViewInformationTemplateParamsDecorator

Feel free to decorate the current widgets with additional logic.

The result array will be given to the shortcode template, and the data will be accessible as regular template variables.

Services

The information can be used, for example, in the text widget template to include user information or to respond to previous user actions. It is also possible to inject services in the shortcodes:

public function __construct(
    protected \OxidEsales\VisualCmsModule\Service\Categories $categoriesService
) {
}

The information above should be enough to create a shortcode widget. Everything else depends on the complexity of the widget.

Note

All currently existing widgets are in the src/ShortCodeCollection/ShortCode folder of VisualCMS. We also have a vcms-examples module which contains examples of how to add more widgets and extending the current ones. These can be used as examples.

Override a existing shortcode

If you want to override a existing shortcode then below is example in which we override the Text shortcode and added a additional field Heading given at vcms-example repository.

OxidEsales\VisualCmsModule\ShortCode\Text:
  class: OxidEsales\VcmsExamples\ShortCode\Text
  tags: [ 'visualcms.shortcode.tag.twig' ]

Extending the shortcode

As “Overriding” could be used for extending the shortcode too, the recommended way to be used for extending shortcodes - service decoration!

The concrete example with shortcode decoration can be found in our Examples module.

Also make sure you register your drecorator:

OxidEsales\VcmsExamples\DecorationExample:
  decorates: OxidEsales\VisualCmsModule\ShortCodeCollection\ShortCode\Action\Action
  arguments: ['@.inner']

Override a shortcode template

If you only want to override a template for a shortcode then below is example given at vcms-example repository.

vcmsTemplateOverrideForApexTheme:
  class: OxidEsales\VisualCmsModule\DataType\ThemeTemplatesConfiguration
  arguments:
    $themeId: 'apex'
    $templates:
      column: '@@oe_vcmsexamples/shortcodes/vcmsexamples_shortcode_column'
      action: '@@oe_vcmsexamples/some_other_template_for_overwriting_the_original_action_template_for_apex'
  tags: [ 'shortcode.themeTemplates' ]

Frontend-Grid

The shortcode Layout configuration settings are also available through the GridItemInterface, please use the getLayoutConfiguration() method.

See also the Module configuration in the German documentation.

Custom Grid System

Attention

The setting for “Custom Grid System” no longer has a function and is only included in the menu for compatibility reasons. Its function has been replaced by Frontend-Grid. See above.