The template helper class gives template developers an easy way to create templates with any desired structure.
The default templates work on the principle of a loop. This was chosen because it is familiar to people who work with WordPress templates and it is a very efficient way to lay out a lot of data. The shortcoming is it lacks flexibility: it’s really only good at displaying a series of data fields, it does not support display structures where different data types or fields need to be treated very differently, or if you want to show the data in an arbitrary order.
It is possible to combine the display of looped and non-looped values into a template, although this pretty much requires that the field groups support this organization by containing looped and non-looped fields in separate groups.
Instantiating the Template class
The Template class is instantiated once for each record and supplies all the data fields of the record, along with several helpful methods for presenting the data fields. The class is designed to be instantiated with the module class that generates the template. In the context of the shortcode template, this module object is referred to as $this. So, we instantiate the Template class in the shortcode template like so:
$record = new PDb_Template($this);
This gives the handle $record all the properties and methods of the template class using the data found in that particular record. This can be used in pdb_single, pdb_record, and pdb_list templates. Except for the pdb_list template, this would normally be done at the top of the template, making the properties and methods available to the whole template.In the pdb_list template, the class is instantiated after the record is assigned with the $this->the_record() method, so it ends up getting reinstantiated for each record in the list.
The public properties
- record – this is the iterator that is looped through by the module to build it’s display. It contains only the fields that are to be displayed and is organized into groups. For the list module, which does not use groups to organize it’s fields, this property is empty.
- fields – this is a collection of field objects indexed by the field name, in the order set by the setup or the shortcode. It provides a convenient way to access the values of any field at random, or it can be iterated to use it in a loop.
- values – this is an array of raw field values and includes all the values of the record, including hidden, internal, and administrative values.
- groups – an array of group objects with name, title, description, and field name array properties.
- module – a string identifying the currently active module: signup, single, record, list, etc.
- base_type – this is simply the class name of the instantiating class…not really needed in a template context, but could be useful for generating CSS classes or something.
The public methods
- has_content($name)
- group_has_content($group)
- get_value($name)
- get_field_prop($name, $property)
- get_detail_link([$page])
- get_edit_link([$page])
- set_edit_page($page)
- set_detail_page($page)
- print_value($name)
- print_title($name)
- print_field_prop($name, $property)
- print_group_title($group)
- has_group_description($group)
- print_group_description($group)
- print_with_link($name, $URL)
- file_uri($name)
Method Descriptions
group_has_content($group)
Tests the named group for the presence of non-empty fields. Returns true if at least one field has a value.
has_content($name)
Returns boolean true if the named field value is non-empty.
get_value($name)
Returns the named value from the record. This is the raw, unformatted value.
get_field_prop($name, $prop)
Returns a property value from the named field object. This provides access to any of the defined properties of the field such as title, values, validation, etc.
get_detail_link([$page])
Returns the URL of the record detail page. If a page identifier is provided, overrides the normal single record detail page with the provided page permalink.
get_edit_link([$page])
Works like get_detail_link, but for the record edit page.
set_detail_page($page)
set_edit_page($page)
Allows the default edit or detail page to be set. This change only affects the specific instance of the Template class.
print_value($name)
Echoes the formatted value of the field.
print_title($name)
Echoes the title of the field.
print_field_prop($name, $property)
Echoes the named property of the named field.
print_group_title($group)
Prints the title of the named group.
print_group_description($group)
Echoes the description of the named group.
has_group_description($group)
Returns true if the group has a defined description.
print_with_link($name, $href)
Echoes the field value wrapped in an anchor tag with the provided href value.
file_uri($name)
Provides the full URI of an image or file associated with an image upload or file upload field.