This article refers to dap version 0.1.5

Lesson 1. Hello, world!

Here are some simple examples illustrating the dap way of document handling. The objective of these examples is to show that dap is not as weird as it might seem (if you have already read dap language quicktour).

Note: C-style //comments are used for short and are invalid in HTML. Cut them out, if you copy the example code into real HTML.

Welcome to dap

Dap functionality is currently implemented in javascript, and can be utilized in any HTML/XHTML document. Important: the document must have a proper !DOCTYPE declaration — this forces browsers to view the document in standards mode; dap may not work in quirks mode. Also, try to keep the document as well-spelled, as possible. The cleaner the better.

One very common issue with dap powered HTML files — the closing tags. Current versions of browsers don't respect self-closing tags in HTML files. It is not a big deal in ordinary HTML, where self-closing tags are generally useless (except <br />, <hr />, <img ... /> and a few others). You will hardly find an <h1/> tag in regular HTML. But when using dap, self-containg elements (elements having neither text, nor sub-elements inside) are very common. Content of such nodes is generated dynamically by their dap-rules, so the tags for such nodes need no any markup inside, and normally should be self-closing. But, as said above, browsers don't like self-closing tags and <h1 d="! =hello"/> will cause problems in an HTML file. The workaround is to use <h1 d="! =hello"></h1>-like constructs instead. The good news is that only HTML files are subject to this bug. In XML, any self-closing tags are okay, thus dap libraries (wich are pure XML files) don't suffer from this issue.

After all, delivering the dap power to an HTML document is as simple as:

<script type="text/javascript" src="http://dapmx.org/0.1.5/core.js"></script>

Status variables and literals

Status variables are defined within the scope of the node and the node's descendants. In the simplest case, it holds a string value and may be updated later, usually, by a descendant's u-rule.

<div d=" $myVar=Hello,world!">//define a variable within the scope of this div
 <h4 d="! $myVar"></h4>//write the variable's value into this h4
 <p>see the numeric value of:</p>
 <ul>
  <li d="ui" u=" $myVar=1">one</li>//ui mapper attaches event listener
  <li d="ui" u=" $myVar=2">two</li>//(click by default)to the node.
  <li d="ui" u=" $myVar=3">three</li>//u-rule updates the variable.
 </ul>
</div>

see the numeric value of:

The first thing about dap is: 'spell it correct!'. You will notice, that steps in dap rules often start with a leading space. Such steps refer to the empty mapper, and this 'leading' space is actually a separator between the empty name of the mapper and the first token. A 'trailng' whitespace is a separator, preceding an 'empty' token. Two (or, generally speaking, a few) consequent whitespaces represent a series of 'empty' tokens. All such whitespaces, if they are present, are significant and cannot be omitted.

An 'empty' mapper does nothing beyond execution of the token list. 'Empty' mappers in the example above (the <div>'s d-rule and <li>s' u-rules) assign a literal value to the variable $myVar. Assigning a value to a variable in d-rule (down phase) defines a new variable within the scope of the node; assigning in u-rule (up-phase) updates its value.

The <li>s' d-rule consists of a single ui mapper, which adds an event listener (click by default) to the node. When the event comes, the node launches up-phase: executes its own u-rule, and bubbles the u-phase up to its parent and so on.

Formatters

Formatters allow to transform the value of a token prior to feeding it to the mapper. Simplest formatters are just string converters.

You might notice, that the "Hello,world!" string from the previous example lacks a whitespace after the comma. That is, because a space character is reserved in dap as tokens separator and thus can't be used in literal values, as well as in aliases, fieldnames and variable names. Equal sign (=) is also invalid in literals. To provide a literal containing whitespaces or equal signs, or any symbols not allowed in an XML-node attribute, use escaped representation of the literal and usc formatter to unescape it:

<i d="! :usc=Yes,%20you%20can%20use%20spaces%20and%20'%3D'%20signs!"></i>

NOTE: This purely syntactical restriction on whitespaces is only applied to literals provided immediately in the dap rule. Values, obtained from datasources or whatever calculated are free from it. Another good reason to keep long textual messages in a separate resource file.


Interactive static dataset

Instead of repeating the same pattern for every given value, you can populate the repeating pattern list by a rowset. The most straightforward way of providing a dataset is building it from a literal by means of some string-to-rowset formatter. Dap core provides two such formatters: csv (comma separated values) and nvp (after 'name:value pairs', though this name is not ideally exact)

In the example below, <tbody> populates <tr> pattern from a literal by the nvp formatter.

<div d=" $color=black $hex=000">//define defaults
 <h4 d="htm.style@color=concat =# $hex; !=space $color :usc=color's%20RGB%20value =is $hex"></h4>
 <table border="1">
  <thead>
   <tr>
    <th>color</th>
    <th>hex value</th>
   </tr>
  </thead>
  <tbody d="* @color,hex:nvp=red:F00;yellow:FF0;green:0F0;cyan:0FF;blue:00F">
   //content is repeated for each row in the dataset
   <tr d="ui" u=" color$ hex$">//on user event, variables are updated from corresponding datafields
    <td d="! color"></td>
    <td style="color:white" d="htm.style@backgroundColor=concat =# hex; ! hex"></td>
   </tr>
  </tbody>
 </table>
</div>


color hex value

Here, the <h4>'s color and <td>'s backgroundColor style properties are set by htm.style mapper. This is not a core dap mapper. It is defined in starter-kit/htm.xml extension library.

The proper notation of a web-color is constructed by concatenation of a # (mesh sign) and an RGB value. The mesh sign is provided literal, RGB value is taken from the row's color datafield, and both tokens are concatenated by the concat flattener. Resulting value is fed to the htm.style mapper which assigns it to the node's style aspect specified by the alias.

The space flattener concatenates tokens by a single space, which is useful for joining separate words into a sentence. Here, in <h4> it concatenates the verbal name of a color (taken from the color field of a dataset row), some introductory literals and the color's RGB value (taken from the hex field) into a human-readable predicate. In many cases, the space flattener can be an alternative way of inserting spaces into literals, as shown in <h4>'s d-rule.


Navigation and external data

A rowset can also be obtained from an external file. The simplest case is a static XML dataset.

<div>
 <table>
  <tbody>
   <tr d=" $page=home">//current page will be pointed by a status variable
    <td>
     //populate the menu as a static rowset
     <ul d="* @page:csv=home,pricelist,contacts">
      <li d="! page; htm.v@chosen=eq page $page; ui" u=" page$"/>
     </ul>
    </td>
    <td>
     //the home div is shown when $page is equal to 'home'
     <div d="? $page@home">
	 <h3>Home page</h3>
      <p>This virtual mini-site sells MiG aircrafts.</p>
      <p>Check the pricelist, and choose your toy.</p>
     </div>
     //the pricelist div
     <div d="? $page@pricelist;  $name= $info=">
      //until a model is selected, display an invitation message
      <h3 d="? $name@:!">Select a model from the list below</h3>
      //once the model is chosen, show its info
      <h3 d="? $name@:?">Description of <span d="! $name"></span>:</h3>
      <p d="! $info" style="height: 44px"></p>
      //the models list is taken from external XML file
      <table border="1">
       <tbody d="* :#dat=/samples/pricelist.xml">
        <tr d="ui" u=" name$ description$info">
         <td d="! name"></td>
         <td d="!=space =$ price:fo.num"></td>
        </tr>
       </tbody>
      </table>
     </div>
     //contacts div
     <div d="? $page@contacts">
      <h3>Contact information</h3>
      <p>To purchase a MiG or a Su, please don't hesitate to contact:</p>
      <a href="http://www.roe.ru/" target="_blank">RosOboronExport</a>
     </div>
    </td>
   </tr>
  </tbody>
 </table>
</div>

Home page

This virtual mini-site sells MiG aircrafts.

Check the pricelist, and choose your toy.

Select a model from the list below

Description of :

Contact information

To purchase a MiG or a Su, please don't hesitate to contact:

RosOboronExport

* Product descriptions are taken from Wikipedia.

* Actual prices may differ from given here.

In this example, the data is taken from external XML file: /samples/pricelist.xml. Flat prices from the file are formatted (digit groups separates to better distinguish the number's order of magnitude) by num formatter from starter-kit/formats.xml library.

To highlight the selected menu item, an htm.mark mapper is used in conjuction with :eq flattener. Dap core :eq flattener compares tokens from the token list and succeeds (returns true) when they all have the same value. The htm:mark mapper checks the flattenered value, and if it is true, assigns the specified CSS-class to the node, otherwise removes that CSS-class from the node. Thus, when the status variable $page matches the datarow's page datafield, the mapper assigns .chosen CSS-class to the <li>. When $page and page don't match, the .chosen is taken off the <li>.


Using external libraries

To use an external dap library in the page, the library is loaded by dap core #lib formatter. Earlier on this page we used the starter-kit/htm.xml and starter-kit/formats.xml libraries. The referene to these libraries can be found in this document's <body> d-rule:

<body class="samples" d="% @htm:#lib=starter-kit/htm.xml @fo:#lib=starter-kit/formats.xml">

You may create your own libraries and use them across multiple pages of a project or even across multiple projects. Actually, this is the recommended way of building large-scale dap projects. Building a dap library is even simpler then building a dap powered HTML-page. Detailed description of the process is given in the next lesson.

IMPORTANT: Currently, due to browsers' security restrictions, dap core #-formatters can load data (yes, dap libraries are data, too) only from the same domain, as of the main page. Thus, to use Starter-Kit libraries, you need them downloaded and deployed on your site.


Dap & CSS

The highlight styles used here, might look not very elegant. These styles are simply chosen on this page to be visible, and have no relation to dap functionality. All fonts, colors etc. are defined in respective CSS-styles and dap itself does nothing about visual appearance of page elements.

However, there are, currently two, css-classes related to dap:

In the attached sample.css file, these classes are defined as follows:

.ui{cursor:pointer; }
.over{color:red; }
.chosen{background-color:yellow; } /* not a dap-related class, but addressed by htm.?@chosen clause */
		

In your own work, you will certainly make them more stylish.


Placing the "powered by dap" logo

Please, don't forget to place the "powered by dap" logo (with a hyperlink to dap home page) on your dap-powered page. This will help dap in its World Dominance Plot и спасет отца русской демократии.

<a target="_blank" href="http://dapmx.org">
 <img src="http://dapmx.org/logo/powered-by-dapmx-0-1.gif" alt="DAPMX 0.1" border="0" style="border:none" />
</a>

The preferred place for the logo is somewhere around the bottom-left corner, or anywhere else on your choice.


DAPMX 0.1