Introduction To DML

The Dynamic Markup Language was originally created for the purpose of providing a developer friendly object-based language for Athene, a multi-platform operating system. Based on the Extensible Markup Language (XML), the language is starting to expand into other areas due to the fact that it can be embedded in any type of XML document as a special extension. For instance, DML can be used to extend the functionality of HTML documents, which is what we will concentrate on in these tutorials. The Dynamic Markup Language also has a dependency on the Pandora Engine, which provides the backbone of the system that DML runs on.

The DML acronym was originally derived from the phrase "Dynamically Extendible Object Based Markup Language". While that's quite a mouthful, the original name should give you a number of useful hints as to what DML is:

It's a Markup Language that has been developed for close XML compliance. This provides a solid learning foundation for anyone that has used XML or HTML based languages.
The instruction set (tags) are dynamically extendible, meaning that the tags available to you can grow and shrink depending on what classes have been installed on your system.
The language is object based. Each tag that is used in a script will create an independently functioning object, which can be manipulated during and after the processing of a DML script.

Some important points that are not immediately clear are:

The language was created primarily for graphics, interface and application construction, rather than for text documents or general programming purposes. This makes it an excellent complement to the HTML standard rather than a replacement.
A DML script file can make references to other DML files during processing to help build the result that the script is trying to achieve. This makes code reuse much easier, something that does not come naturally to XML documents under normal circumstances.
DML supports popular programming concepts such as if statements, loops, variable storage and argument parsing. This effectively has given the DML all the qualities of a fully functional programming language, while retaining the simplicity of XML.

Typical Uses of DML Scripts

DML is typically used for the purpose of interface and graphics construction, but it also makes a good language for batch scripting. "Interface construction" broadly covers the construction of application and game interfaces, as well as building the user environment and GUI at boot time.

While this document concentrates on using DML for building interfaces and graphics, some other uses include:

Directly communicating with the operating system and object APIs.
Writing high level, general purpose programs.
Creating interactive documents.

As the language is still in its infancy, it is difficult to predict how it will develop over time or what areas it will find its most common usage. Ultimately this is due to its dynamic instruction set - as they increase over the next few years, the possibilities open to DML will also increase. You can add your own components to the DML instruction by using the Pandora Engine SDK, so if you need a new feature, you have the option of adding it yourself.

Technical Requirements

As DML is based on the XML standard, it uses identical tag and attribute conventions in order to provide a high level of familiarity to the user. A tag must begin with the opening sign "<", followed by the name of the tag (object), attributes, then the closing sign ">". For instance, an image tag can be defined as:

  <image src="pictures:backgrounds/portrait.jpeg" width="100" height="150"
    x="60" y="70">

Strings must be explicitly defined using quotation marks "", while numbers can be enclosed with or without quotes. The DML interpreter has full support for type checking, so if an attempt is made to write to a field with the wrong type, it will be ignored if conversion is not possible.

Tags must be closed, using the </tagname> construct, or for tags that do not encapsulate anything, the <tagname attributes/> convention can be used as short-hand.

Comments can be specified using the standard declaration of "" is reached.

HTML tags are not supported by the DML interpreter, but you can use them and other non-supported tag types outside of the <dml> area. The DML interpreter is not case sensitive, so use of <image>, <IMAGE> or <Image> will not affect processing, and likewise the attributes are not case sensitive either.

DML scripts should be structured as follows if XML compliance is required:

  <?xml version="1.0"?>
  <!DOCTYPE dml PUBLIC "-//ROCKLYTE//DTD DML 1.0//EN"
    "http://www.rocklyte.com/dtd/dml_1_0.xml">

  <dml>
     ...content...
  </dml>

With or without the XML definition, the DML script will be executed correctly so long as the file extension for the document is ".dml" and the content is correctly defined.

DML Tag Attributes

The <dml> tag supports a number of optional attributes that help to define the content of a DML script. Currently these options include the following:

Type: The Type attribute allows you to associate a DML script with a specific category. Available categories include 'batch' for batch scripts that terminate after completion; 'program' for scripts that generate applications; and 'extension' for scripts that provide functional services for other scripts.

Procedure: If a file contains more than one DML tag, you'll need to give the secondary tags procedure names or they will be inaccessible when you need them.

Any content outside of the <dml> tag will be ignored, so you can safely embed other forms of XML based information within DML scripts without it interfering with the interpreter.

Numeric Support and Calculations

Extensive support for the basic management of numbers is provided by the DML interpreter. This includes full support for floating point numbers, which allows percentages to be correctly supported. Furthermore, calculations that include multiplication, division, addition and subtraction operators are permitted. The following is a basic example:

  <image src="pictures:backgrounds/portrait.jpeg" width="=10*10"
    height="=1500/10" x="=40+20" y="=100-30"/>

It is vital that you enclose your calculations in quotes and precede them with the equal sign. The following construct illustrates an invalid calculation:

  width=10 * 10

The correct usage is:

  width="=10 * 10"

Support for advanced mathematical functions such as sin, log and sqrt are not available, but may appear in future versions if demand for them increases.

Object Instances and Hierarchy

Each time a new tag is declared, an actual operating system object will be created from the class representing that type of object. For instance, when an <image> tag is processed, the DML interpreter will ask the Pandora Engine to create a new object that belongs to the Image class. If successful, the rest of the tag will be processed and fields such as "src", "width", and "height" are written to the image object. After that, the image object initialises itself, and from then on the image object is a fully functional part of the operating system, which functions independently of the DML script itself.

What this essentially means is that the processing of a DML script does not result in a "view" of the script like HTML, but acts more like a language that is compiled at run-time.

Because each tag is treated as an object, this allows object hierarchies and relationships to be developed, as illustrated in this example:

  <render name="my_demo" width="200" height="200">
    <image src="pictures:textures/sandpaper.pcx" width="[my_demo.width]"
      height="[my_demo.height]"/>

    <render name="my_button" width="=[my_demo.width]/10" fixedheight="20">
      <onclick>
        <script static src="utilties:memory_monitor.dml"/>
      </onclick>
    </render>
  </render>

The construction of this script demonstrates an obvious hierarchy, which has organised the objects of the script into logical groups and sub-groups. Top level objects such as "my_demo" are referred to as containers, and their contents are referred to as children. Of course, those children can be containers of more children, and so on.

The organisation of the objects in a script is vital, as many objects are specially developed for the management of child objects, or for performing actions for a container. The particular attributes for each object in this regard is documented for each class in the Pandora Engine SDK.

Referencing Non-Standard Attributes

Because of the many special features in DML, most scripts will contain a few tags that reference attributes that are deemed 'non-standard'. A non-standard attribute is a field name that is not documented as forming part of a tag's standard. For example, the Variable tag supports a "name" attribute as standard. However, any variable fields that we may want to create would inevitably be non-standard attributes. If we wanted to create x, y and z fields in a variable object, we could use the following tag:

  <variable name="myvars" x="10" y="20" z="30"/>

The problem here is that the DML interpreter has no idea that the x, y and z values are non-standard, and will try to process them as standard fields. It also raises questions in regards to error-checking, i.e. if we wanted to ensure that a DML script was following documented standards, errors would be reported for the x, y and z fields even though we are making a legitimate reference.

In order to solve this issue, non-standard attributes can be explicitly specified through the use of the ampersand character. Using the aforementioned example, a "compliant" tag would be created as follows:

  <variable name="myvars" &x="10" &y="20" &z="30"/>

As you can see this makes the definition much clearer, and prevents confusion in the processing of the script. Ultimately the DML interpreter for Athene can process either statement as it can analyse the object definition, thereby clearing up any 'fuzzy areas'. However, it is important to use this standard correctly as it can optimise the execution of your script, and limits the potential for any errors or confusion in the script.

Plugin Usage

Since May 2002, the Dynamic Markup Language has been available for use as a plugin for web browsers. At the time of writing, the Netscape browser is supported for Intel-based Microsoft Windows platforms. The plugin can be installed if the user actively visits the Rocklyte downloads page in advance, or the browser can automatically manage installation by prompting the user to download the plugin when it detects its usage for the first time.

Using DML within HTML-based web pages requires you to use special HTML commands so that the browser can interpet the DML instructions correctly. Here are the steps that you need to take in order to do this correctly:

The <html> tag at the start of the document must contain the attribute "xmlns:dml". This will force the browser to avoid interpeting DML commands as HTML tags, which could otherwise cause confusion.
Each time you want to write a DML statement within your HTML document, you must use the <embed> tag to create an embedded DML graphics area.
The embed tag will need to be associated with a DML statement in order for it to work. There are two ways to do this - either you can write the DML statement in a separate file and make a reference to that file in the src attribute of the embed tag; or you can embed the DML statement within the HTML document (preferably at the end of the file) and refer to its procedure name.

Here is a short example demonstrating a typical DML implementation:

  <html xmldns:dml>
    html content
    <embed type="application/x-dml"
      width="200" height="100"
      src="filename.html"
      pluginspage="http://www.rocklyte.com/dml/plugin.html"
      procedure="main">
    </embed>
    html content
  </html>

  <dml procedure="main">
     dml commands
  </dml>

Now for an explanation of what the embed tag's attributes are used for. The type tells the browser the type of data that is represented by the embed tag. This should always be set to "applications/x-dml", or the plugin may not load correctly. The width and height attributes specify the area that you want to reserve for graphics space. You can set these values to percentages if you want the plugin to take up space relative to its surroundings. The src attribute tells the plugin where it should load the DML data from. If you have stored the script in a separate file, you must refer to it here. If the DML script is in the same file as the HTML document, then you will need to specify a src value that refers back to the document (i.e. use the filename that the HTML document is saved under). If no src value is specified, the plugin will not work correctly. The pluginspage attribute must refer to the location "http://www.rocklyte.com/dml/plugin.html". This allows the browser to find the plugin if the user does not already have it installed. Finally, the procedure is a special attribute that refers to the procedure name of the DML script that you want to execute. This setting is essential if your document contains multiple DML statements - if you do not specify a procedure name, only the first DML statement that the interpreter encounters can be executed.

Plugin File Compression

If you need to distribute a plugin-based DML script that references multiple files (e.g. an external DML file, images and sound files), then you will need to distribute the DML script and the extra files as a compressed package. This is achieved by collecting all of the necessary files and compressing them with a zip algorithm (use your favourite zip program to do this). The core DML script must have a name of "main.dml" within the zip file and will serve as the first execution point when the package is decompressed at the client's machine.

To refer to the package in your HTML embed tag, use the src attribute as you normally would for referencing a standard DML file. The DML plugin will check the file type on receipt so that it can decompress and run it correctly.