Create dynamic, valid HTML5 markup with a simple an intuitive PHP API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
src
.gitattributes
.gitignore
LICENSE
README.md
build.properties
build.xml
composer.json
docs.json

README.md

#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.

For documentation of the codebase, please see Canteen HTML5 docs.

##Requirements

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

##Installation

Install is available using Composer.

composer require canteen/html5 dev-master

Including using the Composer autoloader.

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.

// 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:

<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>.

  1. Part of the tag

    echo html('nav title="Navigation" class=main', 'Welcome');
  2. As an associative array

    echo html('nav', 'Welcome', array('title'=>'Navigation', 'class'=>'main'));
  3. As a shorthand string

    echo html('nav', 'Welcome', 'title="Navigation" class=main');
  4. As an property methods

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

All of these examples output the same markup:

<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.

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

Alternatively, use the addChild method for any container tag.

$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:

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

All examples would output:

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

###CSS Selectors

Tag names can optionally have CSS-style class and id selectors:

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.

####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.

####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.

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

  • 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.

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.

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.

ant docs

##License##

Copyright (c) 2013 Matt Karl

Released under the MIT License.