Outlast

zajDb and data types

Introduction

Before you read through the data types documentation, you should first take a look at the docs on defining models and data and perhaps you can also review the zajModel api docs.

zajDb class

You can use the zajDb class to define (and to later retrieve) the type, behaviour, and database structure for a field. Unlike the more complex zajField class (see more info on zajField), zajDb is not aware of its model context – it simply knows what kind of field it is. You can use its get_field() method to get a model-aware zajField object (see methods below).

zajDb properties

string $type The name of the data type. Each data type must be defined az a zajField class.
array $options An associated array of options. Options can be set as arguments
string $virtual A virtual field (alias) pointing to another.
boolean $in_database True if this is stored in database.
boolean $use_validation True if it has a custom validation method.
boolean $use_get True if it has a custom get() method.
boolean $use_save True if it has a custom save() method.
boolean $use_duplicate True if it has a custom duplicate() method.
boolean $use_filter True if it has a custom filter() method.
boolean $search_field True if this field should be included in a search().
boolean|string $edit_template The path of the template which should be displayed for {% input %} editors. If none, set to false.
boolean|string $show_template The path of the template which should be used when simply showing data from this field. If none, set to false.

zajDb methods

static zajDb YOUR_FIELD_NAME([$option1, $option2, ...]) zajDb objects are created by calling a static method with the name of the datatype. If you want a zajDb of type text you can call zajDb::text() to create it. All data types must be defined either by the system (see below for available types) or a plugin. You can also create your own data type definitions. Some data types require passing options on creation.
zajField get_field($class_name) returns the zajField object associated with this field definition. Since zajDb is not model-aware and zajField is, you need to pass the model’s class name as a parameter to provide context.
zajDb YOUR_OPTION($value) all other methods add or set a key/value item to the zajDb object’s $options property. For a list of available options see docs below.

Data type options

When you define a field in your model’s __model() magic method you can set various options for each field. Each data type can have its own specific options (see below for specifics on data types) but there are some global options as well that are available to all data types.

To set options, simply chain the method to the zajDb() definition like so:

$f->my_text_field = zajDb::text()->default('My default text!')->another_option(true);

Here are the available options:

default(mixed $default_value) use this to specify the field’s default value. The acceptable value will depend on the field’s type.
alias(string $the_other_field_name) if this field should be an alias to another field. This can be used to provide backwards compatibility or convenience.

boolean

boolean – a simple true/false field

The values of boolean as stored in the database are either ‘yes’ or ” for backwards compatibility reasons. Still, you can use true/false when you set the value. You can also test for true/false with if, but do not use the === or !== boolean operators. Just check with standard == or !=.

Boolean fields are displayed as checkboxes.

color

color – a hex code for a color, like #ffffff

Colors are stored as text in the database.

The field is displayed as an HTML5 color input with the possibility to switch to text mode so the user can manually input #hex codes.

date

date – a unix timestamp date field

The value is stored as a unix timestamp integer in the database.

The editor is displayed as a datepicker.

email

email – a text field but uses an HTML5 email input and has built-in validation

It is very similar to text but you can validate the field to check if it is a valid email address.

The editor is displayed as an HTML5 email input.

files

files – a file uploader which can have a list of File objects associated with it

float

float – a float number

id

id – a unique id (OFW uses a 13 character string) – this is automatically created and stored

This is exactly the same as a text field except that it is cached automatically as $object->id. Also it is typically automatically generated and is usually a 13 character unique string created with uniqid().

integer

integer – any integer number

json

json – a json-encoded field where any data can be stored

Json fields are stored in the database as json strings. When you retrieve the data with OFW it will automatically be JSON-decoded for you. When you set and save data you do not need to json-encode it, just send the data – the field definition is created so that the data is encoded when you save it.

locale

locale – a locale value in the format of en_US

The field is displayed as a select box.

locales

locales – a list of locales associated with the object

The field is displayed as multiple checkboxes.

manytomany

manytomany – any many to many connection to another model

The field returns a list of the other objects connected to it (specifically a zajFetcher object). This list can be sorted, paginated, searched, filtered, etc. as any other list (when doing an Example::fetch()).

Manytomany fields are displayed as searchable select boxes with multiple selection capabilities.

manytoone

manytoone – a many to one connection to another model

The field returns a single object connected to it or false if nothing is connected to it.

Manytoone fields are displayed as searchable select boxes with single selection.

map

map – a map coordinate that can be used to generate Google Maps location

The data is stored in two float fields in the database as *_lng and *_lat. When you retreive the data it will be returned as an object with a lng and lat property, so for example {{object.data.map.lng}} would be the longitude position.

The field is displayed with Google Maps with the {% input %} tag.

name

name – a string which is the name of the model

This is exactly the same as a text field except that it is cached automatically as $object->name.

onetoone

onetoone – any one to one connection to another model

This field is very similar to manytoone fields in the way it is stored and displayed.

Reverse onetoone connections are not supported yet.

onetomany

onetomany – any one to many connection to another model

When defining onetomany fields you need to set the name of the other model and the field in the other model it is connecting to. You must have an existing manytoone field on the other end.

Onetomany fields are displayed as searchable select boxes with multiple selection capabilities.

ordernum

ordernum – the order number for listing, an autoincrement field

An autoincremented integer in the database.

The ordernum has no editor but is instead typically edited using a drag and drop UI with Example::reorder();. See the admin interface template for a working example.

password

password – an encoded password

Stored as md5 hash.

Displayed as HTML5 password input.

photo

photo – a photo uploader field which can have a single Photo object associated with it

Stored as a single connection to a Photo object.

Displayed as a photo uploader.

photo fields have the following options:

min_width(int $pixels) The minimum width of the uploaded photo, in pixels. Defaults to 300.
min_height(int $pixels) The minimum height of the uploaded photo, in pixels. Defaults to 300.
max_file_size(string $file_size) The maximum file size of the photo in the format of ‘1mb’. Defaults to ’25mb’.

$f->photo = zajDb::photo()->min_width(300)->max_file_size('25mb');

photos

photos – a photo uploader which can have a list of Photo objects associated with it

Stored as a manytoone connection to Photo objects.

Displayed as a photo uploader.

photos fields have the following options:

min_width(int $pixels) The minimum width of the uploaded photo, in pixels. Defaults to 300.
min_height(int $pixels) The minimum height of the uploaded photo, in pixels. Defaults to 300.
max_file_size(string $file_size) The maximum file size of the photo in the format of ‘1mb’. Defaults to ’25mb’.

$f->photo = zajDb::photos()->min_width(300)->max_file_size('25mb');

rating

rating – a rating which is a float but shows up as stars

This is not currently supported.

richtext

richtext – a rich text editor which is the same as textarea

select

select – a select box with an array of possible values

serialized

serialized – a serialized value where an object is stored in a single field

Like json fields, the data is serialized and unserialized on set and retrieve. See json field docs for an example.

text

text – a text input field

Stored as standard text in the database.

Displayed as a text input.

textarea

textarea – a textarea field

Stored as standard text in the database.

Displayed as a standard HTML text area.

textbox

textbox – a textarea field (alias of textarea)

time

time – a unix timestamp that shows up as a time editor

timestamp

timestamp – a unix timestamp that shows up as a long integer

tinymce

tinymce – a tinymce richtext editor

unittest

unittest – a built-in field which shows if an object was created during a test

You should not use this field for definition. It is stored as a boolean in the database and is used by the system to determine if an object was created while running a unit test.

year

year – a unix timestamp that shows up as a year editor

API reference