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 front end 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

The module is completely compatible with Azure, Flow and with RoxIVE themes. For other themes, minor adaptations might be necessary.

Content Pages

When needed, the two themes content.tpl and content_plain.tpl must be extended by two requests:

content.tpl

[{capture append="oxidBlock_content"}]
    [{assign var="oContent" value=$oView->getContent()}]
    [{assign var="tpl" value=$oViewConf->getActTplName()}]
    [{assign var="oxloadid" value=$oViewConf->getActContentLoadId()}]

    [{* Customisation: Check the display of the heading *}]
    [{if !$oContent->oxcontents__ddhidetitle->value}]
        <h1 class="pageHead">[{$oView->getTitle()}]</h1>
    [{/if}]

    <div class="cmsContent">
        [{$oView->getParsedContent()}]
    </div>
[{/capture}]

[{* Customisation: check the display of the side bar *}]
[{if $oContent->oxcontents__ddhidesidebar->value}]
    [{include file="layout/page.tpl"}]
[{else}]
    [{include file="layout/page.tpl" sidebar="Left"}]
[{/if}]

content_plain.tpl

[{capture append="oxidBlock_content"}]
    [{assign var="oContent" value=$oView->getContent()}]
    [{assign var="tpl" value=$oViewConf->getActTplName()}]
    [{assign var="oxloadid" value=$oViewConf->getActContentLoadId()}]

    [{* Customisation: Check the display of the heading *}]
    [{if !$oContent->oxcontents__ddhidetitle->value}]
        <h1 class="pageHead">[{$oView->getTitle()}]</h1>
    [{/if}]

    [{$oView->getParsedContent()}]
[{/capture}]
[{include file="layout/popup.tpl"}]

Widget Creation

Widgets can be created through the creation of short-code classes. The classes must be added to one of the following directories:

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

Following Namespace is always needed:

use OxidEsales\VisualCmsModule\Application\Model\VisualEditorShortcode;

In the following Example, these Namespaces are also needed:

use OxidEsales\Eshop\Core\Registry;
use OxidEsales\Eshop\Core\DatabaseProvider;
use OxidEsales\Eshop\Application\Component\Widget\ArticleBox;
use OxidEsales\Eshop\Application\Model\Article;
use OxidEsales\Eshop\Application\Model\ArticleList;

A short-code class is structured as follows:

class article_shortcode extends VisualEditorShortcode
{
  • The class name consists of a file name (without a file extension) and the suffix “_shortcode”.
  • The class should always extend the class VisualEditorShortcode, so that standard attributes and methods are made available.

Attributes

Next, attributes can be defined:

protected $_sTitle = 'DD_VISUAL_EDITOR_SHORTCODE_ARTICLE';
protected $_sBackgroundColor = '#e74c3c';
protected $_sIcon = 'fa-newspaper-o';
  • $_sTitle: Title of the widget (Lang-String)
  • $_sBackgroundColor: Color of the widget in the back end
  • $_sIcon: CSS-class for the icon of the widget in the back end (s. http://fontawesome.io/icons/)
  • $_sShortCode: Short-code name
  • $_aOptions: contains the widget options

install()-Method

  • The install() method is called by the back end to initialize the widget.
  • The short-code classes extend the OXID class FrontendController (oxUBase in OXID v5). OXID classes and methods are therefore available.
  • In this example, the file name (without file extension) is set as short-code name.
  • Subsequently, the widget options and entry fields are set in the back end.
public function install()
{
    $this->setShortCode( basename( __FILE__, '.php' ) );

    $oLang = Registry::getLang();

    $this->setOptions(
        array(
            'id' => array(
                // specifies the method used in live search
                'data' => 'searchArticle',
                // possible types: select, text, color, file, multi, textarea, wysiwyg, hidden
                'type' => 'select',
                // Label Description
                'label' => $oLang->translateString( 'DD_VISUAL_EDITOR_WIDGET_ARTICLE' ),
                // placeholder description
                'placeholder' => $oLang->translateString( 'DD_VISUAL_EDITOR_WIDGET_CHOOSE_ARTICLE' ),
                // fields which also be considered in a selection (only type "select")
                'dataFields' => array(
                    // the field "name" returns value "label" to the live search
                    'name' => 'label'
                )

            ),
            'name' => array(
                // hidden field
                'type' => 'hidden',
                // the value is used in previews of widget listings
                'preview' => true
            )
        )
    );
}

parse()-Method

  • The parse() method is called when the short-code is parsed in the front end.
  • The parameter $sContent is a reserved parameter of the widget option content.
  • All other values are passed as an array in the second parameter.
  • In this example, products are loaded using the product ID and subsequently passed to the Smarty function oxid_include_widget so that a product widget is displayed.
  • The return value corresponds to the content delivered to the front end.
public function parse( $sContent = '', $aParams = array() )
{
    /** @var Article $oArticle */
    $oArticle = oxNew( Article::class );
    $oArticle->load( $aParams[ 'id' ] );

    $sOutput = '<div class="dd-shortcode-' . $this->getShortCode() . ' productData productBox' . ( $aParams[ 'class' ] ? ' ' . $aParams[ 'class' ] : '' ) . '">';
    $sOutput .= '[{oxid_include_widget cl="oxwArticleBox" _parent=$oView->getClassName() _navurlparams=$oViewConf->getNavUrlParams() anid="' . $aParams[ 'id' ] . '" isVatIncluded=$oView->isVatIncluded() nocookie=1 sWidgetType=product sListType="listitem_' . $sType . '" inlist=1 skipESIforUser=1}]';
    $sOutput .= '</div>';

    return $sOutput;
}

Alternative: Smarty Template

Alternatively, a Smarty template can be called instead of delivering the content directly:

public function parse( $sContent = '', $aParams = array() )
{
    /** @var Article $oArticle */
    $oArticle = oxNew( Article::class );
    $oArticle->load( $aParams[ 'id' ] );

    $oSmarty = Registry::get( 'oxUtilsView' )->getSmarty();
    $oSmarty->assign(
        array(
            'oView'     => $this->getConfig()->getTopActiveView(),
            'shortcode' => $this->getShortCode(),
        )
    );
    $sOutput .= $oSmarty->fetch( 'ddoe_widget_article.tpl' );
    return $sOutput;
}

The two methods and the attributes mentioned above are all that is needed in order to create a widget or short-code. All else depends on the complexity of the widget.

Note

All provided widgets in the module folder of VisualCMS under Core/shortcodes are open source 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.

  1. Please navigate in the admin area of the eShop to Extensions ‣ Modules ‣ Visual CMS ‣ Settings
  2. Activate the checkbox Use custom grid. This checkbox is located under the point Front end
  3. Enter the prefixes of CSS-classes for your grid system
  4. Enter the maximum number of columns of the grid system
  5. 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.

Widget-Modul Migration from OXID eShop 5.x to 6.x

  • All module files have to be UTF-8 encoded.
  • Code must work with PHP 5.6 or higher.
  • The following namespace must also be specified in modules from now on:
use OxidEsales\VisualCmsModule\Application\Model\VisualEditorShortcode;

Note

Widgets may not be assigned to a namespace!

  • So that standard attributes and methods can be adopted, the class is no longer derived from ddvisualeditor_shortcode, but from VisualEditorShortcode.
class own_shortcode extends VisualEditorShortcode