The ModuleFields class is automatically made available to any module. To begin using it simply initialize the object within your module method.
Module methods that must return a ModuleFields object include:
- getPackageFields
- getAdminAddFields
- getClientAddFields
- getAdminEditFields
- getClientEditFields
Creating ModuleFields
Creating fields using the ModuleFields class allows you to define a set of input fields that may be displayed in a variety of context, without worrying about how those fields are contained. There are three aspects of creating a field, described below, that including: creating the field label, creating the field, and attaching the field to the label.
Creating Labels
Creating a label will return a ModuleField object.
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Create the label
$fields = new ModuleFields();
$my_label = $fields->label("My Field Label", "my_field_label_id");
$fields->setField($my_label);
return $fields;
}
}
?>
Creating Fields
As with creating a label, creating a field will return a ModuleField object. The example below uses the ModuleFields::fieldText() method, but others exist for creating radio buttons, textarea fields, and everything else you'll need.
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Create the label
$fields = new ModuleFields();
$my_label = $fields->label("My Field Label", "my_field_id");
// Create the field
$my_field = $fields->fieldText("my_field_name", array('id' => "my_field_id"));
$fields->setField($my_label);
return $fields;
}
}
?>
Attaching a Fields to a Label
A field may be attached to a label using the ModuleField::attach() method, or, instead, attach a label to a field using ModuleField::setLabel().
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Create the label
$fields = new ModuleFields();
$my_label = $fields->label("My Field Label", "my_field_id");
// Create the field
$my_field = $fields->fieldText("my_field_name", array('id' => "my_field_id"));
// Attach the field to the label
$my_label->attach($my_field);
// OR, attach the label to the field, instead
// $my_field->setLabel($my_label);
$fields->setField($my_label);
return $fields;
}
}
?>
Adding tooltips to a Label
Tooltips can be created using the ModuleFields::tooltip() method, then attached using ModuleField::attach(). In the example below we've eliminated unnecessary variable declarations to give a more concise example.
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Create the label
$fields = new ModuleFields();
$my_label = $fields->label("My Field Label", "my_field_id");
// Create and attach the field to the label
$my_label->attach($fields->fieldText("my_field_name", array('id' => "my_field_id")));
// Attach a tooltip to the label
$my_label->attach($fields->tooltip("This is my tooltip"));
$fields->setField($my_label);
return $fields;
}
}
?>
Tooltips may only be set on top level labels
A tooltip may not be attached to a label that is, itself, attached to a field.
Multiple tooltips may be created per label
... but that would be silly.
Complex Fields
Blesta supports ModuleFields up to two levels deep. This allows you to easily create a set of checkboxes or radio buttons associated with a single field.
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Create the label
$fields = new ModuleFields();
$my_label = $fields->label("My Field Label", "my_field_id");
##
# TODO: FINISH THIS EXAMPLE
#
##
// Create and attach the field to the label
$my_label->attach($fields->fieldCheckbox("my_field_name", array('id' => "my_field_id")));
// Attach a tooltip to the label
$my_label->attach($fields->tooltip("This is my tooltip"));
$fields->setField($my_label);
return $fields;
}
}
?>
Creating HTML content
The ModuleFields class supports HTML content as well. You may choose to set nothing but HTML content, but the best practice is to set fields using the method mentioned in the section above and only set javascript and that sort of thing as HTML content.
To set HTML content use the ModuleFields::setHtml() method.
<?php
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
$fields = new ModuleFields();
$fields->setHtml("
<script type=\"text/javascript\">alert('ok!');</script>
");
}
}
?>