(Deprecated) Guide Layout Controls and Field Controls

Controls are Guide extensions that perform specific actions. In general, a control performs only a single action. However, that action can be as simple or as complex as you require for your specific solution.

There are two types of controls:

Field controls:
Field controls are the items that you add to a Guide panel in Workbench, such as fields, buttons, and lists. In some situations, using a different Flex object makes the user experience more engaging. For example, if the original Numeric Field object is used to store a percentage value, you can map the Numeric Field to an HSlider control. Mapping to a control creates a more intuitive data entry experience for a user.

Guide layout controls:
A Guide layout references Guide layout controls, and they never appear in Workbench. Examples of Guide layout controls include the navigation panel, Next and Previous buttons, the data entry panel, and the Guide Help panel.

Workbench provides a tremendous amount of functionality. However, some situations require you to create specific functionality based on your solution requirements. For example, you can create Guide layout controls that allow your users to quickly move to the first or last panel. These controls are useful in a large Guide. The Next and Previous buttons that appear on a Guide are Guide layout controls that let users move forwards and backwards through a Guide.

To take full advantage of custom controls in a Guide, familiarize yourself with the Guide ActionScript packages. (See ActionScript Language Reference.)

Guide field controls in Workbench

In Workbench, field controls are items that you add to a Guide panel, such as fields, buttons, and lists.

In the Guide Properties view, all the field controls for a Guide are included in the Control Type > Display As list. When you select an item from that list, additional properties appear in the Guide Properties view. Each control type has different corresponding properties. For example, if you select HSlider or VSlider, the Minimum and Maximum properties appear.

When you extend an existing field control, the corresponding additional properties appear in the Guide Properties view.

Control type in the Guide Properties view

Class to extend

Button

mx.controls.Button

Checkbox

mx.controls.CheckBox

Checkbox List

ga.controls.CheckBoxList

Date field

mx.controls.DateField

Drop-down list

mx.controls.ComboBox

Horizontal slider

mx.controls.HSlider

HRule

ga.controls.HRule

Image field

ga.uiComponents.ImageField

List box

mx.controls.List

Nested panel

ga.uiComponents.PanelComponent

Numeric stepper

mx.controls.NumericStepper

Radio button

mx.controls.RadioButton

Radio button list

ga.controls.RadioButtonList

Static list

ga.uiComponents.StaticList

Static text

ga.uiComponents.StaticText

Static text multiline

ga.uiComponents.StaticTextMultiline

Submit Guide button

ga.uiComponents.SubmitGuideButton

Text area

mx.controls.TextArea

Text input

ga.uiComponents.TextInputPicture

Text input comb

ga.uiComponents.TextInputComb

Text input mask

ga.uiComponents.TextInputMask

Text input symbol

ga.uiComponents.TextInputSymbol

Vertical slider

mx.controls.VSlider

Create a control

You can create new controls in either MXML or ActionScript. Save field controls in the controls folder and save Guide layout controls in a different folder.

Important: Do not edit the field control files that are included with Workbench. Instead, make uniquely named copies of the content to help you create field control extensions.

Learn to create custom controls by studying several examples:

Create a field control in MXML

  1. In Flash Builder, select File > New > MXML Component.

  2. Type a unique filename.

  3. From the Based On list, select a component that is most similar in behavior to the component that you want to create. Basing the new control on an existing component lets you take advantage of existing behaviors through inheritance.

  4. (Optional) Set values for Width and Height.

  5. Click Finish.

Create a field control in ActionScript

  1. In Flash Builder, select File > New > ActionScript Class.

  2. Type a unique class name.

  3. In the Superclass field, select the ActionScript class that is most similar in behavior to the control that you want to create. Basing the control on an existing class lets you take advantage of existing behaviors through inheritance.

  4. Click Finish.

    After you create the shell of the new control, add the desired functionality in Flash Builder. For more information about the Guides ActionScript API that you can take advantage of while adding functionality, see ActionScript Language Reference.

    Note: When you develop controls for a Guide, some situations require you to import ActionScript objects. These ActionScript objects are generated automatically from the data model associated with the Guide. The data model contains ActionScript related to the behavior of the objects stored in the data model. This ActionScript can help you develop your custom control. You can access the ActionScript generated for data model objects in the C:\Documents and Settings\<username>\Application Data\Adobe\LiveCycle\ES3\Guides\generated\<LiveCycle Application>\<version>\<data model> folder. Import any required ActionScript files into your Flex library project.

Create Guide layout controls

Guide layout controls are extensions that affect how a user navigates through the sections and panels of a Guide. The Next and Previous buttons, controlled by the NextPanelButton and PreviousPanelButton ActionScript classes respectively, are examples of Guide layout controls.

Do not save Guide layout controls in the controls folder.

For example, you can create Guide layout controls to help Guide fillers browse Guides that contain many sections and panels.

Example: FirstPanelButton Guide layout control

You can create a button object that displays the first panel in the Guide, when a Guide filler clicks it at runtime. When the Guide renders, a button labeled First is inactive, and the user cannot click the button. After the user navigates to another panel in the Guide, the First button becomes active and the user can click it. Clicking the First button displays the first panel in the Guide.

package com.adobe.guides.controls 
{ 
    import mx.controls.Button; 
    import flash.events.Event; 
    import flash.events.MouseEvent; 
    import ga.model.GAEvent; 
    import ga.model.PanelManager; 
 
    public class FirstPanelButton extends Button 
    { 
 
        // The PanelManager class controls the organization and behavior 
        // of panel instances at runtime. The class contains 
        // convenience properties and methods that are useful for  
        // manipulating panels within a Guide. 
        private var _pm:PanelManager; 
         
        protected override function createChildren():void   
        { 
            super.createChildren(); 
            this.label = "First"; 
            _pm = PanelManager.instance; 
 
            // Adds event listeners for the three events that can cause a 
            // change in the state of this button, and reevaluates if the button 
            // should display as enabled. 
            _pm.addEventListener(GAEvent.PAGE_SELECTION_CHANGE, pageChange); 
            _pm.addEventListener(GAEvent.PAGE_REMOVE, pageChange); 
            _pm.addEventListener(GAEvent.PAGE_ADD, pageChange); 
 
            // Sets the default behavior when the Guide renders. In this 
            // case, on the initial panel, the button should be dimmed. 
            super.enabled = false; 
        } 
 
        // When the button is clicked by a user, the current panel displayed 
        // is set to be the first panel in the Guide. 
        override protected function clickHandler(event:MouseEvent):void  
        {  
            if (super.enabled)  
            {  
                _pm.currentPage = _pm.firstPage; 
            }  
        } 
 
        // Conditionally sets the button's enabled property dependent on 
        // whether the current panel is the first panel in the Guide. 
        private function pageChange(event:Event):void  
        {  
            super.enabled = _pm.previousPage!=null; 
        } 
    } 
}
When creating custom navigation controls, be aware of the methods and properties of the PanelManager class. (See ActionScript Language Reference.)

Example: LastPanelButton Guide layout control

You can create a button object that displays the last panel in the Guide, when the Guide filler clicks it at runtime. When the Guide renders, a button labeled Last is displayed. Clicking the button displays the last panel in the Guide.If the Guide filler is on the last panel of the Guide, the Last button is dimmed and the user cannot click it.

package com.adobe.guides.controls 
{ 
    import mx.controls.Button; 
    import flash.events.Event; 
    import flash.events.MouseEvent; 
    import ga.model.GAEvent; 
    import ga.model.PanelManager; 
 
    public class LastPanelButton extends Button 
    { 
        // The PanelManager class controls the organization and behavior 
        // of panel instances at runtime. The class contains 
        // convenience properties and methods that are useful for  
        // manipulating panels within a Guide. 
        private var _pm:PanelManager; 
         
        protected override function createChildren():void   
        { 
            super.createChildren(); 
            this.label = "Last"; 
            _pm = PanelManager.instance; 
 
            // Adds event listeners for the three events that can cause a 
            // change in the state of this button, and reevaluates whether 
            // the button should display as enabled. 
            _pm.addEventListener(GAEvent.PAGE_SELECTION_CHANGE, pageChange); 
            _pm.addEventListener(GAEvent.PAGE_REMOVE, pageChange); 
            _pm.addEventListener(GAEvent.PAGE_ADD, pageChange); 
 
            // Sets the default behavior when the Guide renders. In this 
            // case, on the initial panel, the button should be disabled. 
            super.enabled = true; 
        } 
 
        // When the button is clicked by a user, the current panel displayed 
        // is set to be the last panel in the Guide. 
        override protected function clickHandler(event:MouseEvent):void  
        {  
            if (super.enabled)  
            {  
                _pm.currentPage = _pm.lastPage; 
            }  
        } 
 
        // Conditionally sets the button's enabled property dependent on 
        // whether the current panel is the last panel in the Guide. 
        private function pageChange(event:Event):void  
        {  
            super.enabled = _pm.nextPage!=null; 
        } 
    } 
}

Add custom Guide layout controls to panel and Guide layouts

You can add Guide layout controls to a panel or Guide layout. To implement the controls, add them to the MXML definition that is associated with a panel or Guide layout.

For example, modify the Guide layout in Create a Guide layout. Add the First and Last buttons from Example: FirstPanelButton Guide layout control and Example: LastPanelButton Guide layout control to the layout. Add a new namespace com.adobe.guides.controls.* to simplify the references to the new controls. The bold text represents the references to the custom navigation controls.

<?xml version="1.0" encoding="utf-8"?> 
<gc:Wrapper width="100%" height="100%" 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:gc="ga.controls.*"  
    xmlns:cc="com.adobe.guides.controls.*" > 
     
    <mx:VBox width="100%" height="100%"> 
        <gc:PanelContent width="100%" height="100%" /> 
        <mx:HBox> 
            <cc:FirstPanelButton /> 
            <gc:PreviousPanelButton label="Back" /> 
            <gc:NextPanelButton label="Forward" /> 
            <cc:LastPanelButton /> 
            <gc:SubmitButton label="Submit Data" /> 
        </mx:HBox> 
    </mx:VBox> 
</gc:Wrapper>

Create custom field controls

Field controls are custom components that replace standard Guide items to provide an enhanced user experience.

For example, you can create field controls that provide a more intuitive data entry experience for Guide fillers.

Example: CustomHSlider field control for Guides

You can create an HSlider control for mapping Guide items. This control assumes that the original Guide item specifies integer values from 0 through 100 that indicate a percentage.

When the Guide renders, an HSlider control replaces the original Guide item. The HSlider has the same caption as the original Guide item. The Guide filler can drag the slider to set a value from 0 through 100.

When the Guide filler switches to the PDF form, the value that they set with the slider appears in the corresponding field. If they change the value on the PDF form and then return to the Guide, the slider value updates.

package com.adobe.guides.controls 
{ 
    import mx.controls.HSlider; 
 
    public class CustomHSlider extends HSlider  
    { 
 
        protected override function createChildren():void   
        { 
            super.createChildren(); 
 
            // Sets the minimum, maximum, and initial values for the range. 
            this.minimum = 0; 
            this.maximum = 100; 
            this.value = 0; 
 
            // The increment range for the slider, and the increments for the 
            // increment label. 
            this.snapInterval = 1; 
            this.tickInterval = 10; 
 
            // The label for the range represented by the slider. 
            this.labels=['0%', '100%']; 
 
            // Sets interaction properties allowing the slider to update in 
            //real-time in response to user interaction. 
            this.allowTrackClick = true; 
            this.liveDragging = true;  
        } 
    } 
}

Map Guide objects to custom controls

To use a custom field control in a Guide, associate an object in the Guide tree with the custom field control. Map each Guide object that you want to associate with the new custom field control. You do not need to add the custom field control to a Guide layout or panel layout.

  1. Start Workbench and open the Guide.

  2. In the Guide Tree view, select the Guide object that you want to map.

  3. In the Guide Properties view, click Display As, and then select the custom control. For example, to use the custom control created in the Example: CustomHSlider field control for Guides section, select Custom H Slider.

  4. Save the Guide.

  5. To view the new custom control, preview the Guide.

// Ethnio survey code removed