Administering Form Templates

Aptify's Form Template technology automates and simplifies the creation and maintenance of data forms.The Form Template functionality allows an administrator to create different templates for individual organizations or individual users that may include the removal or addition of entire tabs to forms, or the removal, addition, or rearrangement of fields on the forms. Individual end users may make modifications to how they view records, including rearranging tabs on forms, and may also switch between form templates if more than one template is defined for the form.

This topic covers the following sub-topics:

• About Form Templates
• Copying and Modifying an Existing Form Template
• Creating a New Form Template
• Loading Forms Based on Usage Context
• Modifying the Display Settings for a Hierarchy Browser
• Validating the Preferred Phone Number Settings

About Form Templates

Form Templates define how forms are displayed when a user logs in to Aptify and opens a new or existing record from a particular service. The appearance and order of fields and tabs on a form are defined by the template specified for the user. Templates may be global (shared by all users and groups who have permissions on a template) or may be specific to a group of end users or an individual end user.

All forms in Aptify fall into one of three categories:

• Generated Forms: Entity forms that were created automatically by the Aptify Baseline Form Template Generator. The form template for the Cultures service is an example of generated Form Template.
• Forms Created within Aptify: These forms are created by a developer using the Aptify system. In some cases, these forms begin as generated forms but are then modified as necessary to add additional functionality (such as a Topic Codes control) to a form. In other cases, a developer creates a blank template with tabs and uses the Visual Designer to place fields on the form. The form template for the Companies service is an example of a Form Template created in Aptify.
• Viewer Forms: These are forms that are designed entirely by a developer within Visual Studio .NET. These forms specify a Viewer plug-in at the entity level. Entities that have a Viewer plug-in do not use the Form Templates service, and administrators cannot edit the form within Aptify. The form for the Archive Runs service is an example of a Viewer form.

See Adding Plug-Ins to an Entity for information on how to add a Viewer form to an entity. The steps required to write a Viewer plug-in are beyond the scope of this document.

Administrators and users can modify the form appearance for Generated and Modified Form Templates. A Viewer Form can only be modified in its source code. Therefore, this topic deals with Generated and Modified Forms only.

This topic covers the following sub-topics:

• About the Baseline Form Template Generator
• About the Form Template Services
• About the Form Template Hierarchy

About the Baseline Form Template Generator

Aptify automatically generates the form template for a new entity when an administrator saves it for the first time with the Generate Table option checked on the Entities record. The system also regenerates form templates as needed if there are subsequent changes to the entity that need to be reflected on the form.

For example, if an administrator adds or removes a field from an entity, the system automatically regenerates the template. If an administrator changes the Show In Find attribute for an entity field, the system does not regenerate the template since this change has no impact on the form's appearance.

A form created by the Form Template Generator includes the following characteristics:

• General Tab: The generator adds all entity fields that do not have a Category specified to a General tab. Fields appear in the order in which they appear within the entity (assuming they are in the same category).
• Attachments Tab: The generator adds an Attachments tab to all generated forms.
• Sub-Type Tabs: For top-level entities, the generator adds a tab for each of its sub-type entity.
• Related Entity Tabs: If an entity is the foreign key for another entity (that is, there is a link box on another entity's form that links to this entity), the generator automatically creates a tab that lists the records in the related entity where the current record appears in the link box. These tabs do not appear on the form by default but a user can add them using the Configure option. (See Modifying the Tab Layout on a Form.)
• Other Tabs: If one or more fields have a Category specified, the generator automatically creates a tab using the Category name. Fields in a particular category appear under the tab with the same name.

Notes Concerning Form Template Generator

• The Baseline Form Template Generator does not place the following types of fields on a form:
  • Non-updateable, In Table fields (such as a WhoCreated field)
  • Virtual Fields not associated with an embedded link
  • Embedded link fields 
• If fields are added to or removed from an entity and the entity is saved, the system automatically updates all of the entity's generated, global form templates unless the entity has a Viewer Plug-in specified on the Plug-Ins tab of the Entities record. Note that the system does not automatically update non-generated templates that have been modified for organizations or end users; these must be manually updated, if necessary.
• When an entity is regenerated, the Baseline Form Template Generator deletes any existing generated form templates for the entity and recreates them as necessary. Therefore, if you modify a top level Form Template or a Tab Sub-Template Form Template (thus making it non-generated), you should also modify (for example, rename) all of that template's associated sub-templates to ensure that the generator does not inadvertently delete sub-templates that are used by a non-generated higher level form template.
• The Baseline Form Template Generator does not delete non-generated form templates when regenerating an entity's form templates.
• In some cases you may want to regenerate the entity's form templates without having to regenerate the entire entity. For example, you may want to regenerate the entity's form templates if you modified a form manually and now want to revert to the generated version. Regenerating the entire entity in this case may not be necessary and could have a significant impact on system activity during the regeneration. In this case, an administrator can regenerate an entity's form templates by using the Generate Form Template option on the entity's Form Templates tab without having to manually regenerate the entire entity. Selecting this option triggers the regeneration the entity's form templates without having to manually regenerate the entity as a whole. 
  
   

 

About the Form Template Services

Form Template functionality uses the following services:

• Form Templates Service: This service stores the templates that define the appearance of each form in Aptify (except for Viewer forms). Each form has one or more templates associated with it. There are three types of Form Templates records:
  • Top Level Form Template: This record is a container that defines the entire form.
    • Top Level forms are identified when the Is Top Level option is selected, which appears on the Form Templates record's General tab.
    • In Aptify, a Top Level Form Template typically has a name in one of these formats: [Entity Name].Form or Standard Aptify [Entity Name] Form.
    • Any new generated forms the system creates will use the [Entity Name].Form naming convention.
       
  • Tab Sub-Template: This record is a container for the tabs that appear on a form.
    • In Aptify, a Tab Sub-Template typically has a name in one of these formats: [Entity Name].Tabs or Tab Sub-Template for the [Entity Name] Entity.
    • Any new generated forms the system creates will use the [Entity Name].Tabs naming convention.
       
  • Tab Template: A Tab Template defines what fields appear on a tab.
    • In Aptify, a Tab Template typically has a name in one of these formats: [Entity Name].Tabs.[Tab Name] or [Tab Name] Tab - [Entity Name] Form.
    • Any new generated forms the system creates will use the [Entity Name].Tabs.[Tan Name] naming convention.
       
• Form Template Parts Service: Each Form Templates record contains one or more Form Template Parts. This service defines the items that comprise each template. The applicable parts depend upon the type of Form Template:
  • For Top Level Form Templates, parts typically consist of a Tab Sub-Template Part and, in some cases, a Top Area part.
  • For Tab Sub-Templates, parts typically consist of Tab parts.
  • For Tab Templates, parts typically correspond to fields that implement a specific Form Component (such as a Text Field for a Name field).
     
• Form Template Part Categories Service: This service groups together related Form Template Parts. Typically, categories are created on a per-entity basis. The Aptify Baseline Form Template Generator creates Form Template Part Categories as needed using the following convention: [Entity Name] Form Parts. See Creating Form Template Part Categories and  About the Form Template Part Categories Form.
   
• Form Components Service: This service defines re-usable components, such as the text field and link box, that are the building blocks for all forms. Each component specifies a series of Input Properties. Parts that use a component specify values for these Input Properties to display the desired information.
   
• Form Component Categories Service: This service groups together related Form Components. See Creating Form Component Categories and About the Form Component Categories Form.
•  

About the Form Template Hierarchy

With the exception of Viewer forms, each form in Aptify is comprised of a series of related Form Templates, Form Template Parts, and Form Components records. This is particularly true of forms created by the Aptify Baseline Form Template Generator. The following is an overview of the records that typically comprise a form created by the generator:

• Each form begins with a top-level Form Templates record that uses one of following naming conventions: [Entity Name].Form or Standard Aptify [Entity Name] Form. This template has the Is Top Level option selected on its record's General tab.
  • The Usage Scope and Rank fields on this record determine which users will see this form. User-scope forms take precedence over Group and Global, and Group-scope forms take precedence over Global. Within a particular scope, a lower ranked form takes precedence over a higher rank. By default, all forms created by the generator have a Global scope and a rank of 100.
  • The dimensions on the Format tab specify the default size of the form (in pixels).
  • The Security tab specifies the Users and Groups who can see the form. On generated forms, the entity's security settings automatically flow down to the form.
  • The Part List tab is a sub-type listing that stores the first level of parts that are used by the form.
  • Modified forms may have a Top Area Part that links to a Form Component created by a developer. For an example, see the Aptify.Companies Form Template record.
  • For generated forms, typically there is only one part for a top-level Form Templates record named either Tab Form Part for the [Entity Name] entity or [Entity Name].Tabs. 
• The Tab Form Part is a Tab Control that specifies the number of tabs per row for the form and links to a sub-template, which is a Form Templates record typically named, Tab Sub-Template for the [Entity Name] Entity or [Entity Name].Tabs.
• The Tab Sub-Template record's Part List tab stores links to the Form Template Parts records that correspond to the tabs on the form (one part per tab).
• Depending on the nature of the tab, a Tab part is either a Sub-Template or a Component.
  • A Sub-Template part links to another Form Templates record that defines the fields on a specific tab.
  • A Component part that corresponds to a tab links to a Form Components record that corresponds to a tab control (such as a Topic Codes tab or the Attachments tab).
  • Typically, a tab part uses one of following naming convention: [Tab Name] Tab - [Entity Name] Form (for example, General Tab - Cultures Form) or [Entity Name].Tabs.[Tab Name] (for example, Campaign Segments.Tabs.General). 
• A Sub-Template record defines which fields appear on a tab and each field's position on the form.
  • The layout of a tab's fields can be changed on the Visual Designer tab.
  • The Part List tab lists the fields that appear on the tab. Each field corresponds to a Form Template Parts record. 
• Each field's Form Template Parts record is a Component part that links to a Form Components record.
  • Typically, a field part uses one of the following naming convention: [Entity Name] Template - [Field Name] Field (for example, Cultures Template - Name Field) or [Entity Name].[Field Name] (for example, Campaign Segments.Name).
  • A Component part links to a Form Components record (such as a Text Field). The Input Map tab on the Form Template Parts record defines the parameters for a specific instance of the component.

Consider the example of the Campaign Segments entity's standard form template, shown below, which includes a General tab, a Campaign Documents tab (for a sub-type entity), and the standard Attachments tab.

 

The following flow chart illustrates the relationship between the various records that comprise the standard Campaign Segments form:

IDs are included for illustrative purposes only. The record IDs on your system may vary from what is listed below.
Note that the following abbreviations are used in the diagram:

• FT: Form Templates record (in gray)
• FTP: Form Template Parts record (in white)
• FC: Form Components record (in blue, if viewed on-screen 

 

Copying and Modifying an Existing Form Template

This section describes the methods an organization can use to modify an entity's form template using the existing template as the starting point.

The first step in this process is to create a copy of the existing baseline Aptify form template. This will ensure that any future changes Aptify deploys to the delivered form template do not inadvertently overwrite your organization-specific changes.

Once you have created a copy of the baseline template, an administrator or developer can modify the form to add, remove, or rearrange fields or tabs.

This topic provides information on the following sub-topics related to modifying an existing form template:

• Using the Form Template Copy Wizard
• Modifying the Tab Layout on a Form
• Modifying Field Layout with the Visual Designer
• Adding a New Control to a Form
• Adding a Layout Control
• Displaying Scroll Bars When Form Is Resized
• Configuring Hot Keys for Fields

Using the Form Template Copy Wizard

Aptify provides a Form Template Copy wizard that creates a copy of an entire form template hierarchy for a top-level form, including copies of form template parts. Aptify recommends that a developer use this wizard when working with form templates to create a copy of the system's baseline form template and then modify that copy as desired. This will prevent the system from inadvertently overwriting any of your changes if Aptify modifies the standard form templates at a later date.

Note that cloning a form template is not the same as using this wizard – the cloning operation only clones a particular Form Templates record and remains linked to existing Form Templates and Form Template Parts. Changing these form template parts will then lead to undesirable side effects to the other forms that use the same parts.

Follow these steps to create a copy of a form template:

1. Identify the form template whose structure you want to copy. Make a note of the current Rank for that template.
2. Create or open a view of Form Templates.
3. Click the Form Template Copy Wizard icon in the view toolbar to launch the wizard. 
   
    
4. Review the information on the wizard's Welcome screen and click Next to continue.  
   
    
5. Enter the Form Template that you want to copy in the Top-Level Form Template field.
6. Enter a prefix to add to the name of the templates and parts that the copy process will create in the New Form Template Name Prefix field.
   • For the purposes of packing and unpacking form templates, this prefix will differentiate your copies from the original form. 
7. Specify the rank for the new form templates in the New Form Template's Rank field.
   • If two top-level templates have the same scope, the system displays the template with the lower rank.
   • If you want the copy to display within Aptify, you should specify a rank for the new form template that is lower than the rank for the old form template.
   • By default, the new form template is assigned a rank of 10.
   • See Modifying a Tab Sub-Template's Scope and Rank and Creating a New Form Template for discussions on the impact of the Rank field on form template displays. 
8. Specify a new rank for the old form template in the Old Form Template's Rank field.
   • During the copy process, the wizard will update the Rank for the Form Templates it copies to the value specified in this field.
   • By default, the old form template is reassigned a rank of 100. This may not correspond to the form's current rank (which you identified in Step 1 above).

   • Modify the Old Form Template Rank as necessary depending on which form template you want to display by default within Aptify.

     If necessary, you can always modify a form template's Rank later directly within the Form Templates records.

9. Click Next to continue.
   • Note that only one top level form template can be assigned a particular rank for an entity. If the Rank you specified for the old or new form template is already assigned to another top-level form template, the system will display a message alerting you to this situation. If a message box appears, click OK and modify the Ranks accordingly. Then, click Next again to continue.
      
      
10. When ready, click Finish to begin the copy process.
11. Click OK when notified that the process is complete.
    • The original top level form template and its related templates are updated with the Old Form Template's Rank value you specified in the wizard. The new top level form template and its related templates are assigned the New Form Template's Rank value you specified. In the example below, the Aptify.Persons form template hierarchy has been reassigned a Rank of 99 (as shown previously, the Rank of 100 was already used by another form), and the new copy (DEV.Aptify.Persons) has been assigned Rank 10.  
      
       

Modifying the Tab Layout on a Form

All users can configure their own tab layouts to add, remove, or rearrange tabs on a form as desired. See Editing Form Template Appearance for information on how to modify a template directly from a form. That topic also describes how to switch between available templates.

Note that the system assumes that any template modified directly from the form applies only to that user. If no template existed specific to that user for the form viewed, a new Tab Sub-Template Form Templates record for the specified entity is created automatically, with a Usage Scope of User and the User field set to the User record of the user. This new template uses the global Tab Sub-Template as its Base Template. Also, the Base Template's security permissions flow down to the new template, but because the new template's usage scope is "User," only the creator of the new template has access until the user scope is changed.

An administrator can create a group-scope form by creating a user-level template first and then modifying that Tab Sub-Template's record in the Form Templates service to change its scope to Group so it is available to other users.

Tab Sub-Template Selection Methodology

The system uses the following methodology to determine which Tab Sub-Template to display for a particular user:

• For a particular user and entity, the system selects a User template first (if one exists). If a User template does not exist, the system selects a Group template. If neither a User or Group template exists, then the system selects the Global template.
  • Note that form template purposes, a user is associated with only one group (his/her Primary Group). A user is assigned a Primary Group in the Users record. 
• If the system identifies multiple templates with the same scope, the system uses the record with the lowest rank.

• If the system identifies multiple templates with the same scope and the same rank, the system uses the record with the lowest ID.

  In addition to the template that displays by default, a user can switch between any additional User scope or Group scope templates that apply to that user from the Switch Template dialog (see Switching Between Form Templates for instructions).

Modifying a Tab Sub-Template's Scope and Rank

The following steps describe how to modify the scope and rank of a user-level template.

1. Open the form whose tab layout you want to modify.
2. Follow the steps in Editing Form Template Appearance to add, delete, or reorganize the tabs that appear on the form.
   • This creates a User scope tab sub-template for that entity with a rank of 100.
3. Locate the Form Templates service, found under the Aptify Framework Administration application.
4. Open the Form Templates record that corresponds to the new User scope tab sub-template you created in the earlier steps.
5. Refer to the steps below that correspond to the changes you want to make to the template:
   • To modify the user-level template's rank, enter a new value in the Rank field.
   • See Tab Sub-Template Selection Methodology for information on how the Rank field determines which template the system displays.
   • The Rank field supports a value between 0 and 100.
   • To create a group-level template, follow these steps:
   1. 1. Set Usage Scope to Group.
      2. Specify a group in the Group field that appears automatically. Users whose Primary Group is set to the Group you entered will have access to this template (assuming the group has an entry on the template's Security tab).
      3. Configure the template's Rank. The Rank field supports a value between 0 and 100.
         
         
6. Save the record.
7. If the form template is currently generated, click OK when prompted that the template will become non-generated.
8. Close the record.

Note that the steps above describe how to modify the rank for a user-level template or change it to a group-level template. These steps are not applicable to change a user-level template to a global template. To specify a new global template, you must link the new template to the appropriate Tab Form Part record (thereby replacing the existing global tab sub-template). Also, any user or group-level tab sub-templates must also be linked to the new global template by specifying the new template in the user and group-level templates' Base Template field.

Modifying Field Layout with the Visual Designer

Aptify includes a WYSIWYG (What You See Is What You Get) tool, called the Visual Designer. This tool provides an administrator with the ability to rearrange the parts on a form's tab and to add new fields and controls as needed. (Each field or control on a form's tab corresponds to a different Form Template Parts.)

Note that whenever possible, Aptify developers used this Visual Designer tool to design non-generated form templates for business application entities.

This topic includes the following information on the Visual Designer:

• Opening the Visual Designer
• About the Visual Designer Interface
• Using the Visual Designer to Modify Existing Fields
• Using the Visual Designer to Add New Fields or Controls
• About the Supported Visual Designer Components
• Assigning a Modified Field Layout to a Specific User or Group
• Tips for Using Visual Designer

If you use the Visual Designer to make changes to a tab's field layout, the corresponding Form Templates record becomes non-generated. If you later regenerate the entity, the Baseline Form Template Generator will not overwrite the non-generated Form Templates record. In this case, not all of your entity changes may be reflected in the entity's form template. You will need to modify the non-generated Form Templates record (using the Visual Designer) to add your changes manually or delete the existing Form Templates and regenerate the entity (if you want to recreate a generated form template for the entity). See Tips for Using Visual Designer for information on how to reinstate the generated template as the default.

Opening the Visual Designer

This section describes how to open the Visual Designer and place a record in design mode. Note that once a record is in design mode, you cannot access any other record in the system until you close the Visual Designer. Also, keep in mind that the Visual Designer is only applicable for Tab Templates (that is, Form Template records that have a number of Form Template Parts that define the fields on a form).

An administrator can open the Visual Designer from one of two locations:

• By right-clicking at the bottom of a form and selecting Design In Place from the pop-up menu. The Visual Designer toolbars open automatically.
  • Note that this menu is only available for system administrators.   
    
    
• By clicking the Visual Designer tab on a Form Template record that defines a tab's fields and layout.
  • From a form, you can right-click in the bottom section of a tab and select Open Form Template... to open the Form Templates record that corresponds to that form's currently selected tab.
  • The Visual Designer tab on a Form Templates record is only available for system administrators.
    
     

About the Visual Designer Interface

A system administrator can use the Visual Designer to modify the parts on a form's tab directly without having to open the underlying Form Templates or Form Template Parts record. This topic describes the Visual Designer interface. See About the Aptify Form Template Properties Dialog for a description of how an administrator can use this tool to modify a form.

The following occurs when you click a Tab Template's Visual Designer tab or use the Design In Place right-click menu option:

• The form's selected tab enters design mode (as shown below).
  
  
• The Aptify Form Template Properties Dialog appears.
• The Toolbox appears.

About the Aptify Form Template Properties Dialog

When you first load a form in design mode, the Aptify Form Template Properties dialog is blank. A field's or control's Form Template Part information automatically appears in this dialog when you select an existing part. When you add a new part to a form by selecting a component in the Toolbox, the system automatically displays the selected component's associated input properties. Note that input properties that require a source value appear in red.

In the example below, the Sample Services record's Title field is selected on the form so information related to this field appears in the dialog's Properties tab.


The dialog has three tabs and a button bar. Each of these features is described in the sections below:

• Button Bar
• Properties Tab
• General Tab
• Comments Tab
• Toolbox

Button Bar

The dialog includes a button bar across the top of the window. From left to right, the default buttons provide the following functionality:

• Close Designer Without Saving Changes: Clicking this button closes the Visual Designer and the form exits from design mode. When you click this button, a Yes/No message box appears asking you if you want to save the changes.
• Save Form Template: Click this button to save any changes you made to the form.
• Delete: This button only appears when a field is selected on the form. Click this button to delete the selected field and remove it from the form.

Additional layout buttons appear in the toolbar when you select two or more parts on a form.

These buttons provide the following functionality:

• Align Control Left Edges: This button aligns all of the selected controls with the left side of the left-most selected control.
• Align Control Middles: This button centers the selected controls along a horizontal line using the location of the last selected control as the baseline.
• Align Control Right Edges: This button aligns all of the selected controls with the right side of the right-most selected control.
• Align Control Top Edges: This button aligns the top edges of the selected controls using the last selected control as the baseline.
• Align Control Centers: This button centers the selected controls along a vertical line using the location of the last selected control as the baseline.
• Align Control Bottom Edges: This button aligns the bottom edges of the selected controls using the last selected control as the baseline.
• Resize Selected Controls – Same Width: This button resizes the selected controls to make them the width of the last selected control.
• Resize Selected Controls – Same Height: This button resizes the selected controls to make them the height of the last selected control. Note that the control must support a variable height to resize it. For example, a Text Field uses a fixed height and therefore cannot be resized, while a Multi-Line Text Field uses a variable height and can be resized.
• Resize Selected Controls – Width and Height: This button resizes the selected controls to make them the width and height of the last selected control. Note that only the width will change for a control that uses a fixed height.

Properties Tab

The Properties tab is an Input Map for the part. Each part configures the appropriate form component by specifying values for a form component's Input Properties. For example, the Sample Service's Title field specifies property values for the Text Field component to display the Title field. Note that the Input Properties that appear on this tab flow down from a Form Components record and vary from component to component. See About the Supported Visual Designer Components for information on the default Input Properties for each supported component. You can also review the Input Properties tab for a particular Form Components record for information on the input values required for that component.

An administrator can edit these properties as necessary to modify the appearance of the part. The procedure for editing these properties is the same as specifying values in a Form Template Part's Input Map: double-click an input map row to open the Edit Mapping form. In general, the Source Type is always Static. See About the Supported Visual Designer Components for more information on specifying the source for input properties in the Visual Designer and see Configuring Form Template Part Input Map Tab for general information on input maps.

When you modify the Properties for a field and save your changes, the Visual Designer automatically updates the Input Map in the corresponding Form Template Parts record for that field. The Visual Designer also creates a new Form Template Parts record for any new field or control you add to the form.

General Tab

Information from the field's or control's Form Template Parts record appears under the General tab. This includes the following:

• Type: This read-only field reports the Form Template Part's Type (Component, Sub-Template, or Tab Control). Form Template Parts accessed using the Visual Designer are Component-based.
• Component: This read-only field reports which Form Component this part implements. For example, the Date field's Form Template Part, shown below, implements the Text Field component.
• Layout Key: This field is used to find and reference form template parts within a Form Template Layout control. The Layout Key is the first candidate for match.
• Part Name: Corresponds to the Name from the Form Template Parts record.
• Category: Corresponds to the category for this part. This field links to the Form Template Parts Categories service.
• Description: Corresponds to the Description from the Form Template Parts record.
• Width Sizing: Corresponds to the Resize Width from the Form Template Parts record's Placement tab. By default, fields have Width Sizing set to None. Note that all generated fields have Width Sizing set to Fill so that the width of the field automatically resizes when you resize its form.
• Height Sizing: Corresponds to the Resize Height from the Form Template Parts record's Placement tab. By default, fields have Height Sizing set to None. If you are adding a new control to the bottom of a form, you may want to set Height Sizing to Fill so that the height of the control automatically resizes when the form is resized.
• Enabled: Specifies whether or not the Form Template Part is enabled on the form. This option is checked by default and the Form Template Part is enabled. When the option is unchecked, the form template part appears on the form but it is grayed out and disabled for all run modes.
• Tab Index: This number indicates the order in which focus moves among the fields when a user presses the Tab key on the keyboard. The first position corresponds to a value of 0. By default on a generated form, this is the first field at the top of the tab. When a uses presses the Tab key, the cursor moves to the second field, which has a Tab Index of 1. When the user presses the Tab key again, the cursor moves the third field, which as a Tab Index of 2, and so on. If you rearrange the fields on a tab (or add new fields), then you should update the Tab Index setting for each field as necessary. Modifying the Tab Index changes the order in which parts appear in the template's Part List tab. (See Adding Parts to Form Templates or  Part List Tab.)

An administrator can modify these settings as necessary. When saved, the Visual Designer automatically updates the form and the corresponding Form Template Parts record.

If a new field or component is added through Visual Designer and the changes are saved without specifically providing a Part Name and/or Category, the new Form Template Parts record uses a logic similar to the baseline Form Template Generator to create and categorize the new form template part with the appropriate category (fields for components that correspond to fields, and form parts for things like line separators and group boxes).

 

Comments Tab

An administrator can specify additional information on the Comments tab related to this field. This tab corresponds to the Comments tab on the Form Template Parts record.

Toolbox

The Toolbox appears automatically each time you load the Visual Designer. This toolbox lists the Form Components that are commonly used on Aptify forms, grouped by Form Component Category. You can select a component in the Toolbox to add a new blank field of that type to the form. See About the Supported Visual Designer Components for more information on the supported Form Components in the Toolbox. You can also review the corresponding Form Components record for these components.

Within the toolbox, you can display all of the supported components by selecting the All Items category on the left-hand side of the toolbox (as shown in below). Alternatively, you can choose to view only the components in a particular category by selecting that category from the list (which appears below the All Items option).

The toolbox displays those components that have the Add to Designer Toolbox option selected on its Form Components record and whose assigned category has Scope set to Global on its Form Template Categories record.

In addition to the components, the toolbox contains the Select option as its first entry. Choose this option to select an existing field on the form and load that field's parameters into the Aptify Form Template Properties dialog.

Using the Visual Designer to Modify Existing Fields

 

 

 

 

Follow these steps to use the Visual Designer to modify a form's field layout on a tab:

1. Identify the changes that you want to make a form. You should have an end result in mind before loading the Visual Designer.
2. Open the Visual Designer for the desired form tab. See Opening the Visual Designer.
3. If you want to change the position of existing fields or controls, follow these steps:
   1. Click Select in the Toolbox, if not already selected.
   2. Select a part that you want to move.
   3. Drag that part to a new position (you can also use the arrow keys to move a selected part). In the example below, the Title field has been moved from the top of the form to below the Description field.
      
      
   4. Drag and drop parts as necessary to rearrange their positions, as desired. In the example below, the fields have been rearranged so Description appears first, followed by Title, and then Date.
      • When you move parts on a form, the Visual Designer automatically updates each part's form location information on the corresponding Form Template Parts records' Placement tab.
      • You can use the design buttons to rearrange multiple parts. See About the Aptify Form Template Properties Dialog for details.
      • Edit the Tab Index for the fields on the tab, as necessary. The Tab Index is found on each part's General tab within the Aptify Form Template Properties Dialog. This controls the order in which focus moves among fields when a user presses the Tab key. Typically, the first field on the tab should have a Tab Index of 0, the second should have a Tab Index of 1, etc.
        
        
4. If you want to modify the behavior of an existing part (such as changing a field's Caption name), follow these steps:
   1. Click Select in the Toolbox, if not already selected.
   2. Select the part that you want to edit to load its values in the Aptify Form Template Properties dialog.
   3. Modify the part's input properties, as necessary.
      • For example, to change the caption name, enter a new caption in the Source field for the LabelCaption input property. In the example below, the caption for the Description field has been changed from Description to Details.

      • In general, all Input Properties in a part's Input Map have Source Type set to Static.

        If a part has a Display Culture String specified, the part uses the Culture String as its caption by default. In that case, the default Display Name that appears in the Form Template Properties dialog for the LabelCaption property may differ from what appears on the actual form. If you modify the LabelCaption for an existing field that uses a Culture String, the form will display the new caption you specify rather than the Culture String. To reinstate the Culture String as the field's caption, blank out the LabelCaption property or return it to the original default value (which is some cases may be blank). Note that the system displays the field's Culture String (if assigned) or Display Name if the LabelCaption is blank.

        
        

      • Modify the part's settings on the General tab, as necessary.
        
        
5. Click elsewhere on the form to remove the focus from the part you selected.
   • The changes you made to the part should now appear on the form. For example, if you changed the part's caption, the new caption appears on the form when you click off of the modified part. Note that in some cases, you may need to save the form and close the Visual Designer and the form before all of your changes appear. Also, in some rare cases, you may need to close and reopen Aptify to refresh the form in order to see all of your changes.
6. If you want to delete an existing part, follow these steps:
   1. Click Select in the Toolbox, if not already selected.
   2. Select the part that you want to delete to load its values in the Aptify Form Template Properties dialog.
   3. Click the Delete icon in the Aptify Form Template Properties dialog's toolbar. 
7. Click the Save Form Template button on the Aptify Form Template Properties dialog to save your changes to the form and exit from Visual Designer mode.
   • Click Yes when notified that the form template will become non-generated if it is currently generated. Upon save, the system will mark the corresponding Form Templates record as non-generated when you save changes made using the Visual Designer.
   • Note that when you delete a field, the Visual Designer will automatically reassign Tab Index numbers to reorder the remaining fields. 
8. Close all open records.

Using the Visual Designer to Add New Fields or Controls

System administrators can add new fields or controls to a tab by dragging a component from the Toolbox to the desired location on the form and configuring the input map for that component.
Keep in mind that the Visual Designer is a development environment, and errors may appear in your client's Session Exceptions viewer as you add and configure new parts. These errors should have no impact on your form as long as you remember to configure all of the part's required properties and its General tab prior to saving and exiting the Visual Designer environment.

Follow these steps to use the Visual Designer to add a part to a tab:

1. Identify the fields or controls that you want to add the form and confirm that the necessary fields already exist in the associated entity. You should have an end result in mind before loading the Visual Designer.

   Unless you are using a drawing component (such as a Line Separator or Group Box), you can only add parts that corresponds to fields that already exist in the corresponding entity. In other words, a part needs to link to an existing Entity Fields record in the corresponding entity.

   Likewise, if adding a control that uses an embedded link (such as the Addresses Control, Phones Control, or Code Script Control), the entity must already have the necessary embedded link configured in its Entities record.

   See the individual component descriptions at About the Supported Visual Designer Components for more information on each component's requirements.

2. Open the Visual Designer for the desired form tab. See Opening the Visual Designer.
3. Resize the form and rearrange existing parts, as necessary.
4. Select a component from the Toolbox.
   • See About the Supported Visual Designer Components for the list of supported components and each component's input properties. 
5. Do one of the following to add a new field or control to the form that uses the selected component:
   1. Drag the selected component from the Toolbox to the form. The selected component is added to the top of the tab.
   2. Double-click the component in the Toolbox. A new form template part that uses this component is added to the center of the form.
   3. While the component is selected in the Toolbox, click on the form. A new form template part that uses this component is added to the location you clicked.
      
      
6. Use the anchors to resize the new form template part on the form to the desired length and width. (You can also use the design buttons that appear when you select multiple parts to resize the part based on an existing part already on the form.)
7. Configure the new part's input properties on the Aptify Form Template Properties Dialog's Properties tab.
   • When you place a new part on a form, the Aptify Form Template Properties dialog loads the input properties for the specified component on the Properties tab. See About the Supported Visual Designer Components for information on the input properties for each component.
   • The system automatically inserts <Required> as the source for required inputs, as shown in the example below. You must update all instances where the term, <Required>, appears in the Source column to appropriate value.
   • In order for all data-related parts to function properly, you may need to link the new part to an entity field that exists in the form's entity (and it that entity's table). For example, you can only add a new EmployeeID link box to the -SampleServices form if the SampleServices entity already has an EmployeeID linked field defined.

   • If you want to link a new part's caption so it displays a Culture String that is specified at the Entity Field level, leave the LabelCaption property blank or enter the field's default Display Name.

     Use Static Value as the Source Type for all of the Input Properties for Visual Designer components.

     
     

8. Configure the settings on the General tab.

   • This includes specifying the Part Name for the new Form Template Parts record that the designer will create for the field/control.

     To prevent problems deploying this form template and to prevent the system from inadvertently overwriting any parts you have created or modified, you should assign each part a unique name.

   • By default, the Width Sizing is None. If you want the field to automatically resize when the form resizes, set Width Sizing to Fill. All generated fields on a form created by the Aptify Baseline Form Template Generator have Width Sizing set to Fill and resize automatically when the form is resized.
   • Also, configure the Tab Index based on the new field's location on the form.
     
     
9. Enter any relevant information on the Comments tab.
10. Click off of the part to update its appearance on the form (for example, if you specified a LabelCaption, this caption would now appear on the form).
    • Note that in some cases, you may need to save the form and close the Visual Designer and the form before all of your changes appear on the form (this may include the display of the caption). 
11. Add additional parts or make other modifications to the form, as necessary.
12. Click the Save Form Template button on the Aptify Form Template Properties dialog to save your changes to the form and exit from Visual Designer mode.
    • Click Yes when notified that the form template will become non-generated if it is currently generated. Upon save, the system will mark the corresponding Form Templates record as non-generated when you save changes made using the Visual Designer. 
13. Close all open records.

About the Supported Visual Designer Components

This topic contains sub-topics that describe the components that appear in the Visual Designer's Toolbox that you can use as the building blocks for new parts on a form. It also defines the input properties that you can configure for each component.

The components of the Visual Designer are described in the following sub-topics:

• About the Visual Designer Active Button
• About the Visual Designer Address Control
• About the Visual Designer Addresses Control
• About the Visual Designer Advertising Link Label
• About the Visual Designer Campaign List Import Matching Control
• About the Visual Designer Check Box
• About the Visual Designer Code Script Control
• About the Visual Designer Combo Box
• About the Visual Designer Culture Label
• About the Visual Designer Data Combo Box
• About the Visual Designer Email Control
• About the Visual Designer Entity List View
• About the Visual Designer Filter Rules UI Control
• About the Visual Designer Group Box
• About the Visual Designer Grouped Options
• About the Visual Designer HTML Text Field
• About the Visual Designer Line Separator
• About the Visual Designer Link Box
• About the Visual Designer Links Control
• About the Visual Designer Multi Entity Grid
• About the Visual Designer Multi-Line Text Field
• About the Visual Designer Orders Address Selector
• About the Visual Designer Order Text Button
• About the Visual Designer Payment Button
• About the Visual Designer Payment Information Control
• About the Visual Designer Phone Control
• About the Visual Designer Phones Control
• About the Visual Designer Picture Viewer
• About the Visual Designer Rich Text Field
• About the Visual Designer Special Text Field Box
• About the Visual Designer Sub-Type Control
• About the Visual Designer Text Field
• About the Visual Designer Time Control
• About the Visual Designer View Container

About the Visual Designer Active Button

This component places a clickable button on a form. One example of an Active Button component is the Meeting form's Close Meeting button.

A developer defines the action that takes place when the button is clicked in the form template's Layout Control. See Adding a Layout Control for more information.

This component uses the following input properties:

• Text (required): This string specifies the label for the button that appears on the form.
• TextCultureString: This string specifies the culture string used to localize the button label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for details.
• Action Type: Aptify implements metadata defined actions for active buttons. An Active button form component supports the same type of configuration options as a dashboard button (but executed from a form) to perform operations, such as, opening records or launching a wizard. Defining this as metadata helps reduce the number and complexity of form template layout controls and improves the overall functionality.Valid values are:
  • Click Event: This option creates a clickable button. You need to program what happens when a user clicks the button in a form template's layout control.
  • Generic Data Wizard: Select this action type to launch a metadata wizard from the form.
  • Open Form: Select this action to open a new form or a particular record in a target service.

  • Preview Report: Select this action to open a particular report in the Crystal Reports Viewer or SQL Server Microsoft SQL Server Reporting Services (SRSS).

    SSRS reports are supported in Aptify 5.5.4 and higher.

  • Print Report: Select this action to print a particular Crystal Reports or SSRS report (without previewing it first).
  • Run Find Dialog: Select this action to launch the Aptify Find dialog for a specified service.
  • Run Wizard: Select this action to launch a specified code-based wizard when the user clicks the button.
  • Send Email: Select this action to send an email when the user clicks the button.
  • Open URL: Starting with Aptify 5.5.5, selecting this action opens a specific tab of a record. For example, if you want, this feature is only available in the Aptify web interface.

 

 

 

About the Visual Designer Addresses Control

This component adds the Aptify addresses control to a form. This is the same control that appears on the Persons, Companies, and Organizations forms and provides a single control to manage multiple addresses.

See Managing Address Information for more information on this addresses control and its available features.

Note that the entity must have one or more embedded links to the Addresses entity's ID field (for example, an AddressID field) to successfully use this control. The control will be blank if you add it to an entity that does not have an AddressID embedded field.

Typically, your entity's generated form will already have one or more fields from the Addresses entity. The addresses control replaces these fields so you should delete any redundant fields from the form before adding the Addresses control.

If your entity has multiple embedded links to the Addresses entity, such as a WorkAddressID and HomeAddressID fields, the control automatically identifies the links and populates the address selection drop-down list according. (The drop-down list uses the Display Name for the embedded link field.)

This component uses the following input property:

• Toolbar Indent: This property specifies how far to the right of the control the address toolbar appears on the form. The address toolbar is the first row of the addresses control that includes the Address Type drop-down field and four buttons. By default, the Toolbar Indent is set to 50 pixels and the toolbar is aligned with the Line 1 caption below it. You can increase or decrease the indent size as desired.

About the Visual Designer Addresses Control

This component adds the Aptify addresses control to a form. This is the same control that appears on the Persons, Companies, and Organizations forms and provides a single control to manage multiple addresses.

See Managing Address Information for more information on this addresses control and its available features.

Note that the entity must have one or more embedded links to the Addresses entity's ID field (for example, an AddressID field) to successfully use this control. The control will be blank if you add it to an entity that does not have an AddressID embedded field.

Typically, your entity's generated form will already have one or more fields from the Addresses entity. The addresses control replaces these fields so you should delete any redundant fields from the form before adding the Addresses control.

If your entity has multiple embedded links to the Addresses entity, such as a WorkAddressID and HomeAddressID fields, the control automatically identifies the links and populates the address selection drop-down list according. (The drop-down list uses the Display Name for the embedded link field.)

This component uses the following input property:

• Toolbar Indent: This property specifies how far to the right of the control the address toolbar appears on the form. The address toolbar is the first row of the addresses control that includes the Address Type drop-down field and four buttons. By default, the Toolbar Indent is set to 50 pixels and the toolbar is aligned with the Line 1 caption below it. You can increase or decrease the indent size as desired.

About the Visual Designer Advertising Link Label

This component adds a field label as a hyperlink that can be used to access another record in the system. This is the form component used to display the Options Amount hyperlink in the Advertising Insertion Orders record. When a user clicks this link, the corresponding Advertising Options record opens. (Note that Advertising Management is an add-on application that may not be available on your system.)

This component displays the hyperlink but does not provide the functionality to identify a record to open. A developer defines the action that takes place when the hyperlink is clicked in the form template's Layout Control. See Adding a Layout Control for more information.

This component uses the following input properties:

• LinkLabelText (required): This string identifies the text for the label that will appear as a hyperlink.
• LinkLabelTextCultureString: This string specifies the culture string used to localize the button label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Campaign List Import Matching Control

This component adds the Aptify Import Matching Control to a form. This is the control that appears on Campaign Import Runs record and allows a user to match and post Persons or Companies data from an external file.

There are no input properties associated with this control. See Importing Prospects from an External File for information on using this control during the campaign list import process.

About the Visual Designer Check Box

This component creates a check box on the form (with or without a caption). It uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field whose SQL Data Type is Bit. See Check Box for more information.
• ShowCaption (required): When set to 1, the specified Caption appears on the form. When set to 0, the Caption does not appear. This input property defaults to 1.
• Caption: This string specifies an optional caption that can appear on the form to the right of the check box.
• FontName: This string specifies the font used for the caption. It defaults to Tahoma.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Code Script Control

This component adds the Aptify code script control to a form. This is the same control that appears on the Event Definitions form's Scripts tab, the Message Parts form's HTML and Plain Text tabs, and the Script sub-tab of the Entity Fields form's Validation tab.

See Administering Scripts for information on Aptify's scripting implementation and for how to enter a script in the code script control.

Note that the entity must have an embedded link to the Scripts entity's ID field (that is, an ScriptID field) to successfully use this control.

Typically, your entity's generated form will already have one or more fields from the Scripts entity. The code script control replaces these fields so you should delete any redundant fields from the form before adding the code script control.

This component requires the following input properties:

• DataField (required): Specify the name of the ScriptID embedded field in the entity.
• ScriptTypeID (required): Enter the ID of the Script Types record that corresponds to the type of scripting the entity supports. By default, this property defaults to ID 1, which corresponds to the Messaging script type.
• ScriptLanguageID (required): Enter the ID of the Script Languages record that corresponds to the coding language that scripts in this entity support. By default, this property defaults to ID 1, which corresponds to the VB.NET script type.

The Code Script Control does not have a ScriptName input property. When a user enters a script into the control and saves the record, Aptify creates a Scripts record and automatically populates the script's Name field with [Script Type] Script (for example, Messaging Script).

About the Visual Designer Combo Box

This component creates a drop-down list field (also known as a Combo Box) on the form. It uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that has a static value list. See Standard Combo Drop-down List for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• Style (required): Specifies the combo box style. The options are:
  • 0: Dropdown Combo: With this style, a user can manually type a value within the field or select from the list of pre-defined values using the drop-down arrow. This is the default style that is used for combo boxes that are automatically generated by the Aptify Baseline Form Template Generator for fields that are not required.
  • 1: Dropdown List: With this style, a user cannot type within the field. The user can only select from the list of pre-defined values using the drop-down arrow. This is the default style that is used for combo boxes that are automatically generated by the Aptify Baseline Form Template Generator for required fields. Info: The Simple Combo box style is no longer supported in Aptify 5.0 and will not be supported in future version.
  • 2: Simple Combo: With this style, the list of pre-defined values appear directly below the field (as shown in the example). A user can manually type a value within the field or select from the list of pre-defined values. Note that you need to increase the height of this field to display the dropdown list. 
    
     
• FontName: This string specifies the font used for the LabelCaption and field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• DisableGeDataTransfer: This is an advanced setting for forms that include a layout control.  In Aptify 6.0, this input property is updated so that when it is set to 1, the component value comes from the bound control, and when it is set to 1, the component is updated from the generic entity or is it refreshed from another data access method. The default value is 0.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Culture Label

Use this component to add a culture-aware label to a form. It uses the following input properties:

• Text (required): This is the text that appears in the label. If the value you enter corresponds to a Culture String's Base String, then the text of the label will change to match the local string that corresponds to the user's assigned culture.
• TextAlignment: This string specifies the location of the text within the label. The default value is MiddleRight. You can specify any combination of Top/Middle/Bottom and Left/Center/Right.
• AutoSize: Set this property to a value greater than 0 to automatically resize the label area to fit the text you entered. Note that the text is aligned in the TopLeft of the original label area prior to resizing. Leave this property set to 0 to manually control the size of the label area. 

About the Visual Designer Data Combo Box

This component creates a data combo drop-down field, which displays a list of values, populated with records from another entity or database table. This drop-down menu can display one or more fields from the related entity for each selection. It uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a Data Combo Box. Note that if this field is not required in the entity, then a blank option will be available in the drop-down list. If required, then no blank option will appear, and the field will default to the first value in the list for new records. See Data Combo Drop-down List for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• DisplaySQL (required): This property specifies a SQL statement that returns the fields to display in the data combo box's drop-down list. For example, Select ID,DisplayName from vwApplications corresponds to displaying the ID and DisplayName fields for the records from the Applications entity's Base View (as shown in the example below).
• DisplayField (required): This property specifies the field from the DisplaySQL property to display as the value for the data combo box after a list item has been selected. In the example below, the DisplayField property is set to the Application entity's DisplayName field.
• DataField (required): This property specifies the field from the form's entity that corresponds to this field. Typically, this is the same as the FieldName (such as ApplicationID).
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the LabelCaption and field value. It defaults to Tahoma.
• ValueField (required): This property specifies the field from DisplaySQL property that corresponds to the data value that will be stored in the corresponding entity field. Typically, this is the link entity's ID field.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Email Control

This component adds an email address control to the form. It is particularly useful for entities that store multiple email addresses. This is the same control that appears on the Persons form.

Note that the entity must have one or more email fields (that is, fields with the Extended Type set to Email) to successfully use this control. The control will be blank if you add it to an entity that does not have an Email field.

If your entity has only one email field, then you can just use the default field that was already generated by the Aptify Baseline Form Template Generator. (This corresponds to the Text Field component with an extended type of Email.) However, if your entity has multiple email addresses, you can organize all of the email addresses into the single Email control.

In this case, your entity's generated form will already have one field for each email address in the entity. The Email control replaces these fields so you should delete any redundant fields from the form before adding the Email control. Note that the control's email selection drop-down list reports the Display Name for each email field.

The Email control uses the following input properties:

• FieldString: This string stores the list of fields in the entity that correspond to email fields. When specifying multiple fields, use the pipe character (|) as the field delimiter (for example, "Email1|Email2"). This field is only required if you set -AutoFindEmailFields to 0.
• EmailFieldListWidth (required): This property specifies the width of the email address drop-down list (so user can select from the available email address, such as Home E-mail, Work E-mail, etc.). By default, the width is 32 pixels, which may be too short depending on the email fields' display names. You may want to increase this to 60 or 100 pixels.
• AutoFindEmailFields (required): When set to 1, the control automatically locates and loads the entity fields that have Extended Type set to Email. When set to 0, you must manually specify the list of email fields in the FieldString property. 

About the Visual Designer Entity List View

This component adds a List view to the form. You can add the view either to an existing tab or you can add a blank tab first and then add the view to the blank tab. The example shown above illustrates a view that has been added to a new tab on the Employees form.

In general, this view should display records from a related entity that is linked to the current entity. For example, you might want to add a view to the Dashboard Areas service that displays the list of Dashboard Parts that the area contains. This concept is similar to the Related Entity view tabs that are added automatically by the Aptify Baseline Form Template generator (see About the Baseline Form Template Generator) or to a view added as a separate tab to a form using the Form Template Tab wizard (see Using the Form Template Tab Wizard).

If you want to add a Chart or Calendar view to a form, use the View Container component (see Configuring the View Container Component).

The Entity List View component uses the following input properties:

• Caption (required): The caption for the view.
• Entity (required): The name of the entity whose records will be displayed in the view.
• View Type (required): You can either load an existing view (View ID) or specify a SQL statement to define a temporary view (SQL View). This property defaults to SQL View.
• NewRecordParameterString: An administrator can configure this property to automatically populate fields in new records opened from within a list view. The format for passing new default values is as follows:
  • PARAMS(FieldName1=Value1|FieldName2=Value2|FieldName3=Value3...)
  • For example, to pass in the ID from the current record into the SampleServiceID for a new record in the related entity, you would enter -PARAMS(SampleServiceID=<%ID%>) as this property's Source.
  • Note that the FieldName corresponds to fields in the entity whose records appear in the view. To specify multiple fields, separate the field/value statements with a vertical bar.
  • If you want to pass in values from the current record, enclose the current record's field name with greater than/less than symbols and percentage signs.
    • For example, if the related entity whose records are displayed in the view has a SampleServiceID field, the following string passes in the Sample Services record's ID when you open a new record from the view on the Sample Services form: PARAMS(SampleServiceID=<%ID%>) 
• SQL: If you set View Type to SQL View, specify the SQL statement (including any applicable WHERE clause) to define a temporary view.
• ViewID: If you set View Type to View ID, enter the ID of the view that will be placed on the form.
• FilterSQL: If you are placing an existing view on the form (that is, View Type is set to View ID), you can use this property to filter the results of the view to display a sub-set of the records. The string that you enter for this property is appended as a WHERE clause to the selected view's SQL statement. Typically, you will use this property to display only the records in the related entity that are linked to the current record. For example, if a SampleLinks entity has a SampleServiceID field, you can add an existing list view of the SampleLinks entity to the SampleServices form. To filter the list results to display on those SampleLinks records linked to the current SampleServices record, you would enter SampleServiceID = <%ID%> as the Source for the FilterSQL property, as shown below.
• Enable Paging: Sets the paging behavior for the view. The default value is True enabling paging.
• Page Size: The number of records per page, when paging is enabled. The default value is 250.
• LabelCaptionCultureString: This string specifies the culture string used to localize the caption. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details. 
• DisplayEntityRecordAsModal: Determines whether or not the display of the Entity record (New or Open) displays as a modal or modeless window.  The default behavior is modeless (0). Set the value of this property to true to display the Entity window as a modal window.  Note that, if the List View is displayed in a modal window, the Entity record will be displayed as a modal window, regardless of value for this property.
• CheckBoxColumnRequired: Determines whether the entity list view should display the first column as check boxes to select the records. If the value is 1, the first column will contain check boxes, and if the value is 0, the first column does not contain check boxes. Default value is 1.
• HiddenFilter: This property allows an administrator to specify a WHERE clause filter to limit the set of possible values for the entity list view. 
  • The syntax for the HiddenFilter is a SQL WHERE clause without the "WHERE" preamble (this is appended automatically by Aptify).  
• HideColumns: This property can be used in the Aptify web interface to hide column(s) in the entity list view. The hidden column(s) are still available for internal processing.
• DeferDataLoad: When this property is set to True, the view results are not immediately loaded. The grid is configured but is not loaded until this property is set to False.  This property is supported in the Aptify Web Entity List View Component and not supported in the Windows Desktop client. The default value is False.

About the Visual Designer Filter Rules UI Control

This component adds the Aptify Filter Rules control to a form. This is the same control that appears on the Product Prices form's Filter Rules tab.

See Using the Filter Rules Service for information on Aptify's Filter Rules feature.

Note that the entity must have an embedded link to the Filter Rules entity's ID field (that is, a FilterRuleID field) to successfully use this control.

Typically, your entity's generated form will already have one or more fields from the Filter Rules entity. This control replaces these fields so you should delete any redundant fields from the form before adding the control.

This component requires the following input properties:

• FieldName (required): Specify the name of the FilterRuleID embedded field in the container entity. Typically, this is FilterRuleID.
• NewName: Enter the name that to assign to the embedded Filter Rules records that will be created from within this entity. Aptify will use this as the Name field for all new Filter Rules records it creates that link to a record in this service (unless the developer who wrote the filter rule evaluation logic for this entity specified a different naming criteria).
• NewFilterRuleType: Enter the name of the Filter Rule Types record that corresponds to the type of filter rule the entity supports. Typically, each Filter Rules implementation has its own Filter Rules Types record. See Using the Filter Rules Service for details.

About the Visual Designer Group Box

This component is a drawing tool that a designer can use to visually segment related fields on a form. After drawing a Group Box of the desired size, you can move it on top of other fields. For best results, place the Group Box on top of the other fields rather than place the other fields within the Group Box. In the example shown above, a Phones control, Line Separator, and Email control have been placed on top of the Group Box.

The Group Box control uses the following input properties:

• Text (required): This specifies the caption for the Group Box. In the example shown above, the caption is Contact Info.
• TextCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Grouped Options

This component creates a group box with two or more radio buttons. Typically, a Grouped Options component is used to specify filter values for an Entity List View. For example, the Persons form's Subscriptions tab includes a Grouped Options part that includes three options: All Subscriptions, Active Only, Inactive Only. When a user selects one of these options, the system filters the corresponding view accordingly (for example, the view displays the Person's active subscriptions when the Active Only option is selected).

Note that the relationship between a Grouped Options part and an ELV part is not automatic. A developer must define a Layout Control that handles the communication between the Grouped Options part and the Entity List View (ELV) part (this is also known as inter-part communication). See Adding a Layout Control for more information.

The Grouped Options component supports the following input properties:

• Text (required): This specifies the caption for the component's group box. In the example shown above, the caption is Subscription Options.
• Style (required): This property specifies the layout of the radio buttons, either Horizontal or Vertical.
• Options (required): This property stores the list of options. The component adds a radio button for each option contained in this list. Use a comma as the option delimiter (for example, All Subscriptions, Active Only, Inactive Only).
• TextCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See "Working with Culture Strings" in the Admin Gude for more details.

About the Visual Designer HTML Text Field

This component creates a field that can store text in HTML format. In general, you will want to place an HTML Text Field on its own tab on a form. See Understanding the Common Field Types for information on using this field type.

The HTML Text Field component is suitable for large text fields, such as a field that uses the nvarchar(max) data type. This component uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a multi-line text field. See Multi-Line Text Field for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. If the HTML Text Field will appear on its own tab, set this property to 0.
• LabelCaption: This string specifies the caption that can appear on the form to the left of the field.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• Multiline: A value of 1 specifies that this is a text field supports more than one line. If this property appears as an input property, leave it at its default value.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Line Separator

This component creates a horizontal line two pixels in height by default. It also supports the following properties:

• Style: You can specify a Horizontal or Vertical line.
• SeparatorSize: This property is reserved for future use. 

About the Visual Designer Link Box

This component creates a Link Box, which stores a link between the current entity and another related entity. See About the Link Box Field Type for information on Link Box functionality. This component uses the following input properties:

• EntityName (required): The name of the related entity that is represented by this link box.
• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a Link Box. See About the Link Box Field Type for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• HiddenFilter: This property allows an administrator to specify a WHERE clause filter to limit the set of possible values for the Link Box. The Hidden Filter also limits the set of possible values that appear in the Link Box's Find dialog.
  • The syntax for the HiddenFilter is a SQL WHERE clause without the "WHERE" preamble (this is appended automatically by Aptify). For example, if the linked entity has a Category field and you want to limit the link box value to records in the linked entity where CategoryID equals 1, then you would enter CategoryID=1 as the HiddenFilter's Source. 
• LinkBoxEnabled: When blank or set to a value greater than zero, the link box field is enabled. When set to 0, the Link Box field appears on the form but it is grayed out and disabled. By default, this property is blank and the link box is enabled.
• HyperlinkEnabled: When blank or set to a value greater than zero, the link box's hyperlink functionality is enabled. When set to 0, the caption is in plain text (no hyperlink) so users cannot open the specified record (if one is specified in the link box) or a new record (if the link box is blank).
• NewRecordParameterString: An administrator can configure this property to automatically populate fields in new records opened by clicking the hyperlink when the link box is blank. The format for passing new default values is as follows:
  • PARAMS(FieldName1=Value1|FieldName2=Value2|FieldName3=Value3...)
  • For example, to pass in a default CategoryID for a new record in the related entity, you would enter PARAMS(CategoryID=1) as this property's Source.
  • Note that the FieldName corresponds to fields in the related entity. To specify multiple fields, separate the field/value statements with a vertical bar.
  • If you want to pass in values from the current record, enclose the current record's field name with greater than/less than symbols and percentage signs.
    • For example, if the related entity has a SampleServiceID field, the following string passes in the Sample Services record's ID when you click a blank link box on the Sample Services form: PARAMS(SampleServiceID=<%ID%>) 
• DisableGeDataTransfer: This is an advanced setting for forms that include a layout control. In Aptify 6.0, this input property is updated so that when it is set to 1, the component value comes from the bound control, and when it is set to 1, the component is updated from the generic entity or is it refreshed from another data access method. The default value is 0.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.
• ValueField (required): This property allows an administrator to specify if the linked field is the ID field or the IsName field of the linked entity. When set to 0, the field is the ID field in the linked entity. When set to 1, the field is the IsName field of the linked entity.
• UseDefaultCard: This input property is used with the EntityCardName property to identify a default entity card when multiple entity cards have been created on same entity for different purposes. When this input property is set to 1, the entity card specified in the EntityCardName property is used as the default entity card. The default value of this property is 1.
• EntityCardName: This input property is used with the UseDefaultCard property to identify a default entity card when multiple entity cards have been created on same entity for different purposes. When the UseDefaultCard input property is set to 1, the entity card specified in this input property is used as the default entity card. 

About the Visual Designer Links Control

This component creates a link control for a sub-type entity. This control is used by the Contact Logs and Tasks entities to provide an easy way for a user to link other records to Contact Logs and Tasks. (The links are stored in the ContactLogLinks and TaskLinks sub-type entities, respectively). For Persons, Companies, and Employees, the displayed link information includes the record ID, contact name, phone number, and email address. For all other services, the link information shows the record name and record ID.

Note that to use this control, an entity needs a sub-type entity that has two fields: an Entity ID field and a Record ID field (these two fields identify a particular record in the system). This component uses the following input properties:

• SubTypeName (required): The name of the sub-type entity which will store the links to other records.
• EntityIDField (required): This is the field in the sub-type entity that corresponds to the Entities entity's ID field. Typically, this is EntityID.
• RecordIDField (required): This is the field in the sub-type entity that corresponds to a the record ID in an entity's entity service. Typically, this is AltID.
• AppName: This is the name of the application to be used in dialog boxes, when needed. Note that this property is not used by either the Contact Log or Task Links entity.
• AllowDupes: This property is reserved for future use. If a sub-type entity has logic to check for duplicates, when this value is set to 1, a user can add the same record (EntityID/RecordID pair) more than once to the Links list. When set to 0, each EntityID/RecordID pair can only appear once. Note that this input property is not applicable to either the Contact Log or Task Links entity.
• LinkTypeFilterSQL: By default, the Links Control displays all top-level entities in the Link Type drop-down list. However, in some cases, an organization may want to restrict the set of entities that are available for selection. In this case, an administrator or developer can use this optional parameter to restrict the set of entities that appear in the Link Control's Link Type drop-down list.
  • The expected value for this property is a SQL phrase that can be appended to an existing WHERE clause that defines the set of displayed entities. The control already filters Entities to exclude sub-types (using a WHERE ParentID <= 0  clause). Any text entered for the LinkTypeFilterSQL input is appended to the existing WHERE clause using an AND operator.
  • For example, to filter a Links Control to display only the Persons, Companies, and Contact Log entities in the Link Type drop-down, you would enter the following in the Form Template Part's Input Map for the component's LinkTypeFilterSQL property: Name IN ('Persons', 'Companies', 'Contact Log'). The links Control would then use this WHERE clause to filter entities in the Link Type list: WHERE ParentID <= 0 AND Name IN ('Persons', 'Companies', 'Contact Log') 

About the Visual Designer Multi Entity Grid

The Multi Entity grid displays information about the relationship between the records in two services and allows users to easily add, modify, or delete these relationships. For example, the figure below illustrates the multi entity grid that is included on the Employees form's Skills tab where the Skills records are the rows and the current employee is the single column in the grid. The individual cells in this case identify if the employee is linked to a particular skill (that is, the cells represent actual or potential EmployeeSkills sub-type records). These Employee/Skills relationships can easily be created or deleted by adding or removing a check mark from the appropriate cell.

The features of a multi entity grid include:

• Two Cell Modes: The cells of a multi entity grid can use one of two modes:
  • Check Box: This option identifies if a relationship exists between the row record and the column heading. For example, in the example above, Tim Jones has a check mark in the Management column, which indicates that an EmployeeSkills record exists to track this relationship.
  • Data Entry: This option displays a value from the corresponding record that can be added, edited, or deleted directly within the column's grid. For an example of this implementation, see the Culture Strings form's Local Strings tab. The multi entity grid on this tab displays values from the Local String field of the sub-type record, so a user can easily add new localized content for the Culture String in one or more cultures. See Working with Culture Strings for more information.
     
• Support for Two Display Locations: The Multi Entity Grid control is both a form component and a dashboard component, which means you can add it to dashboard and to forms. See Configuring the Multi Entity Grid Component for information on how to add the multi entity grid to a dashboard.
• Double-click to Open Records: Double-clicking a row heading, column heading, or within a cell opens the corresponding record.
• Toolbar: The multi entity grid contains a toolbar with these options:
  • Open: This button opens the corresponding record for a selected row, column, or cell.
  • Refresh: Clicking this button refreshes the grid. If you make a change to a cell and the change does not reflect immediately, click the Refresh button to display the latest data.

  • Help: If the sub-type entity linked to the grid's cells has on-line help, clicking this button opens the on-line help file in the appropriate location.

    The dashboard implementation of the multi entity grid includes a Refresh button its toolbar. This button is not applicable when the multi entity grid appears as a tab on a form (so the button is not available)

This component supports the following input properties (see the example below; it shows how the input map for the Employee Skills tab has been populated to achieve the grid layout shown in the figure above):

• CellDataSourceEntity (required): Specify the sub-type entity that provides a relationship between the two services you will specify as the grid's rows and columns. Note that one of the services (either the rows or the columns) must be the parent for this sub-type entity.
• CellDisplayField: If you enter Field option for the CellDisplayMode, specify the field from the sub-type entity whose values you want to display in the grid's cells. Users will be able to modify these values directly within the grid.
• CellDisplayMode (required): Enter Exists to display a check box that identifies if a corresponding subtype exists or does not exist. This option is only suitable if the only required fields in the sub-type are links to the row and column services or have a default value specified. Enter Field to display the value of a particular field in the specified sub-type entity.
• ColumnDataSourceEntity: Enter the entity whose records should appear as columns in the grid.
• ColumnDataSourceSQL: If you selected a ColumnDataSourceType of SQL, enter the SQL statement that will return the desired sub-set of records from the specified entity. See the example below where the parent entity is configured to only show the current record as a column since the grid is embedded on a form's tab. The SQL statement uses Aptify's field mark-up convention (<<%field name%>>) to pull in the ID value from the current record.
• ColumnDataSourceDisplayField: Specify the field whose values should display as the column headings.
• ColumnDataSourceOrderByField: Specify the field by which the columns will be sorted (in ascending order).
• ColumnDataSourceType (required): Enter Entity to add a column for each record in the selected entity. If you want to limit the number of columns to a particular sub-set of records, enter the SQL type and specify a SQL statement that returns only the desired records in the ColumnDataSourceSQL field.
• ColumnRelationshipType (required): If the column entity is the cell sub-type entity's parent entity, enter Parent. If the cell sub-type entity has a linked field to the column entity, then enter Field.
• ColumnRelationshipField: Enter the corresponding field from the cell sub-type entity that links it to the column entity (typically, this is a field named [column entity]ID).
• RowDataSourceEntity: Enter the entity whose records should appear as rows in the grid.
• RowDataSourceSQL: If you selected a Type of SQL, enter the SQL statement that will return the desired sub-set of records from the specified entity. See the example below the parent entity is configured to only show the current record as a column since the grid is embedded on a form's tab. The SQL statement uses Aptify's field mark-up convention (<<%field name%>>) to pull in the ID value from the current record.
• RowDataSourceDisplayField: Enter the field whose values should display as the row headings.
• RowDataSourceOrderByField: Enter the field by which the rows will be sorted (in ascending order).
• RowDataSourceType (required): Enter Entity to add a row for each record in the selected entity. If you want to limit the number of rows to a particular sub-set of records, enter the SQL type and enter a SQL statement that returns only the desired records in the RowDataSourceSQL field.
• RowRelationshipType (required): If the row entity is the cell sub-type entity's parent entity, enter Parent. If the cell sub-type entity has a linked field to the row entity, enter Field.
• RowRelationshipField: Enter the corresponding field from the cell sub-type entity that links it to the row entity (typically, this is a field named [row entity]ID). 
  
   

About the Visual Designer Multi-Line Text Field

This component adds a text box to the form that appears in multiple lines. When adding a multi-line text field, you should also expand the height of the field to the desired size. Note that new multi-line fields may appear as a single line until after you have saved your changes and the Visual Designer is closed.

This component uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a multi-line text field. See Multi-Line Text Field for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the caption and the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• Multiline: A value of 1 specifies that this is a text field supports more than one line. Leave this setting at its default value.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Orders Address Selector

This is the control used on the Orders form to allow a user to select an address for a person or company from the set of available addresses. This control has no defined input properties.

About the Visual Designer Order Text Button

This component adds a text field to a form with an informational icon, as shown in the example above. This is the form component used to display the Shipping, Tax, and Handling fields found on an Orders record's Summary area. Clicking the icon displays additional information about how the field's value was calculated.

A developer defines the action that takes place when the button is clicked in the form template's Layout Control. See Adding a Layout Control for more information.

This component uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a standard text field. See Standard Text Field for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the caption and the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• ExtendedType: This property is typically not applicable to an Order Text Button. For standard text fields, it specifies the extended type of the field (see Extended Attribute Fields and Extended Type for more information on the Extended Types).
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Payment Button

This component adds a button to a form.This is the form component used to display the buttons in the Search Buttons Area in the top of the Payments form. See About the Payments Form.

A developer defines the action that takes place when the button is clicked in the form template's Layout Control. See Adding a Layout Control for more information.

This component uses the following input properties:

• Text (required): Specify the caption that will appear within the button.
• ButtonKey (required): Specify the command key that is recognized by the Layout Control (the layout control must be built to handle events based on the ButtonKey property).
• TextCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Payment Information Control

This component adds the Aptify Payment Information control to a form. This is the same control that appears on forms such as Orders and Payments to record payment information.

See About the Payment Information Service for information on Aptify's Payment Information service.

Note that the entity must have an embedded link to the Payment Information entity's ID field (that is, a PaymentInformationID field) to successfully use this control.

Typically, your entity's generated form will already have one or more fields from the Payment Information entity. This control replaces these fields so you should delete any redundant fields from the form before adding the control.

This component uses the following input properties:

• DataField: Specify the name of the PaymentInformationID embedded field in the container entity. Typically, this is PaymentInformationID.
• TypesToShow (required): Specify the set of Payment Types that are available in the drop-down on this form. When set to All, all Payment Types appear in the list. When set to Inflow, only those Payment Types that have the Inflow box checked appear. When set to On Account, only those Payment Types that have the Inflow box unchecked appear.
• ShowHideAccountNumber: Specify when a credit card account number or CC Partial field should be displayed in the Payment Information control. When set to USEDEFAULT (the default setting), the full CC Account # field appears for new records. Once the record is saved, the CC Account #field is replaced with the read-only CC Partial field. When set to MASK, the read-only CC Partial field appears in all cases (for new and existing records). When set to NOMASK, the full CC Account # field appears in all cases (for new and existing records).
  • Note that this property is applicable for new implementations of the Payment Information control. Modifying this property for existing implementations of this control (such as on the Payments form) does not change the default credit card number display behavior. 
• TransactionControlsVisible: Specify whether or not the transaction controls are visible. When set to VISIBLE (the default setting), the credit card payment type's Security #, CC Auth Code, and CC Auth Type fields appear in the payment information control. When set to INVISIBLE, these fields are hidden when a credit card payment type is selected within the control (only the CC Account #/CC Partial and CC Exp. Date fields appear).

About the Visual Designer Phone Control

This component adds the Aptify Phone control to a form. The Phone control is similar to the Phones control except it does not include the drop-down menu to select between multiple phone numbers. Use this control for services that have a single phone number; if a service has multiple phone numbers, use the Phones control instead.

This component uses the following input property:

• DataField: This string links the Form Template Part to a Field in the form's entity. For this input property, specify the name of the container entity's embedded link field -(typically PhoneID).

Note that in order for the control to render properly, the virtual fields for the embedded PhoneNumberID link must be named exactly as CountryCode, AreaCode, Phone, and PhoneExtension. 

About the Visual Designer Phones Control

This component adds the Aptify phone number control to a form. This is the same control that appears on the Persons, Companies, and Organizations forms and provides a single control to manage multiple phone numbers.

See Using the Phone Number Toolbar for more information on this phones control and its available features.

Note that the entity must have one or more embedded links to the Phone Numbers entity's ID field (for example, a PhoneNumberID field) to successfully use this control. The control will be blank if you add it to an entity that does not have a PhoneNumberID embedded field.

Typically, your entity's generated form will already have one or more fields from the Phone Numbers entity. The phones control replaces these fields so you should delete any redundant fields from the form before adding the phones control.
If your entity has multiple embedded links to the Phone Numbers entity, such as a WorkPhoneID and WorkFaxID fields, the control automatically identifies the links and populates the phone number selection drop-down list according. (The drop-down list uses the Display Name for the embedded link field.)

This component uses the following input property:

• Toolbar Indent: This property specifies how far to the right of the control the toolbar appears on the form. The toolbar is the first row of the phone control that includes the Phone Type drop-down field and two buttons. By default, the Toolbar Indent is set to 50 pixels. You can increase or decrease the indent size as desired. To align the toolbar with the left side of the phone number fields, set the indent to 0 or 1.

About the Visual Designer Picture Viewer

This component provides users with a mechanism to view, add, and update pictures that are attached to a record. (The picture's file is stored as an Attachment for that record.)

A user can add any number of pictures to a record, and the viewer supports multiple image file formats, including JPG, GIF, BMP, and PNG. The following are some of the features supported by Aptify's Picture Viewer, which are accessible using its toolbar (shown in the example above):

• Ability to add multiple images to the record in one operation.
• Ability to update pictures that have already been added to the record.
• Ability to delete pictures that have been added to the record.
• Ability to move back and forth through pictures.

Typically, this component is added to a blank tab to display pictures associated with a particular record. This component uses the following input properties:

• FileExtensions: This property can limit the supported File Extensions displayed by the picture viewer. It is a comma-delimited list of file extensions to check. If left blank, the control automatically defaults to check the JPG, BMP, GIF, and PNG file types. You can set this property to * to allow all file types.
• AttachmentCategory: Specifies an Attachment Category to use for all images added to a record. This defaults to blank. This category of attachments is used for viewing/storage of picture attachments associated with the record. If not specified, the attachments are not associated with a category.
• ScaleImage (required): Determines whether the image can be scaled based on the size of the display area. By default, this property is set to True, and the control automatically resizes images to fit the display area available in the control. If set to False, the image is displayed in its native size, and scroll bars are shown if necessary.
• MaintainAspectRatio (required): Determines whether the height/width aspect ratio of the image is maintained when it is scaled to fit within the display area. By default, this property is set to True, but it is only used if ScaleImage is also set to True.
• BorderStyle (required): Modifies the component's border style. The default is Fixed3D, but this property also supports None and FixedSingle (these options correspond to the standard UserControl BorderStyle property).
• ShowToolbar (required): Shows or hides the image toolbar. By default, the toolbar is shown (set to True).

See Adding the Picture Viewer to the Companies Form and About the Picture Viewer Tab for information on how users can add the Picture Viewer to a form and how to use it once it has been added.

About the Visual Designer Rich Text Field

This component creates a field that can store text in Rich Text Format (RTF). In general, you will want to place a Rich Text Field on its own tab on a form. See Understanding the Common Field Types for information on using this field type.

The Rich Text Field component is suitable for large text fields, such as a field that uses the nvarchar(max) data type. This component uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a multi-line text field. SeeMulti-Line Text Field for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. If the Rich Text Field will appear on its own tab, set this property to 0.
• LabelCaption: This string specifies the caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the caption and the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• Multiline: A value of 1 specifies that this is a text field supports more than one line. If this property appears as an input property, leave it at its default value.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Special Text Field Box

This component is used to display special fields for the Persons and Companies forms that may not exist as fields in the entity. For example, this component is used to display Order Total and Order Balance on Persons and Companies record. It is also used to display the RootCompanyMemberType on a Person's Membership tab.

It is used in conjunction with a layout control and/or entity object to set the displayed value for the field. The component calls the GET value from the entity, before the data field is assigned. Then, it calls a SetAddValue if the Field does not exist.

This component uses the following input properties:

• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. If the Rich Text Field will appear on its own tab, set this property to 0.
• FontName: This string specifies the font used for the caption and the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• DataField (required): This string links the Form Template Part to the data field -generated by the entity object or layout control.
• LabelText: This string specifies the caption that can appear on the form to the left of the field.
• TextCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer Sub-Type Control

This component displays the standard grid for a sub-type entity. This is the same component that the form template generator uses to add a sub-type as a separate tab on a form. However, you can use this component to add a sub-type to a tab that has other fields on it (that is, you do not want the sub-type grid to appear on its own tab).

It supports the following input properties:

• SubTypeName (required): This property specifies the name of the sub-type entity to link to this component.
• AllowSort: This property controls the sorting behavior within a sub-type grid. When the property is set to 1 for a particular sub-type grid, a user can sort the sub-type records by clicking on the header of the column that will control the sort. When set to 0 (the default setting), sorting is not allowed within the grid.
• AllowMove: This property controls the record move behavior within a sub-type grid. When the property is set to 1 for a particular sub-type grid (this is the default setting), a user can use the toolbar buttons or the right-click menu to move a selected record to the Top of the grid, Up one row, Down one row, or to the Bottom of the grid. Note that the Move commands are disabled when a user selects more than one record in the grid. When set to 0, a user cannot move a record to a new position within the grid (the Move buttons do not appear in the toolbar and the Move options do not appear in the right-click menu).
• AllowFind Input: This property determines whether the Find option is available in a sub-type grid's toolbar. When the property is set to 1 for a particular sub-type grid (this is the default setting), the Find button is available in the sub-type toolbar. When set to 0, the Find button does not appear in the toolbar.
• FieldList: By default, sub-type grids display fields with the Default In View attribute checked in their entity field definition.This property provides the ability to modify the default fields that appear in the sub-type grid by specifying a comma-delimited list of fields from the sub-type entity to display as grid columns (from left to right). Note that when specified, this property effectively overrides the Default In View setting for that sub-type entity's fields. In other words, if a field with the Default In View attribute enabled is not specified in this field list, it will not appear on the sub-type grid. 

About the Visual Designer Text Field

This component corresponds to a standard text field on a form. It uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field in the form's entity. For this input property, replace the <Required> default with Name of an Entity Field that meets the requirements for a standard text field. See Standard Text Field for more information.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 1.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the field.
• FontName: This string specifies the font used for the caption and the field value. It defaults to Tahoma.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels.
• ExtendedType: If the entity field supports an extended attribute (such as Email or Repository Object), specify the appropriate extended type for this property to enable the extra functionality for this field. See Extended Attribute Fields on and Extended Type for more information on the support Extended Types.
• DisableGeDataTransfer: This is an advanced setting for forms that include a layout control. In Aptify 6.0, this input property is updated so that when it is set to 1, the component value comes from the bound control, and when it is set to 1, the component is updated from the generic entity or is it refreshed from another data access method. The default value is 0.
• LabelCaptionCultureString: This string specifies the culture string that can be used to localize the field's label (if applicable). For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.
• CharacterCasing: This property determines how the characters are cased. When set to 1, as the user enters text within the field, the characters are converted to uppercase and remain uppercase when the record is saved. When set to 0 (the default value), the case of the characters are left unchanged.

About the Visual Designer Time Control

This component adds a time control to a form for fields that use the Time data type. It uses the following input properties:

• FieldName (required): This string links the Form Template Part to a Field (with the Time data type) in the form's entity.
• ShowLabel (required): When set to 1, the specified LabelCaption appears on the form. When set to 0, the LabelCaption does not appear. This input property defaults to 0.
• LabelWidth (required): This property specifies the width of the LabelCaption in pixels. A typical LabelWidth in Aptify is between 79 and 99 pixels. The default value is 70.
• LabelCaption: This string specifies an optional caption that can appear on the form to the left of the control.If left blank and ShowLabel is 1, then the field's display name is used as the label.
• Caption: This string specifies an optional caption that can appear on the form to the left of the control and provided that same function as the LabelCaption property.
• DisableGETransferData: When set to 1, the implementer is required to move the value to/from the bound control to the Aptify Generic Entity (GE) or other data access method. 
• DisableGeDataTransfer: This is an advanced setting for forms that include a layout control. In Aptify 6.0, this input property is updated so that when it is set to 1, the component value comes from the bound control, and when it is set to 1, the component is updated from the generic entity or is it refreshed from another data access method. The default value is 0.
• LabelCaptionCultureString: This string specifies the culture string to localize the label (if desired). For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

About the Visual Designer View Container

This component adds an existing view to the form. It supports three view types (List, Chart, and Calendar), but is best suited for Charts and Calendars. You can add the view either to an existing tab or you can add a blank tab first and then add the view to the blank tab. The example shown above illustrates a view that has been added to a form.

In general, you should use the View Container component if you want to add an existing Chart or Calendar view to a form. For List views, use the Entity List View component (see Configuring the Entity List View Component). If you decide to use the View Container with a List View, keep in mind that you can only specify an existing view (the View Container does not support views defined by a SQL statement). The View Container component uses the following input properties:

• Caption: The caption for a list view. Note that the property is not applicable for Chart and Calendar views (i.e., the value you specify does not appear on the form).
• Entity (required): The name of the entity whose records will be displayed in the view.
• View Type (required): The View Container only supports existing views. You cannot specify your own SQL statement. Therefore, View Type must be set to View ID.
• NewRecordParameterString: This parameter is only applicable for List views. An administrator can configure this property to automatically populate fields in new records opened from within the list view. The format for passing new default values is as follows:
  • PARAMS(FieldName1=Value1|FieldName2=Value2|FieldName3=Value3...)
  • For example, to pass in the ID from the current record into the SampleServiceID for a new record in the related entity, you would enter -PARAMS(SampleServiceID=<%ID%>) as this property's Source.
  • Note that the FieldName corresponds to fields in the entity whose records appear in the view. To specify multiple fields, separate the field/value statements with a vertical bar.
  • If you want to pass in values from the current record, enclose the current record's field name with greater than/less than symbols and percentage signs.
    • For example, if the related entity whose records are displayed in the view has a SampleServiceID field, the following string passes in the Sample Services record's ID when you open a new record from the view on the Sample Services form: PARAMS(SampleServiceID=<%ID%>)
       
• SQL: Leave this parameter blank. The View Container component does not support the placement of temporary views on a form.
• ViewID: Enter the ID of the view that will be placed on the form. Although not displayed in red, this field is required to successfully place a view on a form.
• FilterSQL: This parameter is only applicable for List views. You can use this property to filter the results of the view to display a sub-set of the records. The string that you enter for this property is appended as a WHERE clause to the selected view's SQL statement. Typically, you will use this property to display only the records in the related entity that are linked to the current record. See Configuring the Entity List View Component for more information on this property.
• LabelCaptionCultureString: This string specifies the culture string used to localize the label. For this input property, specify the base string for the applicable Culture String record. See Working with Culture Strings for more details.

Assigning a Modified Field Layout to a Specific User or Group

In some cases, you may want a modified field layout to be available to only a specific user or to a specific group.

The following steps describe how to reinstate the baseline form template as the default and apply the modified layout to a specific user or group members. (Note that this does not apply to changes you make to non-generated forms — regenerating the baseline form may not return the form to its original state.)

1. Create a view of Form Templates service where the template's Entity field is the entity whose forms you want to modify.
2. Open the non-generated Tab Template you modified with the Visual Designer.
3. Change the Name and Description for the template.
4. Save and close the record.
5. In the Entities service, regenerate the entity and its baseline form templates. See Regenerating an Entity for instructions.
6. Return to the Form Templates service and identify the newly generated Tab Template and the corresponding non-generated Tab Template you renamed earlier in these instructions. Write down the IDs of both records.
7. Open the non-generated Tab Template.
8. Specify the newly generated Tab Template in the Base Template field.
   • The generated Tab Template is the Sub-Template for the form's Tab Part. By specifying the generated template as the Base Template, you can link your non-generated tab to the generated form templates. 
9. Modify the template's Usage Scope and enter a User or Group in the corresponding field.
   • If you want to assign the modified layout to a specific user, select User from the Usage Scope field and enter the user in the User field (which appears automatically).
   • If you want to assign the modified layout to a specific group, select Group from the Usage Scope field and enter the group in the Group field (which appears automatically).
     • Note that this template will apply only to users who have this group set as their Primary Group.
       
       
10. Save and close the Form Templates record.
11. Close the Aptify client and connect as the specified user or as a user whose Primary Group is the specified group to confirm that the modified template appears for that user.

While users' cans switch between numerous tab layouts, users cannot switch between field layouts.

Tips for Using Visual Designer

• Any field you add to a form with the Visual Designer must already exist in the corresponding entity. For example, you can use the Visual Designer to move a field from one tab to another (by deleting the field from the first tab and then adding it to the second tab).
• When a user updates a record through a form that includes multiple controls that are bound to the same field, any updates made to one of the bound controls is reflected immediately within the other control(s). This allows you to maintain the same data element across multiple tabs and locations on a single form.
• If you add parts to a form, you may also want to increase the default size of the form. Follow these steps:
  1. Open the top-level form template for that form (typically this record has a name in one of the following formats: Standard Aptify [Entity Name] Form or [Entity Name].Form).
  2. Change the Name and Description of this template to prevent any confusion if the the entity is regenerated in the future. (Otherwise, when if the entity is regenerated, Aptify may create a second form template with the same name. However, the entity's displayed form template should continue to use your modified  layout.)
  3. You may also want to modify the Rank field (so it is less than 100). This will ensure that your new form will always take precedence of any form automatically generated in the future.
  4. Click the Format tab.
  5. Enter a larger number in the Default Height field. This number is in pixels.
  6. Save the record.
  7. Click Yes if prompted that the form is generated and will become non-generated.
  8. Close the record.
  9. You may also want to consider changing the name and rank of any sub-templates and parts that are related to this top-level template and save these sub-templates to make them non-generated.
     • This is not a requirement but a best practice recommendation to avoid having duplicate form template names if an entity is regenerated in the future.

• The LabelCaption for an existing field may differ from the field's default caption if the field has been associated with a Culture String. Note that if you change a field's LabelCaption using the Visual Designer, the new caption you specified will override the field's Culture Strings association (if applicable).
• When you rearrange fields using the Visual Designer, you should also modify the Tab Index for the fields to update the tab order. (That is, the order in which fields become in focus as a user presses the Tab key.) The Tab Index field is on the General tab of the Aptify Form Template Properties Dialog.
• If you use the Visual Designer to make changes to a tab's field layout, the corresponding Form Templates record becomes non-generated. If you later want to return to the default generated form, follow these steps:
  1. Follow the steps in Regenerating an Entity to regenerate the entity and regenerate its baseline form templates.
  2. Create a view of Form Templates service where the template's Entity field is the entity whose forms you want to modify.
  3. Locate the non-generated Tab Template in your view.
  4. To disable the modified Tab Template, either modify the ranks of the templates so that the one to disable has a higher rank, or delete the record.
  5. Close and reopen the Aptify client.
  6. Open the form. The field layout from the generated Tab Template should display.

Adding a New Control to a Form

Form templates are made up of parts which are based on generic form components. These components define the functionality of the form template parts and indicate which data may be modified on those parts when they are added to a form template. Components may represent specific field types, such as text boxes or link boxes. They may also represent specific groups of fields, such as the top area of a form or all the fields on a particular tab.

In some cases, an organization may want to add a new tab to a form. This includes generic Aptify controls, such as a Topic Codes tab, as well as controls developed specifically to address an organization's requirements.

The following is an overview of how to add a new control or tab to an existing form template:

1. If a developer has written a new component, add the component file to the Aptify Object Repository and create a new Form Components record. See Creating Form Components.
2. Create a new Form Template Part for the new control. See Creating Form Template Parts.
3. Add the new part to the appropriate Form Template's Part List. See Adding Parts to Form Templates.
   • Note that adding a Part to a generated form template will make that template non-generated. Therefore, if you are adding a Part to a generated form template, Aptify recommends that you change the name of the form to alleviate confusion if you regenerate the entity and its forms in the future. Also, you should mark as non-generated any sub-templates that this template's parts use. See Notes Concerning Form Template Generator for more information. 
4. Close and reopen Aptify and then open the form to confirm that the new control has been successfully added.

Creating Form Components

Creation of new form components is possible within Aptify. Each component is based on .NET assemblies that implement the Aptify's IFormComponent interface. New components require new objects and classes to be written and compiled. The creation of this code is beyond the scope of this topic. A sample Form Components record is shown below.

1. Open a new record from the Form Components service.
2. Enter a name and description for the component.
3. Enter a Category. If necessary, you can create a new category. See Creating Form Component Categories.
4. Select the Run Mode from the list to indicate how the component is enabled for use in form template parts.
   • All: The component is enabled for all records (new and saved) defined by the form template.
   • New Only: The component is only available for new records.
   • Saved Only: The component is only available for existing records. 
5. If Run Mode is set to either New Only or Saved Only, the Disabled Behavior field is available. Available options are:
   • Disable: Selected by default. This disables the template part, so it appears as read-only. For example, when a component is set to Saved Only, it appears as disabled until the record is saved (at which point it becomes enabled).
   • Hide: Prevents the template part from being visible except during the run mode selected for the form template part. For example, if Run Mode is set to Saved Only and Disabled Behavior is set to Hide, the part is not visible on new records. 
6. Enter any additional information in the Comments field.
7. If this component corresponds to a tab on a form, you can specify an icon from the Object Repository in the Icon field.
   • Tab parts that use this component will automatically display the selected icon to the right of the tab name, as shown below. 
     
      
8. Select the Add to Designer Toolbox option if you want to include this component in the Visual Designer's Toolbox.
   • This is only applicable for components that correspond to a field on a form, such as a Text Field. 
9. You can specify that a form component is a container component to support the hosting of a sub-template. Select the Is Container option when you want this component to be able to host a sub-template. 
10. Click the Windows Control tab.
    • The Web Control tab is reserved for future use. 
11. In the Object field, enter the component file's location in the Aptify Object Repository.
12. Enter the Class within the object that implements the component's functionality.
13. Enter the .NET Assembly Name for the component.
14. Enter a License key for the component (if implementing a control from a third-party vendor).
15. Save the record.

Defining Form Component Input Properties

The input properties of a form component define the data elements that may be configured when this component is attached to a template part. For example, if the component defines a text field, information that may be modified when that text field is placed in a template includes the label of the field and the font type and size of the text inside the field.

1. Open a new Input Properties record from the Input Properties tab of the Form Components form.
   
    
2. Enter a name and description for the input property.
3. Choose a type from the Type list.
4. If this input property is required, select the Required option.
5. Click OK to save and close the Input Properties record.
6. Repeat steps 1 through 5 to define additional input properties.
   • Alternatively, you can click OK and New in Step 5 to save the current record and open an new Input Properties record in one step. 

Creating Form Component Categories

Form components may be grouped together based on an organization's business-specific reporting needs. These groupings are defined in Form Component Categories records.

Follow these steps to create a new category:

1. Open a new record from the Form Component Categories service.
2. Enter a name and description.
3. If the components in this category apply to a specific entity, change the Scope to Entity and specify that entity in the Entity field. Otherwise, leave the Scope set to Global.
4. Save and close the record.
5. Repeat the above steps to add additional categories as necessary. 

Creating Form Template Parts

The pieces of form templates are defined individually as form template parts. For example, a part might be a field or a tab that displays on the form or even the entire tab section of the form combined. These parts are combined on the form template to create the unique data view. In general, the system automatically creates Form Template Parts as necessary when generating forms for a new entity. A sample form template part is shown below.

However, if you want to create your own part, follow these steps:

1. Open a new record from the Form Template Parts service.
2. Enter a name and description.
3. Select an existing Form Template Part Categories record in the Category field. Or, you can create a new category. See Creating Form Template Part Categories.
4. Enter a Base Part, if applicable.
   • If this part is based on an existing part, the base part is linked here. A form template part may be based on another part to allow the user to create a duplicate with a different display name or display characteristics. 
5. Enter the Display Name for the part.
6. If this part corresponds to a tab on a form, you can specify an icon from the Object Repository in the Icon field.
   • The tab will automatically display the selected icon to the right of the tab name, as shown above. 
7. If you want to localize the display name of this form template part based a user's assigned culture, enter a Culture String in the Display Culture String field (see Linking Fields to Culture Strings for more information).
8. Select the Type from the list.

   • Component: The form template part is based on a form component. Enter the name of an existing form component in the Form Component field.

     You can also enter an existing form template in the Sub-Template field, if the form component is identified as a Container component. See the information on the Is Container option in Creating Form Components for details.

   • Tab Control: template part is based on another form template. Enter the name of an existing form template in the Sub-Template field and specify the number of tabs to display per row on the form in the Tabs Per Row field. 
   • Sub-Template: The form template part is based on another form template. Enter the name of an existing form template in the Sub-Template field. 
9. If the Type is set to Component, enter the name of the form component in the Form Component field. See Creating Form Components for more information. 

10. If the Type is set to Tab Control or Sub-Template, you can specify a sub-template in the Sub Template field. 

    The sub-templates can also be specified when the Type is set to Component, if the form component is identified as a Container component. See the information on the Is Container option in Creating Form Components for details.

11. Set the Run Mode and Disabled Behavior to control the behavior of this part.
    • A developer can easily conditional control the availability of one or more parts on a form without having to write a Layout Control. Each Form Template Parts record includes Disabled Behavior and Run Mode fields that determine the conditions under which a particular part should be available on a form, as described below:
    • When a Form Template Part has a Run Mode of All, the part is always visible on a form.
    • When a Form Template Part has a Run Mode of New Only and a Disabled Behavior of Disable, the specified part is only available on new records. Once the record has been saved, the field or tab becomes unavailable.
    • When a Form Template Part has a Run Mode of New Only and a Disabled Behavior of Hide, the specified part is only available on new records. Once the record has been saved, the field or tab is automatically removed from the form and is no longer available.
    • When a Form Template Part has a Run Mode of Saved Only and a Disabled Behavior of Disable, the specified part is only available for saved records. The field or tab is grayed out and unavailable on new records and automatically becomes available once the record has been saved.
    • When a Form Template Part has a Run Mode of Saved Only and a Disabled Behavior of Hide, the specified part is only available for saved records. The field or tab is not visible on new records and is automatically added to the form once the record has been saved.
    • If you want to disable the part for all run modes, clear the Enabled option at the bottom of the form. 
12. Enter the location for the template part from the list in the Location field.
    • Select Automatic if the part corresponds to a tab on a form. The location of the tab on the form is determined automatically by the sequence in which it appears on the Part List tab of a Forms Templates record.
    • Select Specific if the part corresponds to a field on a form. Also, configure the settings on the Placement tab; the location of the field on the form is determined by the Placement tab's position and size coordinates, which are in pixels. 
13. If you want the template part to be disabled on the form (no matter the run mode), clear the Enabled option.
14. Save the record.
    • Note that the Enabled option is reserved for future use. 
15. Configure the Input Map (see Configuring Form Template Part Input Map Tab) if you set the form template Type to Component or Tab Control.

This topic consists of below sub-topics.

• Configuring Form Template Part Input Map Tab
• Creating Form Template Part Categories

Configuring Form Template Part Input Map Tab

The Input Maps tab on the Form Template Parts record is applicable when Type is set to Component or Tab Control on the General tab. When the part's Type is set to Component, the Input Map tab provides a list of mappings for the input properties associated with the component upon which this form template part is based. If the defined part's Type is set to Tab Control, the Input Map allows a form template administrator to define the tab control's styling including the coloring of the tabs and display area as well as the font of the tab headings.

Select the appropriate steps depending on the part's Type: 

• Configuring Component Input Maps
• Configuring a Tab Control Input Map Tab

Configuring Component Input Maps

When the Type is set to Component, the form template part inherits a list of input maps that reflect the input properties set up on the Form Component selected. Follow the steps below to define input properties for a form component:

1. Select the Input Maps tab on the Form Template Parts record.
   
    
2. Select a Source Type and Source for the input map:
   • If the Source Type is Static Value, enter an alphanumeric value in the Source cell.
   • If the Source Type is Entity Field, enter the name of an entity field in the Source cell.
   • If the Source Type is SQL Statement, enter an SQL statement in the Source cell.
   • If the Source Type is GE Object, the source is an in-memory generic entity object; enter oGE in the Source field. 
3. Save the record.

Note that typically all Form Template Part inputs use a Static Value source type. 

Configuring a Tab Control Input Map Tab

When the Type is set to Tab Control, a form template administrator can define the way in which a tab control appears on a form including the font of the tab headings and the color of both the tab headings and the form area that appears under the selected tab. Follow the steps below to define the tab styling for the Tab Control.

1. Select the Input Maps tab on the Form Template Parts record.
   
    
2. If you want to use the default Aptify Tab Control settings, select the Use Default Settings option.
   • When checked, Aptify's default tab styling is used and the other fields on the Input Map tab become disabled. Note that when you check this option, the default values are populated in the corresponding field and any customized settings are lost. 
3. If you want to define the appearance of the tabs and display area on the form, make sure the User Default Settings check box is cleared and modify the tab control's style, color and fonts as desired.

Creating Form Template Part Categories

Form template parts are, by default, grouped together based on the entity or sub-entity to which they belong. These groupings are defined in Form Template Part Categories records. The system automatically creates Form Template Part Categories as necessary when generating forms for a new entity. A sample category created by the Form Template Generator is shown below. For example, to distinguish form template parts that may be used on the Cultures form, those parts are grouped under the Cultures Form Parts form template part category.

If necessary, you can create your own categories:

1. Open a new record from the Form Template Part Categories service.
2. Enter a name and description.
3. Enter the name of an Entity to which this part category applies.
4. Save and close the record. 

Adding Parts to Form Templates

1. Create a new Parts record from the Part List tab on the Form Templates record.
   
    
2. Select a Form Template Parts record in the Part field. Add comments if desired.
3. Click OK to save the record.
4. Repeat steps 1 through 3 to add additional parts to the form template.
   • Alternatively, you can click OK and New in Step 3 to save the current record and open a new Parts record in one step. 
5. Use the arrow buttons on the Parts tab to reorder the parts.
   • For tab parts, the order in which the parts appear in the Part List corresponds to the order in which the tabs appear on the form. (This corresponds to the Tab Index option on the Visual Designer's Aptify Form Template Properties Dialog.) 
6. Save the Form Templates record.
7. Close and reopen the Aptify client.
8. Verify that the template is correct by opening a record from the service on which the template is based. If the template is linked to a particular organization or user, make sure to use an appropriate login so that the correct form template is viewed.
   • Note that the Enabled option is reserved for future use. 

Adding a Layout Control

A developer can add functionality, such as inter-part communication or linking a button to an action, to a form by writing a Layout Control. A developer can also utilize layout control logic for form templates used as pages in meta-data wizards. See Defining Wizard Pages for details.

Writing a layout control is beyond the scope of this document; see the information on the Aptify.Framework.WindowsControl.FormTemplateLayout class in the Aptify Software Development Kit (SDK) for information on writing a layout control.

After a developer has created a Layout Control that defines the desired behavior, follow these steps to implement it in Aptify:

1. Open the top-level Form Templates record for the entity and click the Layout Control tab.
   • Aptify recommends associating a layout control that defines inter-part communication and other functionality with the top-level form template rather than with a specific tab's form template. This way, the functionality will remain intact, even if fields move to different tabs on the same form. 
2. Click the Object Repository icon in the Layout Control Object field to open the Select Object Repository Object dialog.
3. Browse to the Object Package for your organization where you want to store the layout control object.
   • You can add the object to the Object Repository from the Layout Control Object field, if it has not been added already. See Creating Object Repository Objects for more information.
   • See Best Practices When Configuring Object Repository Objects for information on recommended naming and storing conventions. 
4. Double-click the .NET Assembly (Private Deployment) Object Type. Select .NET 
   
5. Click the New button and browse to the location of the layout control's file.
6. Select the object you just added and click OK to return to the Form Templates record. (The Object Name field is automatically populated with the Object Package.Object Name of the object you selected, as shown in the figure above.)
7. Enter the layout control's class name in the Layout Control Class field.
8. Enter the layout control's .NET assembly name in the Layout Control Assembly field.
   • If you have written a layout control for a Form Template to add behavior to the form within the Windows environment, this layout control does not apply to the form when rendered in the AWA environment. Due to the differences between the Windows and Web environments, a separate Web-specified layout control is required to add behavior to forms accessed using AWA.  If you want to control the behavior of forms in Aptify web, see the topics under Developing for Aptify Web for more information.
     
   • The Layout Control tab for the top-level Persons form template is shown below.
     
   • The Web Layout Control Object, Web Layout Control Class, and Web Layout Control Assembly fields (which were used with previous versions of Aptify Web (AWA)) are no longer applicable. 
9. Save and close the Form Templates record.
10. Close and reopen the Aptify Desktop client.

Displaying Scroll Bars When Form Is Resized

Aptify includes a layout control that a form template administrator can add to a new or existing form template to display a scroll bar when a form's height needs to be modified to see all the fields on the form. If you want the scroll bar to display for a particular form template, open the associated Form Templates record and add the following to the Layout Control tab.

• Layout Control Object: Startup.Form Template Controls
• Layout Control Class: Aptify.Framework.WindowsControls.ScrollPanelFormTemplateLayout
• Layout Control Assembly: AptifyFormTemplateControls

The scroll bar functionality is not enabled by default and must be added to each form template in which you want to use this feature. 

Configuring Hot Keys for Fields

In Aptify, you can use the LabelCaption Input Property to specify a hot key. For text fields this is done using the ampersand (&) before the letter specified as the hot key (including extended text fields like Date fields). Use ALT + the configured character to place the cursor in field) and F4 to select the icon associated with the field.

Follow these steps to configure a hot key for a specific field:

1. Open the form template that includes the field you want to modify.

   You can also modify the field directly on a form using the Design in Place feature. See Modifying Field Layout with the Visual Designer for more details.

2. Select the Parts tab.
3. Double-click the field you want to modify from the form template parts listed.
4. Click the Part link to open the field's Form Template Parts record.
5. Select the Input Map tab.
6. Double-click the Source column in the LabelCaption row.
   
   
7. If needed, enter a value for the label (usually the same as the field name) and then enter an ampersand (&) before the letter in which you want the hot key to be based.
   • In the example below, when a user selects ALT + W, the cursor will be placed in the Web Site field.
     
     
8. Click OK.
9. Save and close all open records.
10. Verify the hot key by navigating to the field. Select ALT + the configured character specified above in Step 7.
    • If the field is blank the cursor is placed at the beginning of the text field.
    • If the field is already populated, the value is highlighted.
      
      

Once you have navigated to an Extended Type field, you can select F4 to launch the appropriate action. For example, if the field is of Extended Type Web, a user can launch the website without having to click the icon. If the field is of Extend Type Date, clicking F4 displays the Select Date dialog.

Creating a New Form Template

Form templates are collections of template parts, grouped and sequenced as necessary to provide a unique view of the data to the user, organization, or application specified. In general, the system creates form templates as necessary when generating forms for new entities. The top-level Form Templates record for a new entity is shown below.

If necessary, follow these steps to create a new top level Form Templates record:

1. Design the form that you want to display to users or to a sub-set of users.
   • Review About Form Templates for information on how-on-how Aptify constructs the forms that appear by default when using the system.
   • You should also map out what Form Template Parts and sub-templates your new top-level form will require.
   • When creating a top-level form template from scratch, you may find it easier to create each individual sub-templates and relevant parts first before you create the record for the top-level form template container. Or you can create the form and its tabs first, and then draw the necessary fields using the Visual Designer. See About Form Templates for general information on the types of parts and sub-templates typically created in Aptify.
   • You can clone or use existing sub-templates and parts to simplify the process for creating a new top level form template. Note that you should avoid including any generated form templates in your design since these records may be subject to change when the entity is regenerated. Therefore, change generated form templates to nongenerated as necessary.
   • If you want this form to open in a specific context, check the Apply Filer Rules box and add the necessary filters that determines the context in which this form is Displayed. See Loading Forms Based on Usage Context for more details. 
2. Open a new record from the Form Templates service.
3. Enter a name and description for the template.
4. Select the Entity for the template.
5. Place a check mark in the Is Top Level box.
6. Set the Usage Scope. A User level form template takes precedence over a Group or Global template. A Group template takes precedence over a Global template.
   • Global: The template applies to all groups and users identified on the Security tab. You must identify groups and/or users on the two permission sub-tabs of the Security tab to grant access rights to the users on a global level. Global usage allows many different groups and users to access the form template.
   • Group: The template applies only to users associated with the specified group in the Group field. (The Group field will display when the Usage Scope is set to Groups.) Only users with same group identified as their Primary Group will have access.
   • User: The template applies only to the user who is listed in the User field. (The User field will display when the Usage Scope is set to User.) 
7. If Usage Scope is set to Group, enter a Group in the Group field. If Usage Scope is set to User, enter a user name in the User field.
   • No matter which usage scope is selected, the corresponding users and groups must have permissions granted on the Security tab. 
8. Specify the Rank for this form. If multiple forms exist with the same scope, the applicable set of users will only see the lowest ranked form template.
   • If multiple forms have the same scope and rank, then the one with lowest ID will display.
   • The Rank field supports a value from 0 to 100. The default rank for generated templates is 100. 
9. Click the Format tab and specify a Default Height and Default Width for the form template (in pixels).
   • These sizing options are applicable to top-level templates that serve as the container for an entire form. The Default Height and Default Width are not applicable for sub-templates that help define templates. For example, the Campaign Segments.Tabs.General form, which does not need default dimensions, is a sub-template that helps define the appearance of the Campaign Segments.Form, which requires default dimensions. 
10. Click the Security tab and add User and Group Permissions to the form.
    • Security settings are only applicable to top-level templates that serve as the container for an entire form. If a user does not have access to the template, he or she cannot open the form.
    • Note that granting users and groups Read Access is sufficient. The Edit Access and Delete Access options are reserved for future use.
    • For generated form, the system automatically adds the users and groups that have permissions to the entity to the form template's Security tab.
      
      
11. Click the Parts tab and add the relevant Form Template Parts to the template.
    • See Adding Parts to Form Templates for more information on parts.
    • Typically, a top-level template includes parts that link to one or more sub-templates (such as a Tab Sub-Template linked to a Tab Form Part or a Top Area part). 
12. If the template only includes fields (no tabs), click the Visual Designer to use the Visual Designer to add fields to a template.
    • See Modifying Field Layout with the Visual Designer for information on using the Visual Designer. 
13. If a developer has written a layout control for the form, add the relevant file information to the Layout Control tab. See Adding a Layout Control for details.
14. Save the record.

Loading Forms Based on Usage Context

When using forms in Aptify, there may be times when it is useful to display different forms within the same service. For example, it may be useful to display different Companies forms depending on company's type. Or perhaps, when opening a new record, the form should be optimized for data entry whereas when opening an existing record, the form should be optimized for viewing information.  Aptify includes functionality that allows different forms to appear based on the usage context. To implement this functionality, top-level forms (that is Form Templates that have Is Top Level set to true) include a Filter Rules control in which a form template administrator can determine the context in which a particular form is displayed based on usage. The below example illustrates how Aptify has used this functionality to provide a Products form that is specific to Meetings.

When the Apply Filter Rule box is checked, a form template administrator can create filters based on several different services (context). Below describe each one:

• Entity: Creates filters statements based on the service in which the form belongs.
  • For example, if you want a particular form to open for Companies record where the Company Type is Vendor, you could specify the following on a top-level Form Templates record (template must be associated with Companies):
    • Service: Companies
    • Field: CompanyType
    • Operator: Exactly Matches
    • Value: Vendor 
  • If you want a different form to be displayed when a user opens a new record in a service, specify an entity filter statement with an ID value <= 0. To display a particular form for existing records, specify a filter statement with and ID value > 0. 
• User: Creates filters based on attributes of the currently logged in user.
  • For example, if you want users with trusted user accounts to be displayed a certain form, you could specify the following filter statement on a top-level Form Templates record. 
    • Service: Users
    • Field: IsTrusted
    • Operator: =
    • Value: 1 
• Group: Created filters based on a group's permissions.
  • For Example, if you want users whose primary group is Accounting to be displayed a certain form, you could specify the following filter statement on a top-level Form Templates record.
    • Service: Groups
    • Field: Name
    • Operator: Exactly Matches
    • Value: Accounting 
• Application Context: Creates filter statements based on the application environment from which the form is launched.
  • For example, if you want a different form to appear for Aptify Web Access Users than Aptify Smart Client users, and you could specify the following filter statement on a top-level Form Templates record using the Application Name field. By default, this is set to the value of the configuration file attribute, Startup.GeneralStartup.ApplicationName, but it can also be set programmatically.
    
    • Service: Application
    • Field: Application Name
    • Operator: Exactly Matches
    • Value: AWA 
• The Application Context service includes several fields that can be used to filter based on a particular software version including:
  • MajorVersion: The Major File Version number. By default, this is set to the Major part of the File Version for Aptify Shell.exe (0 for Aptify 6.0) This can also be set programmatically.
  • MinorVersion: The Minor File Version number. By default, this is set to the Minor part of the File Version for Aptify Shell.exe (0 for Aptify 6.0, x for Aptify 6.x) This can also be set programmatically.
  • ServicePackNumber: The Service Pack number. By default, this is set to the Build part of the File Version for Aptify Shell.exe (3 for Aptify 6.0 SP3, 0 for Aptify 6.x) This can also be set programmatically.
  • UI Type: A string that is used to identify the Application's User Interface Type. It is intended to be used to differentiate between applications that are delivered to different platforms. This can be used to target Form Templates to the Desktop client, a WinForms application, Aptify Web Access (Silverlight) and, eventually, other platforms like phones and tablets. By default, the value can be defined by the configuration file attribute Startup.GeneralStartup.UIType. It can also be set programmatically. To utilize this filter, ensure that your applications are setting the UIType to a different value for each application UI type. 
• Application Context can also be filtered based on a client's monitor including resolution height (ScreenResolutionHeight) and width (ScreenResolutionWidth) and the number of monitors (NumberofMonitors). 

Modifying the Display Settings for a Hierarchy Browser

Administrators can modify the display settings of a hierarchy browser for an entity by updating the SQL for the appropriate input properties. 

Perform the following steps to modify the display settings:

1. Open the Form Template Parts service.
2. Search for and open the hierarchy browser form template part record for the selected entity (e.g., the hierarchy browser for the Companies entity is Companies.Browser).
3. Click the Input Map tab.
4. Update the SQL in the Source column for the input properties you want to change.
   • In the Desktop client, click in the Source column and update the information. 
   • In the Web interface, double-click the property, update the Source field in the Input Map record, and click OK.
   • For example, to update the hierarchy browser to display a child company's name and ID, you would change the HierarchyNodeItemsSQL input property.
     
     
     
     

   • To make this change, you would modify the default value of the SQL for the HierarchyNodeItemsSQL input property from the default value:

     SELECT ID, Name FROM vwCompanies WHERE ParentID=[~ID~] ORDER BY Name

     
     To the following value:

     SELECT ID,(Name +' (ID: '+(convert(nvarchar,ID))+')') As Name FROM vwCompanies WHERE ParentID=[~ID~] ORDER BY Name

     In this example, an alias for the company is not required. When the control processes the SQL results to add nodes to the tree, two fields are going to be returned. The first field is an integer (generally an ID field), and the second field is a string (generally a name, but it could be any desired string field or calculation, as in the example above).

5. Save and close the Form Template Parts record.
6. Open a record for the selected entity and validate that the hierarchy browser display changed as expected. 
   • In the example below, the hierarchy browser in the Divisions tab for the Companies entity has been updated to display the child company's name and ID: 
     
     

Validating the Preferred Phone Number Settings

Aptify has the ability to specify a preferred phone number type in a Persons record using the Aptify Desktop client. This new field, Pref. Phone, may not work in environments with a modified version of the Persons record.

If the preferred phone number type function does not work in your environment, perform the following steps to validate the layout key settings of the Form Template Part Persons Phone Control and Persons Preferred Phone records.

1. Open the Form Template Parts service in the Framework application.
2. Find and open the Persons Phone Control record.
3. In the Layout Key field, ensure that the value is set to Persons Phone Control.
4. Save and close the Persons Phone Control record.
5. Find and open the Persons Preferred Phone record.
6. In the Layout Key field, ensure that the value is set to Persons.PreferredPhone.
7. Save and close the Persons Preferred Phone record.