Entwicklerinformationen

Visual CMS lässt sich durch das Hinzufügen weiterer Widgets erweitern.

Der Editor erstellt aus allen Widgets Shortcodes (ähnlich wie BBCode) und speichert diese als Inhalt ab. Im Frontend werden die Shortcodes wieder geparst und die entsprechenden Klassen angestoßen.

Auch die Verwendung von eigenen Frontend-Gridsystemen ist möglich. Im Standard verwendet das Modul im Frontend eine abgespeckte Version des Bootstrap Gridsystems.

Theme Integration

Das Modul ist komplett kompatibel zum Azure-Theme, zu Flow und zu RoxIVE. Für andere Themes sind eventuell kleinere Anpassungen nötig.

Inhaltsseiten

Die beiden Dateien content.tpl und content_plain.tpl müssen bei Bedarf um zwei Abfragen erweitert werden (s. Smarty Kommentar innerhalb des Quellcodes: „Anpassung:…“):

content.tpl

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

    [{* Anpassung: Überprüfung der Anzeige der Überschrift *}]
    [{if !$oContent->oxcontents__ddhidetitle->value}]
        <h1 class="pageHead">[{$oView->getTitle()}]</h1>
    [{/if}]

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

[{* Anpassung: Überprüfung der Anzeige der Sidebar *}]
[{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()}]

    [{* Anpassung: Überprüfung der Anzeige der Überschrift *}]
    [{if !$oContent->oxcontents__ddhidetitle->value}]
        <h1 class="pageHead">[{$oView->getTitle()}]</h1>
    [{/if}]

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

Ein eigenes Widget erstellen

Widgets können durch das Erstellen von Shortcode-Klassen erstellt werden. Diese Klassen müssen zu einem der folgenden Verzeichnisse hinzugefügt werden:

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

Note

Die jeweiligen Module müssen aktiv sein und der Dateiname ist zugleich auch der Klassen-Prefix.

Folgender Namespace wird immer benötigt:

use OxidEsales\VisualCmsModule\Application\Model\VisualEditorShortcode;

Für das folgende Beispiel, werden noch diese Namespaces benötigt:

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;

Eine Shortcode-Klasse ist folgendermaßen aufgebaut:

class article_shortcode extends VisualEditorShortcode
{

Der Klassenname besteht aus Dateiname (ohne Endung) und dem Suffix „_shortcode“.
Die Klasse sollte sich immer von der Klasse VisualEditorShortcode ableiten, damit Standard-Eigenschaften und Methoden übernommen werden.

Eigenschaften

Als nächstes können Eigenschaften festgelegt werden:

protected $_sTitle = 'DD_VISUAL_EDITOR_SHORTCODE_ARTICLE';
protected $_sBackgroundColor = '#e74c3c';
protected $_sIcon = 'fa-newspaper-o';

$_sTitle: Bezeichnung des Widgets (Lang-String)
$_sBackgroundColor: Farbe des Widgets im Administrationsbereich
$_sIcon: CSS-Klasse für das Icon des Widgets im Administrationsbereich (s. http://fontawesome.io/icons/)
$_sShortCode: Shortcode-Name
$_aOptions: Beinhaltet die Widget-Optionen

Note

Alle Eigenschaften können auch durch Set-Methoden gesetzt werden (Bsp.: setShortCode())

install()-Methode

Die install()-Methode wird beim Initialisieren der Widgets im Administrationsbereich aufgerufen.
Die Shortcode-Klassen erben von der OXID-Klasse FrontendController (oxUBase in OXID v5), somit stehen OXID-Klassen und -Methoden zur Verfügung.
In diesem Beispiel wird der Dateiname (ohne Endung) als Shortcode-Name gesetzt.
Anschließend werden die Widget-Optionen bzw. -Eingabefelder im Administrationsbereich gesetzt.

public function install()
{
    $this->setShortCode( basename( __FILE__, '.php' ) );

    $oLang = Registry::getLang();

    $this->setOptions(
        array(
            'id' => array(
                // Legt eine Methode fest, welche bei einer Livesuche angesprochen wird
                'data' => 'searchArticle',
                // Mögliche Typen: select, text, color, file, multi, textarea, wysiwyg, hidden
                'type' => 'select',
                // Label Bezeichnung
                'label' => $oLang->translateString( 'DD_VISUAL_EDITOR_WIDGET_ARTICLE' ),
                // 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' => array(
                    // Das Feld "name" bekommt den Rückgabewert "label" der Livesuche zugewiesen
                    'name' => 'label'
                )

            ),
            'name' => array(
                // Verstecktes Feld
                'type' => 'hidden',
                // Der Wert wird zur Vorschau in der Widget Auflistung verwendet
                'preview' => true
            )
        )
    );
}

parse()-Methode

Die parse()-Methode wird ausgeführt, wenn der Shortcode im Frontend ausgelesen wird.
Der Parameter $sContent ist reserviert für die Widget-Option content.
Alle weiteren Werte werden im Array des zweiten Parameters übergeben.
In diesem Beispiel wird anhand der Artikel-ID der Artikel geladen und anschließend an die Smarty-Funktion oxid_include_widget weitergegeben, um ein Artikel-Widget anzuzeigen.
Der Return-Wert entspricht dem ausgelieferten Inhalt an das Frontend.

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

Alternativ kann man, statt den Inhalt direkt auszugeben, ein Smarty-Template aufrufen:

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;
}

Die beiden Methoden und oben genannten Eigenschaften reichen aus, um ein Widget bzw. Shortcode zu erstellen. Alles Weitere hängt von der Komplexität der Widgets ab.

Note

Alle mitgelieferten Widgets liegen quelloffen im Modulordner von VisualCMS unter Core/shortcodes und können als Beispiele genutzt werden.

Eigenes Gridsystem

Um ein eigenes Gridsystem zu verwenden sind nur einige Einstellungen notwendig.

Navigieren Sie im OXID eShop Administrationsbereich zu Erweiterungen ‣ Module ‣ Visual CMS ‣ Einstell.
Das Kontrollkästchen Eigenes Gridsystem verwenden unter dem Punkt Frontend anhaken
CSS-Klassen Prefixe für Ihr Gridsystem eintragen
Anzahl der max. Spalten des Gridsystems eintragen
Speichern

Danach lassen sich Offsets und Spaltenbreiten nicht mehr per Designeinstellungen des Widgets anpassen, sondern müssen per Drag & Drop auf der CMS-Seite vorgenommen werden. Siehe auch unter Positionierung von Widgets.

Beispiele

Foundation

960 Gridsystem

Note

Das Gridsystem Ihrer Wahl muss im Theme eingebunden sein.

Widget-Modul Migration von OXID eShop 5.x auf 6.x

Alle Moduldateien müssen UTF-8 encodiert sein.
Code muss mit PHP 5.6 oder höher funktionieren.
Folgender Namespace muss ab sofort zusätzlich in Modulen angegeben werden:

use OxidEsales\VisualCmsModule\Application\Model\VisualEditorShortcode;

Note

Widgets selbst dürfen keinem Namespace zugeordnet werden!

Damit Standard-Eigenschaften und Methoden übernommen werden können, wird die Klasse ab sofort nicht mehr von ddvisualeditor_shortcode, sondern von VisualEditorShortcode abgeleitet.

class eigener_shortcode extends VisualEditorShortcode