Admin Manual - HTML Fields and Template Tags
From PikaDocs
By Matthew Friedlander
Pika Software (http://www.pikasoftware.com/)
| Table of contents |
Pika 4 Template Tags: An Overview
This section is directed at Pika 4.0+ users, for users of previous versions the old template guide has been moved here
Included below is a listing of the types of template tags that are supported by default in Pika CMS 4. The new Pika 4 templating library (pikaTempLib.php) also allows you to add new template tags and customize the tags below via the template plug-in system.
The template tag structure determines the course of action taken. As in previous versions of Pika the Template system accepts a data array of values coded by fieldname and a template file.
Some examples:
data_array = array('first_name' => 'Matthew', 'last_name' => 'Friedlander')
fieldname = first_name
template_file = subtemplates/template.html
The Template system then scans the template file replaces any matching template tags with the values stored in the data array.
For example lets take a look at the text of the template.html template file:
Hello! My name is %%[first_name]%% %%[last_name]%%
Using the data array above the template.html file will output:
Hello! My name is Matthew Friedlander
As you can see above the Templating system scanned the template.html file and replaced the two fieldname tags (first_name, last_name) with the matching named values from the data_array above and returned the templated file. The above example shows a very simple direct text replacement. The Templating library is capable of creating many different types of output such as drop downs, checkboxes, text input fields, and others.
Template Tag Structure
Template tags have their own syntax and their behavior can change based on how the tag is ordered and written. Below is a listing of the ways in which template tags can be structured.
%%[fieldname]%%
The simplest directive is one where only a single name is included. The Templating system searches the supplied data array variable for a match. If a match exists in the array the template tag is removed and replaced with that value. If a match is not found it simply removes the template tag from the string.
%%[fieldname,menuname]%%
In some cases as in the case of a HTML Dropdown you want to create a list of options that the user can select. This can be done by passing a menuname directive to the Templating system. In this example the fieldname contains the value to be matched against the supplied menuname. The Templating system will search for a menu that matches the menuname provided. The above example creates a HTML Dropdown list and set its value to the supplied fieldname’s value from the data array supplied to the template system.
%%[fieldname,menu_name,plug-in_type]%%
In this example we are specifying a custom menu type overriding the default dropdown output. If for example we were to specify “radio” for plug-in_type the generated output would create a radio menu consisting of all the items in menu_name and matched to the value in fieldname.
%%[fieldname,plug-in_type]%%
For template types not driven by menus the second directive can instead refer to the plug-in_type. A good example of this would be the textinput type which creates an html input type text tag. In this case the plug-in_type specified handles matching the fieldname and constructing the selected output. Important to note: the plug-in_type name cannot match any current menu_name - otherwise it will default to that menu as per the %%[fieldname,menuname]%% tag structure above.
%%[fieldname,menu_name,plug-in_type,directive,directive,...]%%
For any of the above template tags you can append any number of operational directives to change the result. For example the op “disabled” can be specified after any tag sequence and the resulting form input will be generated with the disabled operator (disabling the input). This is only for input tag generation, other custom types may or may not recognize or utilize this directive. In the event that you specify an op which is not recognized the plug-in function will ignore it.
Template Tag Types
Below is a listing of the types of tags that are supported in Pika 4.0. They are divided into several categories based on their usage and output.
Text Types
The following Template tags all generate or manipulate text output. As such they can be used in either a Pika screen template or in Document Assembly forms.
Text Replacement
%%[fieldname]%%
Replaces tag with value fieldname from data array.
Text Address
Displays a complete address from fields in the data array. By default it pulls the fieldnames from Pika standard locations. However, this behavior can be overridden via the directives.
%%[fieldname,text_address]%%
Note: text_address uses multiple fields from the data array. When assigning a fieldname to the tag be sure that it does not match any existing fieldname in the data array.
| Directive | Values | Default | Description |
|---|---|---|---|
| org | fieldname | org | fieldname containing the Organization name in the data array |
| address | fieldname | address | fieldname containing the first Address line in the data array |
| address2 | fieldname | address2 | fieldname containing the second Address line in the data array |
| city | fieldname | city | fieldname containing the City in the data array |
| state | fieldname | state | fieldname containing the State in the data array |
| zip | fieldname | zip | fieldname containing the Zip Code in data array |
| nobreak | [true,false] | false | Displays address as single line if true, otherwise breaks into multiple lines. |
| output | [text,html,rtf] | true | Alters the line breaks per text/html/rtf standards |
Example 1: Default Usage
%%[client_address,text_address]%%
Outputs:
123 Happy Street Suite#3 Mainsville, NY 12345
Example 2: nobreak Directive
%%[client_address,text_address,nobreak]%%
Outputs:
123 Happy Street Suite#3 Mainsville, NY 12345
Example 3: output Directive
%%[client_address,text_address,output=html]%%
Outputs:
123 Happy Street<br/> Suite#3<br/> Mainsville, NY 12345
Text Date
Displays a calendar date converted from the mysql date format YYYY-MM-DD (ex. 2009-11-13) into a more familiar MM/DD/YYYY format.
%%[fieldname,text_date]%%
Example 1: Default Usage
%%[close_date,text_date]%%
Outputs:
11/13/2009
Text Menu
Displays the text label of the selected menu option given a supplied fieldname
%%[fieldname,menuname,text_menu]%%
Examples:
%%[undup,undup,text_menu]%%
Outputs:
Unduplicated Service
Text Name
Displays a full text name of a contact.
%%[fieldname,text_name]%%
Note: text_name uses multiple fields from the data array. When assigning a fieldname to the tag be sure that it does not match any existing fieldname in the data array.
| Directive | Values | Default | Description |
|---|---|---|---|
| first_name | fieldname | first_name | fieldname containing the first name |
| middle_name | fieldname | middle_name | fieldname containing the middle name |
| last_name | fieldname | last_name | fieldname containing the last name |
| extra_name | fieldname | extra_name | fieldname containing extra name |
| salutation | [true,false] | false | If set to true displays Mr. or Ms. depending on the value of the gender field |
| order | [first,last] | first | If set to first outputs first middle last, if set to last outputs last, first middle |
| no_extra | [true,false] | false | If set to true does not display extra name. |
| no_middle | [true,false] | false | If set to true does not display middle name. |
Example 1: Default Usage
%%[client_name,text_name]%%
Outputs:
John Robert Smith Jr.
Example 2: order, no_middle, and no_extra Directives
%%[client_name,text_name,order=last,no_middle,no_extra]%%
Outputs:
Smith, Robert
Text Phone
Displays a full text of a phone number.
%%[fieldname,text_phone]%%
Note: text_address uses multiple fields from the data array. When assigning a fieldname to the tag be sure that it does not match any existing fieldname in the data array.
| Directive | Values | Default | Description |
|---|---|---|---|
| area_code | fieldname | area_code | fieldname containing the area code |
| phone | fieldname | phone | fieldname containing the phone number |
| phone_notes | fieldname | phone_notes | fieldname containing the phone notes |
| notes | [true,false] | false | If set to true appends the value of phone notes to the end of the phone number |
Example 1: Default Usage
%%[client_phone,text_phone]%%
Outputs:
(888)888-1234
Example 2: notes Directive
%%[client_phone,text_phone,notes]%%
Outputs:
(888)888-1234 x229
HTML Form Input Types
The following tags all generate HTML form input fields and populate them with values either stored in the database or provided directly from the PHP script via the data array.
Checkbox
Generates a HTML checkbox populated with a value specified by fieldname.
%%[fieldname,checkbox]%%
or you can also use the legacy syntax
%%[fieldname,yes_no,checkbox]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the checkbox |
| id | fieldname | fieldname | Sets the id property of the checkbox |
| class | css class name | plcheck | Sets the css style class |
| label | text | Adds the <label> tag to the checkbox containing the supplied string | |
| tabindex | number | 1 | Sets the tabindex property of the checkbox |
| disabled | [true,false] | false | Sets the disabled property of the checkbox if marked true |
| no_hidden | [true,false] | false | If true, does not generate matching hidden input tag |
| onfocus | javascript | Sets the onfocus property of the checkbox | |
| onblur | javascript | Sets the onblur property of the checkbox | |
| onclick | javascript | Sets the onclick property of the checkbox | |
| onmouseup | javascript | Sets the onmouseup property of the checkbox | |
| onmousedown | javascript | Sets the onmousedown property of the checkbox |
Example 1: Default Usage
%%[good_story,checkbox]%%
Outputs:
<input type="hidden" name="good_story" value="0"/> <input type="checkbox" name="good_story" id="good_story" value="1" class="plcheck" tabindex="1" />
Example 2: label and id Directives
%%[good_story,checkbox,label=Good Story,id=gs_lookup]%%
Outputs:
<input type="hidden" name="good_story" value="0"/> <input type="checkbox" name="good_story" id="gs_lookup" value="1" class="plcheck" tabindex="1" /> <label for="gs_lookup">Good Story</label><br/>
Menu
Menus serve to limit the data that can be entered by a user into a particular field to a set of predefined values. For example, if a given field in Pika CMS should have either an "A", "B", or "C" value, a menu can be used to make sure a well-meaning user does not enter the value �D" into that field. Once a menu has been entered into Pika CMS, it can be used on an unlimited number of fields. The list of values for menus are stored on the database; each menu is in a separate database table.
%%[fieldname,menu_name]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the menu |
| id | fieldname | fieldname | Sets the id property of the menu |
| class | css class name | plmenu | Sets the css style class |
| tabindex | number | 1 | Sets the tabindex property of the menu |
| disabled | [true,false] | false | Sets the disabled property of the menu if marked true |
| onfocus | javascript | Sets the onfocus property of the menu | |
| onblur | javascript | Sets the onblur property of the menu | |
| onchange | javascript | Sets the onchange property of the menu | |
| noblank | [true,false] | false | Default is to include a blank value in any menu, does not include this value if marked true |
Example 1: Default Usage (Unduplicated Service Menu)
%%[undup,undup]%%
Outputs:
<select name="undup" id="undup" class="plmenu" style="" tabindex="1" > <option selected value=""> </option> <option value="1">Unduplicated Service</option> <option value="0">Duplicated Service</option> </select>
Example 2: onChange and noblank directives
%%[undup,undup,onchange=setSomething(this.value);return false;,noblank]%%
Outputs:
<select name="undup" id="undup" class="plmenu" style="" tabindex="1" onChange="setSomething(this.value);return false;" > <option selected value="1">Unduplicated Service</option> <option value="0">Duplicated Service</option> </select>
Menu Groups
Multiselect
Radio Button
Generates a HTML radio selection populated with a value specified by fieldname.
%%[fieldname,undup,radio]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the radio |
| id | fieldname | fieldname | Sets the id property of the radio |
| class | css class name | plradio | Sets the css style class |
| tabindex | number | 1 | Sets the tabindex property of the radio |
| disabled | [true,false] | false | Sets the disabled property of the radio if marked true |
| onfocus | javascript | Sets the onfocus property of the checkbox | |
| onblur | javascript | Sets the onblur property of the checkbox | |
| onclick | javascript | Sets the onclick property of the checkbox | |
| vertical | [true,false] | false | If true displays radio selections vertically rather than horizontally |
Example 1: Default Usage
%%[undup,undup,radio]%%
Outputs:
<input type="radio" name="undup" id="undup_27919" value="1"class="plradio" tabindex="1" /> <label for="undup_27919">Unduplicated Service</label> <input type="radio" name="undup" id="undup_81460" value="0"class="plradio" tabindex="1" checked /> <label for="undup_81460">Duplicated Service</label>
Example 2: vertical Directive
%%[undup,undup,radio,vertical]%%
Outputs:
<input type="radio" name="undup" id="undup_35188" value="1"class="plradio" tabindex="1" /> <label for="undup_35188">Unduplicated Service</label> <br/> <input type="radio" name="undup" id="undup_58075" value="0"class="plradio" tabindex="1" checked /> <label for="undup_58075">Duplicated Service</label> <br/>
Text
Generates a HTML input text populated with a value specified by fieldname.
%%[fieldname,input_text]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the text input |
| id | fieldname | fieldname | Sets the id property of the text input |
| class | css class name | Sets the css style class | |
| tabindex | number | 1 | Sets the tabindex property of the text input |
| disabled | [true,false] | false | Sets the disabled property of the text input if marked true |
| size | number | Sets the size property of the text input | |
| maxlength | number | Sets the maxlength property of the text input | |
| onfocus | javascript | Sets the onfocus property of the text input | |
| onblur | javascript | Sets the onblur property of the text input | |
| onclick | javascript | Sets the onclick property of the text input | |
| onmouseup | javascript | Sets the onmouseup property of the text input | |
| onmousedown | javascript | Sets the onmousedown property of the text input | |
| onkeyup | javascript | Sets the onkeyup property of the text input |
Example 1: Default Usage
%%[number,input_text]%%
Outputs:
<input type="text" name="number" id="number" value="X-09-00001" tabindex="1" />
Example 2: size, maxsize, and onblur Directives
%%[number,input_text,size=11,maxsize=45,onblur=somefunct(this.value);]%%
Outputs:
<input type="text" name="number" id="number" value="X-09-00001" size="11" maxsize="45" onBlur="somefunct(this.value);" tabindex="1" />
Date
Generates a HTML input text populated with a date value specified by fieldname.
%%[fieldname,input_date]%%
Normally in Pika if you output a date value from the database directly it will appear in the Mysql Date Format YYYY-MM-DD (ex. 2009-11-19). Prior to version 4 of Pika it was necessary for the php script to handle formatting it into the more familiar format MM/DD/YYYY. The input_date now does that formatting for you automatically with the field value supplied. Otherwise it is virtually identical to the input_text tag.
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the text date input |
| id | fieldname | fieldname | Sets the id property of the text date input |
| class | css class name | Sets the css style class | |
| tabindex | number | 1 | Sets the tabindex property of the text date input |
| disabled | [true,false] | false | Sets the disabled property of the text date input if marked true |
| size | number | Sets the size property of the text date input | |
| maxlength | number | 10 | Sets the maxlength property of the text date input |
| onfocus | javascript | Sets the onfocus property of the text date input | |
| onblur | javascript | Sets the onblur property of the text date input | |
| onclick | javascript | Sets the onclick property of the text date input | |
| onmouseup | javascript | Sets the onmouseup property of the text date input | |
| onmousedown | javascript | Sets the onmousedown property of the text date input | |
| onkeyup | javascript | Sets the onkeyup property of the text date input |
Example 1: Default Usage
%%[destroy_date,input_date]%%
Outputs:
<input type="text" name="destroy_date" id="destroy_date" value="11/19/2014" tabindex="1" />
Textarea
Generates a HTML input textarea populated with a value specified by fieldname.
%%[fieldname,input_textarea]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| name | fieldname | fieldname | Sets the name property of the textarea |
| id | fieldname | fieldname | Sets the id property of the textarea |
| class | css class name | Sets the css style class | |
| tabindex | number | 1 | Sets the tabindex property of the textarea |
| disabled | [true,false] | false | Sets the disabled property of the textarea if marked true |
| rows | number | 3 | Sets the size property of the textarea |
| cols | number | 33 | Sets the maxlength property of the textarea |
| onfocus | javascript | Sets the onfocus property of the textarea | |
| onblur | javascript | Sets the onblur property of the textarea | |
| onclick | javascript | Sets the onclick property of the textarea | |
| onmouseup | javascript | Sets the onmouseup property of the textarea | |
| onmousedown | javascript | Sets the onmousedown property of the textarea |
Example 1: Default Usage
%%[elig_notes,input_textarea]%%
Outputs:
<textarea name="elig_notes" id="elig_notes" cols="3" rows="33" tabindex="1" /> Over Income</textarea>
Example 2: cols, rows, and onblur Directives
%%[elig_notes,input_textarea,cols=11,rows=45,onblur=somefunct(this.value);]%%
Outputs:
<textarea name="elig_notes" id="elig_notes" cols="11" rows="45" onBlur="somefunct(this.value);" tabindex="1" /> Over Income</textarea>
Other Types
Javascript
This tag directive allows you to include javascript functions into html templates loaded from file. This allows you to re-use javascript functions out of the js directory as a library rather than maintaining multiple copies in multiple locations.
%%[filename,javascript]%%
| Directive | Values | Default | Description |
|---|---|---|---|
| parse | [true,false] | false | If set to true will scan the supplied javascript file for template tags and process them (ex. %%[base_url]%%) |
| script_tags | [true,false] | true | If set to true will include opening and closing javascript tags (<script></script>) if set to false it does not add the tags. |
For example, say we have a javascript function that ensures that an entered date is valid. This function runs when a user moves away from entering a date and raises an error if the date entered is not valid.
function isValidDate(field) {
...
...
}
We insert this function on a form field, such as the open date to be run when the user moves away (onBlur) from the field.
Filing Date:<br/> %%[filing_date,input_date,onblur=isValidDate(this);]%%
