Model Class

Data modeling and validation

In Janitor the Model bridges the gap between data storage and input. When you define a model, you have to consider both, because in the end they are unseparable. If no one puts in any data, there is nothing to store. So the Model is covering storage, transaction and input aspects all together. Read more about the Janitor Model Concept.

The Janitor model is made up of a number of different data/input types, and this class provides the functionality for composing your own data models for your custom items, but also for other classes which may need to receive or store validated user input.

The Core Janitor Model is inherited by all itemtypes and classes with an associated model. By extending the model class, your own classes are extended with capability to define data properties, input type support and validation.

The Model class in turn extends the HTML Class, providing form and input rendering capabilities, also based on the specification provided in your model, but always leaving room for customisation.

Functions

Model::addToModel

Definition

Name
Model::addToModel
Syntax
Void = Model::addToModel( String $name [, Array $_options ] );

Description

The addToModel method is typically used in type class constructors, but can be used in any class which extends the Model class, and allows the class to define and receive specific input conditions and validate any received data. It is used to compose the data model of that specific type class. Each addition to your model is referred to as an (model) entity, and you'll end up with the

As a minimum, you must define the entity name, and in addition you can specify one of the predefined input type's listed below, special validation conditions such as min/max values, input pattern, hint_message and error_messages – and much more. See the full options list below.

Any model entity, can be modified during runtime, or be rendered using a different type than originally defined, so that you can fine tune your interface for custom workflow needs.

Parameters

$name
String Name of entity to add to model
$_options
Array Optional settings
Options
label
Label of the entity. Used for rendering inputs for 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, tag, user_id, item_id. Default is string.
(See expanded explanation below)
value
Value of entity if posted or set.
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)
error_message
An error message used when rendering the entity input.
(Not applicable for type hidden)
hint_message
A hint message used when rendering the entity input.
(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)
unique
Whether the data value must be unique for this entity. Set to a database table, to enforce enable checking for uniqueness against the database.
(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 below.
(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 below.
(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)
min_width
Minimum width of uploaded images and videos, stated as an integer of pixels.
(Only applicable for type files and html)
min_height
Minimum height of uploaded images and videos, stated as an integer of pixels.
(Only applicable for type files and html)
allowed_formats
File formats allowed for upload. Stated as the allowed file extension, fx. jpg or png. More allowed proportions can be comma separated, fx. jpg,png. Though all formats are supported, anything other than image, video, audio pdf or zip uploads, will automatically be zipped and provided as as zip file. Default gif,jpg,png,mp4,mov,m4v,mp3,pdf,zip.
(Only applicable for type files and html)
allowed_proportions
Image and video proportions allowed for upload. Stated as a 4 decimal representation of the proportion (width/height), fx. 1.7778 or round(4/3, 4). More allowed proportions can be comma separated, fx. 1.7778,1.3333.
(Only applicable for type files and html)
allowed_sizes
Image and video sizes allowed for upload. State as WIDTHxHEIGHT, fx. 540x288 or 1000x400. More allowed sizes can be comma separated, fx. 540x288,1000x400.
(Only applicable for type files and html)
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)

Return values

Void

Data and Input types

Each data and input type may interpret a property differently, due to the nature of the type. For example, the min property means minimum length for a string type, while it means minimum value for an integer type. Find the nuances below.

Most of the input types can be directly linked to the classic HTML input types, while others are a kind a pseudo input types, constructed on top of the classic HTML input types.

hidden

The hidden input type is just that. A hidden input. Equivalent to a input type="hidden".

value
Value of entity
id
Element id in HTML
string

Regular string input of maximum 255 characters. No other limitations apply. Equivalent to a input type="text".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
compare_to
Name of entity to compare value to
text

Multiline text input. Equivalent to a textarea.

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
select

Select type input, also known as an options dropdown. Equivalent to a select.

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
options
Array of options
required
Is data required
error_message
Error message
hint_message
Hint message
html

HTML Editor based input. Expects value to be correctly formatted HTML. Equivalent to a (very advanced) textarea.

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
min_width
Minimum width of uploaded viewable media
min_height
Minimum height of uploaded viewable media
allowed_formats
Allowed file formats allowed
allowed_proportions
Allowed image and video proportions
allowed_sizes
Allowed image and video sizes
allowed_tags
Allowed tags and special content types
media_add
A custom media save path
media_delete
A custom media delete path
file_add
A custom file save path
file_delete
A custom file delete path
files

File or files input. Equivalent to a input type="file".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
max
Maximum number of files. Default 1.
min_width
Minimum width of uploaded viewable media
min_height
Minimum height of uploaded viewable media
allowed_formats
Allowed file formats allowed
allowed_proportions
Allowed image and video proportions
allowed_sizes
Allowed image and video sizes
number

Numeric input. Integers and floats. Equivalent to a input type="number".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum numeric limit of value
max
Maximum numeric limit of value
integer

Numeric input. Integers only. Equivalent to a input type="number".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum numeric limit of value
max
Maximum numeric limit of value
email

Email input. Equivalent to a input type="email".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
compare_to
Name of entity to compare value to
tel

Phone number input. Equivalent to a input type="tel".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
compare_to
Name of entity to compare value to
password

Password input. Equivalent to a input type="password".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
compare_to
Name of entity to compare value to
date

Date input. Equivalent to a input type="date".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum date
max
Maximum date
datetime

Datetime input. Equivalent to a input type="datetime".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
unique
Require value to be unique
pattern
Regex pattern to match
min
Minimum date or datetime
max
Maximum date or datetime
checkbox

A single checkbox. Equivalent to a input type="checkbox".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
radiobuttons

Set of radiobuttons. Equivalent to a input type="radio".

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Element field className in HTML
required
Is data required
options
Array of options
error_message
Error message
hint_message
Hint message
tag

Tag input. Custom entity for tag input. Will accept a valid tag or a tag id.

Options
label
Label of entity
value
Value of entity
id
Element id in HTML
class
Field element className in HTML
required
Is data required
error_message
Error message
hint_message
Hint message
autocomplete
Allow autocomplete
pattern
Regex pattern to match
min
Minimum length of value
max
Maximum length of value
user_id

user_id input. Custom entity for user_id input validation. Will accept a valid user_id only. This type cannot be rendered directly, and therefor a renderable type must be specified when creating a form input, for entities of type user_id.

This is commonly being used to validate values sent from the frontend using an input type hidden, or a select.

The options available for user_id, depends entirely on the needed rendering types.

item_id

item_id input. Custom entity for item_id input. Will accept a valid item_id only. This type cannot be rendered directly, and therefor a renderable type must be specified when creating a form input, for entities of type item_id.

This is commonly being used to validate values sent from the frontend using an input type hidden, or a select.

The options available for item_id, depends entirely on the needed rendering types.

Examples

In Itemtype Class constructor

Shortest possible, "name", type string:

$this->addToModel("name"));

A required string entity with the name "lastname":

$this->addToModel("lastname", [ "type" => "string", "label" => "Enter lastname", "required" => true, "hint_message" => "Type lastname now. Later not an option.", "error_message" => "Lastname must be string or it is confusing." ]);

A select entity with the name "favorite_color":

$this->addToModel("selected_option", [ "type" => "select", "label" => "Choose your favorite color", "options" => ["" => "Select option", "1" => "White", "2" => "Light gray"], "hint_message" => "Select a color", "error_message" => "Color must be selected" ]);

A required radiobuttons entity with the name "gender":

$this->addToModel("gender", [ "type" => "radiobuttons", "label" => "Gender", "options" => ["yes" => "Yes", "no" => "No"], "required" => true, "hint_message" => "Choose gender", "error_message" => "One must be selected" ]);

A required files entity with the name "screenshots":

$this->addToModel("screenshots", [ "type" => "files", "label" => "Screenshots", "required" => true, "max" => 20, "min_height" => 1000, "allowed_proportions" => round(16/9, 4), "hint_message" => "Type * files", "error_message" => "Files must be added" ]);

Dependencies

PHP
  • foreach
  • switch...case
Janitor
  • Model::setProperty

Model::getPostedEntities

Definition

Name
Model::getPostedEntities
Syntax
Void = Model::getPostedEntities();

Description

Get posted values for all entities in the model of the class the method is invoked on.

This method will look in the $_POST array for any entities of it's model, and map values to the model entity value property.

When getting posted values with this method, you are sure to get any value posted, in a sanitized format. The values will also be available for built in validation.

Parameters

None

Return values

Void The method populates the model entities but does not return anything.

Examples

If you add a name property to your model, like this:

$model->addToModel("name", ["type" => "string"]);

Then getPostedEntities can be used to retrieve any data posted to this property and make it available via your class, like this:

$_POST["name"] = "Test name"; $model->getPostedEntities(); print $model->getProperty("name", "value");

Outputs Test Name

Dependencies

PHP
  • count
  • if...else
  • foreach
  • isset
Janitor
  • getPostPassword
  • getPost
  • Model::getProperty
  • Model::setProperty

Model::validateList

Definition

Name
Model::validateList
Syntax
Boolean = Model::validateList( Array $list [, Integer $item_id ] );

Description

Validate a list of model entity names. Receives Array of names to validate, and optionally an item_id for unique checks.

If validation identifies errors, all values are sanitised for screenrendering and false is returned.

If you are seeking to validate newly posted values, remember to invoke getPostedEntities first – only then will the values be available in the model.

Parameters

$list
Array Array of entity names to check
$item_id
Integer Optional item_id to use for unique validation

Return values

Boolean true on successful validation without errors. false on error.

Examples

To validate the entities "name", "title" and "phone":

$this->validateList("name","title","phone");

Dependencies

PHP
  • foreach
  • count
  • isset
Janitor
  • prepareForHTML
  • Model::getProperty
  • Model::setProperty
  • Model::validate

Model::validate

Definition

Name
Model::validate
Syntax
Boolean = Model::validate( String $name [, Integer $item_id ] );

Description

Validate the value of a model entity, based on specified validation rules.

Adds an error message to the global message handler, in case of error.

If you are seeking to validate newly posted values, remember to invoke getPostedEntities first – only then will the values be available in the model.

Parameters

$name
String Name of entity names to check
$item_id
Integer Optional item_id to use for unique validation

Return values

Boolean true on success, false on error.

Examples

To validate the entities "title":

$this->validate("title");

Dependencies

PHP

None

Janitor
  • message()->addMessage
  • Model::getProperty
  • Model::setProperty
  • Model::isUnique
  • Model::isString
  • Model::isHTML
  • Model::isFiles
  • Model::isNumber
  • Model::isInteger
  • Model::isEmail
  • Model::isTelephone
  • Model::isPassword
  • Model::isDate
  • Model::isDatetime
  • Model::isChecked
  • Model::isTag
  • Model::isUser
  • Model::isItem

Model::getModel

Definition

Name
Model::getModel
Syntax
Array = Model::getModel();

Description

Get the internal model entity array, with all current properties.

Parameters

None

Return values

Array Current model entity Array.

Examples

None

Dependencies

PHP

None

Janitor

None

Model::setProperty

Definition

Name
Model::setProperty
Syntax
Void = Model::setProperty( String $name , String $property , Mixed $value );

Description

Set or update property in Internal Model entity Array. Can be used to override a value at any point in the process. The supported properties can be found under addToModel.

Parameters

$name
String Name of entity for property to set
$property
String Property to set
$value
Mixed Array or String containing value.

Return values

Void

Examples

$postModel->setProperty("headline", "hint_message", "Oh no, third time? Really?");

Dependencies

PHP

None

Janitor

None

Model::getProperty

Definition

Name
Model::getProperty
Syntax
Mixed = Model::getProperty( String $name , String $property );

Description

Get property value of name, from current Model entity array. Will use the default_values as fallback values if specified property has not been set.

Parameters

$name
String Name of entity for property to get
$property
String Property to get

Return values

Mixed String or Array with value, or false if none exists.

Examples

$postModel->getProperty("headline", "value");

Dependencies

PHP
  • isset
Janitor

None