In addition to standard form widgets, concrete5 provides a myriad of other widgets for linking to pages, selecting pages, selecting users, working with dates, and much much more. In addition to providing widgets that would otherwise take your hours to code yourself.
- Data persistence on POST: when submitting the core form helpers, their data will remain as originally entered, without having to worry about checking $_REQUEST variables.
- Do more with less. Once you learn the syntax, writing forms using these helpers can save you a lot of time and code.
Loading the Helper(s)
You can load these helpers using the following syntax. The helpers are all available under concrete/helpers/form/ and are loaded using:
$fooName = Loader::helper('form/foo'); These Form Helpers Include, and are listed by concrete5 core usage
- Attribute: $af = Loader::helper('form/attribute');
- Color: $fh = Loader::helper('form/color');
- Date Time: $dtt = Loader::helper('form/date_time');
- Page Selector: $pageSelector = Loader::helper('form/page_selector');
- Rating: $rt = Loader::helper('form/rating');
- User Selector: $uh = Loader::helper('form/user_selector');
Attribute Helper
Loading The Attribute Helper
You can load the concrete5 form helper using the following simple code
$af = Loader::helper('form/attribute'); The $af variable now contains an instance of the FormAttributeHelper.
Usage
$af->setAttributeObject($obj);
$af->display($key,$required,$includeLabel = true);
- $key
This is an AttributeKey Object - $required
Required Field. Typically optional. - $includeLabel
Includes a label.
All of the heavy lifting is handled by concrete5 behind the scenes to render the myriad of attribute values.
Loads an object into the current instance of the helper, which will then be queried against when running the display method below. Examples of these objects include "Page", "UserInfo".
Color Picker
Provides a color picker and saves the selected color to to a hidden form element as a six-digit hex color.
Usage
$fh->output($name, $label, $value = null, $includeJavaScript = true)
- $name The name of the hidden input element that the hex color will be stored in.
- $label the public label of the color picker element.
- $value
selected hex color(if available) - $includeJavascript Boolean to include the JavaScript activation routines for the color picker along with the widget. Default is true.
Prints out the star rating widget.
Date Time
Loading the Date Time Helper
The Date Time Helper is loaded using
$dtt = Loader::helper('form/date_time'); The $dtt Object is now an instance of DateTimeHelper.
This helper provides a calendar and an optional time dropdown selector. Useful for selecting dates and date/time combinations.
- $field
This is both the css selector ID and the post Array values via name Attribute - $value This is the string value, usually populated by a $this->set in a controller.
- $prefix
This is used in datetime to join the multiple fields under one common prefix to later translate - $calendarAutoStart This is used as an auto start to set the DateTimeHelper's html output to current local time.
- $includeActivation This requires check-box activation of the datetime.
Methods
$dtt->date($name, $value, $calendarAutoStart)
Creates a jQuery ui Date Element. Omits the Hour Minute Second Dropdowns
print $dtt->date('check-in', "7/23/2010", true); //true is provided and thus usually omitted. $dtt->datetime($prefix, $value, $includeActivation,$calendarAutoStart)
Creates a date time element using jQuery ui Calendar.
print $dtt->datetime('check-in-beach', "7/23/2010", false,true); //last two args are usually omitted. $dtt->translate($prefix, $arr = $_POST)
$dtt->translate('check-in-beach'); This is loaded again in the controller or any object method that utilizes form values. This method essentially combines myriad of post values in the method request array via the provided prefix and glues them back together in a format that is suitable for storing in a timestamp field in a db. This is useful when working with the datetime() function, as it means you don't have to parse the request array for the date, hours, minutes and AM/PM.
Page Selector
Provides an easy way to select a page from a combination sitemap/search form. Saves a numeric page ID to a hidden form element.
$pageSelector = Loader::helper('form/page_selector'); - $fieldName
This is used as the id, the fieldName is referenced in the postArray as $this->post('fieldName'); - $cID Integer, CollectionID Value. If provided it is the preset when the page selector is displayed.
- $javascriptFunc
You may provide your own javascript function. - $calendarAutoStart This is used as an auto start to set the DateTimeHelper's html output to current local time.
- $includeActivation This requires check-box activation of the datetime.
Methods
$pageSelector->selectPage($fieldName, $cID, $javascriptFunc)
Creates a link that, when clicked, launches the sitemap and page search interfaces. When clicking any of the pages in this interface, the function specified by $javascriptFunc will be run, with the selected page ID and page name as its first and second parameters. If specified, the $cID parameter will autoload a page as the selected page.
print $pageSelector->selectPage('parent-page',1,'ccm_selectSitemapNode'); // parent-page is id and name, 1 is cID of PageObj $pageSelector->sitemap($args)
Placeholder Method, no examples in core.
print $pageSelector->sitemap();
Rating
Provides a rating widget and saves the rating into a hidden form element.
print $rt->rating($name, $selectedValue, $includeJavaScript = true)
User Selector
Provides an interface for selecting a single or multiple users. Saves to a hidden form element.
print $form->selectUser($name, $uID = false, $javascriptFunc = 'ccm_triggerSelectUser')
Creates a link that, when clicked, launches the user search interface. When clicking any of the user results in this interface, the function specified by $javascriptFunc will be run, with the selected user ID, user name and user email address as its parameters. If specified the $uID parameter will autload a user as the select user.