HTML Class

HTML output for Model based input templates

The HTML Class is providing some essential HTML output methods, primarily for creating HTML Form elements. It allows you more access control over your forms and generates Templator compliant HTML.

The HTML Class is extended by the Model Class, and thus also indirectly by your Item type classes. That means all the HTML methods are also available through any Item type Class, such as fx. the TypePost Class, but also in any other Class that extends the Model Class. When invoking an HTML method through a Type Class or similar, the methods can utilize the defined Model entities, allowing you too easily create HTML inputs for any entity in your Model.

The HTML Class is also conveniently auto-instantiated as a global $HTML variable in Janitor, and the $HTML instance is directly available in all templates, which are loaded using the template methods of the Page Class (Page::page, Page::header, Page::footer and Page::template). When invoking HTML methods directly through the $HTML instance, there is no link to the model – only by invoking these methods through a Type Class or similar, will they be able to use Model entities as data source.

As with most other system classes in Janitor, the HTML Class is actually split into a HTML Class and a HTML Core Class. It is in fact the HTML Core Class that provides the methods below – the HTML Class is only intended as a placeholder for your additions or customisations.

Functions

HTML::attribute

Definition

Name
HTML::attribute
Syntax
_returntype_ = HTML::attribute( String $attribute_name [, Mixed $attribute_value ]*N );

Description

Creates an HTML attribute of type $attribute_name, with values passed as individual successive parameters. You can pass as many $attribute_value's as you desire.

Attribute values that resolve to false or empty strings will be ignore.

If all passed attribute values resolve negatively (to false or empty string), the method will return an empty string, as an attribute without values, doesn't make any sense.

This method can conveniently be used to add a number of yet undetermined className values to a class attribute.

Parameters

$attribute_name
String Attribute to create if valid values are passed
$attribute_value
Mixed Repeating parameter, containing values for the attribute. Additional values can be passed as additional parameters.

Return values

String String containing the attribute including values, or empty string if no valid values are passed.

Examples

$max = 10; $min = false; $HTML->attribute("class", "main", ($max ? "max:".$max ; ""), $min);

Will return:

class="main max:10"
$max = ""; $min = 0; $HTML->attribute("class", "main", ($max ? "max:".$max ; ""), $min);

Will return:

class="main min:0"
$max = ""; $min = 0; $HTML->attribute("class", ($max ? "max:".$max ; ""), $min);

Will return and empty string, as both $max and $min resolves to nothing.

Dependencies

PHP
  • func_get_args
  • count
  • htmlentities
  • stripslashes
Janitor

None

HTML::toOptions

Definition

Name
HTML::toOptions
Syntax
Array = HTML::toOptions( Array $multi_array , String $value_index , String $text_index [, Array $_options ] );

Description

Convert multi dimensional Array to valid options Array for selects and Radiobuttons – and optionally add additional options in the same go.

Data exchanges in Janitor is done with associative Arrays. Lists of datasets are Arrays of associative Arrays. To create a valid options Array from a list of datasets (which is commonly what you need), you might just need two properties from each dataset, requiring you to iterate the whole list and create a new Array with the correct keys and values. That is what this function does.

Note that it is valid to have Named indices, with an empty string as Key, which we use for default options (they have no value to send).

Parameters

$multi_array
Array Array of Associative Array, in which to find specified keys and values.
$value_index
String Key of Value in Associative Array, to use as options Key
$text_index
String Key of Value in Associative Array, to use as options Value
$_options
Array Additional options
Options
add
Additional options to add to the beginning of the new Options Array

Return values

Array Associative array of selected key values, prepended additional options.

Examples

$data_sets = [ ["id" => "1", "name" => "Tom", "title" => "Naive, hungry cat"], ["id" => "2", "name" => "Jerry", "title" => "Thrill seeking enthusiast"], ["id" => "3", "name" => "Fido", "title" => "Kind hearted puppy"] ]; $HTML->toOptions($data_sets, "id", "name");

Returns:

["1" => "Top", "2" => "Jerry", "3" => "Fido"]
$data_sets = [ ["id" => "1", "name" => "Tom", "title" => "Naive, hungry cat"], ["id" => "2", "name" => "Jerry", "title" => "Thrill seeking enthusiast"], ["id" => "3", "name" => "Fido", "title" => "Kind hearted puppy"] ]; $HTML->toOptions($data_sets, "id", "name", ["add" => ["" => "Choose side"]]);

Returns:

["" => "Choose side", "1" => "Top", "2" => "Jerry", "3" => "Fido"]

Dependencies

PHP
  • is_array
  • switch...case
  • foreach
Janitor

None

HTML::jsMedia

Definition

Name
HTML::jsMedia
Syntax
String = HTML::jsMedia( Array $item [, String $variant ] );

Description

Provide media info as classVars string. It will get first media element from item, or first of variant from item, if variant is specified.

Parameters

$item
Array Item data array, with mediae index populated
$variant
String Optional variant to match when finding media

Return values

String classVars string with media info, empty string en error

Examples

$HTML->jsMedia($item, "mediae");

Might return something like:

format:jpg variant:mediae-xyzdefgh

Dependencies

PHP

None

Janitor
  • Items::getFirstMedia

HTML::jsData

Definition

Name
HTML::jsData
Syntax
String = HTML::jsData( Array $_filter );

Description

Create a data attributes string with backend endpoints for JavaScript interfaces.

Parameters

$_filter
Array Array of endpoint areas to include
Available endpoint areas
order
Endpoint for updating item order
tags
Endpoint for getting, adding and removing tags
media
Endpoint for deleting media and updating media name and order
comments
Endpoint for updating or deleting comments
prices
Endpoint for deleting prices
qna
Endpoint for updating or deleting QnA's

Return values

String String of data attributes with all the endpoint related to specifed areas – or all areas if none are defined. Will always add a csrf-token data attribute.

Examples

No examples

Dependencies

PHP
  • array_search
Janitor
  • Session::value
  • Page::validPath

HTML::formStart

Definition

Name
HTML::formStart
Syntax
String = HTML::formStart( String $action [, Array $_options ] );

Description

Create a start form tag, including hidden csrf-token input, if the action is accessible for the current user.

Parameters

$action
String Path to use as action value for the form. Optionally relative path, which will be appended to current controller path.
$_options
Array Form settings
Options
class
Classname for form
id
Id for form
target
Target value for form, Default none.
method
Method value for form, Default post.
enctype
Encoding for form, Default application/x-www-form-urlencoded

Return values

String HTML string for form as specified, or empty string if $action is not accessible to user.

Examples

$model->formStart("/update", array("class" => "autoForm i:autoForm"));

Will return:

<form action="/update" method="post" class="autoForm i:autoForm" enctype="application/x-www-form-urlencoded"> <input type="hidden" name="csrf-token" value="6dc41813-dedc-4695-a0ba-56470f7b2020" />

Dependencies

PHP
  • preg_match
  • foreach
  • switch
Janitor
  • Page::validatePath
  • session()->value

HTML::formEnd

Definition

Name
HTML::formEnd
Syntax
String = HTML::formEnd();

Description

Create an end form tag, if formStart has previously been called (and not been ended yet).

Parameters

None

Return values

String End form tag, if "open" form exists, otherwise empty string.

Examples

None

Dependencies

PHP
  • isset
Janitor

None

HTML::input

Definition

Name
HTML::input
Syntax
String = HTML::input( String $name [, Array $_options ] );

Description

Create Templator compliant Form input HTML, using Model entities when available – if formStart has been invoked. The input method supports all the same input types as are available for Model creation.

The method is primarily intended to be invoked through a Type Class, and in that case it can utilize the defined Model entities – just use the entity name as input name, and the method will use the properties you already defined to construct the input. Any entity property can be overridden directly through the $_options Array, when invoking this method, if customisation is needed.

The method can also be invoked directly through the HTML class, but in that case it will not have access to Model entities. Any property can be set directly through the $_options Array, when invoking this method.

Note: Only properties specified in the Model will be used for serverside validation. Any overrides or additions made when invoking the input method, will be limited to the rendering client.

Parameters

$name
String Input name (or Model entity name).
$_options
Array Optional settings.
Options
label
Label of the entity.
(Not applicable for type hidden)
type
Type of the entity. One of the predefined types, hidden, string, text, select, html, files, number, integer, email, tel, password, date, datetime, checkbox, radiobuttons. Default is string.
(See Model Class documentation for a full explanation)
value
Value of entity.
options
A named Array of options for selects and radiobuttons, following the format [option name => option value].
(Only applicable for type select and radiobuttons)
id
A custom element id used when rendering the entity input. As default an input_#entity_name# is generated.
class
A custom className used when rendering the entity input – applied to input field.
(Not applicable for type hidden)
required
Whether data is required for this entity. Default false.
(Not applicable for type hidden)
readonly
Render this input as readonly. Default false.
(Not applicable for type hidden, files and html)
disabled
Render this input as disabled. Default false.
(Not applicable for type hidden, files and html)
error_message
An error message for client side validation.
(Not applicable for type hidden)
hint_message
A hint message for client side validation.
(Not applicable for type hidden)
autocomplete
Whether the browsers native autocomplete functionality should be turn on. Default false.
(Not applicable for type hidden, checkbox, radiobuttons, select, html and files)
pattern
A regular expression pattern data must match for this entity.
(Not applicable for type hidden, checkbox, radiobuttons, select and files)
min
Minimum abstract for this entity. Has different meanings depending on context - see input type overview in Model Class documentation.
(Not applicable for type hidden, checkbox, radiobuttons, select and files)
max
Maximum abstract for this entity. Has different meanings depending on context - see input type overview in Model Class documentation.
(Not applicable for type hidden, checkbox, radiobuttons and select)
compare_to
If the input value must match that of another. Typically used for email or password "repeat to confirm" inputs.
(Only applicable for type string, email, tel and password)
allowed_tags
Tags and special content types, that are allowed in the HTML input. Default p,h1,h2,h3,h4,h5,h6,code,ul,image,download.
(See the full list below)
(Only applicable for type html)
media_add
A custom save path for adding viewable media through the HTML editor. Default is to addHTMLMedia on current controller.
(Only applicable for type html)
media_delete
A custom delete path for deleting viewable media through the HTML editor. Default is to deleteHTMLMedia on current controller.
(Only applicable for type html)
file_add
A custom save path for adding downloadable files through the HTML editor. Default is to addHTMLFile on current controller.
(Only applicable for type html)
file_delete
A custom delete path for deleting downloadable files through the HTML editor. Default is to deleteHTMLFile on current controller.
(Only applicable for type html)

Note: The $_options properties can and should primarily be defined via your model, rather than when invoking the input method.

Return values

String HTML representing a Templator compliant input field – if form has been started (using HTML::formStart).

Examples

To create an input field for "name", using all properties from name entity defined in TypePost.

$typePostClass->input("name");

To create an input field for "classname", and making it required.

$typePostClass->input("classname", ["required" => true]);

To create an custom input field, special_token, for a string between 5 and 10 chars, with frontend validation only.

$HTML->input("special_token", ["type" => "string", "required" => true, "min" => 5, "max" => 10]);

Dependencies

PHP
  • isset
  • foreach
  • switch...case
  • preg_replace
  • preg_match
  • htmlentities
Janitor
  • Page::validPath

HTML::output

Definition

Name
HTML::output
Syntax
String = HTML::output( String $name [, Array $_options ] );

Description

This method will output a model entity as a kind of readonly element. It will be encapsulated in a div.field, but the entity value will be shown in a p or a ul instead of in an input field.

The value will also be included in a hidden input inside the div.field.

Parameters

$name
String Input name (or Model entity name).
$_options
Array Optional settings.
Options
label
Label of the entity.
type
Type of the entity. list or p. Default p.
value
Value of entity.
options
An array of values to show in a list.
class
A custom className used when rendering the entity.
id
A custom element id used when rendering the entity p or ul.
hint_message
A hint message.

Return values

String HTML representing a Templator compliant output field.

Examples

None

Dependencies

PHP
  • foreach
  • switch...case
  • isset
Janitor

None

HTML::button

Definition

Name
HTML::button
Syntax
String = HTML::button( String $value [, Array $_options ] );

Description

Create an HTML input type=button.

Parameters

$value
String Value for input type=button.
$_options
Array Button settings
Options
type
Type value of button input. button or submit. Default button
name
Name value of button input.
class
Classname value of button input.
wrapper
HTML wrapper for input.

Return values

String HTML input type=button element – or empty string, if HTML::formStart has not been called first.

Examples

$model->button("Button text", ["class" => "primary"]);

Returns

<input value="Button text" type="button" class="button primary" />
$HTML->button("Button text", ["class" => "primary", "wrapper" => "li.input"]);

Returns

<li class="input"><input value="Button text" type="button" class="button primary" /></li>

Dependencies

PHP
  • isset
  • foreach
  • switch...case
  • preg_match
  • preg_match_all
  • implode
Janitor

None

HTML::submit

Definition

Name
HTML::submit
Syntax
String = HTML::submit( String $value [, Array $_options ] );

Description

Shorthand method to create submit buttons. Will simply invoke HTML::button with type=submit.

Parameters

$value
String Value for input type=submit.
$_options
Array Button settings
Options
type
Type value of button input. button or submit. Default button
name
Name value of button input.
class
Classname value of button input.
wrapper
HTML wrapper for input, stated in a selector style syntax, like li.readmore.

Return values

String HTML input type=submit element, optionally wrapped in $wrapper – or empty string, if HTML::formStart has not been called first.

Examples

$HTML->submit("Save text", ["class" => "primary" "wrapper" => "li.input"]);

Returns

<li class="input"><input value="Save text" type="submit" class="button primary" /></li>

Dependencies

PHP

None

Janitor

None