Liftoff

Liftoff Documentation

Creating user input fields in Liftoff

❗️

Please follow all of these directions carefully.

Missing any of these steps will prevent your template from working.

The Liftoff XML descriptor file

Liftoff uses a portable XML file for determining what fields and types are available for your users to see and manipulate when configuring a product. This file is required for any product template you create. You'll find that the file is very flexible in nature and fairly easy to navigate once you've set one up.

Example XML File

Example of user input fields against the sample above

Understanding the XML file

There are four main components to the XML file:

  • Document Node
  • Groups Node
  • Group Node
  • Variable Nodes

The document must always have the following XML header:
<?xml version="1.0" encoding="UTF-8"?>

The document must also have the starting <document> and closing </document> elements defined. All other fields should be placed between the closing and opening of those elements.

By default, end users have the ability to "copy configuration" of one custom product to another, if the values are the same. If you wish to disable this feature, you will need to add the following line within any existing variable group in your product XML:
<variable type="hidden" name="CopyConfiguration">false</variable>

Groups

A group is a set of variable fields under a single heading. For example, you may want to group an area of input together in one section called "Imprint" or "Images", depending on the need. This allows for clean separation of input types and allows you to define steps for your user to take. After completing each section, the next section will open.

📘

You must have at least one group defined in the XML file.

Example of using groups to manage input selections.

Creating a Group
Directly after the <groups> opening element and before the </groups> closing tag, you can insert a new group.

Below is an example of an acceptable group node with attributes:
<group page="1" order="1" name="Imprint Information">

  • page - This attribute is reserved for future development. For now, its value is always 1.
  • order - Refers to the sorting you wish to apply to this group. Groups will be read in via the order in which they're listed.
  • name - Refers to the display name of this group. The sample above refers to "Imprint Information" as the display name.

Be sure to close your group tag with a closing </group> element.

Variable Fields

Variable fields appear within the group sections on your product configuration pages.

Variable field attributes

Attribute

Description

name

The name of the variable field. This will be passed into Pageflex and should be the SAME as variable names you have installed on your template.
alt textalt text
An exception to this would be the variable name "CopyConfiguration" which is used when you want to disable the Copy Configuration option that appears when multiple products or quantities of the same product with the same set of variables exist in the cart. This is used by adding the following to the template:
variable name="CopyConfiguration" order="1" type="hidden" attributes="">false</variable>

caption

The value displayed to the user on the input form.
alt textalt text

attributes

These values can vary based on the control type selected. See the Variable Control Types section for additional details.
alt textalt text

maxLen

Determines the maximum length of a text field. The default value is 50.
alt textalt text

type

This determines the control type. The following control types are available:
alt textalt text
checkboxlist
colorpicker
fontpicker
hexcolorpicker
hidden
invisible
pantograph
recordselect
select
static
style
table
text
updatepreview
upload
dataupload
disableProofLink

alt textalt text
MICR Validation Controls
(AFFIRM account required)
account
bankcitystatezip
bankname
fraction
optionopenhiddensig
routing
sigline
sigline2
sorting
alt textalt text

helpText

When given a string of text as a value, this attribute allows you to place hints or instructional / explanatory text on the customization page in order to explain the purpose or requirements of a variable (e.g., "Your account number can be found by visiting www...")

hidden

Value of 1 indicates this field is present on the form, but hidden from view.
alt textalt text

required

By adding this attribute to your variable element, you force the user to make an entry. The value for this attribute can be any text you want the user to see if they've failed to properly enter data. Example:
alt textalt text
required="First name is required".
alt textalt text
The text "First name is required" will appear in messaging to the user if they attempt to submit the form with no value present in this field.
alt textalt text

reset

This attribute affects native system variables (see Using data-driven content with Pageflex). By providing one of 3 values, you can control the way the form functions.
alt textalt text
A value of always will force the form value to be updated when a user selects a new identity, places a reorder, or manually updates via the Update Profile Fields button.
A value of manual will only update the form value if the user clicks the Update Profile Fields button.
A value of auto will automatically update the form value if a user selects a new identity or places a reorder.

value

You can create a default value for this field by inputting information between the <variable> and </variable> tags. Example:
alt textalt text
<variable order="4" name="Message1" attributes="" type="text" caption="Description">BRAND NEW</variable>.
alt textalt text
You can use variable declarations to inject other data automatically into these fields. See Mapping Dynamic Data below.

Conditionally hiding/showing variables

It is possible to conditionally hide or show a variable control on the customization form based on the presence of a value, or the presence of a specific value in another variable control through the use of special values for the attributes attribute listed above.

Currently, these attributes can operate on the text, select, and recordselect variable control types.

The syntax is:
attributes="ifField:var_fieldName,ifFieldValue:yourValueHere,then:showOrHide

This is further explained in the following table:

Attribute

Values allowed

Description

ifField

The name of any text, select or recordSelect variable as defined in the template XML, preceded by var_

Example: var_textOne

This attribute defines the field on whose value you would like to base your decision to hide or show the field to which this attribute is applied.

ifFieldValue

This attribute is optional.

Values may include any alphanumeric string.

Example: abc

If this attribute is provided, it must include a value.

If the variable field named by the ifField attribute has a value matching the value of this attribute, the then attribute's action will be taken.

If this attribute is omitted, then the action specified by this field's then attribute will be taken if the variable field named by the ifField attribute has any value other than an empty string.

then

show or hide

If the conditions imposed by this field's ifFieldValue are met, then the described action will be taken. This field will either be hidden or shown.

When a variable control / field is hidden by this feature, its current value is stored, and its value is then set to an empty string. When shown again, its previous value is restored.

By providing these attributes on multiple variable controls in your XML, you can chain this behavior such that hiding or showing one field can trigger multiple others to hide/show simultaneously.

🚧

Using select and recordselect with IF/THEN syntax

If you wish to utilize the IF/THEN feature with select and recordselect variable controls, be sure to give the first option in the select's defaults a value of "" (empty string) or, in the case of recordselect, ensure that the first record in the associated set has a value of "" (empty string).

Variable Control Types

The following control types are available under the current spec:

Control Type

Description

checkboxlist

Generates a list of selections the user can make using checkboxes.
alt textalt text
Using attributes=source:<data source name> will generate a list using a configured data table from Liftoff's "Records" feature.
alt textalt text
Example:
<variable order="1" name="Amenities" attributes="source:Amenities" maxLen="8" type="checkboxlist" caption="Amenities"></variable>
alt textalt text
A checkboxlist control may be filtered in the same way as a recordselect control.
alt textalt text

hexcolorpicker

This control generates a color icon that, when clicked, will display a color-picking modal window. Values are returned in hex format.
alt textalt text

imagepicker

An image picker allows you to create a gallery of pre-loaded image assets. The gallery allows for interactive re-sizing and cropping of images.
alt textalt text
Below is an example of a basic image picker implementation:
<variable name="Image" order="1" caption="Image" type="imagepicker" attributes="recordSource:Images,dimensions:300x300"/>
alt textalt text
In the example above, set your type to imagepicker.
alt textalt text
Please note the following attributes and definition for each:
alt textalt text
recordSource: record source should point to an existing record you have created. Please note that your record should contain the following fields: category and image
alt textalt text
dimensions: this setting allows you to determine the width and height of the image. The proper syntax for this is <width>x<height>
alt textalt text
displayField: this setting has no current effect, but if provided will override sortFieldCode.
alt textalt text
sortFieldCode: Provide a field code from the record set corresponding to recordSource by which you would like to sort results
alt textalt text
sortOrder: This value determines the order in which images will be sorted in the picker based on the values in sortFieldCode. Valid options are asc, desc, and rand for ascending, descending, or random order.
alt textalt text

invisible

This is an invisible control that can be given a default value that auto-populates a template. Values are text-based.
alt textalt text

recordselect

This control allows you to pull dynamic data from a Records table you've established in the Content->Records section of the Liftoff admin. For example, if you had a Records table you wanted to populate a drop down list, you would use syntax similar to this:
alt textalt text
<variable order="1" name="Name" attributes="recordType:Stores,displayField:Name" type="recordselect" caption="Location"></variable>
alt textalt text
The attribute recordType:Stores above indicates we're pulling data from the Stores table and the displayField:Name indicates we're using the Name field as the display value for our drop down list. Advanced filtering options are also available; see Filtering record set data within Pageflex for details.
alt textalt text
Alternatively, if multiple recordselect fields share the same options, you can point the recordselect variable to a <default> node using an optionList attribute, and then specify the record attributes in the <default> node instead. Note that in this approach, the recordType attribute is required in both the recordselect variable and the <default> node, but all other record attributes (including filter directives) are specified in the <default> node:
alt textalt text
In the appropriate <group> section:
<variable order="1" name="Name" attributes="recordType:Stores,optionList:StoreList" type="recordselect" caption="Location"></variable>
alt textalt text
In the <defaults> section:
<default name="StoreList" attributes="recordType:Stores,displayField:Name"></default>
alt textalt text
Multiple recordselect variables may be linked together using the optionGroup attribute. When recordselect variables are linked together with the same optionGroup value, then when the user selects an option for one variable in the group, that option is disabled for all the other variables in the group.
alt textalt text
Finally, recordselect controls can be used in conjunction with text controls to pre-populate values when an option is chosen. For additional details on dynamic field mapping, see Using data-driven content with Pageflex.
alt textalt text

select

The select control has been deprecated in favor of the recordselect control.
alt textalt text

static

A static field can be used to create defaulted data that your user cannot alter by hand. In some cases, you may want to make the results appearing in this field to be dynamic, driven by a recordselect or profile variable. Below is an example of a static field:
alt textalt text
<variable order="1" name="CommunityHeading" attributes="" maxLen="50" type="static" caption="Property Name">@[email protected]</variable>
alt textalt text

style

The style control adds additional controls such as bold, italic and underline to a text containing component. Below is an example of a style control:
alt textalt text
<variable name="Information1Style" order="1" caption="" type="style" maxLen="50" attributes="">false,false,false</variable>
alt textalt text

table

This constructor creates a tabular interface for entering data. Please note this control may require knowledge of Pageflex Document Actions for consuming and distributing input. Example:
alt textalt text
<variable name="Locations" order="1" type="table" maxLen="15" attributes="columns:Date and Time|Location|Address,columnLengths:50|50|50"/>
alt textalt text
In the above example, the attributes listed are columns and columnLengths. Column names can be separated by the | symbol, with a maximum of three columns. The column length attribute defines the maximum allowed characters for each input box created in the table.
alt textalt text

text

This control is fairly versatile. It can be used for the following activities:
alt textalt text
1.) basic textual input
2.) used as a hidden, pre-populated field
3.) receive data as the target of a recordselect selection
4.) receive default data using the @@ constructors for pulling profile data.
alt textalt text
If this field needs to be required, you can add an attribute of required="Required text goes here" to force entry into that field. The text after = allows you to throw an exception message with that text if input is not received.
alt textalt text

updatepreview

Adding this control places a button on your form that, when clicked, forces the proof to update using the variables currently established on the form.
alt textalt text

upload

If your template requires an image to be uploaded, this control can be used to allow images and other files to be uploaded and merged into your template.
alt textalt text

dataupload

Data uploads allow users to upload an Excel spreadsheet as a data source for a template. Upon uploading a spreadsheet, the control will display a listing of available fields that allow your user to map data to a Pageflex template. Additionally, a control panel is available that allows you to page through the available rows within the spreadsheet.
alt textalt text

disableProofLink

Include this variable, without any additional attributes or value, when you wish to hide the Download button that normally appears below the template preview image.
alt textalt text
This may be useful when your product is intended for digital delivery, and includes a cost (i.e. you don't want your customer downloading the item for free).
alt textalt text
Note that even if you specify a download variable, disableProofLink will still override it and take the Download button away.
alt textalt text

XML File Examples

Below are several example XML files you can use to reference when setting up your first XML descriptor files:

<?xml version="1.0" encoding="UTF-8"?>
<document>
 <groups>
  <group page="1" order="3" name="Imprint Information">
   <variable order="1" name="EducationDestination" attributes="" maxLen="50" type="text" caption="Academic Credential"></variable>
   <variable order="1" name="Name" attributes="" maxLen="50" type="text" caption="Name"></variable>
   <variable order="2" name="Title1" attributes="" maxLen="50" type="text" caption="Title 1"></variable>
   <variable order="2" name="Title2" attributes="" maxLen="50" type="text" caption="Title 2"></variable>
   <variable order="2" name="Title3" attributes="" maxLen="50" type="text" caption="Title 3"></variable>
   <variable order="6" name="Tel" attributes="" maxLen="50" type="text" caption="Phone (Enter Numbers Only)"></variable>
   <variable order="8" name="Cell" attributes="" maxLen="50" type="text" caption="Cell (Enter Numbers Only)"></variable>
   <variable order="8" name="Fax" attributes="" maxLen="50" type="text" caption="Fax (Enter Numbers Only)"></variable>
   <variable order="7" name="Email" attributes="" maxLen="50" type="text" caption="Email"></variable>
  </group>
 </groups>
</document>
<?xml version="1.0" encoding="UTF-8"?>
<document>
 <groups>
  <group page="1" order="3" name="Imprint Information">
   <variable order="1" name="Name" attributes="" maxLen="50" type="text" caption="Name">@[email protected]</variable>   
   <variable order="2" name="Title" attributes="" maxLen="50" type="text" caption="Title">@[email protected]</variable>
   <variable order="2" name="Address" attributes="" maxLen="50" type="text" caption="Address">@[email protected]</variable>
   <variable order="6" name="CityStatezip" attributes="" maxLen="50" type="text" caption="City, State Zip">@[email protected], @[email protected]  @[email protected]</variable>
   <variable order="7" name="Email" attributes="" maxLen="50" type="text" caption="Email">@[email protected]</variable>
  </group>
 </groups>
</document>
<?xml version="1.0" encoding="UTF-8"?>
<document>
<groups>
<group page="1" order="3" name="Custom Information">
<variable order="1" name="Name" attributes="recordType:Stores,displayField:Name" type="recordselect" caption="Location"></variable>
<variable order="2" name="EmpName" attributes="" required="Name is required." maxLen="50" type="text" caption="Name *"></variable>
<variable order="2" name="Title" attributes="" required="Title is required." maxLen="50" type="text" caption="Title *"></variable>
<variable order="1" name="Address1" attributes="recordselectVariable:var_Name,recordField:Address1" required="Address is required." maxLen="50" type="text" caption="Address *"></variable>
<variable order="1" name="City" attributes="recordselectVariable:var_Name,recordField:City" required="City is required." maxLen="50" type="text" caption="City *"></variable>
<variable order="1" name="State" attributes="recordselectVariable:var_Name,recordField:State" required="State is required." maxLen="50" type="text" caption="State *"></variable>
<variable order="1" name="ZIP" attributes="recordselectVariable:var_Name,recordField:ZIP" required="ZIP is required." maxLen="50" type="text" caption="ZIP *"></variable>
<variable order="2" name="Phone" attributes="recordselectVariable:var_Name,recordField:Phone" maxLen="50" type="text" caption="Phone"></variable>
<variable order="2" name="Extension" attributes="" maxLen="4" type="text" caption="Extension"></variable>
<variable order="2" name="Cell" attributes="" maxLen="50" type="text" caption="Cell"></variable>
<variable order="2" name="Fax" attributes="" maxLen="50" type="text" caption="Fax"></variable>
<variable order="2" name="Email" attributes="" required="Email is required." maxLen="50" type="text" caption="Email *"></variable>
</group>
</groups>
</document>

Variable resetting for future reorders

Many web-to-print subscribers utilize profile variables. These are variables that automatically merge a user’s profile data into an active web-to-print order, saving on entry time. With this feature, you can enable future reorders of web-to-print products to re-evaluate these variables, based on your specification. This is especially useful when your user’s profile information changes often. Instead of requiring the user to manually update their new order, Liftoff will automatically merge the newest version of this data directly into their reorder.

There are four options for resetting your template variables:

  • Auto – value is automatically updated if the customer selects a new identity or places a reorder
  • Manual – value is only updated if the customer clicks a new Update Profile Fields call to action on the customization page
  • Always – value is updated automatically upon selecting a new identity / placing a reorder or manually via the Update Profile Fields call to action on the customization page
  • None – value is never updated beyond initial population

Below is an example of how you might implement these values in your variable XML:

<variable order="1" name="Name" attributes="" maxLen="50" type="text" caption="Name" reset="auto">@[email protected]</variable>

<variable order="2" name="Address" attributes="" maxLen="50" type="text" caption="Address" reset="always">@[email protected]</variable>

<variable order="3" name="CityStateZip" attributes="" maxLen="50" type="text" caption="City State Zip" reset="manual">@[email protected] @[email protected] @[email protected]</variable>

Implementation is as simple as creating a “reset” attribute for a given variable, and supplying either “auto,” “always,” or “manual” as the value for the attribute.

Using dynamic, data-driven data with your templates

Using Liftoff's comprehensive Records technology, you can merge data from tables you create in the cloud to feed and power your templates and user input forms. For more on this feature, please see this article: Using data-driven content with Pageflex

Updated 7 months ago

Creating user input fields in Liftoff


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.