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
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".
string
Regular string input of maximum 255 characters. No other limitations apply. Equivalent to a input type="text".
Options
text
Multiline text input. Equivalent to a textarea.
Options
select
Select type input, also known as an options dropdown. Equivalent to a select.
Options
html
HTML Editor based input. Expects value to be correctly formatted HTML. Equivalent to a (very advanced) textarea.
Options
files
File or files input. Equivalent to a input type="file".
Options
number
Numeric input. Integers and floats. Equivalent to a input type="number".
Options
integer
Numeric input. Integers only. Equivalent to a input type="number".
Options
Email input. Equivalent to a input type="email".
Options
tel
Phone number input. Equivalent to a input type="tel".
Options
password
Password input. Equivalent to a input type="password".
Options
date
Date input. Equivalent to a input type="date".
Options
datetime
Datetime input. Equivalent to a input type="datetime".
Options
checkbox
A single checkbox. Equivalent to a input type="checkbox".
Options
radiobuttons
Set of radiobuttons. Equivalent to a input type="radio".
Options
tag
Tag input. Custom entity for tag input. Will accept a valid tag or a tag id.
Options
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