De:TemplateVariablen

From MODx Wiki

Dieser Artikel ist eine Übersetzung aus dem englischen Wiki.

Vielleicht gibt es noch Übersetzungsfehler oder andere Ungereimtheiten. Wenn du gut Englisch versteht vergleiche doch mal die beiden Artikel.

1 Was sind Template-Variablen?
2 Template-Variablen erstellen
3 @-Bindings
4 Dokument-spezifische Variablen
5 Siehe auch

[edit]

Was sind Template-Variablen?

Eine Template-Variable (TV) ist eine spezielle Variable die Inhalte in einem Template oder Dokument repräsentiert.
Wenn ein Dokument für die Anzeige vorbereitet wird, wird der Inhalt mit den Eigenschaften der TV ausgewertet.
TVs müssen dem Template, in dem sie benutzt werden, explizit zugewiesen werden.

[edit]

Template-Variablen erstellen

Hier geht es darum wie Template-Variablen erstellt und einem Dokument zugewiesen werden und wie die Variablen beim Bearbeiten eines Dokuments geändert werden.
Template-Variablen werden in der Ressourcenverwaltung erstellt. Im Tab Template Variablen gibt es einen Link 'Template Variable erstellen'. Im darauffolgenden Editor wird ein Name, optional eine Beschreibung und der Input-Typ angegeben. Der Input-Typ legt fest, mit welchem Bedienelement ein Benutzer seine Wahl treffen kann. Beispiele sind ein Ausklappmenü, ein Texteingabefeld oder eine Checkbox.

Aufruf einer Template-Variable im Dokument-Editor oder Template
Wie die "fest verdrahtete" Anzeige des Dokument-Inhalts:

[*content*], also der Name eingeschlossen in [**]: [*TVName*]

Eingabeoptionswerte
Die Text-Box mit Namen Eingabeoptionswerte bietet eine Liste der Optionen für den Input-Typ Select.
Mögliche Formate:
option1==wert1||option2==wert2||option3==wert3
oder
option1||option2||option3

Der Trenner "==" wird benutzt um einer Option einen Wert zuzuweisen, während der Trenner "||" mehrere Optionswerte voneinander trennt.

Rot==#FF0000||Gruen==#00FF00||Blau==#0000FF

Wenn ein Benutzer das Dokument editiert erscheint eine Liste in der Rot, Gruen und Blau zur Auswahl stehen. Beim Abspeichern werden die zugewiesenen Werte #FF0000, #00FF00 oder #0000FF in die Datenbank geschrieben.

Im Fall option1||option2 wird auch der angezeigte Wert gespeichert, z.B. bei Rot||Gruen||Blau wird entweder Rot, Gruen oder Blau angespeichert.

Standardwert
Setzt einen Standardwert für die Variable, z.B.:
Input-Typ: Rot||Gruen||Blau||Orange
Um Gruen und Orange beim Editieren ausgewählt zu haben wäre die Eingabe im Standartwert Gruen||Orange.

Objektauswahl
Definiert in welchem Format die TV ausgegeben wird.
Es gibt statische und dynamische Formate. Dynamische Formate können die Anzeige bewegen, auswechseln oder modifizieren.
So zeigt der Ticker abwechselnde Texte die per || getrennt eingegeben wurden und das Marquee scrollt den Inhalt des TVs automatisch.
Die Ausgabe wird automatisch von DIV-Tags mit der CSS-Klasse “#tvVariablenName” umschlossen.

Sortierung
Legt bei mehreren TVs die Reihenfolge fest.

Template-Berechtigungen
TVs funktiunieren (noch) nur in Templates die hier aktiviert werden.

Zugangskontrolle
Legt fest welche Dokument-Gruppen die TV bearbeiten dürfen.

[edit]

@-Bindings

[edit]

was sind @-Bindings?

Im Kontext von TVs ist eine Datenquelle ein Speicherort von Inhalten die angezeigt werden.
Folgende Möglichkeiten können eine Datenquelle für TVs darstellen:

   * eine Datei auf dem Server
   * eine Datenbanktabbelle auf die MODx Zugriff hat
   * ein Dokument aus dem Dokumentbaum
   * ein Chunk
   * das Ergebnis eines ausgeführten PHP-Skripts

Diese Datenquellen können für Verarbeitung und Anzeige in einem Dokument an eine TV gebunden werden, also als Eingabe dienen.

Syntax:

   * @FILE file_path
   * @DOCUMENT document_id
   * @CHUNK chunk_name
   * @SELECT sql_query
   * @EVAL php_code

Der von der TV angenommene Wert der Quelle kann ein String, ein Array oder ein Recordset sein.
Der zurückgegebene Wert hängt davon ab welches @BINDING benutzt wird. Einige Ausgabe-Optionen der TV wandeln dabei den Eingabewert entweder in einen String oder Array um.

(...)

For example, controls that accept string values such as a radio button group or select list will attempt to convert a record set (rows and columns) into the following format: col1row1Value==col2row1Value||col1row2Value==col2row2Value,...

Please note that @ bindings will work only when used inside “Input Option Values” or “Default Value” fields (indicated by the database icon next to them). bind_1.gif

When placing @ bindings inside the “Input Option Values” field, they are used to format input options only when editing document within the Manager, for example to create a drop-down list of Cities or Countries.

When placing @ bindings inside the “Default Value” field the returned value is used to render to the final web page. This makes it simple to build complex forms for data input on the web very quickly.

[edit]

@FILE

Syntax @FILE file_path

Binds the variable to a file, where file_path is the path and name of the file. The return value is a string containing the content of the file. The file path is the abosulte path from the root of the server or your particular installation.

Der "@FILE" Kopplungs-Befehl ist sehr nützlich für den Fall, das man Daten ausgeben will, welche sich in einem "File" befinden. Mittels dieser Zeichen: || und == als "Trenner" und "Zuweiser" kann man sogar Daten aus externen Datenbanken einbinden.

Gehen wir z.B. davon aus wir wollten Daten aus einer Datei namens headline_news.txt welche sich in einer Datenbank eines ausgelagerten Servers befinden. Diese Informationen könnten regelmäßig aktualisiert werden und wir und die Besucher unserer Webseite wären quasi immer auf dem Neusten Stand. Also hier die Antwort auf die Frage: "Wie geht das ?"

Zunächst erstellen wir eine neue Template-Variable und setzen den Darstellungs-Modus (Widget) auf "Ticker".

We then add the @FILE command inside the default value of the TV. This will point to where the headline_news.txt is located in our example.

Each headline in the headline_news.txt file is separated by a new-line (lf or \n) character. We can use the Delimiter property of the Ticker to separate each item and display them one at a time. We’ll also change the background color of the ticker using the Style property. bind_4.gif

Note: The \n character is used to represent the new line character

[edit]

@DOCUMENT

Syntax @Document document_id

Binds the variable to a document. Where document_id is the numeric id of the document. The returned value is a string containing the content of the document.

Using this binding we can include other documents as parts of the web template.

For example: We could create a document called MySideBarInfo (id:18) which will store some information to be displayed in the sidebar of our template. We could then create a simple TV called MySideBar and bind it to document 18 (MySideBarInfo) bind_5.gif

By adding the [*MySideBar*] variable inside the template we’ll be able to render the content of document 18 whenever the page is displayed. This effectively gives you the ability to emulate the “blocks” concept of many other content management systems.

[edit]

@CHUNK

Syntax @CHUNK chunk_name

Verknüpft die Variable mit einem Doukument. Wobei der "chunk_name" der Name des chunks ist. Der zurückgegebene Wert ist ein string der den Inhalt des chunks trägt.

This binding is very similar to the @DOCUMENT binding with the exception that it will bind the TV to a chunk (or htmlsnippet).

Example: @CHUNK MycontactForm

[edit]

@INHERIT

Syntax @INHERIT default content if no other content found

The @INHERIT binding takes advantage of the hierarchical structure of the document tree by allowing Template Variable content to "cascade" down the document tree. What this means is that you can apply content to whole sections of your site by editing just one TV.

This binding can be used for Input Option Values or the Default Value like any other binding. However, it is really only useful when used for the Default Value.

When this binding is used as a Default Value for a TV, if no content is specified for this TV in the current document, the binding will look at it's parent document for content, and if none is found, it's parent and so on until it reaches the top of the document tree. If it no content is found it will use the default content.

For example: Let's say you have a "Help & Support" section of your site and in every page in the Help & Support section you want your footer message to read "If you need any further support please contact us" while you want the rest of your site to read "Copyright yoursite.com." If you were to set the Default Value for the Footer template variable as shown below @INHERIT Binding

all you'd have to do is edit the Footer template variable in the first document of the Help & Support section of your site and you'd be done. Because the content from the one top Help & Support document would become the default value for all documents beneath it.

[edit]

@SELECT

Syntax @SELECT sql_query

Binds the variable to a database query that returns a recordset. Where sql_query is the actual database query. The return value is a recordset.

Example: We can use the @SELECT command the same way we would use a regular SQL SELECT statement: bind_6.gif

Note: When using the CMS database tables you can use the {PREFIX} tag before the table name. This will append the database and table prefix to the table name. You can also use manually apply the table prefix to the table name if it’s known. For example, modx_site_content, where modx_ is the table prefix used in this example.

The result is a simple database listing of the first 10 documents. bind_7.gif

You can also use the @SELECT command to provide your document editors with a dynamic list of options from a DropDown Menu.

Example: @SELECT color_name, color_value FROM colors

When the user edits the document he/she will see a list of color options from which to choose.

@SELECT is key to working with DataGrids which will be outlined in an upcoming Tutorial.

[edit]

@EVAL

Syntax @EVAL php_code

Evaluates a string of php codes and process the returned value from the code. Where php_code is the actual php code to be evaluated. The returned value can be either a string, array or a recordset. @EVAL return “The time stamp is now ”.time();

using the @EVAL command you can write php codes to do almost anything possible with php scripts today. This is probably the most flexible and powerful of all the commands as it opens up TV bindings to virtually unlimited possibilities. Nested Bindings

You can nest one @ binding inside another. For example, an @EVAL binding can be placed inside chunk while you can use the @CHUNK binding to retrieve the chunk containing @EVAL.

[edit]

Dokument-spezifische Variablen

This is a listing of all of the (currently) available document-specific variables. They are accessed with [*variable-name*] tags. These values can also usually be retrieved from the $modx->documentObject['variable-name'] array.

   * id - The document's ID. Can also be obtained with $modx->documentIdentifier.
   * type - Whether document, folder or weblink.
   * contentType - The content type, such as text/html.
   * pagetitle - The title of the page.
   * longtitle - The longtitle of the page.
   * description - The description of the page.
   * alias - The alias of the page. Used in creating Friendly URLs.
   * published - [0|1] Whether or not the document is published.
   * pub_date - Date the document is to be published. This is not a "normal" date, and must be processed by a script for meaningful output. Example: strftime("%d/%m/%y %H:%M:%S", $value)
   * unpub_date - Date the document is to be unpublished. See 'pub_date'.
   * parent - The ID of the document's parent.
   * isfolder - [0|1] Whether or not the document is a folder.
   * introtext - The summary of the document.
   * content - The content of the document.
   * richtext - [0|1] Whether or not a RichText Editor is to be used when editing the document.
   * template - The ID of the template to used for the document.
   * menuindex - The order in which the document is to be listed in the menu.
   * searchable - [0|1] Whether or not the document is to be searchable.
   * cacheable - [0|1] Whether or not the document is to be cached.
   * createdby - The user ID of the creator of the document.
   * createdon - The date the document was created. See 'pub_date'.
   * editedby - The ID of the user who last edited the document.
   * editedon - The date the document was last edited. See 'pub_date'.
   * deleted - [0|1] Whether or not the document has been deleted (but not yet completely removed from the database by emptying the trash).
   * deletedon - The date the document was deleted. See 'pub_date'.
   * deletedby - The ID of the user who deleted the document.
   * menutitle - The title to be shown in the menu. If empty, the pagetitle is used.
   * donthit - [0|1] Disable page hit count for the document.
   * haskeywords - [0|1] Whether or not the document has links to keywords.
   * hasmetatags - [0|1] Whether or not the document has links to meta tags
   * privateweb - [0|1] Whether or not this document has been assigned to a private web document group.
   * privatemgr - [0|1] Whether or not this document has been assigned to a private manager document group.
   * content_dispo - [0|1] Whether the document's content-disposition is attachment or inline.
   * hidemenu - [0|1] Whether or not the document is to be hidden in the menu.

[edit]