brickrouge/brickrouge

A toolkit to create HTML elements


Keywords
form, bootstrap, html, widget, element
License
BSD-3-Clause

Documentation

Brickrouge

Release Build Status HHVM Code Quality Code Coverage Packagist

Brickrouge helps you create HTML elements and custom HTML elements such as inputs, forms, dropdowns, popover, calendars… with all the CSS and JavaScript required to make them beautiful and magical.

Here are some of its features:

  • Create any kind of HTML element as well as custom HTML elements.
  • Compatible with Bootstrap
  • Standalone and patchable
  • Object-oriented
  • Localization support
  • Populate and validate forms

Brickrouge uses Bootstrap for its style, and MooTools for its magic. Ready under a minute, you'll have everything you need to create beautiful and clean web applications. Together with the framework ICanBoogie, Brickrouge is one of the precious components that make the CMS Icybee.

Please, visit brickrouge.org for more information.

Creating elements

With the Element class you can create any kind of HTML element. The attributes are defined using an array and custom attributes are used to define custom properties.

<?php

use Brickrouge\Element;

echo new Element('div', [

    'data-type' => 'magic',

    'class' => 'well'

]);
<div class="well" data-type="magic" />

Specifying the content of an element

The content of an element, or inner HTML, is specified by either INNER_HTML or CHILDREN custom attributes. INNER_HTML specifies the inner HTML of an element, while CHILDREN specifies the children of an element.

<?php

use Brickrouge\Element;

echo new Element('div', [

    Element::INNER_HTML => "I'm in a (magic) well",

    'data-type' => 'magic',

    'class' => 'well'

]);
<div class="well" data-type="magic">I'm in a (magic) well</div>

Note that CHILDREN always wins over INNER_HTML:

<?php

use Brickrouge\Element;

echo new Element('div', [

    Element::INNER_HTML => "I'm in a (magic) well",
    Element::CHILDREN => [

        '<span>Me too !</span>',

        new Element('span', [ Element::INNER_HTML => "Me three !" ])

    ],

    'data-type' => 'magic',

    'class' => 'well'

]);
<div class="well" data-type="magic"><span>Me too !</span><span>Me three !</span></div>

Specific classes

Altought any HTML element can be created with the Element class, specific classes are available for specific element types. They usually help in creating complex elements. Here is a list of the classes included with Brickrouge:

  • A: A link element.
  • Actions: An actions group that can be used by forms, popovers, dialogs…
  • Alert: An alert element.
  • Button: A button element.
  • Form: A form.
  • Group: A control group element, usually used in forms to group controls.
  • Modal: A modal.
  • Popover: A popover.
  • Searchbox: A searchbox, as found in navigation bars.
  • Text: A text input.

Widgets

Brickrouge's widgets are what is generally called custom HTML elements. Widget types are associated with a JavaScript constructor and Brickrouge makes sure that widgets are constructed when the DOM is ready or updated, or when the widget custom property of an element is obtained.

All widgets mechanisms are handled by the Brickrouge.js library, you might want to check it out.

The following is an example of a very simple widget, when it is constructed its background is set to the color defined by the data attribute color:

<?php

use Brickrouge\Element;

echo new Element('div', [

    Element::IS => "Color",
    Element::INNER_HTML => "Color!",

    'data-color' => "#F0F",
    'data-color-name' => "Fuchsia"

    'id' => 'my-color'

]);

HTML representation of the element:

<div brickrouge-is="Color" id="my-color" data-color="#F0F" data-color-name="Fuchsia">Color!</div>

The widget constructor always takes as arguments the element for which the widget is constructed and the normalized data attributes of that element.

!function (Brickrouge) {

    var Color = new Class({

        initialize: function(el, options) {

            el = document.id(el)
            el.setStyle('background', options.color)
            el.innerHTML = options.colorName

        }

    })

    Brickrouge.register('Color', function (element, options) {

        return new Color(element, options)

    })

} (Brickrouge);

Obtaining the widget associated with an element

The widget custom property is used to obtain the widget associated with an element (if any). If the widget has not yet been created, getting the property creates it. The element associated with a widget is always available through its element property.

var color = Brickrouge.Widget.from(document.id('my-color'))
// or
var color = Brickrouge.from(document.id('my-color'))

console.log('element and options:', color.element, color.options)

When a widget has been built

The widget event is fired after a widget has been built.

Brickrouge.observe('widget', function(widget) {

    console.log('A widget has been built:', widget)

})

When the DOM is updated

The update event is fired after the DOM was updated.

Brickrouge.observe('update', function(fragment, elements, widgets) {

    console.log('This fragment updated the DOM:', fragment)
    console.log('These elements are new to:', elements)
    console.log('These widgets have been built:', widgets)

})

Note: The event is fired a first time after Brickrouge is ran.

Forms

Forms are usually instances of the Form class. The children of the form are specified using the CHILDREN custom attribute, while the actions of the form are specified using ACTIONS. For convenience, hidden values can be specified using HIDDEN.

<?php

namespace Brickrouge;

echo new Form([

    Form::RENDERER => Form\GroupRenderer::class,

    Form::HIDDENS => [

        'hidden1' => 'one',
        'hidden2' => 'two'

    ],

    Form::ACTIONS => [

        new Button('Reset', [ 'type' => 'reset' ]),
        new Button('Submit', [ 'class' => 'primary', 'type' => 'submit' ])

    ],

    Form::CHILDREN => [

        'sender_name' => new Text([

            Group::LABEL => "Sender's name",

            Element::REQUIRED => true

        ]),

        'sender_email' => new Text([

            Group::LABEL => "Sender's e-mail",

            Element::REQUIRED => true,
            Element::VALIDATION => 'email'

        ])

    ],

    'name' => 'sender'

]);

The produced HTML, formatted for readability:

<form name="sender" action="" method="POST" enctype="multipart/form-data" class="has-actions">
    <input type="hidden" name="hidden1" value="one" />
    <input type="hidden" name="hidden2" value="two" />

    <fieldset class="group--primary group no-legend">
        <div class="form-group form-group--sender-name required">
            <label for="autoid--sender-name" class="form-control-label">Sender's name</label>
            <div class="controls">
                <input required="required" type="text" name="sender_name" id="autoid--sender-name" />
            </div>
        </div>

        <div class="form-group form-group--sender-email required">
            <label for="autoid--sender-email" class="form-control-label">Sender's e-mail</label>
            <div class="controls">
                <input required="required" type="text" name="sender_email" id="autoid--sender-email" />
            </div>
        </div>
    </fieldset>

    <div class="form-actions">
        <button type="reset" class="btn">Reset</button>
        <span class="separator">&nbsp;</span>
        <button class="primary btn" type="submit">Submit</button>
    </div>
</form>

Submitting forms using XHR

Forms can be sent using XHR very easily thanks to the JavaScript Form class:

var form = new Brickrouge.Form('myForm', {

    onComplete: function(response) {

        console.log('complete:', response)

    }

});

form.submit()

ICanBoogie operation responses are supported and the following properties are recognized:

  • errors: An array of key/value where key is the name of an element, and value the error message for that element.
  • message: If the request is successful, this property is used as a success message.

The class automatically creates alerts according to this properties. If the replaceOnSuccess option is true the success message is inserted before the form element, which is then hidden.

Retriving the instance associated with a form element

The Form instance associated with a form element can be retrived with the retrieve() method:

var form = document.id('myForm').retrieve('brickrouge.form')

Note: Unlike the widget custom property, brickrouge.form does not create an instance, you need to do that yourself. This might change is the future.

Making private assets accessible from the web

Brickrouge can make unaccessible files–such as assets in the Phar–accessible from the web by copying them to a directory defined by the Brickrouge\ACCESSIBLE_ASSETS constant :

<?php

define('Brickrouge\ACCESSIBLE_ASSETS', __DIR__ . DIRECTORY_SEPARATOR . 'public' . DIRECTORY_SEPARATOR);

?>

<link rel="stylesheet" href="<?= Brickrouge\Document::resolve_url(Brickrouge\ASSETS . 'brickrouge.css') ?>" type="text/css">
<link rel="stylesheet" href="<?= Brickrouge\Document::resolve_url(Brickrouge\ASSETS . 'responsive.css') ?>" type="text/css">

Note: The directory must be writable by PHP.

Patching Brickrouge

Brickrouge was initially designed to work with the framework ICanBoogie. The project has evolved to stand alone and now provides means to patch critical features such as translation, errors handling or form storing/retrieving. Fallback for each feature are provided so you can patch what you need and leave the rest.

How patching works

Brickrouge helpers are defined in the "lib/helpers.php" file. For the most part they are dummy functions. For instance, calls to the Brickrouge\t() function are forwarded to the Brickrouge\Helpers::t() function, and with some magic the calls can be forwared elsewhere.

Helper functions are patched using the Brickroue\Helpers::patch() function.

As a side note, because calls are really handled by the Helpers class, you can either use Brickrouge\t() or Brickrouge\Helpers::t().

Using ICanBoogie translator

For instance, this is how the t() helper function can be patched to use the translator of the framework ICanBoogie:

<?php

Brickrouge\Helpers::patch('t', 'ICanBoogie\I18n\t');

Building Brickrouge

Brickrouge comes with pre-built compressed CSS and JavaScript files, but you might want to play with its source, in which case you might probably want to build it yourself. A Makefile is available for this purpose.

Open a terminal, go to Brickrouge directory, and type "make":

$ cd /path/to/Brickrouge/
$ make

This consolidates the various CSS and JavaScript files and create compressed files in the "assets/" directory. The following files are created:

Note that you need the SASS compiler to compile the CSS files. JavaScript files are compressed using the online Closure compiler.

More information

For more information and a demonstration please visit the Brickrouge homepage.


Requirements

The package requires PHP 5.5 or later. The following packages are also required: icanboogie/prototype and icanboogie/errors.

Installation

The recommended way to install this package is through composer:

$ composer require brickrouge/brickrouge

Cloning the repository

The package is available on GitHub, its repository can be cloned with the following command line:

$ git clone https://github.com/Brickrouge/Brickrouge.git

Documentation

You can generate the documentation for the package and its dependencies with the make doc command. The documentation is generated in the build/docs directory. ApiGen is required. The directory can later be cleaned with the make clean command.

Testing

The test suite is ran with the make test command. PHPUnit and Composer need to be globally available to run the suite. The command installs dependencies as required. The make test-coverage command runs test suite and also creates an HTML coverage report in "build/coverage". The directory can later be cleaned with the make clean command.

The package is continuously tested by Travis CI.

Build Status Code Coverage

License

Brickrouge is licensed under the New BSD License. See the LICENSE file for details.