canteen/html5

Create dynamic, valid HTML5 markup with a simple an intuitive PHP API

Canteen HTML5

Create dynamic, well-formatted HTML5 markup with a simple an intuitive PHP API. This is a fork/rewrite of the Gagawa project. CanteenHTML5 is a concise, flexible and easy to remember API which makes it possible to create simple markup (such as a link) or more complex structures (such a table, document or nested list). All tags and attribute names are validated against the current HTML5 specification., _(*1)

For documentation of the codebase, please see Canteen HTML5 docs., _(*2)

Requirements

This library requires a webserver running PHP 5.3+. Also, the root namespace for the library is Canteen\HTML5., _(*3)

Installation

Install is available using Composer., _(*4)

composer require canteen/html5 dev-master

Including using the Composer autoloader., _(*5)

require 'vendor/autoload.php';

Usage

Basic

To create an HTML node, simply call global html method, passing in the tag name and then any attributes., _(*6)

// Enable the global use of html()
Canteen\HTML5\HTML5::useGlobal();

// Turn on autoloading if not using composer's autoloading
Canteen\HTML5\HTML5::autoload();

echo html('img src=home.jpg');
echo html('img', 'src=home.jpg'); 
echo html('img', array('src'=>'home.jpg')); 

All of these examples would output:, _(*7)

<img src="home.jpg" />

Adding Attributes

There are dfferent ways to add attributes for HTML container nodes such as <p>, <div>, or in the example below, <nav>., _(*8)

1. Part of the tag, _(*9)

   echo html('nav title="Navigation" class=main', 'Welcome');
   

2. As an associative array, _(*10)

   echo html('nav', 'Welcome', array('title'=>'Navigation', 'class'=>'main'));
   

3. As a shorthand string, _(*11)

   echo html('nav', 'Welcome', 'title="Navigation" class=main');
   

4. As an property methods, _(*12)

   $nav = html('nav', 'Welcome');
   $nav->class = 'main';
   $nav->title = 'Navigation';
   echo $nav;
   

All of these examples output the same markup:, _(*13)

<nav title="Navigation" class="main">Welcome</nav>

Adding Nested Elements

Any HTML5 container tags (such as <p>, <span>, or <div>) can have child elements. These elements can be strings or other HTML5 element objects., _(*14)

$label = html('span', 'Website!');
$link = html('a', $label);
$link->href = 'http://example.com';
echo $link; 

Alternatively, use the addChild method for any container tag., _(*15)

$link = html('a');
$link->href = 'http://example.com';
$link->addChild(html('span', 'Website!'));
echo $link;

Or appendTo to target a container to be added to:, _(*16)

$link = html('a');
$link->href = 'http://example.com';
html('span', 'Website!')->appendTo($link);
echo $link;

All examples would output:, _(*17)

<a href="http://example.com"><span>Website!</span></a> 

CSS Selectors

Tag names can optionally have CSS-style class and id selectors:, _(*18)

echo html('a#example'); //<a id="example"></a>
echo html('span.small'); //<span class="small"></span>
echo html('span.small.label'); //<span class="small label"></span>
echo html('span#example.small.label'); //<span id="example" class="small label"></span>

API Documentation

For self-closing elements (e.g. <br>, <img>)

html($tag, $attributes=null);

• $tag {string} The name of the valid HTML5 element which can contain CSS selectors or short-hand attribute string.
• $attributes {array | string} (optional) Collection of element attributes

Returns a Canteen\HTML5\Node object., _(*19)

Node Methods

• setAttribute($name, $value) Set an attribute by name and value.
• setAttributes($values) Set an associative array of name/value pairs.
• setData($name, $value) Set data-* fields on the HTML5 element.
• getData($name) Get the data-* field on the HTML5 element.
• appendTo(NodeContainer $container) Add the element to the end of a container element.
• prependTo(NodeContainer $container) Add the element to the beginning of a container element.

For container HTML elements (e.g. <p>, <div>)

html($tag, $contents=null, $attributes=null);

• $tag {string} The name of the valid HTML5 element which can contain CSS selectors or short-hand attribute string.
• $contents {string | Node | NodeContainer} (optional) The string of the contents of the tag, or another element created by html()
• $attributes {array | string} (optional) Collection of element attributes

Returns a Canteen\HTML5\NodeContainer object., _(*20)

NodeContainer Methods (extends Node)

• addChild($node) Add a Node object to the bottom of the collection of nodes
• addChildAt($node, $index) Add a Node object at a specific zero-based index
• removeChild($node) Remove a particular node from the container
• removeChildAt($index) Remove a node by zero-based index
• removeChildren() Remove all children from the container
• getChildren() Get the collection of all Node objects
• getChildAt($index) Get a Node object at a specific index

Additional Components

Document

The Document object is used for creating a bare-bones HTML5 document., _(*21)

Canteen\HTML5\Document($title='', $charset='utf-8', $beautify=false);

• $title {string} (optional) The title of the document
• $charset {string} (optional) The HTML character set to use
• $beautify {boolean} (optional) If the output should be an indented work of art.

Properties, _(*22)

• head {NodeContainer} The document's <head> element
• body {NodeContainer} The document's <body> element
• title {NodeContainer} The document's <title> element

    use Canteen\HTML5\Document;
    $doc = new Document('Untitled');
    $doc->head->addChild(html('script src=main.js'));
    $doc->body->addChild(html('div#frame'));
    echo $doc;

SimpleList

The SimpleList for conveniently creating <ul> and <ol> elements., _(*23)

Canteen\HTML5\SimpleList($elements, $attributes=null, $type="ul");

• $elements {array} The collection of strings or other HTML elements
• $attributes {array | string} (optional) Collection of element attributes
• $type {string} (optional) A value of either "ul" or "ol"

Table

The Table object is used for creating <table> elements., _(*24)

Canteen\HTML5\Table($data, $headers=null, $checkbox=null);

• $data {array} The collection of associative-arrays with key/value pairs
• $headers {array} (optional) The names of the header labels
• $checkbox {string} (optional) The name of the key name in the data to replace with a checkbox, for instance "id"

// Create a sample table with some rows of dummy data
$table = new Table(
    array(
        array('id'=>1, 'first'=>'James', 'last'=>'Smith'),
        array('id'=>2, 'first'=>'Mary', 'last'=>'Denver'),
        array('id'=>3, 'first'=>'Charlie', 'last'=>'Rose')
    ),
    array('ID', 'First Name', 'Last Name')
);

Rebuild Documentation

This library is auto-documented using YUIDoc. To install YUIDoc, run sudo npm install yuidocjs. Also, this requires the project CanteenTheme be checked-out along-side this repository. To rebuild the docs, run the ant task from the command-line., _(*25)

ant docs

License

Copyright (c) 2013 Matt Karl, _(*26)

Released under the MIT License., _(*27)