kwebble/hadroton

This package is abandoned and no longer maintained. The author suggests using the kwebble/fillum-html package instead.

A PHP library to create HTML documents using PHP syntax

Maintainers

Details

github.com/kwebble/hadroton

Source

Issues

Installs: 16

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

0.1 2018-08-07 07:54 UTC

Requires

  • php: >=7.1

Requires (Dev)

MIT a81a98b8ffce465abf807e25f4190f788c97c353

This package is not auto-updated.

Last update: 2019-02-20 18:59:44 UTC

README

Open source PHP library to create HTML 5 documents in code.

Copyright © 2016, 2017, 2018 Rob Schlüter

Licensed under the MIT License. For details see the included LICENSE file.

The source code of this project is hosted on GitHub: https://github.com/kwebble/fillum-html

You can contact me through the contact form on my website: http://kwebble.com/about

Status

This project follows the version numbering rules of Semantic Versioning 2.0.0.

This means the current version is an unstable development version. Do not use this software in production environments yet.

Description

This library can generate HTML in PHP code. The advantages of using this library over a dedicated templating system:

  • there is no need to learn and use a separate template language to create HTML output.
  • all normal PHP tools to develop, refactor and test source code can be used.
  • web pages and their elements are PHP objects. This allows normal manipulation using object oriented techniques.
  • there are no separate templates to compile or interpret.

The shortest way to generate HTML documents and elements is with the HtmlToolbox class. It has a set of static methods to create common HTML elements. The methods names match the HTML elements they create. So there's an a method to create links, ol, ul and li methods to create lists etc. For example:

    use kwebble\fillum\html\HtmlToolbox as H;

    $h = new Document();

    $h->appendBody(
        H::div(['class' => 'top'], H::h1('Welcome to Fillum HTML'))
      , H::div( ['class' => 'content']
              , H::p('This is some text.')
              , H::p('Here is another paragraph.')
        )
    );

    echo $h->toHtml();

First the alias H is created to reference the HtmlToolbox class. This is the common alias for the toolbox and used throughout this documentation.

Then a document is created:

    $h = new Document();

An initial document contains 2 empty elements, a head and body.

Finally 2 divisions are added to the body of the document. The result is a HTML document with this structure:

    <html>
        <head></head>
        <body>
            <div class="top">
                <h1>Welcome to Fillum HTML</h1>
            </div>
            <div class="content">
                <p>This is some text.</p>
                <p>Here is another paragraph.</p>
            </div>
        </body>
    </html>

Finally the HTML representation is generated with toHtml and echoed.

Using the Element class

The toolbox does not include methods for every HTML element. If elements are required that the toolbox does not include use the Element class.

This is how to create individual elements:

    $sidebar = new Element('aside');

To include attributes provide them as an array of names and values:

    $sidebar = new Element('aside', ['id' => 'sidebar', 'class' => 'related-products']);

The contents of an element can be passed in the constructor or added later. This uses the constructor to add a paragraph:

    $sidebar = new Element('aside', [], new Element('p', [], 'You might like these'));

The constructor also accepts multiple elements:

    $sidebar = new Element('aside', [],
        new Element('h1', [], 'Related products')
      , new Element('p', [], 'You might like these')
    );

The contents can be text:

    $p = new Element('p', [], 'Hello and welcome');

note: Fillum HTML does not check if the structure of the passed contents are valid. For example it is possible to put text in a ol-element or a p-element in a header.

Adding data

To add data to an existing element use the append method. This adds the content after all current elements:

    $div = H::div();
    $div->append(H::h1('Welcome here'));

To add multiple elements there are two options. First, append accepts more elements just like the constructor:

    $div->append(
        H::p('This is some text.')
      , H::p('Here is another paragraph.')
    );

The second option is to use the fluent interface of append:

    $div->append(H::p('This is some text.')
        ->append(H::p('Here is another paragraph.');

It is allowed to pass an array to append:

    $div = H::div();

    $text = [
        H::p('The first paragraph.')
      , H::p('Paragraph number 2.')
    ]

    $div->append($text);

Creating your own HTML structures

In most situations a web page consists of a number of separate parts. For example a header with menu and search bar, a sidebar or a container for videos.

With Fillum HTML you can define these elements as classes and let them generate their HTML. Such custom parts should extend the Element class.

Here is an example class for a simple search form with an input field and submit button:


    use kwebble\fillum\html\HtmlToolbox as H;
    use kwebble\fillum\html\Element;
    use kwebble\fillum\html\HtmlConstants;

    /** A search form.
     */
    class SearchForm extends Element {

    /** Creates the form.
     */
    public function __construct() {
        parent::__construct(
            'form'
          , ['method' => 'GET', 'action' => '/find']
          , H::input(HtmlConstants::INPUT_TYPE_TEXT, 'q')
          , H::button(HtmlConstants::BUTTON_TYPE_SUBMIT, 'Go')
        );
    }
}

As you can see the code uses values from the HtmlConstants class. This is a class that defines a number of constants for commnon values in HTML.

The SearchForm class can be used as any part of a webpage:

    use kwebble\fillum\html\HtmlToolbox as H;

    $h = new Document();
    $h->appendBody(new SearchForm());

    echo $h->toHtml();

Predefined constants

Creating elements from text

The StringInterpreter class can turn a string with HTML to Elements.

    // Assume $html is filled with HTML created elsewhere.

    use kwebble\fillum\html\Document;
    use kwebble\fillum\html\StringInterpreter;

    $h = new Document();
    $h->append((new StringInterpreter())->fromHtml($html));

    echo $h->toHtml();

The input can be cleaned up by using a filter that defines which elements and attributes are kept. This filter only allows p, a and img tags, href in the a element and src in the img element:

    use kwebble\fillum\html\Document;
    use kwebble\fillum\html\StringInterpreter;

    $allowed = [
        'p'   => [],
        'a'   => ['href'],
        'img' => ['src']
    ];

    $h = new Document();
    $h->append((new StringInterpreter($allowed))->fromHtml($html));

    echo $h->toHtml();

Generating HTML output

To generate the HTML that repesents the document use the toHtml() method:

    use kwebble\fillum\html\Document;

    $h = new Document();

    $h->append(new Element('p', [], 'This is some text.')
      ->append(new Element('p', [], 'Here is another paragraph.');

    $h->toHtml();