captcha

[%captcha [ id="<string>" ] %]

Die Funktion "captcha" wird verwendet, um eine Grafik anzuzeigen, welches Text enthält, den der Besucher lesen und in das daneben eingeblendete Eingabefeld eingeben muss. Dies ist eine allgemein gebräuchliche Variante zum Schutz vor Spam.

Der Parameter "id" ist optional. Er kann beispielsweise verwendet werden, wenn eine Beschreibung in einem "label" angezeigt werden soll.

Weitere Hinweise finden Sie auch im Kochbuch für Entwickler, Kapitel "Verwenden eines CAPTCHA".

create

[%create template="<string>" file="<string>" table="<string>" [ where="<string>" ] [ desc="<boolean>" ] [ sort="<string>" ] [ page="<integer>" ] [ entries="<integer>" ] [ titles="<boolean>" ] [ on_new="<string>" ] [ on_edit="<string>" ] [ on_delete="<string>" ] [ on_search="<string>" ] %]

Die Funktion "create" generiert automatisch eine GUI für eine gewählte Datenbank. Voraussetzung ist das Vorhandensein einer gültigen Strukturdatei, welche die Datenbank beschreibt.

Ein Beispiel für eine Funktion, zum Download einer Datei (Argument "on_download"):

<?php 
function myDownload($ARGS)
{
   if ($source = DbBlob::getFileId() === false) {
       return false;
   }
   // Download einer Datei:
   if (preg_match('/\.gz$/', $source)) {
       $dbBlob = new DbBlob($source);
       $dbBlob->read();
       header('Content-Disposition: attachment; filename=' . $dbBlob->getPath());
       header('Content-Length: ' . $dbBlob->getFilesize());
       header('Content-type: ' . $dbBlob->getMimeType());
       print $dbBlob->get();
       // Download einer Grafik:
   } else {
       $image = new Image($source);
       $image->outputToScreen();
   }
   exit;
}
?>

Achtung! Diese Funktion prüft nicht automatisch, ob der Nutzer die ausgewählte Datei im Sinne der Semantik Ihres Programms herunterladen "darf". Dies ist leider auch gar nicht möglich, ohne die Kriterien zu kennen, welche Sie innerhalb Ihres Programms dafür anwenden. Daher bleibt es an dieser Stelle Ihnen überlassen zu verifizieren, dass der Benutzer die notwendige Berechtigung besitzt, um die gewünschte Datei einzusehen.

embeddedTags

[%embeddedTags [ show="<string>" ]  [ hide="<string>" ] %]

Die Funktion "embeddedTags" generiert automatisch eine Schaltflächen, mit denen der Gast Ihrer Webseite beim Schreiben eines neuen Eintrags Text formatieren kann (fett, kursiv, etc.).

Die Liste "show" kann verwendet werden, um Tags festzulegen, welche angezeigt werden sollen und die Liste "hide" kann man benutzen, wenn Sie möchten, dass ganz bestimmte Tags nicht dargestellt werden.

Sie können in der Liste "show" mit dem Zeichen "-" Zeilenumbrüche und mit dem Zeichen "|" Trennstriche in die Ausgabe einfügen.

<!-- Alle Tags einblenden -->
[%embeddedTags%]
<!-- Die Tags "u", "i" und "b" einblenden -->
[%embeddedTags show="b,u,i"%]
<!-- Alle Tags außer "url" und "mail" einblenden -->
[%embeddedTags hide="url,mail"%]
<!-- Die Tags "u","i","b", einen Trennstrich und dann den Tag "url" anzeigen -->
[%embeddedTags show="u,i,b,|,url"%]

import

[%import [preparser="true"] file="<string>"%]

[%import [preparser="true"] id="<string>"%]

Oder alternativ mit folgenden Parametern:

Die Funktion "import" ersetzt die verschiedenen ursprünglichen Funktionen zum Einfügen von Dateien durch eine einheitliche Funktion. Sie unterscheidet sich außerdem in der Art, wie die Dateien behandelt werden. Die Funktion "import" behandelt die zu importierende Datei wie ein eigenständiges Template. Dieses hat mehrere Vorteile: das eingefügte Template unterliegt bspw. den selben Sicherheitseinschränkungen wie das Basistemplate. Außerdem (und noch viel wichtiger:) sorgt dieses Vorgehen dafür, dass die Korrektur enthaltener Pfadangaben korrekt arbeiten kann.

Der Parameter "file" gibt den Namen der Datei an, welche importiert werden soll.

Alternativ kann der Parameter "id" verwendet werden, um statt den Pfad und Dateinamen fest im Template vorzugeben, die Id des Templates anzugeben. Das Framework bestimmt den zu der Id passenden Dateinamen zur Laufzeit automatisch. Dies hat den Vorteil, dass die Datei umbenannt oder in einen anderen Pfad verschoben werden kann, ohne dass die Verweise auf diese Datei in allen anderen Templates korrigiert werden müssen.

Anwendungsbeispiel: angenommen Sie haben ein Template "a.html" für den Skin "default" definiert und dieser importiert das Template "b.html". Nun möchten Sie einen neuen Skin anlegen. In diesem Skin wollen Sie den Inhalt der Datei "b.html" ändern, aber den Inhalt der Datei "a.html" unverändert lassen.
1. Fall: Falls Sie im Skin "default" das Template "b.html" über den Parameter "file" importiert haben, dann können Sie "b.html" in Ihrem neuen Skin nicht ändern, ohne den Pfad in "a.html" zu ändern. Das bedeutet, Sie müssten in Ihrem neuen Skin auch die Datei "a.html" anpassen.
2. Fall: Falls Sie im Skin "default" dem Template "b.html" eine Id (zum Beispiel "b") zugewiesen haben und das Template über den Parameter "id" importiert haben, dann können Sie in Ihrem neuen Skin die Id des Template "b" mit dem Pfad einer anderen Datei überschreiben, welche nur für diesen Skin verwendet wird. Dadurch müssen Sie den Pfad im Template "a.html" nicht ändern und können das Template unverändert lassen.
Hinweis: Das Zuweisen von Ids zu Dateien erledigen Sie über die Konfigurationsdateien (*.config) im Verzeichnis des jeweiligen Templates.

Das Flag "preparser" bestimmt, wann eine Datei importiert werden soll: BEVOR oder WÄHREND der Parser das Template abarbeitet. Wird es gesetzt, wird die Datei VOR dem eigentlichen Parsen eingefügt. Das Flag "preparser" sollte beispielsweise immer dann verwendet werden, wenn das importierte Template auf Variablen zugreifen muss, welche durch das Basistemplate gesetzt werden. Klassisches Beispiel sind Templates, welche innerhalb des Körpers von Schleifen importiert werden. ("foreach", "section") Diese benötigen das Flag "preparser", falls sie auf die Schleifenvariablen zugreifen können müssen. Alternativ können Sie der Anweisung "Import" eine Liste aller Variablen übergeben, auf welche Sie innerhalb des Templates zugreifen müssen.

Achtung! Wird der Parameter "preparser" verwendet, so wird das importierte Template nicht einzeln geparst, übersetzt und im Cache gespeichert, sondern in den Quellcode des Templates kopiert, welches die Import-Anweisung enthält. Es wird zur Laufzeit nicht geprüft, ob sich der Inhalt des importierten Templates seit dem letzten Aufruf geändert hat. Wenn Sie das importierte Template ändern, müssen Sie daher den Template-Cache explizit leeren, damit die Änderungen wirksam werden.

[%if $foo%]
[%$bar%]
[%/if%]

preview

[%preview [ width="<integer>" ] [ height="<integer>" ] %]

Die Funktion "preview" erzeugt ein Vorschaufenster auf einen Eintrag, welchen der Besucher geschrieben hat.

Im Text enthaltene Smilies und Tags werden dabei grafisch dargestellt. Dadurch hat der Besucher die Möglichkeit vor dem Abschicken des Formulars zu prüfen, wie sein Beitrag aussehen wird.

Beim Aufruf der Funktion werden automatisch die erforderlichen JavaScript-Dateien eingebunden. Außerdem wird eine Schaltfläche mit der Aufschrift "Vorschau" erstellt. (In der englischen Version lautet die Beschriftung "Preview".) Beim Anklicken wird oberhalb dieser Schaltfläche ein Fenster eingeblendet, welches die Vorschau zeigt.

Die Attribute "width" und "height" geben Breite und Höhe des Vorschaufensters an. Diese Werte werden als CSS-Anweisungen umgesetzt. Wenn Sie diese verwenden möchten, achten Sie daher bitte darauf, dass Sie eine Maßeinheit (zum Beispiel "px" für Pixel) angeben müssen. Prozentuale Angaben, wie "70%" sind ebenfalls erlaubt. Zahlen ohne Maßeinheit, wie "70" werden jedoch im Browser möglicherweise fehlerhaft dargestellt.

Die Angaben beziehen sich nicht auf die gesamte Größe des Vorschaufensters, sondern sinnigerweise auf den darin dargestellten Text. Die folgende Abbildung demonstriert dies:

Abbildung: Darstellung der Randbereiche

Der hier lila gefärbte Bereich ist der, dessen Größe über die Attribute "width" und "height" festgelegt wird. Der hellgrüne Bereich ist die Gesamtgröße des Feldes. Der Platz, welcher für die Überschrift benötigt wird, ist hellblau dargestellt. Der Rahmen ist hier violett angedeutet. Die Gesamtgröße des Fensters richtet sich also nach den Werten der Attribute "width" und "height", zuzüglich der Überschrift, des Rahmens (border) und des Randbereichs (margin) des Fensters.

printArray

[%printArray value="<array>" %]

Diese Funktion wandelt ein (eventuell mehrdimensionales) Array in einen String um und gibt diesen aus. Das Array wird im SML-Format dargestellt. Dies kann unter anderem für das Debugging von Templates interessant sein, um herauszufinden welchen Namen eine gesuchte Variable hat.

Hinweis: Ab Version 2.9.3 des Yana Frameworks unterstützt diese Funktion Syntaxhervorhebung bei der Ausgabe.

printUnorderedList

[%printUnorderedList value="<array>" [ keys_as_href="<bool>" ] [ layout="<int>" ] %]

Diese Funktion wandelt ein (eventuell mehrdimensionales) Array in eine unsortierte Liste im HTML-Format um und gibt diese aus. Es wird der Tag "ul" verwendet.

Man kann diese Funktion verwenden, um Baummenüs zu erzeugen. Wahlweise können in diesem Menü Links erzeugt werden. Dazu verwenden Sie bitte die URLs als Schlüssel des Arrays und die Beschriftung als Werte. Außerdem setzen Sie den Parameter "keys_as_href" auf "true".

<?php 
$A = array(
    '1.html' => 'Link',
    'Menü 1' => array(
        '2_1.html' => '1. Eintrag',
        '2_2.html' => '2. Eintrag',
        'Menü 2' => array(
            '2_3_1.html' => '1. Eintrag',
            '2_3_2.html' => '2. Eintrag'
        ),
    ),
    'Menü 3' => array(
        '3_1.html' => '1. Eintrag',
        '3_2.html' => '2. Eintrag',
        '3_2.html' => '3. Eintrag'
    ),
);
$YANA->setVar('A', $A);
?>

Die Schlüssel werden fett gedruckt und die Werte kursiv - dies lässt sich jedoch per CSS ändern. Es werden folgende CSS-Klassen verwendet:

• gui_array_list
• gui_array_head
• gui_array_key
• gui_array_value
• gui_array_head_open

rss

[%rss [ image="<string>" ] %]

Diese Funktion erzeugt Hyperlinks, zu den verfügbaren RSS-Feeds einer Webseite.

Das Argument "image" kann verwendet werden, um ein Icon auszuwählen. Klickt der Nutzer auf diesen Link, so wird die entsprechende Datei geöffnet. Die Liste der RSS-Feeds wird im Quellcode der Anwendung erzeugt. Siehe dazu auch das Kochbuch für Entwickler, Kapitel: "Sonstige Funktionen".

Tipp: Auch wenn Sie die Hyperlinks nicht erzeugen, können Ihre Besucher die verfügbaren RSS-Feeds Ihrer Webseite trotzdem lesen, weil diese Links zusätzlich im Header der Datei zu finden sind. Diese Informationen kann der Browser des Besuchers, sofern er dazu in der Lage ist, verwenden, um Ihrem Besucher das Lesen der Feeds zu ermöglichen. Diese Variante ist für Ihre Gäste allerdings umständlicher und sollte daher vermieden werden.

<?php 
// Der Wert 'mein_rss' ist der Name der Funktion, welche den RSS-Feed ausgibt
RSS::publish('mein_rss');
?>

Hinweis: In den mitgelieferten Skins werden die Hyperlinks auf vorhandene RSS-Feeds automatisch erzeugt, so dass Sie diese Funktion in der Regel nicht selbst benötigen, außer wenn Sie einen eigenen Skin schreiben. In diesem Fall sollten Sie die Hyperlinks in den Kopfbereich der Seite einbinden, wo diese für Besucher leicht zugänglich sind.

sizeOf

[%sizeOf value="<mixed>" [ assign="<string>" ] %]

Die Funktion "sizeOf" gibt die Länge eines Arrays oder Strings als Zahl zurück. Falls der Parameter "assign" angegeben wird, so wird der Rückgabewert in der Variable mit diesem Namen gespeichert und die Funktion liefert kein Ergebnis zurück.

smilies

[%smilies [ width="<integer>" ] %]

Die Funktion "smilies" generiert automatisch eine Tabelle aller verfügbaren Emoticons / Smilies, mit einem Link zum Einfügen in das angegebene Eingabefeld.

smlLoad

[%smlLoad file="<string>" [ section="string" ] [ scope="string" ] %]

Diese Funktion bietet die gleiche Schnittstelle wie die Smarty-Funktion "config_load". Allerdings arbeitet diese Funktion mit SML-Dateien mit den Dateiendungen "*.sml", "*.cfg" oder "*.config".

Anders als die herkömmlichen Konfigurationsdateien der Smarty-Engine, dürfen SML-Dateien mehrdimensionale Array-Definitionen enthalten.

Außerdem darf das Argument "scope" den Wert "template_vars" besitzen, welcher bewirkt, dass die Variablen der SML-Datei als Templatevariablen verwendet werden  - damit ist es möglich auf mehrdimensionale Arrays in gewohnter Weise zuzugreifen. Dieses Feature gibt es nur für smlLoad() und nicht für config_load().

<TEST>
    <A>1</A>
    <B>
        <C>2</C>
    </B>
</TEST>

[%smlLoad file="foo.sml" section="TEST.B" scope="template_vars"%]
[%$C%]

[%smlLoad file="foo.sml" section="TEST.B"%]
[%#C#%]

[%smlLoad file="foo.sml" scope="template_vars"%]
[%$TEST.B.C%]

sml_load

Der Funktionsname "sml_load" ist ein Alias für die Funktion "smlLoad". Sie können beide Bezeichnungen alternativ verwenden.

Zur Beschreibung dieser Funktion.

varDump

[%varDump var="<mixed>" %]

Hinweis: Diese Funktion dient ausschließlich dem Debugging. Sie steht nur zur Verfügung, wenn das Framework im Debugmodus betrieben wird. Ist dieser Modus deaktiviert, wird beim Versuch die Funktion aufzurufen ein Fehler erzeugt. Dies dient der Sicherheit Ihrer Anwendung.

Die Funktion "varDump" gibt den Inhalt einer Variablen aus.