.. _ref-mad:

###############################################################################
Das MAD-Dokument 
###############################################################################

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.


Presentation
================================================================================

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. :ref:`ref-font`). 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.


Widgets
================================================================================

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 :ref:`ref-toolkit`,  :ref:`ref-charts` und :ref:`ref-media`.


Engines
================================================================================

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 :ref:`ref-toolkit` und der ChartController in :ref:`ref-charts`.


Includes
================================================================================

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.

.. _ref-templates-in-mad:

Templates
================================================================================

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");


Benennung von Widgets
================================================================================

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. :ref:`ref-vars`). 


Definition von externen Ressourcen
===============================================================================

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>
   
MAD-Validierung
================================================================================

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"