Brickrouge
, (*1)
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., (*2)
Here are some of its features:, (*3)
- 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., (*4)
Please, visit brickrouge.org for more information., (*5)
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., (*6)
'magic',
'class' => 'well'
]);
```
```html
```
### 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
"I'm in a (magic) well",
'data-type' => 'magic',
'class' => 'well'
]);
```
```html
I'm in a (magic) well
```
Note that `CHILDREN` always wins over `INNER_HTML`:
```php
"I'm in a (magic) well",
Element::CHILDREN => [
'Me too !',
new Element('span', [ Element::INNER_HTML => "Me three !" ])
],
'data-type' => 'magic',
'class' => 'well'
]);
```
```html
Me too !Me three !
```
## 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](https://www.google.com/search?q=html+custome+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
"Color",
Element::INNER_HTML => "Color!",
'data-color' => "#F0F",
'data-color-name' => "Fuchsia"
'id' => 'my-color'
]);
```
HTML representation of the element:
```html
Color!
```
The widget constructor always takes as arguments the element for which the widget is constructed
and the normalized data attributes of that element.
```js
!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.
```js
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.
```js
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.
```js
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
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:
```html
```
### Submitting forms using XHR
Forms can be sent using XHR very easily thanks to the JavaScript `Form` class:
```js
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:
```js
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
<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., (*7)
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., (*8)
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., (*9)
Helper functions are patched using the Brickroue\Helpers::patch() function., (*10)
As a side note, because calls are really handled by the Helpers class, you can either use
Brickrouge\t() or Brickrouge\Helpers::t()., (*11)
Using ICanBoogie translator
For instance, this is how the t() helper function can be patched to use the
translator of the framework ICanBoogie:, (*12)
<?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., (*13)
Open a terminal, go to Brickrouge directory, and type "make":, (*14)
$ 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:, (*15)
Note that you need the SASS compiler to compile the CSS files. JavaScript
files are compressed using the online Closure compiler., (*16)
For more information and a demonstration please visit the Brickrouge homepage., (*17)
Continuous Integration
The project is continuously tested by GitHub actions., (*18)
, (*19)
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., (*20)
Contributing
Please see CONTRIBUTING for details., (*21)
License
Brickrouge is released under the BSD-3-Clause., (*22)
Wallogit.com
