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.

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

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

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

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

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

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

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

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

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

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

Definition

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

Description

_description_

Parameters

$value

String Text value of link.

$action

String HREF value of link.

$_options

Array Optional link settings

Options

$id: Name value of button input.
$class: Classname value of link.
$target: Target value for link.
$wrapper: HTML wrapper for input, stated in a selector style syntax, like li.readmore.

Return values

String HTML string containing a, optionally wrapped in $wrapper – or empty string, if $action is not accessible to user.

Examples

$HTML->link("Link text", "/janitor/tests", ["class" => "button", "wrapper" => "li.link"]);

Returns

<li class="link"><a href="/janitor/tests" class="button">Link text</a></li>

Dependencies

PHP

isset
foreach
switch...case
preg_match
preg_match_all
implode

Janitor

Page::validatePath

Definition

Name: HTML::navigationLink
Syntax: String = HTML::navigationLink( Array $node );

Description

Create a HTML element for navigations. Includes a selected class if $node["link"] is equal to current url. Includes a path class if current url contains $node["link"].

Parameters

$node: Array Janitor navigation node data set.

Return values

String HTML string with li and a. Includes a selected or a path, if link value equals or is contained in current url.

Examples

None

Dependencies

PHP

preg_match
strpos

Janitor

Page::validatePath

HTML Class

HTML output for Model based input templates

Functions

HTML::attribute

Definition

Description

Parameters

Return values

Examples

Dependencies

PHP

Janitor

HTML::toOptions

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

PHP

Janitor

HTML::jsMedia

Definition

Description

Parameters

Return values

Examples

Dependencies

PHP

Janitor

HTML::jsData

Definition

Description

Parameters

Available endpoint areas

Return values

Examples

Dependencies

PHP

Janitor

HTML::formStart

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

PHP

Janitor

HTML::formEnd

Definition

Description

Parameters

Return values

Examples

Dependencies

PHP

Janitor

HTML::input

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

PHP

Janitor

HTML::output

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

PHP

Janitor