Cape.MarkupBuilder - API Reference

General notes - #a(), #abbr(), #address() - #area(), #base(), #br() - #attr() - #btn() - #checkBox() - #checked() - #class() - #css() - #data() - #disabled() - #elem() - #fa() - #fieldsFor() - #formFor() - #hiddenField() - #labelFor() - #markup() - #on() - #onblur(), #onfocus(), etc. - #passwordField() - #radioButton() - #selectBox() - #sp() - #space() - #text() - #textareaField() - #textField()

General notes

All instance methods of Cape.MarkupBuilder are chainable. Each method returns the instance itself.

Example

var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.p(function(m) {
      m.text('Hello,').sp().text(this.guest.name).text('!');
      // The above single statement is equivalent to the
      // following four statement;
      //   m.text('Hello,');
      //   m.sp();
      //   m.text(this.guest.name);
      //   m.text('!');
    })
  }
})

All instance methods except #attr, #class, #css, #data, #sp, #space and #text take the options argument, which will be translated into the attributes of element to be created.

Example

var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.p(function(m) {
      m.p('Hello, world!', { title: 'greeting' });
      // The above code generates the following <p> tag:
      //   <p title="greeting">Hello, world!</p>
    })
  }
})

When the options argument has a visible key and its value is falsey (false, null, 0, [], etc.), it sets the display style to none to make this element invisible.

Example

var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.p(function(m) {
      m.p('Hello, world!',
        { visible: Date.now().getDay() === 0 });
      // On sunday, the above code generates the following:
      //   <p>Hello, world!</p>
      // On other days:
      //   <p style="display: none">Hello, world!</p>
    })
  }
})

#a(), #abbr(), #address(), etc.

Usage

  • a(content [, options])
  • a([options,] function)
  • abbr(content [, options])
  • abbr([options,] function)
  • address(content [, options])
  • address([options,] function)
  • etc.

Following HTML 5 elements can be added to the virtual dom tree by the markup builder’s method with the same name:

a, abbr, address, article, aside, audio, b, bdi, bdo, blockquote, body, button, canvas, caption, cite, code, colgroup, datalist, dd, del, details, dfn, dialog, div, dl, dt, em, embed, fieldset, figcaption, figure, footer, h1, h2, h3, h4, h5, h6, head, header, html, i, iframe, ins, kbd, label, legend, li, main, map, mark, menu, menuitem, meter, nav, noscript, object, ol, optgroup, option, output, p, pre, progress, q, rp, rt, ruby, s, samp, script, section, select, small, span, strong, style, sub, summary, sup, table, tbody, td, textarea, tfoot, th, thead, time, title, tr, u, ul, var, video

When the first argument is a string, it becomes the content of element. When the last argument is a function, it creates a dependent virtual dom tree.

Example

var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.article(function(m) {
      m.p('The agenda for the meeting is as follows:');
      m.ul(function(m) {
        m.li('Performance of business');
        m.li('Challenges on business');
        m.li('Our next goal');
      })
    })
  }
});

You can pass a hash object as options to these methods to set the attribute values of the element. The position of this argument should be after the string argument and before the function argument.

Example

var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.article({ id: 'agenda' }, function(m) {
      m.p('The agenda for the meeting is as follows:',
        { className: 'statement' });
      m.ul({ style: 'color: blue' }, function(m) {
        m.li('Performance of business');
        m.li('Challenges on business');
        m.li('Our next goal');
      })
    })
  }
});

#area(), #base(), #br(), etc.

Usage

  • area([options])
  • base([options])
  • br([options])
  • etc.

Following HTML 5 void elements can be added to the virtual dom tree by the markup builder’s method with the same name:

area, base, br, col, embed, hr, img, input, keygen, link, menuitem, meta, param, source, track, wbr

They don’t take a string argument nor a function argument, though. They only accept a hash object to set the attribute values of the element.

Example

var LogoMark = Cape.createComponentClass({
  render: function(m) {
    m.div({ id: 'agenda' }, function(m) {
      m.img({ src: '../images/logo.png', alt: 'Logo Image' })
    })
  }
});

#attr()

Usage

  • attr(name, value)
  • attr({ name1: value1, name2: value2, … })

Set the value of attributes for the element which will be added nextly.

Example

render: function(m) {
  m.attr('alt', 'Logo Image');
  // Or, m.attr({ alt: 'Logo Image' });
  m.img({ src: '../images/logo.png' });
  // These two statements are equivalent to the following
  // single statement:
  //   m.img({ src: '../images/logo.png',
  //           alt: 'Logo Image' })
}

The attribute values are set cumulatively.

Example

render: function(m) {
  m.attr('alt', 'Logo Image');
  m.attr('width', '180');
  m.attr('height', '120');
  m.attr('title', 'Cape.JS');
  m.img({ src: '../images/logo.png' });
  // These two statements are equivalent to the following
  // single statement:
  //   m.img({ src: '../images/logo.png',
  //           alt: 'Logo Image',
  //           width: '180', height: '120',
  //           title: 'Cape.JS' })
}

The values set by #attr does not affect the elements created after the next element.

Example

render: function(m) {
  m.attr('alt', 'Logo Image');
  m.img({ src: '../images/logo.png' });
  m.img({ src: '../images/download.png' });
  // The last statement creates a <img> tag without
  // alt attribute.
}

#checkBox()

Usage

  • checkBox(name, [options,] function)

Create a <input type="checkbox"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name". See #formFor for details.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.labelOf('privileged', function(m) {
      m.checkBox('privileged');
    });
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <label for="user-field-privileged">
  //       <input type="checkbox" name="user.privileged"
  //         id="user-field-privileged">
  //     </label>
  //   </form>
}

#btn()

Usage

  • btn(content, options)
  • btn(options, callback)

Create a <button> element whose type attribute is set to button by default.

Example

render: function(m) {
  m.formFor('test', function(m) {
    m.btn('Click');
  });
  // The above code generates the following HTML tags
  //   <form name="test">
  //     <button type="button">Click</button>
  //   </div>
}

#checked()

Usage

  • checked(boolean)

This is a shortcut method which has the same effect with #attr('checked', boolean). See #attr().

Example

render: function(m) {
  m.checked(true).input({ type: 'checkbox' })
  // The above code generates the following HTML tag
  //   <input type="checkbox" checked>
}

#class()

Usage

  • class(name)
  • class(names)
  • class({ name1: boolean1, name2: boolean2, … })

Set the class attribute value for the element which will be added nextly.

Example

render: function(m) {
  m.class('container');
  m.div(function(m) {
    m.p('Hello, World!')
  });
  // The above code generates the following HTML tags
  //   <div class="container">
  //     <p>Hello, World!</p>
  //   </div>
}

Example

render: function(m) {
  m.class('panel panel-standard');
  m.div('Hello World!');
  // The above code generates the following HTML tags
  //   <div class="panel panel-standard">
  //     Hello, World!
  //   </div>
}

Example

render: function(m) {
  m.class({ panel: true, 'panel-standard': true, top: false });
  m.div('Hello World!');
  // The above code generates the following HTML tags
  //   <div class="panel panel-standard">
  //     Hello, World!
  //   </div>
}

As #attr, the #class method add classes cumulatively and affects only the nextly added element.

#css()

Usage

  • css(name, value)
  • css({ name1: value1, name2: value2, … })

Set the styles for the element which will be added nextly.

Example

render: function(m) {
  m.css('color', 'red').span('Danger');
  // This is equivalent to the following statement:
  //   m.span('Danger', { style: 'color: red' })
}

Note that you should write names of style in camel case.

Example

render: function(m) {
  m.css({ backgroundColor: 'red' }).p('Danger');
  // This is equivalent to the following statement:
  //   m.p('Danger', { style: 'background-color: red' })
}

#data()

Usage

  • data(name, value)
  • data({ name1: value1, name2: value2, … })

Set the data-* attribute value for the element which will be added nextly.

Example

render: function(m) {
  m.data('id', '7');
  m.div(function(m) {
    m.p('Hello, World!')
  });
  // The above code generates the following HTML tags
  //   <div data-id="7">
  //     <p>Hello, World!</p>
  //   </div>
}

As #attr, the #data method sets attribute values cumulatively and affects only the nextly added element.

Example

render: function(m) {
  m.data({ id: '7' });
  m.p('Hello, World!');
  m.p('Hello, World!');
  // The above code generates the following HTML tags
  //   <p data-id="7">Hello, World!</p>
  //   <p>Hello, World!</p>
}

The names specified in camel case are converted into a string separated by dashes.

Example

render: function(m) {
  m.data({ messageId: '7' });
  m.p('Hello, World!');
  // The above code generates the following HTML tags
  //   <p data-message-id="7">Hello, World!</p>
}

#disabled()

Usage

  • disabled(boolean)

This is a shortcut method which has the same effect with #attr('disabled', boolean). See #attr().

Example

render: function(m) {
  m.disabled(true).input({ type: 'text' })
  // The above code generates the following HTML tag
  //   <input type="text" disabled>
}

#elem()

Usage

  • elem(content [, options])
  • elem([options,] function)

Create an HTML element. The first argument is a CSS selector, such as "div.container".

When the second argument is a string, it becomes the content of element. When the last argument is a function, it creates a dependent virtual dom tree.

Example

render: function(m) {
  m.elem('div#wrapper', function(m) {
    m.elem('div.container', function(m) {
      m.elem('div.row', function(m) {
        m.elem('div.col-md-6', 'Hello');
        m.elem('div.col-md-6', 'World');
      })
    })
  })
  // The above code generates the following HTML tags
  //   <div id="wrapper">
  //     <div class="container">
  //       <div class="row">
  //         <div class="col-md-6">Hello</div>
  //         <div class="col-md-6">World</div>
  //       </div>
  //     </div>
  //   </div>
}

You can pass a hash object as options to these methods to set the attribute values of the element. The position of this argument should be after the string argument and before the function argument.

Example

render: function(m) {
  m.elem('div#wrapper', { style: 'margin-top: 10px' },
    function(m) {
    m.elem('div.container', function(m) {
      m.elem('div.row', function(m) {
        m.elem('div.col-md-6', 'Hello',
          { style: 'font-weight: bold' });
        m.elem('div.col-md-6', 'World');
      })
    })
  })
  // The above code generates the following HTML tags
  //   <div id="wrapper" style="margin-top: 10px">
  //     <div class="container">
  //       <div class="row">
  //         <div class="col-md-6"
  //           style="font-weight: bold">Hello</div>
  //         <div class="col-md-6">World</div>
  //       </div>
  //     </div>
  //   </div>
}

#fa()

Usage

  • fa(name [, options])

Add a font awesome icon (actually, it is just an empty <i> tag) to the virtual dom tree. Its first argument is the icon’s name, such as "download", "gear", etc. You can pass a hash object as the optional second argument to set the attribute values of <i> tag.

Example

render: function(m) {
  m.a({ href: './download.html' }, function(m) {
    m.fa('download').text(' Download');
  })
  // The above code generates the following HTML tags
  //   <a href="./download.html">
  //     <i class="fa fa-download"></i> Download</a>
}

#fieldsFor()

Usage

  • fieldsFor(name, [options,] function)

Create a scope for nested forms. In this scope, a prefix is addded to the name of each form control.

Example

render: function(m) {
  m.form(function(m) {
    m.textField('name');
    m.fieldsFor('home_address', function(m) {
      m.textField('city');
      m.textField('street');
    })
  })
  // The above code generates the following HTML tags
  //   <form>
  //     <input type="text" name="name">
  //     <input type="text" name="home_address/city">
  //     <input type="text" name="home_address/street">
  //   </form>
}

If you pass the index option to this method, the prefix is numbered:

Example

render: function(m) {
  m.form(function(m) {
    m.textField('name');
    m.fieldsFor('address', { index: 1 } function(m) {
      m.textField('city');
      m.textField('street');
    })
    m.fieldsFor('address', { index: 2 } function(m) {
      m.textField('city');
      m.textField('street');
    })
  })
  // The above code generates the following HTML tags
  //   <form>
  //     <input type="text" name="name">
  //     <input type="text" name="address/1/city">
  //     <input type="text" name="address/1/street">
  //     <input type="text" name="address/2/city">
  //     <input type="text" name="address/2/street">
  //   </form>
}

#formFor()

Usage

  • formFor(name, [options,] function)

Create a <form> tag whose name attribute is name.

Using this method instead of #form, the form name prefix is added to the name attribute of subordinate form controls.

The id attribute is set automatically. When the form name is 'foo', the id attribute of a form control whose name is bar becomes 'foo-field-bar'.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.textField('name');
    m.checkBox('privileged');
  })
  // The above code generates the following HTML tags
  //   <form name="user">
  //     <input type="text" name="user.name"
  //       id="user-field-name">
  //     <input type="hidden" name="user.privileged"
  //       value="0">
  //     <input type="checkbox" name="user.privileged"
  //       id="user-field-privileged" value="1">
  //   </form>
}

#hiddenField()

Usage

  • hiddenField(name, [options,] function)

Create a <input type="hidden"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.hiddenField('privileged');
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <input type="hidden" name="user.privileged"
  //       id="user-field-privileged">
  //   </form>
}

#labelFor()

Usage

  • labelFor(name, label)

Create a <label> tag whose name attribute is name. Its for attribute is set appropriately.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.div(function(m) {
      m.labelFor('name', 'User name').sp().textField('name');
    });
    m.fieldsFor('home_address', function(m) {
      m.div(function(m) {
        m.labelFor('city', 'City').sp().textField('city');
      });
      m.div(function(m) {
        m.labelFor('street', 'Street').sp().textField('street');
      });
    });
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <div>
  //       <label for="user-field-name">User name</label>
  //       <input type="text" name="user.name"
  //         id="user-field-name">
  //     </div>
  //     <div>
  //       <label for="user-field-home-address-city">
  //         City</label>
  //       <input type="text" name="user.home-address/city"
  //         id="user-field-home-address-city">
  //     </div>
  //     <div>
  //       <label for="user-field-home-address-street">
  //         Street</label>
  //       <input type="text"
  //         name="user.home-address/street"
  //         id="user-field-home-address-street">
  //     </div>
  //   </form>
}

#markup()

This method is for internal use. Do not override it.

#on()

Usage

  • on(eventName, function)

Set the handler of event eventName for the element which will be added nextly to function.

Example

render: function(m) {
  m.on('click', function(e) { this.counter++ });
  m.on('dblclick', function(e) { this.counter = 0 });
  m.span('Click me!');
  // These two statements are equivalent to the following
  // single statement:
  //   m.span('Click me!',
  //     { onclick: function(e) { this.counter++ },
  //       ondblclick: function(e) { this.counter = 0 } })
}

The attribute values are set cumulatively.

#onblur(), #onfocus(), etc.

Usage

  • onblur(function)
  • onfocus(function)
  • etc.

These are shortcut methods which have same effects with #on('blur', function), #on('focus', function), etc.

Similar shortcut methods are defined for the following events:

blur, focus, change, select, submit, reset, abort, error, load, unload, click, dblclick, keyup, keydown, keypress, mouseout, mouseover, mouseup, mousedown, mousemove

Example

render: function(m) {
  m.onclick(function(e) { this.counter++ });
  m.ondblclick(function(e) { this.counter = 0 });
  m.span('Click me!');
  // These two statements are equivalent to the following
  // single statement:
  //   m.span('Click me!',
  //     { onclick: function(e) { this.counter++ },
  //       ondblclick: function(e) { this.counter = 0 } })
}

#passwordField()

Usage

  • passwordField(name, [options,] function)

Create a <input type="password"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.passwordField('password');
    m.passwordField('password_confirmation');
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <input type="password" name="user.password"
  //       id="user-field-password">
  //     <input type="password"
  //       name="user.password_confirmation"
  //       id="user-field-password-confirmation">
  //   </form>
}

#radioButton()

Usage

  • radioButton(name, value[, options])

Create a <input type="radio"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

The second argument becomes the value of this radio button.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.label('A', function(m) {
      m.radioButton('plan', 'a');
    })
    m.label('B', function(m) {
      m.radioButton('plan', 'b');
    })
    m.label('C', function(m) {
      m.radioButton('plan', 'c');
    })
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <label>
  //       <input type="radio" name="user.plan"
  //         id="user-field-plan-a" value="a">A
  //     </label>
  //     <label>
  //       <input type="radio" name="user.plan"
  //         id="user-field-plan-b" value="b">B
  //     </label>
  //     <label>
  //       <input type="radio" name="user.plan"
  //         id="user-field-plan-c" value="c">C
  //     </label>
  //   </form>
}

#selectBox()

  • selectBox(name, [options,] callback)

Create a <select> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.selectBox('plan', function(m) {
      m.option('A', { value: 'a' });
      m.option('B', { value: 'b' });
      m.option('C', { value: 'c' });
    })
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //      <select name="plan" id="user-field-plan">
  //        <option value="a">A</option>
  //        <option value="b">B</option>
  //        <option value="c">C</option>
  //      </select>
  //   </form>
}

#sp()

This is an alias to #space().

#space()

Usage

  • space()

Add a single space character. Same as text(' ').

Example

render: function(m) {
  m.p(function(m) {
    m.text(this.message);
    m.space();
    m.strong(this.name);
    m.text('!');
  })
}

#text()

Usage

  • text(string)

Add string as a text node to the virtual dom tree. The special characters (<, >, &) are escaped automatically.

Example

render: function(m) {
  m.h1(function(m) {
    m.text(this.title).sp();
    m.small(this.subtitle);
  })
}

If you want to create a content from a string without escaping it, use innerHTML property:

render: function(m) {
  m.p({ innerHTML: '&copy; <span>Foo Bar, Inc.</span>' })
}

#textareaField()

Usage

  • textField(name, [options,] function)

Create a <input type="text"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.labelFor('remarks', 'Remarks').br();
    m.textareaField('remarks');
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <label for="user-field-remarks">
  //       Remarks</label><br />
  //     <textarea name="user.remarks"
  //       id="user-field-remarks"></textarea>
  //   </form>
}

#textField()

Usage

  • textField(name, [options,] function)

Create a <input type="text"> tag tailored for form manipulation. Its first argument is the base of name attribute value. If the surrounding <form> tag has a name "user", then the name attribute becomes "user.name".

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.labelFor('login_name', 'Login Name').sp();
    m.textField('login_name');
  });
  // The above code generates the following HTML tags:
  //   <form name="user">
  //     <label for="user-field-login-name">
  //       Login Name</label>
  //     <input type="text" name="user.login_name"
  //       id="user-field-login-name">
  //   </form>
}