sys application template

sys application template(1)			  BIG-IP TMSH Manual			  sys application template(1)

NAME
       template - Enables the creation of user-defined templates.

MODULE
       sys application

SYNTAX
       Configure the template component within the sys application module using the syntax in the following sections.

   CREATE/EDIT/MODIFY
	create template [name]
	modify template [name]
	 options:
	  actions [add | delete | modify | replace-all-with] {
	     definition {
	       options:
		html-help [string]
		implementation { [string] }
		presentation  { [string] }
		role-acl [add | delete | modify | replace-all-with] {
		    [role]
		}
		role-acl none
		run-as [string]
	     }
	  }
	  description [string]
	  requires-modules [add | delete | modify | replace-all-with] {
	      [string]
	  }
	  requires-bigip-version-max [string]
	  requires-bigip-version-min [string]
	  metadata
	    [add | delete | modify] {
	      [metadata_name ... ] {
		value [ "value content" ]
		persist [ true | false ]
	      }
	  }

	edit template [name]

   DISPLAY
	list template
	list template [name]

   DELETE
	delete template [name]

   GENERATE
       Note: generate cryptographic signature or checksum based on template fields - html-help, implemenation, macro
       and presentation in definition section.

	generate template [name]
	  options:
	    checksum
	    signature

   SAVE/LOAD
	save template [name] file [filename]
	load template [filename]

DESCRIPTION
       Application templates allow a user to define a custom interface for easily creating complex configurations.
       The user can create multiple templates for various types of configurations. Once built, the user can use a
       template to create an application, which is a specific set of configuration objects (such as Virtual IP
       addresses, pools, and so forth), that work together to perform some task.

       The template is composed of two primary parts, the presentation and the implementation.

       The presentation section describes a form (a set of questions and user interface elements) that the user must
       fill out in order to create an application.

       The implementation section describes how the values collected from the user (the form variables) are used to
       generate the actual configuration objects which are part of the application.

       The presentation section of the template is written in a simple language called Application Presentation
       Language or APL. The implementation section of the template is written in TCL and provides access to tmsh
       scripting commands.

APPLICATION LIFECYCLE
       Before describing in detail how a template is written, it is important to explain how the resulting template
       will be used. Since templates are used to create and edit applications, it makes sense to review the
       application lifecycle.

   Application Creation
       The user selects which template to use for his application. The system presents an empty form, based on the
       template's presentation script that the user fills out and submits. The system collects and stores the form
       variables in a newly created application object. Configuration objects are generated based on the form
       variables by the template's implementation script.

   Application Editing
       The user selects an existing application that he would like to change. The system reloads the form associated
       with the template that was used to create the application and refills all form variables using the previous
       user input, which is gathered from the application object. The user edits the form and submits it. The
       template's implementation script is run again to compute a new set of configuration objects for the
       application. The system alters the current configuration objects associated with the application to match the
       newly computed set of configuration objects, including creating, modifying, and deleting objects as needed.

   Application Deletion
       The user selects an application to delete. All configuration objects associated with the application are
       removed.

APPLICATION TEMPLATE LANGUAGE
       The application template language describes the user interface presented to a user making a new application,
       or editing an existing application. It describes what questions to ask, how the questions are presented (for
       example, a free form field or a list of options), and the names of the variables used to store the values the
       user inputs.

       It consists of a set of primitive form elements (string, choice, etc), a set of grouping and organization
       constructs (section, table, etc), methods for hiding or displaying portions of the form based on the values of
       other portions (optional), a method to associate human-readable text with various form elements (text) and
       methods for creating user defined types(define group, define section, etc) for reuse of application
       presentation language elements.

   Primitive Elements
       Primitive elements represent the actual user interface components. The system displays each primitive element
       as part of the form, and associates it with a form variable. The following lists the basic primitive types:

       choice
	   A list of options from which the user can select (a drop-down menu).

	    choice  [default ""] [display ""] {"", "", ...}

       editchoice
	   Multiple choices are available that the user can select, or a new value can be entered if the choices are
	   not acceptable.

	    choice  [default ""] [display ""] {"", "", ...}

       multichoice
	   Similar to a basic choice element except that multiple items may be selected from the available choices.

	    choice  [default ""] [display ""] {"", "", ...}

       password
	   Similar to a string element except the contents may be obscured to prevent others from seeing the value.

	    password  [default ""] [display ""] [required]

       string
	   A basic text box into which the user can enter an arbitrary string.

	    string  [default ""] [display ""] [required] [validator ""]

       Each primitive element is associated with a variable name, which defines where the value collected by the form
       is stored. In addition, primitive elements can have additional parameters such as a default value, a
       validation method that provides for additional requirements (for example, the string must be an IP address).

       The following defines the format for the string primitive values, using normal BNF syntax:

       ·    default - A sensible default value to which the string is initialized when a new application is created.

       ·    display - Directs the renderer how to display the element. This can be small, medium, large, xlarge, or
	    xxlarge.

       ·    required - If present, a valid value must be entered before the application can be created.

       ·    validator - The name of a well known validation method.

   Section
       The section construct is used to group form variables (primitives) into logical sections for display.

       Each section is named, and header text can be defined for a section using the text construct.

       Every variable must be inside a section. The format for a section is:

	section  {  }

       For example, to represent the data associated with a virtual IP:

	section vip
	{
	   string address
	   string port default "80" display "small"
	}

   Table
       The table construct is similar to section, except that it represents a grouping of elements that can be
       repeated zero or more times. The syntax for table and section are identical.

	table  {  }

       For example, to collect a list of nodes from a user to populate a pool, you can add any number of nodes, each
       of which has an address and port:

	section pool
	{
	  table members
	  {
	    string address
	    string port default "80" display "small"
	  }
	}

       The table above is displayed using a JavaScript-editing widget that enables you to add and remove pool
       members. Each member contains two form variables:  address and port.

   Optional
       The optional construct allows the form elements to be hidden or shown based on the state of other form
       elements. The syntax of the optional construct is:

	optional () {  }

       The expression in the optional construct is evaluated during the display of the form. The content section is
       displayed or hidden, based on its value.

       To dynamically hide parts of the presentation based on the answer to a earlier question, use the variable name
       in the expression:

	section chooseopts {
	  choice show_section_1 {"yes", "no"}
	}
	section section1
	{
	  optional (chooseopts.show_section_1 == "yes")
	  {
	    string str
	  }
	}

   User defined types
       The define construct allows the creation of user-defined types out of primitive types. The defined type can
       then be used multiple times independently at different places. 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. For more details on application presentation language script, See
       help sys application apl-script.

       For example, user defined choice type can be defined as below and can be reused at multiple sections:

	define choice yesno {
	  "Yes", "No"
	}
	section ssl_section {
	    yesno use_ssl
	}
	section optimizations {
	    yesno use_wa
	    yesno offload_ssl
	}

       The define group construct allows the creation of user-defined type to allow the user to group multiple
       elements of existing types together. The defined type can be reused multiple times independently similar to
       the above.

       For example IpAddress and port can be grouped into a user-defined type and reused in multiple sections:

	define group addrport {
	   string addr required validator "IpAddress"
	   string port
	}
	section http_section {
	   addrport server
	}
	section sip_section {
	   addrport client
	   addrport server
	}

   Localization
       The text element lets you define the localized text labels for sections, table, row and other sub-elements.
       For message element, body text can be localized in addition to the label. Similarly for the choice, editchoice
       and multichoice element, display text associated with each choice value can be localized. The syntax for the
       text element is:

	 text [""] {
	   
 "