Introduction

Here you can find some examples on how to use Mkup in your own projects. I will keep the examples basic to make getting started as easy as possible. The API is ment to be easier to use than to explain, due to the many different parameter types each function understands. This pays off as soon as you get more expierenced with Mkup.

Basics

Adding text

Creating text nodes is simple using the function text(). Calling this function creates a text node as child of the current node:

var mkup = Mkup.mkup($('results'));
mkup.div()
    .text("inside the div")
    .childSpan()
    .text("inside the span")
    .up()
    .text("back inside the div")
    .write();

Result:

<div>
  inside the div
  <span>
    inside the span
  </span>
  back inside the div
</div>

Chained function calls

With Mkup, you can chain function calls to create the markup as needed. This makes the code more readable and makes it reflect more of the html that would be used to create the nodes.

var mkup = Mkup.mkup($('results'));
mkup.div("panel");
mkup.childDiv("hd");
mkup.text("header");
mkup.div("bd")
mkup.text("body");
mkup.div("ft");
mkup.text("footer");
mkup.write();

Creates the same nodes as:

Code:

var mkup = Mkup.mkup($('results'));
mkup.div("panel")
    .childDiv("hd").text("header")
    .div("bd").text("body")
    .div("ft").text("footer")
    .write();

The result is in both cases:

<div class="panel">
  <div class="hd">header</div>
  <div class="bd">body</div>
  <div class="ft">footer</div>
</div>

Navigation: getting around inside the DOM tree

Mkup assumes that following nodes should be added relative to the last one added. When creating child nodes using child() or childX() (where X is the tag name), the cursor moves one step down into the tree. Use up() or its cousin upTo() to move the cursor back up where you want it to be.

Example:

var mkup = Mkup.mkup($('results'));
mkup.child("div").child('ul').child();
for(var i=0; i<3;i++){
    mkup.element('li').child("span").child("em").text('Item #'+i).up().up();
}
mkup.up().up();
mkup.text("back in the top div")
mkup.write();

Result:

<div>
  <ul>
    <li><span><em>Item #0</em></span></li>
    <li><span><em>Item #1</em></span></li>
    <li><span><em>Item #2</em></span></li>
  </ul>
  back in the top div
</div>

The basic rule is simple: for every child() or childX() call, you need to place a call to up() to get where you came from.

If you call up() when the cursor is at the root level, an Error gets thrown.

Counting child() calls to add needed up() calls is not very nice, so mkup contains a method that makes moving around nicer: upTo(refName)

Code:

var mkup = Mkup.mkup($('results'));
mkup.childDiv(null,"topDiv")
    .child('ul')
    .child();
for(var i=0; i<3;i++){
    mkup.li(null,'listItem'+i)
    .childSpan()
    .childEm()
    .text('Item #'+i)
    .upTo('listItem'+i);
}
mkup.upTo("topDiv").childSpan()
    .text("back in the top div")
mkup.write();

Result:

<div>
  <ul>
    <li><span><em>Item #0</em></span></li>
    <li><span><em>Item #1</em></span></li>
    <li><span><em>Item #2</em></span></li>
  </ul>
  <span>back in the top div</span>
</div>

As you can see, upTo() moves the cursor next to the node with the name you use as paramter. The next call will add a node into it.

Using node references

This example shows how to use write(object) to write references to created nodes into a custom object. It uses child() to make the first li() create a child node.

var mkup = Mkup.mkup($('results'));
var items={};
mkup.ul().child();
var i=0;
for(;i<5;i++){
  mkup.li(null,"item"+i).text("Item #"+i);
}
mkup.write(items);

items.item2.update("Hello");

Resulting nodes:

<ul>
  <li>Item #0</li>
  <li>Item #1</li>
  <li>Hello</li>
  <li>Item #3</li>
  <li>Item #4</li>
</ul>