Applies To:

Show Versions Show Versions

Manual Chapter: iApps Template Authoring
Manual Chapter
Table of Contents   |   << Previous Chapter

About the iApps template framework

An iApps™ template has three sections; implementation, presentation, and help. You can view and edit all three sections with the system's Template Properties screen or with a text editor. If you choose to use an editor, you may find it helpful to see the structure of an empty template as shown here.

sys application template f5.template_name { actions { definition { html-help { <HTML help definition goes here> } implementation { <Back-end Tcl and TMSH code goes here> } presentation { <Application presentation language code goes here> } } } }

Help section

The help section, written in HTML, can give application services users more information about the template.

Implementation section

The implementation section contains the tmsh and Tcl code that performs the actions of the template on the BIG-IP® system.

Presentation section

The presentation section contains the Application Presentation Language that is used by the BIG-IP system to create the template's graphical user interface.

Template design considerations

Well-designed, easy-to-use templates should be the goal of all iApps™ template authors.

While it may seem obvious, it is important that your template's presentation section follows these basic design considerations:

  • Use a question and answer format.
  • Be simple.
  • Be clear.
  • Be complete.
  • Be understandable.
  • Follow established conventions.

A complex presentation section will frustrate users and generate more support questions and comments for you, the template author.

About application reentrancy

Application reentrancy, used only by template developers, is the ability to change a configuration by changing the template inputs, allowing edits to the configuration at the template's level of abstraction. If a new configuration is created by an application service, the old configuration is changed to this new configuration by the mark-and-sweep process.

iApps service object
Stores the values associated with template inputs
Mark-and-sweep
On reentrancy, tmsh create is changed to tmsh modify . Untouched objects are deleted in the sweep.

About the implementation section

The implementation section of an iApps™ template contains the executable code that processes the elements of the presentation section. Template authors must be familiar with Tcl and tmsh scripting in order to write implementations.

About value elements

Value elements are primitives in the implementation section that represent the actual user interface components. Displayed as part of the form, value elements are associated with a form variable such as <type>, <name>, or <properties>.

About the presentation section

iApps™ templates use the application presentation language to create application-specific user interfaces in the BIG-IP® Configuration utility. Application presentation language code is parsed when a template is selected for use in an application service. When the template is updated, the system also checks the syntax of the code.

About the iApps application presentation language

The iApps™ application presentation language defines the user interface in the presentation section of an iApps template. The language describes what questions to ask, how the questions are presented (input field verses a pull-down list, for example), and the names of the variables used to store the values of the user entries. It consists of a set of primitive form elements, a set of grouping and organization constructs, methods for hiding or displaying portions of the form based on the values of other portions (optional), and a method to associate various form elements (text) with text that users can read.

About application presentation language elements

Application presentation language elements are the graphics building blocks of the presentation section. The iApps™ application presentation language uses the following elements to create the user interface for template users.

  • string
  • password
  • choice
  • editchoice
  • multichoice
  • table
  • row
  • message
  • section
  • optional
  • text definitions
  • include
  • define

string

The string element is the most basic element where a user may enter a single value.

Properties
Property Description
default The default value presented if no value was previously entered. This can be a string or a Tcl expression.
display Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge.
required If this property is displayed, the user must provide a valid value.
validator Tells the renderer what type of data is valid. If input is not valid, the user is returned to the template screen that has a red error message next to the field in question. Validators include FQDN, IpOrFqdn, IpAddress, NonNegativeNumber, Number, and PortNumber
Syntax Example
string user_name required string port default "80" display "small" validator "PortNumber"

password

The password element is similar to a string element, except the contents are obscured to protect the data.

Properties
Property Description
display Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge.
required If this property is displayed, the user must provide a valid value.
Syntax Example
password passwd required

choice

The choice element presents a list of options where only one item can be selected.

Properties
Property Description
choices Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression.
default The default value presented if no value was previously entered. This can be a string or a Tcl expression.
display Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge.
Syntax Examples
choice pools tcl { tmsh::run_proc utils:get_items ltm pool } choice yesno default "no" {"yes", "no"} choice load_balance_method { "Round Robin" => "round-robin", "Least Connections" => "least-connections-memeber", "Ratio" => "ratio-member" }
Note: In the choices family of APL elements, the => attribute maps the actual value provided to the implementation script to what is displayed in the Configuration utility.

editchoice

The editchoice element presents multiple choices that users can select, and allows the user to enter a new value if the default choices are not acceptable.

Properties
Property Description
choices Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression.
default The default value presented if no value was previously entered. This can be a string or a Tcl expression.
display Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge.
Syntax Example
editchoice port default "80" {"* All Services" => "*", "HTTP" => "80", "HTTPS" =>"443"}
Note: In the choices family of APL elements, the => attribute maps the actual value provided to the implementation script to what is displayed in the Configuration utility.

multichoice

Use the multichoice element to allow the user to select multiple items from the available choices.

Properties
Property Description
choices Required. This lists the available items that the user can select. This is a list of strings that can be defined manually or populated with a TCL expression.
default The default value presented if no value was previously entered. This can be a string or a Tcl expression.
display Gives a hint to the renderer about how this element should be displayed. The values can be small, medium, large, xlarge, or xxlarge.
Syntax Example
multichoice your_string default {"Choice1", "Choice3"} {"Choice1", "Choice2", "Choice3"}
Note: In the choices family of APL elements, the => attribute maps the actual value provided to the implementation script to what is displayed in the Configuration utility.

table

The table element can have items added to it, with each item containing multiple pieces of information. Each element added as a child of the table element defines the columns of the table. While the string and choice elements give the ability to set scalar types, table provides the ability to set list types.

Syntax Example
table servers { string address choice port {"80", "443"} }

row

You can also think of the row element as a single-row table, and each element that is added as a child of the table element defines the columns of the row.

Syntax Example
your_row seven { string bar1 string bar2}

message

The message element adds an extra text message within a section.

Syntax Example
message mymsg "This is my message to you."

section

The section element is the topmost hierarchical layout element. The primary function of this element is to group related sub-elements together.

Syntax Example
section ssl_questions { choice ssl_enabled { "true", "false" } }

define

The define element allows the creation of user-defined types created out of existing types. The defined type can then be used multiple times independently. This is especially useful in conjunction with the include element because types can be defined in the included application presentation language script, and then used where necessary in the template.

Syntax Example
define choice boolean_question {"True", "False"} section basic { boolean use_ssl }

optional

The optional element allows application variables to be hidden or shown based on the state of other application variable. The syntax for the optional element is: optional (<expr>) { <contents...> }. Visibility of optional elements is re-evaluated any time the value of an element changes. With optional, you can use only elements that have a value like string or choice .

Syntax Example

In this example, the optional_questionstring should be shown only if use_ssl is set to "True"

choice use_ssl {"True", "False"} optional (use_ssl == "True") { string optional_question }

include

The include element copies the referenced content of the application presentation language script into the current document.

Properties

None.

Syntax Example
include "com.f5.apl.common"

text

The text element lets you define the text labels and questions for sections, elements, table, or row sub-elements. The syntax for the text element is: text { <section, element, table, or row>.<string name> <"string contents in parenthesis"> }.

Syntax Example

In this example, the text strings contain the template's "edit" section's questions.

section edit { string addr string port } Text { edit “The EDIT section” edit.addr “What IP address do you want for the EDIT virtual server?” edit.port “What port should the EDIT virtual server answer on?” }

Dynamic data binding using Tcl expressions

You can use Tcl expressions to dynamically generate default values or an available-choices list at run time. Tcl expressions can retrieve information from the mcpd service and process the data as needed.

After a Tcl script is run, the returned data can be processed into discrete items separated by a new line (\n). Next, split the items by tabs (\t) into display and value segments that represent what the user sees, and what is saved by the mcpd, respectively. Without a tab to split the items, the display is the same as the value.

For example, if a Tcl expression for a choice element returns disp1\t val1\n disp2\t val2, then the list of items presented to the user would be disp1 and disp2.

The following example creates a choice that presents a list of LTM®pool names. Note how the tmsh commands are used to retrieve the data.

section my { choice pools tcl { set objs [tmsh::get_config ltm pool] foreach obj $objs { append results [tmsh::get_name $obj] append results "\n" } return $results } }

About disabled Tcl commands

When you use iApps™ to create your own templates from scratch, along with tmsh, you also use Tool Command Language (Tcl) for most of the basic instructions. Because a subset of Tcl commands is disabled from use with iApps templates, you should avoid using these when creating or editing iApps templates.

The Tcl commands that are disabled for iApps template use are:

after auto_execok auto_import
auto_load auto_mkindex auto_mkindex_old
auto_qualify auto_reset bgerror
cd close eof
exec exit fblocked
fconfigure fcopy file
fileevent filename flush
gets glob http
interp load memory
namespace open package
pid pkg::create pkg_mkIndex
proc pwd rename
seek socket source
tcl_findLibrary tell unknown
update uplevel upvar
vwait    

Presentation section usage recommendations and limitations

The iApps™ application presentation language has the following usage recommendations and limitations. Follow the recommendations and avoid the limitations to ensure that the system will accept and run your template .

Recommendations or limitation Detail
Forward definition order Variables exist only if they have been defined earlier in the template. Specifically, you can create an optional section that displays its contents based on a field above it in the template, but not based on a field that exists below it in the template.
No nested sections or tables The section and table elements do not function correctly if they are embedded in other APL elements.
No Tcl insertion inside optionals Reliable execution cannot be guaranteed because optional states are unpredictable.
Optionals inside tables must depend on elements outside the table This ensures correctly displayed tables.

About layout properties

Layout elements do not have a value or define a variable. Their primary function is to give hints to the renderer on how the children of the element should be displayed. The layout elements also affect the variable name for the element. When referencing a specific variable within the application presentation language, such as within an expression, then the fully-qualified dotted name is used. For example, if a string called string is contained within a section, my, then the full name would be my.string.

About element validators

Validators are used on certain elements to define what user input is allowable. The BIG-IP® system always has the final say on what is allowed, but if a validator value is given to the Configuration utility, it can present the user with a more useful error message about the location of the error.

Note: The validator name is not case-sensitive.
Validator Accepts
FQDN Domain name (RFC 1034)
IpOrFqdn ipv4, ipv6 or domain name (explicitly disallow "*")
IpAddress "*", ipv4 or ipv6
NonNegativeNumber Integer >=0
Number Any integer
PortNumber "*" or int value 0-65535 (inclusive)

The following is an example of a validator that restricts text box input to a valid port number.

string port default "*" validator "portnumber"

About the help section

The help section of an iApps™ template contains HTML help text that template users can access in the BIG-IP® Configuration utility under the Help tab. Template authors can supply as little or as much help content as needed. F5 Networks encourages all template authors to provide at least a minimum amount of help.

Important: For security purposes, the help section only displays text using a simplified set of HTML commands. The help section does not support images, links, and scripts.

HTML tags supported in the template help section

An iApps™ template's help section supports only the HTML tags listed in the following table. Templates containing HTML tags that are not listed in the table generate an error message when an application service tries to use them.

HTML tag Function
<b> Defines bold text
<blockquote> Defines a long quotation
<br /> Defines a single line break
<code> Defines computer code text
<dd> Defines a description of a term in a definition list
<dl> Defines a definition list
<dt> Defines a term (an item) in a definition list
<em> Defines emphasized text
<h1> to <h6> Defines HTML headings
<i> Defines italic text
<li> Defines a list item
<ol> Defines an ordered list
<p> Defines a paragraph
<pre> Defines preformatted text
<small> Defines small text
<strike> Defines strikethrough text
<strong> Defines strong text
<sub> Defines subscripted text
<sup> Defines superscripted text
<u> Defines underlined text
<ul> Defines an unordered list
<!--...--> Defines a comment

About the role-acl property

The role-acl property restricts user access to application services. Besides using the standard user roles to control access to application services, you can further restrict access by setting the role-acl property on the template used for an application service. For example, if you want only administrators to manage the application services, then you set the role-acl property to just admin.

The role-acl property exists at the same hierarchal level in the template as the template sections, as shown below. The role-acl property can only be edited using a text editor because it is not visible in the Configuration utility.

sys application template f5.template_name { actions { definition { html-help { <HTML help definition goes here> } implementation { <Back-end TCL and TMSH code goes here> } presentation { <APL GUI code goes here> } role-acl { admin manager resource-admin } } } }

The role-acl property is also useful if a template creates objects that the user role is not able to create. For example, the Application Editor role is not allowed to create pools, so if your template creates pools, then you should set the role-acl property so that the user gets a more meaningful error message.

Table of Contents   |   << Previous Chapter

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)