EinenBlockSchreiben

Guite edited this page Nov 12, 2014 · 5 revisions

Einen Block schreiben

Dieses Tutorial deckt eine Einführung in das Zikula Block System ab und wie man einen einfachen Block erstellt. Quelle: Übersetzt aus dem englischen Wiki Writing a block

Einleitung

Ein Block besteht aus einem php file und, abhängig der Notwendigkeit einer "custom block configuration", einen oder zwei template files. Ein Block muss mit einem Modul verknüpft sein. Bevor du beginnst einen Block zu schreiben, denke zunächst über folgende Informationen nach

  • Das Modul mit welchem der Block verknüpft sein soll
  • Einen einzigartigen Identifizierer, innerhalb des Anwendungsbereiches des Modules, für diesen Block. Bekannt als 'block key' oder 'bkey'
  • Ob dein Modul ein template benötigt um "custom settings" zu definieren

Die Dateistruktur des Blocks erstellen

Nachdem die Infos des vorigen Absatz klargestellt hast kann nun die "basic file structure" definiert werden. Die files die du benötigst sind:

modules/<module>/pnblocks/<bkey>.php
modules/<module>/pntemplates/<module>_<bkey>.htm
modules/<module>/pntemplates/<module>_<bkey>_modify.htm falls dein Block ein template für die 'custom settings' benötigt

Das php file erstellen

Das php file des Blockes beinhaltet einige Funktionen, welche dem Zikula Core über den Block informieren, wie der Block dargestellt wird und wie mit sämtlichen 'custom settings' des Blockes umgegangen wird. Diese Funktionen sind:

<module>_<bkey>block_init
<module>_<bkey>block_info
<module>_<bkey>block_display
<module>_<bkey>block_modify falls der Block ein template für die custom settings benötigt.
<module>_<bkey>block_update falls der Block ein template für die custom settings benötigt.

Den php Code schreiben

init Funktion

_block_init

Der Zweck dieser Funktion ist es den Zikula Core über das Zugriffsrechte-Schema, welches der Block benutzt, wissen zu lassen. Es ist üblich, dass der 'block key' und der Blocktitel dazu genutzt werden.

function <module>_<bkey>block_init()
{
    pnSecAddSchema('<module>:<bkey>block:', 'Block title::');
}

info Funktion

_block_info

Der Zweck dieser Funktion ist es dem Block-Modul Informationen über diesen Block mitzuteilen. Diese Information wird dann vom Block-Modul benutzt sein Verhalten zu ändern wenn der Blöcke erstellt und editiert werden.

function <module>_<bkey>block_info()
{
    return array('text_type'        => '<bkey>',
                 'module'           => '<module>',
                 'text_type_long'   => '<text description of the block>',
                 'allow_multiple'   => <boolean - true or false>,
                 'form_content'     => <boolean - true or false>,
                 'form_refresh'     => <boolean - true or false>,
                 'show_preview'     => <boolean - true or false>,
                 'admin_tableless'  => <boolean - true or false>);
}

Der Nutzen jedes Wertes ist:

  • text_type - Der Typ des Blockes. Setzte dies als 'block key'
  • module - Das Modul zu dem der Block gehört
  • text_type_long - Eine Beschreibung des Zwecks des Blocks
  • allow_multiple - Mehrere Instanzen des Blocks erlauben
  • form_content - Ein Textfeld anzeigen, welches einen direkten Zugriff zum 'content' Feld des Blocks erlaubt. Dieser Wert ist abhängig von der Beschaffenheit des Blockes.
  • form_refresh - Die Block 'refresh value' nutzen. Dies ist sinnvoll für Blöcke die Daten von externen Quellen nutzen.
  • show_preview - <editieren.. weiss nicht was das bringt, falls überhaupt etwas>
  • admin_tableless - Dem Block Modul mitteilen, dass das 'modify template' neue Tabellenlosse Formmethode nutzt.

display Funktion

_block_display

Diese Funktion erstellt den 'output' welchen der User sieht im Block. Der Code dieser Funktion ist sehr abhängig davon welchem Zweck der Block dienen soll. Wie auch immer gibt es einige Standardinhalte, welche diese Funktion ausmachen.

function <module>_<bkey>block_display($blockinfo)
{
    // Security check (1)
    if (SecurityUtil::checkPermission('<module>:<bkey>block:', "$blockinfo[title]::", ACCESS_READ)) {
        return false;
    }

    // Check if the module is available. (2)
    if (!pnModAvailable('<module>')) {
        return false;
    }

    // Get variables from content block (3)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // Defaults (4)
    if (empty($vars['<yourvar>'])) {
        $vars['<yourvar>'] = <your default value for this var>;
    }

    // if your block need access to the modules pntables (5)
    pnModDBInfoLoad('<module>');

    // if your block uses special localisation (6)
    pnModLangLoad('<module>');

    // ..........hier deinen eigenen Blockcode einfügen.......... (7)

    // Create output object (8)
    $pnRender = pnRender::getInstance('<module>');

    // assign your data to to the template (9)
    $pnRender->assign(....., ......);
    $pnRender->assign(....., ......);

    // Populate block info and pass to theme (10)
    $blockinfo['content'] = $pnRender->fetch('<module>_block_<bkey<.htm');

    return themesideblock($blockinfo); (11)
}

Dieser Block-Code zeigt ein Beispiel, welches für die meisten Blöcke benötigt wird, wenn auch nicht für alle Blöcke.

  • Einen Sicherheits-Check ob der gegenwärtige Benutzer auf den Block zugreifen darf
  • Einen Check, ob das Modul mit dem der Block verknüft ist existiert
  • Jegliche Block Variablen bestimmen - dieser Code ist nur nötig wenn dein Block irgendwelche 'custom block'-Variablen nutzt
  • Definiert die 'defaults' für irgendwelche Block Variablen - wieder nicht nötig wenn dein Block solche nicht nutzt.
  • Einen Verweis, dass der Block auf die pntables des betreffenden Modules zugreifen soll. Er könnte auch auf andere Module zugreifen.
  • Einen Verweis, die Sprach-Lokalisation des Modules zu laden.
  • DEINEM CODE
  • Ein neues 'output'-Objekt erschaffen um den 'block output' zu übergeben
  • Irgendwelche template Variablen abtreten.
  • Den 'output' vom template holen.
  • Den 'block output' zurück zum Core schaffen um diese in irgendein 'theme block template' einzupacken.

Obwohl der Block zu einem Modul gehört kann dieser jederzeit angezeigt werden, auch wenn andere Module aktiv sind. In diesem Fall werden die Modul-stylesheets nicht geladen und der 'block output' wird ohne die speziell für das Modul designte css übergeben.

Um das zu umgehen kannst du ab Postnuke .8 folgenden Code einfügen

// insert directly after step 6
PageUtil::addVar('stylesheet', ThemeUtil::getModuleStylesheet('<module>'));

modify Funktion

_block_modify

Diese Funktion wird vom Block Modul aufgerufen, falls der Block irgendwelche 'custom block' Variablen hat. Die Antwort dieser Funktion ist ein Teil einer Forum, welche nur die benötigten 'Kontrollen' beinhaltet die 'custom block' Variablen zu editieren. Der 'output' dieser Funktion wird in die 'standard block modify' Form eingefügt. Der PHP code dieser Funktion wird so in etwa ausehen:

function <module>_<bkey>block_modify($blockinfo)
{
    // Get current content (1)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // Defaults (2)
    if (empty($vars['<yourvar>'])) {
        $vars['<yourvar>'] = <your default value>;
    }

    // Create output object (3)
    $pnRender = new pnRender('<module>', false);

    // assign all block variables (4)
    $pnRender->assign($vars);

    // Return the output that has been generated by this function (5)
    return $pnRender->fetch('<module>_block_<bkey>_modify.htm');
}
  • Sämtliche momentanen Block Variablen Einstellungen holen
  • 'default' Werte für die Block Variablen setzten welche noch nicht gesetzt
  • Ein neues 'output'-Objekt erstellen mit 'caching turned off'
  • Sämtliche Blockvariablen dem template übergeben
  • Den 'output' zurückgeben welcher vom template erstellt wurde zum Block Modul

Das HTML template wird, abhängig von der Nummer der Variablen und dem Typ der benötigten 'form controll' in etwa so wie dieser folgende Code aussehen. In diesem Beispiel wird eine einfache Textbox für eine Block Variable erstellt.

<div class="pn-adminformrow">
    <label for="<module>_<variable_name>"><!--[pnml name="_A_TEXT_LABEL"]--></label>
    <input id="<module>_<variable_name>" type="text" name="<var>" value="<!--[$<var>pnvarprephtmldisplay]-->" size="5" maxlength="5" />
</div>

update Funktion

_block_update

Diese Funktion wird aufgerufen wenn der Seiten Administrator einen Block diesen Typs updatet. Diese Funktion liest und speichert Werte für die 'form controls' welche von der 'modify'-Funktion erstellt wurden. Der php code dieser Funktion sieht etwa so aus:

function <module>_<bkey>block_update($blockinfo)
{
    // Get current content (1)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // alter the corresponding variable (2)
    $vars['<your var>'] = FormUtil::getPassedValue('<your var>', <your default value>, 'POST');

    // write back the new contents (3)
    $blockinfo['content'] = pnBlockVarsToContent($vars);

    // clear the block cache (4)
    $pnRender = new pnRender('<module>');
    $pnRender->clear_cache('<module>_block_<bkey>.htm');

    return $blockinfo; (5)
}

Der obige Code führt folgende Funktionen aus:

  • Die momentan definierten Block Variablen holen
  • Die erhaltenen 'form'-Werte lesen vom 'Post'-array und einen 'default' definieren.
  • Die neuen Variablen zurück zum Block-Inhalt-Feld schreiben.
  • Einen neuen 'output' erschaffen und sämtliche 'cached pages' diesen Blockes löschen.
  • Den modifizierten 'blockinfo'-array zurückgeben zum Block Modul für spätere Verwendung.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.