Firing form guide events from your form design script

When designing forms in LiveCycle Designer ES that will eventually be rendered as a form guide by the server I regularly come across the need for script on the form to notify the form guide something needs to be done.  One such case is the use of xfa.host.messageBox().  When this script is executed in a form guide the default Flex Alert is shown.  While this is fine for quick informational messages it cannot be styled to match the look of my form guide nor can it handle any user response.  This article covers one possible technique that can be used to allow your form scripting to send events to the form guide.

 

Step 1: xfa.host.name == "Flash"

This one line of script will very quickly become your friend when scripting a form that may be rendered as a form guide.  Keying on the current host name allows you to target your script to only run in certain environments.  This technique is not only valuable to ensure scripting outside of the supported xfa subset can still be executed in Acrobat/Reader it also opens the door for some inventive scripting when the form is being hosted in Flash (ie. form guide).  One such door that opens is the ability to enter ActionScript directly in your form design script that will only get executed when in a form guide context.

 

Step 2: Add ActionScript to your form design script

Let’s look at a case where the client-side click event of a button in your form design has the following script.

//Show Yes/No message box
var ans = xfa.host.messageBox("My Text" , "My Title",  2);

if (ans == 3)
{
   // No is selected
}
else
{
   // Yes is selected
}

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

In order to get a similar result in the form guide where the user gets presented with a Yes/No message box that must be answered an event can be fired. On the same click event we can add the following script.

if (xfa.host.name == "Flash")
{
this.dispatchEvent(new XfaModelEvent("showCustomDialog", false, false, "My title", "My text", null);
}

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

This ActionScript will fire an event on the form guide that can be listened for and acted upon accordingly.  The name of the event, showCustomDialog, could be any string you wish.  You could also fire events with multiple names fro myour form script for any number of desired behaviours.

Step 3: Create a Popup Manager in Flex

In order for this technique to work your form guide will need to reference a custom Flex library that includes a custom guide layout (ie. Wrapper).

First, I’ll explore the creation of a Xfa Popup Manager in Flex. There are many ways you could write your Flex code to display popups requested from scripting in your form design.  This method is one such approach but could be altered to suit your individual needs.  Here are the basic steps I will be following.

  1. Create a class called XfaPopUpManager
  2. Create a static public function called "manage" that takes a Page as input
  3. Set up listeners for all panel items on the current page
  4. Handle popup events when they occur
  5. Listen for popup close events

And here is the abbreviated class code.

public class XfaPopUpManager
{
private var popup:Alert;

static public function manage (oPage:Page):XfaPopUpManager
{
return new XfaPopUpManager(oPage);
}

public function XfaPopUpManager(oPage:Page):void
{
addPopupListeners(oPage);
}

/**
      * Creates listeners in order to provide a custom popup dialog for
      * those fields that dispatch a "showCustomDialog" XfaModelEvent at runtime.
      */
public function addPopupListeners(oPage:Page):void
{
for each (var item:PanelItem in oPage.layout.getPanelItems())
{
if(item.boundData != null && item.boundData.hasEventListener("showCustomDialog") == false)
{
item.boundData.addEventListener("showCustomDialog", popupHandler);
}
}
}




    /**    
* show popup has been requested - present a dialog.
*/
protected function popupHandler(oEvent:Event):void
{
if (displayPanelItems[oEvent.currentTarget] != null)
{
var title:String = "";
var msg:String = "";
if (oEvent is XfaModelEvent)
{
title = XfaModelEvent(oEvent).propertyName;
msg = XfaModelEvent(oEvent).propertyValue;
}
doShowPopup(title, msg);
}
}
    /** 
* Creates Dialog style popup for programmed popUp requests.
* @param title
* @param displayText
* /
protected function doShowPopup(title:String, displayText:String):void
{
// Prevent multiple occurrences of a modal dialog. This may happen due to cloned
// fields that already have listeners.
if (popup != null) return;
var flags:uint = Alert.YES | Alert.NO;
popup = Alert.show(displayExt, title, flags, null, handlePopupClose);
}
    /** 
* Handle the pop up close event
*/

private function handlePopupClose(event:CloseEvent):void
{
if (event.detail == Alert.YES)
{
//Yes selected
} else if (event.detail == alert.NO)
{
//No selected
}
popup = null;
}
}

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

 

In the handlePopupClose function you could place any logic required by the form. An extension to this technique that I won’t cover here would be to pass the SOM expression of a hidden button on your form that could be programmatically clicked as another parameter of the XfaModelEvent.  This way the script that runs after the message box is dismissed could be the same whether the form is being hosted by Acrobat or Flash.

For example…

Xfa.instance.resolveNode(somExpression).execEvent("click");

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

 

Step 3: Hook it all up  in your custom guide layout

We’re almost done!  All that needs to be done now is some wiring in your custom guide layout.

First you will need to listen for the Page Selection Change event.

panelManager.addEventListener(GAEvent.PAGE_SELECTION_CHANGE, pageChange);

This listener can be added to your wrapper’s createChildren() function.

Next the page change listener function needs to be created which is where the popup manager we created will be set up.

private function pageChange(event:GAEvent):void
{
//...
XfaPopUpManager.manage(event.page);
//...
}

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

When running a a form guide your form should now be able to dispatch events to the guide runtime and then act on those events based on the custom Flex code you tied those events to.

Share on Facebook

Keeping your custom panel layouts styled: Part 2

Last week I covered a number of style names that can be added to your guide layouts when creating custom form guide components.  By adding these style names to your layout you can take advantage of all the styling that gets defined in Guide Builder and is included with each guide definition.  Similar to guide layouts there are also a few of style names that can be included in custom panel layouts.

Here are a selection of style names that can be added to your custom panel layouts.  These styles can be defined by going to Customize Appearance in Guide Builder and navigating to the appropriate panel listed under each style name description.  A number of these style names do not need to be included in your MXML since they are handled internally by the Panel Item component.

Style Name MXML Description
layoutobjects <mx:VBox width="100%" height="100%" styleName="layoutobjects"> Defines padding for your top-level panel layout container.

Guide Builder: no editable in Guide Builder

panelhelp <gc:HelpPanel id="helpPanel" styleName="panelhelp" /> Applies the font, background and border styles to the help panel component.

Guide Builder: Customize field and text > Panel help background, font

fieldhelp handled by <ga:PanelItem/> Applies the font, background and border styles to a field help component.

Guide Builder: Customize field and text > Field help background, Field Active, font

panelitem handled by <ga:PanelItem/> Applies the font and background styles to a field component.

Guide Builder: Customize field and text > Field background, Font

panelcaption handled by <ga:PanelItem/> Applies the font and color styles for field captions.

Guide Builder: Customize field and text > Font

paneltext handled by <ga:PanelItem/> Applies the font and color styles for panel text.

Guide Builder: Customize field and text > Font

Share on Facebook

Keeping your custom guide layouts styled: Part 1

When creating custom layouts to be used with form guides it is a good practice to ensure that your layouts can be styled.  One method that will achieve this goal is to use the style names that get defined by Guide Builder.  By adding these style names to various components in your layout you can take advantage of all the styling that gets defined in Guide Builder and is included with each guide definition.

Here are a selection of style names that can be added to your custom guide layouts.  These styles can be defined by going to Customize Appearance in Guide Builder and navigating to the appropriate panel listed under each style name description.

Style Name MXML Description
application

<mx:VBox width="100%" height="100%" styleName="application"/>

Defines the overall background gradient colors for the guide.

Guide Builder: Customize guide, logo and progress bar -> Background

logo <mx:VBox styleName="logo" left="0"/> Specifies a location to hold an image such as a logo.

Guide Builder: Customize guide, logo and progress bar -> Logo

guidetitle <mx:Label text="{panelManager.gaModel.name}" styleName="guidetitle"/> Specifies font and color styles.

Guide Builder: Customize guide, logo and progress bar -> Font

guide

<mx:HDividedBox styleName="guide"/>

Defines background color/image, border color, padding and corner radius styles.

Guide Builder: Guide Builder: Customize guide, logo and progress bar -> Border, Guide background

panelnav

<mx:Panel styleName="panelnav"/>

Defines font, background color, background image, background alpha, border and header styles.

Guide Builder: Customize panels -> Panel border, Panel header, Navigation, Font

guidehelp

<mx:Panel styleName="guidehelp"/>

Defines font, background color, background image, background alpha, border and header styles.

Guide Builder: Customize panels -> Panel border, Panel header, Guide help, Font

paneldata

<mx:Panel styleName="paneldata"/>

Defines font, background color, background image, background alpha, border and header styles.

Guide Builder: Customize panels -> Panel border, Panel header, Data entry, Font

buttons

<gc:NextPanelButton styleName="buttons"/>

Defines theme color, fill colors and font styles.

Guide Builder: Customize buttons and repeater layouts -> Button color, Button theme color, Font

 

For further information on how to include form guide specific style names in your own layouts browse the guide source included with the LiveCycle install.  The source and associated Flex project have been made available for all the default guide layouts, panel layouts and guide controls.

./LiveCycle8.2/LiveCycle_ES_SDK/samples/FormGuides/GuideSource

In my next post I will cover the various styles that can be applied to your custom panel layouts.

Share on Facebook

Tips and tricks from the form guide team

A great new blog is now available from the Form Guide team at Adobe.  This blog will contain contributions from many memebers of the form guide team as they discuss tips, tricks and best practices concerning Form Guides.

The team is also looking for questions and suggestions from those early adoptors out there already using Form Guides to help guide future postings so be sure to provide lots of comments.

The URL for the new blog is:

http://blogs.adobe.com/lcformguides/

technorati tags:

Blogged with Flock

Share on Facebook

Drag and Drop support in Guide Builder

Did you know that the Guide Builder tool included with LiveCycle Designer not only supports drag and drop from the Designer canvas but also from the file system?

I’ll start with drag and drop with LiveCycle Designer.  In Guide Builder the form hierarchy is provided to allow a user to pick form objects that they wish to appear in their form guide. While this hierarchy provides a quick way to see all the objects on a form they may not be easy to find particularily on a larger form.  In these cases it may be easier to pick objects directly from the design view canvas in LiveCycle Designer.  With Guide Builder running switch back to Designer and pick the fields you want to include in your form guide.  Next, drag and drop these fields on top of Guide Builder.  When a panel is selected these fields will be automatically added to that panel otherwise a dialog will appear asking you where you would like the fields to be placed.

If that wasn’t cool enough Guide Builder also supports SWC, CSS, XML and XDP file types being dragged form the file system.  How each of these files is handled depends on what view Guide Builder is currently in. 

When in the Edit Guide view any guide definitions found in XML or XDP files will be imported into the current guide.  Any SWC files that are dropped onto Guide Builder will be added as custom library components for the currently selected guide.

When in the Customize Appearance view any SWC or CSS files that are dropped onto Guide Builder will be used as a custom style for the currently selected guide.

For more information on using Guide Builder look up Using Guide Builder in the LiveCycle Designer ES Help.

technorati tags:

Blogged with Flock

Share on Facebook

Form Guide Documentation

LiveCycle ES has now been out on the market for just over six months.  This means people are finally starting to get their feet wet and are looking at form guides as a possible solution to create engaging data capture applications.  As a result I been getting more requests lately on how one should actually get started creating a form guide.  For those just getting started there is a fiar amount of documentation already available online that is worth reading.

  1. Using Guide Builder
    (LiveDocs)

    • The LiveCycle ES Designer documentation contains a whole section on how to use Guide Builder
  2. Getting Started With Form Guides
    (PDF)

    • This is a great document that provides an overview of form guides, walks through creating a new form guide and touches on customization.
  3. Customizing Form Guides (PDF)
    • If you are really interested in creating custom form guide components this is the document for you!  This document provides information about creating customized guide layouts, panel layouts and controls using Flex Builder. This is also the place to go if you want to learn about taking advantage of the built in styling capabilities of form guides.

While these documents are great starting point for your form guide solution development over the next few months I will be posting additional articles that cover some of the holes and more difficult aspects of creating form guides.  If you have specific questions feel free to leave a comment and I’ll do my best to address it.

Share on Facebook

Meet me at MAX

There is only a little over a week to go before Adobe’s biggest developer conference ever kicks off and I will be presenting there once again this year.

Adobe MAX 2007 is taking place in Chicago this year from September 30 to October 3. This year’s conference is shaping up to be bigger and better in all aspects than any previous year. If you are a developer using any of Adobe’s products this is definately the must attend event of the year.

If you are already planning to attend MAX I would like to point out some of the exciting sessions being presented around the LiveCycle suite of products.

First, I will plug my own session that will cover LiveCycle Forms ES and its new form guide feature. Over the past year I have been on the form guide team in Ottawa busily creating a tool for LiveCycle Designer ES called Guide Builder. This tool is a Flex-based desktop application that provides an extremely easy interface for creating dynamic and interactive form guides. Without giving too much away I am really excited to talk about this cool new feature and how it leverages the best of PDF and Flex technologies. Please come by one of my two sessions to learn more about LiveCycle Forms and form guides and be sure to say “hi” as well!

Everything You Want to Know about LiveCycle Form Guides

  • Monday, October 1 4:30 pm – 5:30 pm (room #177)
  • Wednesday, October 3 4:15 pm – 5:15 pm (room #177)

So, what else should you do while at MAX? If you are interested in learning more about LiveCycle here are a few sessions I think will be invaluable.

Hands On: Designing PDF Forms and Flex-based Form Guides
Boot Camp for LiveCycle
Forms Gone Wild
Hands On: Building an Application Using LiveCycle ES

Hands On: Extreme Form Makeover – with LiveCycle Designer 8, ES and Flex

And like the infomercials say…”and that’s not all folks”!

Stop by the after hours lounges in each of the hotels for some networking opportunities.  If you want to learn more about Adobe products be sure to head over to the community pavillion.  Finally be sure to come out to the LiveCycle meet the team BOF on Monday night starting at 7:30 pm.

This year is shaping up to be a great MAX and I can’t wait to meet the people who are eager to learn more about developing great applications using Adobe technology.

See you at MAX!

technorati tags:, , ,

Share on Facebook

Introducing Form Guides

,

It has been way too long since I last updated this blog.  Now that I back for what I hope to be much more frequent updates regarding LiveCycle, Flex and rich Internet applications I decided to give my blog a fresh new look as well.

Over the past year I have been on the team that has been actively developing the new form guide functionality released with the LiveCycle Enterprise Suite.  In particular I have been developing the new Guide Builder tool that is included with LiveCycle Designer.  Now that LiveCycle ES has been released this post is the first in a series I plan to write over the next couple of months that covers the new form guide technology and how it works.

Form guides are Flash Player compatible wizard-like panels that help guide people through a data capture experience which are rendered using LiveCycle Forms ES.  While the form guide technology is included with LiveCycle Forms ES, there is also a tool called Guide Builder included with LiveCycle Designer ES that enables form guides to be defined from existing PDF and XML templates.

Imagine you have a document-based PDF form.  While this form is very capable of collecting data it may not be the most intuitive experience for a novice user. Such a form is still required however for going offline, collecting signatures and printing.  Also, if the form has been already imported into LiveCycle Designer additional scripting may have been added. Form guides enable a user to take their document centric forms and apply a new skin or user interface to them while still maintaining the same underlying data model.  In fact, the data model is shared between form guides and the PDF so one could actually enter data in either and see instantly in both renderings of the form!

Providing a different skin to an exisintg PDF form is ony the first step in form guide generation.  Form guides also provide a wealth of new features not available when simply filling out a document-based PDF.  Navigation can be added, sections of the form will dynamically appear as a auser enters data and answers questions, transitions can be added and interactive content incorporated into the final application as well.

 

Share on Facebook

Guided Activities highlighted at Adobe MAX

After the Blue Man Group performed during the opening general session at Adobe MAX on Tuesday we were treated to a number of demos of new products coming soon from Adobe.  Near the end of all the demos Ben Forta did a demo of creating a Rich Internet Application from a document created in LiveCycle Designer.  Since time was running out this demo got very little stage time but was quite compelling nevertheless. Basically what Ben’s demo showed was that using Adobe products one could take one of the millions of PDFs out there, import it into LiveCycle Designer, specify the layout of the RIA by selecting fields in the Designer, and then rendering the updated XML form template using LiveCycle Forms as a compiled and integrated Flex application.

WOW!!!  Without even having to open Flex Builder a business user will be able to create applications that leverage the Flex Framework from within LiveCycle Designer and have LiveCycle Forms handle the actual generation.

technorati tags:, , ,

Blogged with Flock

Share on Facebook

Hanging out at MAX

I have been in Las Vegas for a few days now for the Adobe MAX developer conference and have kept quite busy.  Getting a reliable Internet connection has been difficult at times though.

Since arriving on Sunday I have been working on finalizing my LiveCycle Forms workshop which I am presenting on Tuesday and Thursday.  I also have spent some time at the LiveCycle pavillion (be sure to stop by if you’re at the conference) and attended a few sessions with the rest of my free time.  Oh, I’ve also managed to check out some of the Las Vegas strip and nearby casinos just so you don’t think I haven’t been outside yet.

So, after my first full day at my first Adobe MAX conference I must say that the experience has been very rewarding.  Be able to meet people that use LiveCycle or are interested in using it is great!

For Wednesday I will spending my time between the pavillion hall and will also be atending Matt Butler’s LiveCycle session.  I am also going going to update my workshop content before Thursday based on feedback I received today.

technorati tags:,

Blogged with Flock

Share on Facebook