Applies To:

Show Versions Show Versions

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

About the iApps template framework

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

sys application template f5.template_name { actions { definition { html-help { <!-- insert html help text --> } implementation { tmsh::create cli alias shared f5.template_name command list } macro { <% #insert text and macro syntax here %> } presentation { # insert apl script } role-acl none run-as none } }

Help section

The help section, written in HTML, can provide users with more details about the template.

Macro section

The macro section provides template developers with the ability to develop macros that create objects, and then associate them with iRules.

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 (APL) that is used by the BIG-IP system to create the template's graphical user interface (GUI).

About template design considerations

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

A complex presentation section can frustrate users and generate more support questions and comments for you, the template author. Here are some basic design considerations your template should follow:

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

About application reentrancy

Application reentrancy, describes the process of making revisions to an application service by revising the design template entries that you used to create it. When you select an application service and then click Reconfigure, you can change the entries on the design template that defines that application service. If you make changes to an application service that results in a new configuration, a mark-and-sweep process transforms the old configuration to this new configuration.

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 macro section

The macro section of an iApps template allows template developers to create macro templates. These templates produce generic text that can be used as iRules. Using macros in this fashion makes it very straightforward to produce iRules that your users can easily customize with their unique input while maintaining syntactical accuracy and consistency.

When macros are used with iApps templates, the iApps user customizes the iRule simply by responding to simple questions. These responses are then used to populate the macro variables using a tmsh command (TMSH::Macro_expand).

The iApps developer can use the presentation section of the iApps template to make it very straightforward for end users unfamiliar with Tcl code to use and customize iRules. The graphical user interface (GUI) displays questions related to the customizable sections of the iRule that the developer specified in the presentation section of the iApps template. Users can then make simple modifications to create high performance, custom iRules. The resulting iRules are less error prone, and easier to deploy and provide the benefit of fully re-entrant iApps.

Built into the macro syntax is the ability to include implicit or explicit debug statements in the iRules text. These statements can provide iRules developers an excellent mechanism for adding troubleshooting support to their iRules without incurring a runtime cost when the iRules are in production.

For example, consider a template that requests responses for IP addresses and pool names. You create a macro file that contains a list of addresses and pool names, and distribute that to your users; the values will populate the template when the iApps template runs. Users can revise the macro file with entries appropriate for their topology.

Syntax Example

This sample iRule includes macro parameters set up to be populated at runtime.

when HTTP_REQUEST { if { [HTTP::uri] starts_with "/foobar" } { switch -glob [HTTP::uri] { "*[0-9].jpg" { pool numbers_pool } default { if { [string length [substr [HTTP::uri] 0 "?"]] > 0 } { HTTP::respond 200 content "<html><head><title>Where's the number?</title></head></body><h1>Where's the number?</h1></body></html>" } } } } } when HTTP_RESPONSE { if { [HTTP::header Content-Length] > 100 } { log local0. "too much data requested." drop } }

This sample illustrates the same iRule, after the parameters have been populated using the macro syntax.

when HTTP_REQUEST { if { [HTTP::uri] starts_with "<%=$url_prefix%>" } { switch -glob [HTTP::uri] { "<%=$glob_pattern%>" { pool <%=$matched_pool%> } default { if { [string length [substr [HTTP::uri] 0 "?"]] > 0 } { HTTP::respond 200 content "<html><head><title><%=$html_title%></title></head></body><h1><%=html_message%></h1></body></html>" } } } } } when HTTP_RESPONSE { if { [HTTP::header Content-Length] > <%=$max_content_length%> } { log local0. "too much data requested." drop } }

Macro delimiter syntax

The delimiters for macro parameters are defined in the table.

Delimiter/Command Name Description
%< Code to Evaluate The beginning of an expansion code block.
<%= Evaluate and Output The beginning of an expansion code block. Spool the output after evaluating.
<%D[0-9][0-9] Debugging/Logging Code The beginning of a debug/logging code block with the debug threshold set to 0 through 99.
%> Close Code/Output Block The end of the current block (applies to all delimiter types).
<%D[0-9][0-9]= Debugging/Logging Output The beginning of an debug expansion code block. Spool the output after evaluating.

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 template localization

Text strings in an iApp template can be localized by including localized text stings identified with ISO 639-1 language codes. The text string for a supported locale is selected at run time based on the requesting browser's locale preference. If a string for that locale is not included, the default text string is used.

Tip: Let your template users know that localized text is available either with a note in help or with a notice at the top of the template.
text { loc.example “default text” } text "de_AT" { loc.example "Text für österreichische locale (text for German in Austrian locales)" } text "es_MX" { loc.example "texto predeterminado (text for Spanish in Mexico)" }

About template double-byte character support

For international iApps template audiences, the application presentation language text and html commands support Unicode double-byte characters. Using double-byte characters with any other Application Presentation Language (APL) commands might produce unpredictable results.

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 }
define group type

The built-in grouptype for define allow the you to group multiple elements together into a single defined type so that it can be reused, but will not visually group the elements like "section" does. .

Usage considerations Details
Restricted use The group type can only be used as part of a define.
Transparent for parent/child type checking You cannot have a top-level string; it must be inside of a section. When the traversal type checks are made, the group element is ignored and the parent is compared with the top-level elements in the group.
No text association The group element is not allowed to have text associated with it.
Syntax Example
sys application apl-script f5.apl_common { script { define group snatpool { noyes use_snat optional ( use_snat == "No" ) { noyes need_snatpool optional ( need_snatpool == "Yes" ) { table snatpool_members { string addr required validator "IpAddress" } } } } } } sys application template f5.http { presentation { section basic { ... snatpool snat } text { basic.snat.use_snat "Do the HTTP servers have a route back to application clients via this BIG-IP system?" basic.snat.need_snatpool "Will you have more than 64,000 connections at one time? If so, you will need to enter at least one IP address for each 64,000 connections. " basic.snat.snatpool_members "Enter IP addresses that can be used for a SNAT pool. Enter one IP address for each 64,000 connections " basic.snat.snatpool_members.addr "Address: " } } }

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_question string should be shown only if use_ssl is set to "True"

Important: Only the == and != operators are valid in the optional statement. This may require a little extra thought on your part if you are used to creating conditional statements using a broader range of operators.
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 LTMpool 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    

About 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.

Recommendation 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.
Optionals inside tables must depend on elements outside the table iApps cannot locate variables inside a template's table, so they must be located outside the APL table element structure.

About layout elements

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   |   Next 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)