View on GitHub

WebFiori UI Package

In this page:

Introduction

Effective user interaction hinges on a well-crafted front-end, traditionally comprising HTML, CSS, and JavaScript. WebFiori streamlines this process by offering a comprehensive suite of PHP classes. These classes empower developers to build a web page's Document Object Model (DOM) directly within the PHP environment, eliminating the need for manual HTML coding. This fosters an efficient and streamlined approach to front-end development within WebFiori applications. Additionally, WebFiori framework allows the use of basic HTML for the ones who would like to keep the traditional approach of using HTML.

All of this and more was made possible through the user interface library of WebFiori Framework.

Note: This library can be included using composer by including this entry in the require part of the composer.json file: "webfiori/ui":"*" .

WebFiori's Object-Oriented Approach to UI Construction

WebFiori embraces an object-oriented paradigm for crafting user interfaces. Its UI library provides a spectrum of classes, each meticulously designed to map to a specific HTML element. These classes derive functionality from the fundamental HTMLNode class, empowering the creation of any HTML or XML tag structure. This extensible architecture grants developers the flexibility to extend the class [ HTMLNode ] and construct custom elements, fostering the development of highly customized and dynamic user interfaces that perfectly align with application requirements.

All the classes which are related to user interface creation can be found in the namespace webfiori\ui .

The Class HTMLNode

The library consist of many classes which represents different types of HTML elements. All classes are sub-classes of the class HTMLNode . This class basically can be used to represent any HTML or XML tag. The developer can extend this class and create his own custom elements.

The class HTMLDoc

This class represents a virtual HTML document. It can be used to build the DOM of the web page and modify it directly inside PHP.

Note: An instance of the class HTMLDoc is wrapped inside the class WebPage . It is always recommended to use the class WebPage to represent any web page.

Using The Library

Basic Usage

The very basic use case is to have HTML document with a text in its body. The developer can simply create an instance of the class HTMLDoc and add a text to its body:

Code

1 2 3 
                                                    $doc = new HTMLDoc();
$doc->getBody()->text('Hello World!');

The structure of HTML document that be rendered will be similar to the following HTML code:

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 
                                                    <!DOCTYPE html>
<html>
    <head>
        <title>
            Default
        </title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    </head>
    <body itemscope="" itemtype="http://schema.org/WebPage">
        Hello World!
    </body>
</html>

Building More Complex DOM

To add more elements to the body of the document, the class HMLNode can be used. It simply can be used to create any type of HTML element. The developer can extend this class to create his own custom UI components. The library has already a set of pre-made components which are used in the next code sample. A list of the classes which represents the components can be found here . The following code shows how to create a basic login form.

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 
                                                    //Create new instance of "HTMLDoc".
$doc = new HTMLDoc();

// Build a login form.
$body = $doc->getBody();
$body->text('Login to System')->hr();
$form = $body->form(['method' => 'post', 'action' => 'https://example.com/login']);
$form->label('Username:')->br();
$form->input('text', ['placeholder'=>'You can use your email address.', 'style' => 'width:250px'])->br();
$form->label('Password:')->br()
$form->input('password', ['placeholder' => 'Type in your password here.', 'style' => 'width:250px'])->br();
$form->input('submit', ['value' => 'Login']);

The given PHP would be rendered to the following HTML code.

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 
                                                    <!DOCTYPE html>
<html>
    <head>
        <title>
            Default
        </title>
        <meta name = "viewport" content = "width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    </head>
    <body itemscope = "" itemtype = "http://schema.org/WebPage">
        Login to System
        <hr>
        <form method = "post" action = "https://example.com/login">
        </form>
        <label>
            Username:
        </label>
        <br>
        <input type = "text" placeholder = "You can use your email address." style = "width:250px;">
        <br>
        <label>
            Password:
        </label>
        <br>
        <input type = "password" placeholder = "Type in your password here." style = "width:250px;">
        <br>
        <input type = "submit" value = "Login">
    </body>
</html>

Adding Children

It is possible to add children to HTMLNode instance using the method HTMLNode::addChild() . Same method is also availble in the class HTMLDoc::addChild() . The method accepts a string that represents the name of the node that will be added or an instance of the class HTMLNode

Code

1 2 3 4 5 6 7 8 9 10 11 
                                                    $doc = new HTMLDoc();

$superChild = new HTMLNode('section', ['id' => 'main-sec']);
$doc->addChild($superChild);

$superChild->addChild('h1', ['class' => 'section-heading'], false)
           ->text('Section Title');

$superChild->addChild(new HTMLNode('p'), [], false)
           ->text('This is a paragraph.');

The output of the code would be something similar to the following:

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
                                                    <!DOCTYPE html>
<html>
    <head>
        <title>
            Default
        </title>
        <meta name = "viewport" content = "width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    </head>
    <body itemscope itemtype = "http://schema.org/WebPage">
        <section id = "main-sec">
            <h1 class = "section-heading">
                Section Title
            </h1>
            <p>
                This is a paragraph.
            </p>
        </section>
    </body>
</html>

Attributes

Each DOM node can have a set of attributes such as style or class . The class HTMLNode has a generic method which can be used to set any attribute value which is the method HTMLNode::setAttribute() . The method accepts two parameters, the first one is the value of the attribute and the second one is its value.

Code

1 2 3 
                                                    $node = new HTMLNode();
$node->setAttribute('class','red-button');

No Value Attributes

It is possible to have attributes without values (such as the attribute disabled or itemscope ).

Code

1 2 3 4 5 
                                                    $node = new HTMLNode();
$node->setAttribute('class','red-button')
     ->setAttribute('itemscope')
     ->setAttribute('disabled');

This would render to the following HTML.

Code

1 2 3 
                                                    <div class = "red-button" itemscope disabled>
</div>

Setting Multiple Attributes

If developer would like to set the values for more than one attribute at one shot, he can use the method HTMLNode::setAttributes() . The method accespts an array that contains the values of the attributes.

Code

1 2 3 4 5 6 7 8 
                                                    $node = new HTMLNode();
$node->setAttributes([
    'class' => 'red-button',
    'itemscope',
    'disabled',
    'onclick' => 'performAction()'
])->text("I'm a Red Button.");

HTML output:

Code

1 2 3 4 
                                                    <div class = "red-button" itemscope disabled onclick = "performAction()">
    I'm a Red Button.
</div>

Specific Attributes Methods

In addition to the method HTMLNode::setAttribute() , there are methods which are specific for setting different attributes of the node. This section lists the available methods.

Working With HTML Template Files

One of the features of the library that it provides a basic templating engine which only uses slots. It is possible to write HTML document in a separate HTML files and then combine files inside PHP to build the whole document. This can be helpful in making your code reusable.

Loading Template File

Loading HTML files can be achived using the static method HTMLNode::fromFile() . Assuming that there exist the following HTML code and a developer would like to load it into HTMLNode instance.

Code

1 2 3 4 5 6 7 
                                                    <section>
    <h1>Super Page</h1>
    <p>
        This is a paagraph inside my super page.
    </p>
</section>

The following PHP code can be used to load the file.

Code

1 2 3 4 5 6 7 8 
                                                    $component = HTMLNode::fromFile('path/to/template/my-html-file.html');

//Now the developer can modify the component as needed.
$component->setClassName('main-section')
          ->paragraph('Another paragraph inside my super page.')
          ->comment('The element was modified inside PHP.')
          ->paragraph('Hello World!');

The rendered HTML of the given example will be similar to the following:

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 
                                                    <section>
    <h1>Super Page</h1>
    <p>
        This is a paagraph inside my super page.
    </p>
    <p>
        Another paragraph inside my super page.
    </p>
    <!--The element was modified inside PHP.-->
    <p>
        Hello World!
    </p>
</section>

Slots

Slots in simple terms are places in your code that can be filled with values. The values are usually dynamically generated or taken from a storage such as a database or files. Slots in HTML template files are represented using mustache syntax. Any string in your HTML code which is placed between {{}} is considered as slot. Slots can be placed in any place in your HTML code.

Assuming that there exist the following HTML document which has slots:

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 
                                                    <html>
    <head>
        <base href="{{base}}">
        <title>{{page-title}} | {{site-name}}</title>
    </head>
    <body>
        <p>
            Welcome {{visitor}} to my website!
        </p>
        <p>
            This page has slots!
        </p>
        <p>
            You visited this website at {{visit-time}}
        </p>
    </body>
</html>

In order to fill slots with values, the developer have to use the second argument of the method HTMLNode::fromFile() . The second argument is an associative array that can have slots values.

The following code shows how to load the document into HTMLDoc instance and fill the solts with values.

Code

1 2 3 4 5 6 7 8 
                                                    $doc = HTMLNode::fromFile('template.html', [
    'page-title' => 'Welcome to My Website',
    'site-name' => 'Awesome Website',
    'visitor' => 'Ibrahim',
    'visit-time' => date('Y-m-d H:i:s'),
    'base' => 'https://portal.example.com'
]);

The rendered document with filled slots would be similar to the following HTML code.

Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 
                                                    <!DOCTYPE html>
<html>
    <head>
        <base href = "https://portal.example.com">
        <title>
            Welcome to My Website | Awesome Website
        </title>
    </head>
    <body>
        <p>
            Welcome Ibrahim to my website!
        </p>
        <p>
            This page has slots!
        </p>
        <p>
            You visited this website at 2020-09-14 10:26:04
        </p>
    </body>
</html>

Components

The library has a set of pre-made components at which the developer can use to build web pages. The components include most commonly used HTML elements. In addition to the given ones, the developer can extend the class HTMLNode To create his own custom components.

Available components are:

Next: Themes

Previous: The Class Response