Maongo-Präsentationen (Presentations) werden in der Beschreibungssprache Maongo Application Description (MAD) verfasst. MAD ist eine deklarative XML-Sprache, die das Layout, die Hierarchie, die Logik, die Animationen u.a.m. einer Presentation beschreibt.
Ein MAD-Dokument trägt die Endung .mad.
Innerhalb eins MAD-Dokuments kann Javascript als Scripting Sprache verwendet werden. Siehe dazu :ref:`ref-actions
Die meisten Sachverhalte in Maongo lassen sich sowohl in XML und als auch in JavaScript ausdrücken. Die Dokumentation wird daher beide Schreibweisen präsentieren.
Namen und Bezeichner sind in Maongo case-sensitiv.
Die Presentation bildet die Grundfläche, auf der weitere Widgets (s.u.) platziert werden. Die Presentation ist ein Widget mit speziellen Eigenschaften und kann nur als äußerer Container benutzt werden. Eine Presentation ist immer rechteckig. Die Größe der Fläche wird über die width- und height-Attribute definiert.
Eine “leere” Presentation kann wie folgt definiert werden:
<presentation width="400" height="300">
<property name="Title" value="Mein erstes Maongo"/>
</presetation>
Die Presentation besitzt die Property Title, mit der der zu verwendende Fenstertitel gesetzt werden kann. Weiterhin besitzt eine Presentation auch alle anderen Eigenschaften eines Widgets, wie beispielsweise BackgroundColor oder Rotation.
Die Presentation ist der einzige Ort, in der die der Anwendung zur Verfügung stehenden Fonts deklariert werden können (s.u. Schriften). Außerdem ist die Presentation der bevorzugte Ort, vererbbare Properties auf einen Standardwert zu setzen: beispielsweise die Farbangaben (BackgroundColor, ForegroundColor).
Die Presentation kann in allen Widgets mit this.Presentation (JavaScript) bzw. durch Lookup auf “Presentation” adressiert werden.
Ein Widget ist der Grundbaustein im Maongo System. Es ist eine graphische Komponente, die eine Reihe von veränderbaren Eigenschaften (Properties) besitzt. Das Widget kann Daten empfangen, verarbeiten und weiterleiten, es ist durch Funktionen (Actions) erweiterbar, es lässt sich animieren und in automatischen Layouts verwenden.
Widgets werden auf der Fläche der <presentation> angeordnet und können ineinander verschachtelt werden. Es entsteht so ein hierarchischer Widget-Baum, der die Maongo-Anwendung ausmacht. Befinden sich mehrere Widgets auf derselben hierarchischen Ebene, so werden sie in der Reihenfolge der Definition gezeichnet. Das zuerst (zuoberst im Quellcode) definierte Widget liegt demnach in der hintersten Zeichenebene.
Das Maongo-Framework enthält unterschiedliche Widgets für verschiedene Einsatzzwecke (Text, Button, Charts, ...), die alle Erweiterungen der Klasse Widget sind.
Die Widgets sind organisiert in den Sammlungen Maongo-Toolkit, Maongo-Charts und Maongo-Media.
Bestimmte Funktionen benötigen keine grafische Komponente; sie sind in Maongo als Engines realisiert. Eine Engine wird wie ein Widget im XML definiert, hat aber keine visuelle Repräsentanz. Beispiele für Engines sind die Kommunikations-Engines im Maongo-Toolkit und der ChartController in Maongo-Charts.
Der Maongo-Code muss nicht in einem einzigen Dokument stehen. Der Include-Mechanismus erlaubt es, Anwendungen modular zu organisieren und mehrfach benötigten Code an verschiedenen Stellen einzubinden.
Das oberste XML-Element einer Include-Datei ist <mad>. Eine Include-Datei kann weitere Dateien inkludieren.
Eine Include-Datei wird mit mit dem Element <include source="*URL*"/> inkludiert, das Attribute “source” wird als absolute oder zum inkludierenden Dokument relative URL angegeben.
Die folgende Presentation inkludiert zwei MAD-Dateien:
<presentation width="800" height="450">
<widget>
<include source="test_1.mad"/>
</widget>
<widget>
<include source="test_2.mad"/>
</widget
</presentation>
// Quellcode der Datei test_1.mad
<mad>
<widget>
<property name="BackgroundColor" value="red"/>
</widget>
</mad>
// Quellcode der Datei test_2.mad
<mad>
<widget>
<property name="BackgroundColor" value="green"/>
</widget>
</mad>
Der Include-Mechanismus wird direkt beim Laden der Presentation ausgeführt; der Parser löst die <mad />-Tags auf und fügt den Inhalt der inkludierten Datei an Stelle des include-Statements ein.
Eine andere Möglichkeit, wiederverwendbare Objekte zu definieren, bilden Templates. Ein Template ist ein Widget (u.U. mit Child-Widgets), das zur späteren Verwendung definiert, aber nicht dargestellt wird.
Zur Definition wird der <template>-Tag verwendet. Alle Attribute und Properties sind anolog zum Widget zu verwenden. Templates müssen ein gültiges name-Attribut haben:
<template name="meinTemplate"/>
Zur Verwendung des Templates an anderer Stelle im XML definieren Sie ein Widget und setzen als type-Attribut den Templatenamen mit vorangestelltem @:
<widget type="@meinTemplate" />
Properties, die bereits im Template definiert sind, dürfen an dieser Stelle nicht noch einmal definiert werden. Soll der Property-Wert des Templates überschrieben werden, so ist der <set>-Tag zu nutzen.
Ein einfaches Beispiel:
<!-- Template wird definiert -->
<template name="BoxTemplate">
<property name="Shape" value="R 30,30"/>
</template>
<!-- Template wird mehrfach verwendet und um unterschiedliche
Hintergrundfarben ergänzt -->
<widget name="Box1" type="@BoxTemplate" x="10" y="10">
<property name="BackgroundColor" value="red"/>
</widget>
<widget name="Box2" type="@BoxTemplate" x="50" y="10">
<property name="BackgroundColor" value="green"/>
</widget>
In einem komplexeren Beispiel werden im Template ein Vielzahl von Properties vordefiniert:
<!-- Template wird definiert -->
<template name="HeadLineTemplate" type="Text">
<property name="MultiLine" value="true"/>
<property name="TextAlign" value="top-left"/>
<property name="ForegroundColor" lookup="Design.HeadlineColor"/>
<property name="BackgroundColor" value="transparent"/>
<property name="Texture" lookup="HeadlineTexture"/>
<property name="TextureMode" value="force"/>
</template>
<!-- Template wird verwendet -->
<widget name="HeadLine" type="@HeadLineTemplate" x="0" y="0" shape="R 614 100">
<property name="Font" value="Swiss721BT-Bold-32"/>
<property name="BaseLineOffset" value="-8"/>
<property name="LineHeight" value="40"/>
<set property="BackgroundColor" value="red" />
</widget>
Im Beispiel wird eine Headline mit Farben und Hintergründen im Template definiert. Positionierung und Größe der Headline werden erst bei Verwendung des Templates gesetzt.
Templates können in der gezeigten Art und Weise im XML verwendet werden; mit JavaScript lassen sich auch Widgets zur Laufzeit aus Templates erzeugen.
Beispiel:
var newWidget = Type.addTemplateToWidget(myParent, "BoxTemplate", "NewBox");
Widgets (und andere Elemente wie Templates und Actions) können aus anderen Widgets oder aus Skrtipten heraus adressiert werden, wenn sie ein name-Attribut haben. Der Name eines Maongo-Objekts darf aus Buchstaben, Zahlen und Unterstrich bestehen:
Gültige Zeichen innerhalb eines Widget Namens: [a-zA-Z0-9_]+
Der Widget-Name ist stets case-sensitiv.
Der Widget-Name wird im Namespace seines Parent-Widgets verwaltet. Bei Doppelungen innerhalb des gleichen Namespace (z.B. wenn eine Property, ein Define und/oder ein Widget dieselbe Bezeichnung haben), wirft der MAD-Parser einen Fehler.
Fehlerhaftes Beispiel:
<presentation>
<widget name="Box1">
<property name="BackgroundColor" value="red"/>
</widget>
// dies führt zu einem Namenskonflikt
<widget name="Box1">
<property name="BackgroundColor" value="green"/>
</widget>
</presentation>
Funktionierendes Beispiel:
<presentation>
<widget name="Box1">
<property name="BackgroundColor" value="red"/>
</widget>
<widget name="Box2">
<property name="BackgroundColor" value="green"/>
// aufgrund der Verschachtelung kann der Name "Box1" hier wieder genutzt werden
<widget name="Box1">
<!--...-->
</widget>
</widget>
<presentation>
Benannte Objekte werden beim Lookup ohne weitere Pfadangaben gefunden, wenn der Name im Namespace des Widgets selbst, des Parents, seines Parents, (etc. bis zur Presentation) gefunden werden kann (vgl. Defines, Lookups, Bindings).
Wenn in einem Export extern abgelegte und in der MAD-Datei referenzierte Daten wie bpsw. Bilder etc. berücksichtigt und ggf. an einen anderen Ausspielort mitkopiert werden sollen, so müssen die entsprechenden Verzeichnisse/Dateien in der Presentation als <resource> gekennzeichnet werden.
Beispiel:
<presentation>
<resource directory="./assets"/>
<resource file="./assets/animage.png"/>
<!-- ... -->
</presentation>
Die formale Gültigkeit von MAD-Dateien kann mit einer XML Schema Definition (XSD) überprüft werden. Manche Texteditoren können die XSD-Datei auch für Code Completion nutzen.
Um Validierung und ggf. Code Completion nutzen zu können, empfehlen wir folgenden Dokument-Kopf:
<?xml version="1.0" encoding="UTF-8"?>
<presentation xmlns="http://www.maongo.com/mad"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.maongo.com/mad/mad.xsd"
>
<!-- ... -->
</presentation>
Ist kein Online-Zugriff auf die XSD-Datei gewünscht, so kann sie auch neben das mad-Dokument gelegt und die schema-location wie folgt modifiziert werden:
xsi:schemaLocation="http://www.maongo.com/mad/mad.xsd mad.xsd"