brickrouge / brickrouge
A toolkit to create HTML elements
Installs: 1 788
Dependents: 7
Suggesters: 1
Security: 0
Stars: 31
Watchers: 5
Forks: 6
Open Issues: 0
Requires
- php: >=8.0
- ext-mbstring: *
- icanboogie/common: ^2.0
- icanboogie/errors: ^3.0
- icanboogie/prototype: ^5.1
Requires (Dev)
- olvlvl/filecache: dev-master
- phpstan/phpstan: ^1.9
- phpunit/phpunit: ^9.6
README
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
- Support localization
- 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.
Installation
composer require brickrouge/brickrouge
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) { class Color { constructor(el, options) { el.setStyle('background', options.color) el.innerHTML = options.colorName } } Brickrouge.register('Color', (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.
const element = document.getElementById('my-color') const color = Brickrouge.Widget.from(element) // or const color = Brickrouge.from(element)
When a widget has been built
The widget
event is fired after a widget has been built.
Brickrouge.observeWidget(ev => { console.log('A widget has been built:', ev.widget) })
When the DOM is updated
The update
event is fired after the DOM was updated.
Brickrouge.observeUpdate(ev => { console.log('This fragment updated the DOM:', ev.fragment) console.log('These are new custom elements:', ev.elements) console.log('These widgets have been built:', ev.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"> </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:
const element = document.getElementById('myForm') const form = new Brickrouge.Form(element) form.observeComplete(ev => { console.log('complete:', ev.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.
Retrieving the instance associated with a form element
The Form
instance associated with a form element can be retrieved with the retrieve()
method:
const element = document.getElementById('myForm') const form = Brickrouge.Form.from(element)
Note: Unlike
Brickrouge.from()
,Brickrouge.Form.from()
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.
Continuous Integration
The project is continuously tested by GitHub actions.
Code of Conduct
This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.
Contributing
Please see CONTRIBUTING for details.
License
Brickrouge is released under the BSD-3-Clause.