Posts tagged "CQ and LiveCycle"

POST data size limit

A generic Mobile Form workflow involves rendering a form, filling up fields and then submit it for further processing. Mobile Form submits data to server on HTTP POST. If the form is very big or it is merged with large size data, sometimes there is chance that the submission payload exceeds the default limit of the server. In this case, you might see HTTP 500 error on form submission. If you inspect the server logs, you will see this exception – “Template is not specified”.

On jboss server, POST size limit is 2MB as per its documentation. You can increase the POST size limits and here is how to do it for JBOSS.

  • Go to <jboss_dir>/server/<server_name>/deploy/jbossweb.sar directory and look for server.xml.
  • There is a <Connector> specified for “HTTP/1.1″ protocol like this

<Connector protocol=”HTTP/1.1″ port=”8080″ ….>

  • Add an attribute “maxPostSize” to this if not already added. Specify its value as per the requirement. ‘0’ means there is no limit on POST size.

After changing the settings, you have to restart the app server to affect these changes. After this you should be able to submit the form.

Cache is king

Cache plays a very important role in the performance of Mobile Form or for that matter any component. Mobile Form caches all the intermediate objects required to process (rendition or submission) a form on first request. It doesn’t cache the objects dependent on the data as they are very likely to change.

Mobile Form maintains two different levels of cache. The flow goes like this as depicted in the flow diagram:

1) From the request it picks up the template and resolves its fragments and images.

2) The resolved template (with referred fragment and images) along with the dependency list (of images and fragments) is store in the cache. This cache store is called PreRender Cache as it stores entities and artifacts generated before final rendering.

3) Now this resolved template is used to generate the  rendered content like HTML and stored in the cache again. This cache store is called Rendered Cache and it stores rendered content.

CacheWorkflow

Mobile Form doesn’t cache the templates that have missing references to fragments or images. So if you notice Mobile Form is taking way too much time, then please check the server logs if there are missing reference warning.

Another reason for ignoring artifacts for cache is the size of the object. In fact, one can configure the maximum size of the object that is to be cached. Please refer to Mobile Form Configuration post for more details.

The Mobile Form admin should configure the Cache size and max object size based on the requirements. We have test data that shows cached rendering is as much as 1000 times faster than non cached rendering. So please make sure all your important forms are using cache.

Mobile Form upscaling

Mobile Form rendition of an XFA form is almost similar to PDF Form rendition in terms of behavior and appearance. Some of the dissimilarities are discussed in Mobile Form Vs PDF Form post. In this post, I’ll discuss one key difference that a form designer should take care while designing the XFA Template and that is where it is so critical to preview your templates from the designer itself.

Browsers or any screen presentation application for that matter translates all the measurements to pixels as screen can only understand pixels. So if you specify a text in html to be “10 pt (points)” it will be  calculated to pixels and then rendered on the screen. Point or any measurement unit conversion to Pixel is not exact science. It depends on various environment parameters like OS, screen resolution of the device etc. Yet, there is a very good approximation for that conversion and that is 1 inch = 72 points = 96 pixels.

If Mobile Form adheres to the standard approximation then one can see the same pixel perfect rendition of the form on PDF, Browser and Designer. We ran few heuristics across all the browsers and devices and it turns out that if we follow the standard scale we might loose on fidelity side due to differences in the imaging model of browsers and PDF.

For example, the default width of borders around the field or any line is “0.0069 inch”, if you design a form using LiveCycle Designer, which is co-incidentally also the most frequently used border thickness. If Mobile Form follow the standard scale that is “96 pixels” for “1 inch”, then this thickness would translate into “0.6624 pixels”. PDF imaging model is sophisticated enough to handle such subpixel sizes. The detail on how it does is beyond the scope of this document. But the browsers ignore anything less than a pixel. So following standard scale will result into no boders or lines in most of the forms.

While conceptualizing the Mobile Form, the main idea was to enable form filling on the browsers rather than matching the pixel perfectness of the PDF. So Mobile Form upscales the form rendition to make “0.0069 inch” thick borders visible. It uses “1 inch = 72 points = 144 pixels“. At this scale the thickness turns out to be close to 1 pixel and that makes all the browsers happy.

Upscaling by 150% has its own side effects that the form designer should be careful of. Here is the two screenshots of the forms (posted at Adobe Forums) in pdf and in html. You can see the effect of scaling in Mobile Form.

Upscale

Since Mobile Form is upscaling everything, you should check your text sizes so they don’t look not too big after upscaling. Another thing to note is image, since Mobile Form upscale it by 150% just make sure its picture quality remains good enough.

 

Access Metadata from XDP

In this post, I’ll address a use case where in profile you want to access data from the rendered form. Sometimes, you might want to access metadata associated with the form. You can add metadata to the form using the Form Properties option of the File menu in LiveCycle Designer.
form_prop1

 

You can add title, description and also custom properties like shown in the picture below. This meta data makes your form more accessible as this info is read by screen readers also. More info on designing accessible forms can be found at Accessible Mobile Form.

form_prop_diag

 

Title specified in this data will appear in the title bar of the Adobe Reader when you open the pdf form. If you want to show the title in Html Form, you can leverage the FormBridge APIs to retrieve the form data.

1
2
3
4
5
6
7
8
9
10
$(function(){
    window.formBridge.connect(
        function(){
            var titleResult = window.formBridge.getFieldProperties("xfa.form..desc.title","value");            if(titleResult &amp;&amp; !titleResult.errors &amp;&amp; titleResult.data &amp;&amp; titleResult.data[0]){
                $(document).attr('title', titleResult.data[0]);
            }
        }
    );
});

XFA Form stores all the metadata associated with the form in <desc> element of the root level subform. Since the name of your root level subform can be different for all the forms, you are rendering with a profile, you have to use a form independent SOM expression. That is why at line 4 of the script, you can see the double dot notation.
In the similar way you can extract any meta data present in the form and use it in html form.

Hide template reference

In this post I will describe how one can you pass template reference without using request parameter. The default profile of Mobile Form takes all the parameters like template reference, data reference etc through HTTP request parameter. If Mobile Form is deployed to serve the forms on internet then you might not like to expose such URLs on public forums. That is probably because it would expose the internal repository structure to the end user.
With the default profile, a form url would like http://<lcserver>:<port>/lc/content/xfaforms/profiles/test.html?contentRoot=repository:///Applications/FormSubmission/1.0&template=SimpleForm.xdp. This link contains the template reference present in your LC repository which you might not like to expose. In this post, I will cover how you can create a new profile to cope up with this problem.

Creating a new Mobile Form profile is very similar to creating a new resource and resource renderer i.e. to create a sling script and a jcr content node if required. I created a sample application package. You can install  the package using http://<lcserver>:<port>/lc/crx/packmgr/index.jsp UI.

Now go to http://<lcserver>:<port>/lc/crx/de page (CRXDE Lite).  Browse the content node and you would notice nodes like following:

profile1

 

A sling:folder node form, then nt:unstructured node leave and template. Mobile Form rendition service, an OSGi service reponsible for generating html5 snippet for the xdp, can also take input from a template child node of the profile node which is leave in this case. If you select profile node leave in crxde lite, you notice the properties of this node like the following:

 

 

profile3

 

You would notice one of the properties on the profile node is sling:resourceSuperType which is xfaforms/profile in this case. This is the property that makes any node Mobile Form profile node. This suggests sling to pass on the http requests to this node via profile renderer scripts which is profile jsp in Mobile Form context.

Mobile Form profile jsp page usually takes input from the request parameter but that is not the only way to pass parameters. For example to pass template info to profile jsp, you can create a child node named template in profile node hierarchy and specify template reference like the following:

profile2

 

Using the child template node you can hide the template information from URL of the form. The new URL would be  http://<lcserver>:<port>/lc/content/forms/leave.html without any refresh to the template location.

 

Decoding Mobile Form Html

Mobile Form generates html snippet from XDP template designed from LiveCycle Designer. In this post, we will decode the internal structure of the generated html snippet. Once you are familiar with the html structure, you can customize it at will.

Generally, Mobile Form generates an html <div> element for every object of XFA form maintaining the same hierarchical structure. Here is the html snippet source of the xfa form and the red lines shows the 1-1 mapping between xfa objects and html.

xh

As mentioned earlier, for each xfa object, Mobile Form will have a corresponding div. Every div has, in general, 4 attributes:

  1. class: This is the attribute that should be used for customization. Mobile Form generates many different class selectors based on the various attributes of XFA object. One can use these class selectors to specify styles on the objects.
  2. id: This is for internal usage. There is no guarantee for getting same id all the time. Anybody shouldn’t use it for customization.
  3. style: This is again for internal usage. XFA form specific layout styles are applied on the element using this attribute.
  4. data-xfamodel: This is again for internal usage. Mobile Form keeps xfa form specific data in this data attribute. One should not temper with this to ensure smooth processing.

All set for customizing the individual html elements of Mobile Form, well, you need to know what all class selectors are applied on each div element. Mobile Form first adds a class for type of objects like subform, field, draw, area etc, then subtype of object like if it a field then what type of field: textfield, choicelist etc then the name of the object. You will find these 3 class selectors on each and every html div element corresponding to XFA objects. Here is the complete list:

XFA Object Class Selectors in Html div
Button field, buttonfield
Check Box field, checkboxfield
Circle draw, arc
Content Area contentarea
Date Field field, datefield
Date/Time Field field, datetimefield
Decimal Field field, numericfield
Drop-down List field, choicelistfield
Email Submit Button field, buttonfield
Image Field field, imagefield
HTTP Submit Button field, buttonfield
Image draw, image
Line draw, line
List Box field, choicelistfield
Numeric Field field, numericfield
Password Field field, passwordfield
Print Button field, buttonfield
Radio Button field, radiofield
Rectangle draw, rectangle
Reset Button field, buttonfield
Signature Field field, signaturefield
Subform subform
Table subform
Text Field field, textfield
Text draw, text
Time Field field, timefield

Besides the above class selectors, Mobile Form adds the name of the object as a class selector also. This is very useful if you want to apply some customizations to a particular field or draw element.

I will now backup a bit and describe how Mobile Form generates an html form from an XFA Form.
The initial html snippet generated by Mobile Form looks like the following with all the jsp variables <%=@@variables@@%> expanded into encoded html strings, as soon as you open any form in the browser:

1
2
3
4
5
6
7
8
9
10
11
<form id="lcforms_xfaform_container" action="/lc/content/xfaforms/submission/default" enctype="application/x-www-form-urlencoded" method="post" target="_self">
<div class="formLoading" id="formLoadingDiv" data-xfadom="&lt;%=formDom%&gt;" data-xfahtmldom="&lt;%=firstpagedom%&gt;" data-xfaresthtmldom="&lt;%=resthtmldom%&gt;" data-xfahiddenobjdom="&lt;%=hiddenObjDom%&gt;" data-xfamergeddom="&lt;%=mergedFormDom%&gt;" data-xfalocaleset="&lt;%=localeset%&gt;" data-internalcss="&lt;%=internalcss%&gt;" data-xfarendercontext="&lt;%=renderContext%&gt;">
 
Loading...
 
<script type="text/javascript">
_initializeXfaLoading();
</script>
 
</div>
</form>

Here formAction is the submitUrl specified in the request parameter. For detail on the request parameters refer Mobile Form. The <div> at line 2 contains all the data required to show a form. The _initializeXfaLoading() method of xfa runtime javascript generates the actual form while loading which will look like following:

1
2
3
<form id="lcforms_xfaform_container" enctype="application/x-www-form-urlencoded" method="post" target="_self">
<div class="xfaform form1" role="form" data-xfamodel="{}"><!-- form content goes here --></div>
</form>

Now let’s see how Mobile Form represents individual XFA Objects into Html objects.
For draw elements, Mobile Form uses SVG.
The text objects are represented using SVG Text. We don’t use html text because the layout generated by the html text doesn’t really match up to the text layout by XFA. SVG Text gives more control to the author by not doing auto layout. The “text” element of SVG has textLength attribute that gives finer control over the length of the text object. SVG is the primary reason why Mobile Form looks closer to PDF Form. Similarly line, arc and rectancle are represented by SVG only. Only The image object is represented using html5 <img>.

XFA Field object is wrapped in one html <div> that contains two different <div>, one each for caption and widget, something like the following:

1
2
3
4
<div class="field textfield TextField1" id="_15" data-xfamodel="">
<div class="caption" role="presentation" data-xfamodel=""><svg> Text Field </svg></div>
<div class="widget textfieldwidget" data-xfamodel=""><input type="text" /></div>
</div>

Field caption is represented in SVG just like the draw text object whereas the field widget, the interactive area or the area where user can click and fill the data, is represented using html5 <input>. If caption is not present on the field, Mobile Form not only omits the caption div but also merge widget div and field div. Every div has a performance cost while loading the page or interacting with it. So in order to optimize the user experience, we merge div elements. For Date Field and List Box, Mobile Form uses javascript widgets to match up to widgets in PDF Form.

Mobile Form profile

Mobile Form enables LiveCycle XFA forms on mobile devices. It does it by rendering XFA Form to Html5 document.

As per Sling website, Apache Sling is a web framework that uses a Java Content Repository, such as Apache Jackrabbit, to store and manage content. Sling applications use either scripts or Java servlets, selected based on simple name conventions, to process HTTP requests in a RESTful way.

Mobile Form has a service that generates HTML snippet from XFA form. That html snippet, along with the xfaform css and js, can be embedded into any web page using the sling constructs like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<%@ page session="false" %>
<%@taglib prefix="sling" uri="http://sling.apache.org/taglibs/sling/1.0"%>
<%@taglib prefix="cq" uri="http://www.day.com/taglibs/cq/1.0" %>
 
<%
    String locale = "en_US";
    request.setAttribute("xfaLocale",locale.replace("_",""));
%>
<!DOCTYPE html>
<html>
       <head>
               <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
               <meta charset="UTF-8">
               <cq:includeClientLib categories="xfaforms.I18N.${xfaLocale}" />
               <cq:includeClientLib categories="xfaforms.runtime" />
       </head>
       <body id="formBody">
            <sling:include resourceType="xfaforms/render"/>
       </body>
</html>

Pause and take a look at the highlighted lines 14,15 and 18. Rest of the stuff is pretty standard sling jsp script. We use the recommended practice for including client side libraries. The first includeClientLib is for including the locale specific messages you can modify the xfaLocale parameter to control it where as the other includeClientLib is for including the XFA Runtime.

Sling include @ line 18 is responsible for the html snippet, I mentioned earlier. You can create you page and just add these lines to include client side libs and html snippet to get the form running.

We call the content node and the sling script, responsible for rendering form embedded in web page, Html profile. We call it so because, profile dictates how a form should look like and how it behaves. That means one needs to play with the profile for all the customization required in the form. Mobile Form leaves a lot of hooks in the generated html snippet in order to help the customization.

Mobile Form data submission

Mobile Form is a form after all, a way to capture user data at the end of the day. Once you got the data from users, you want to feed that data for further business processing.  If you see my first post on mobile forms you would notice there is a API parameter submitUrl that can be of help here. You can configure your Mobile Form to post data in xml format to your service on submission of the forms. Since you can invoke any LiveCycle process or service RESTfully, you can technically trigger a process on form submission. In this post, I’ll describe how to trigger a process on form submission in detail. You can follow the same approach to POST the form data to any service.

All LiveCycle processes can be configured to be invoked over REST endpoint. You can create a process in your application and configure it for default start point. You can create a process to have input and output variable.

Mobile Form posts data to the specified submitUrl via data request parameter. If you don’t specify custom any “submitUrl”, the default submission servlet will show you the data in your browser. You can easily customize the default submission servlet and send data for further processing.

You can download custom submission servlet package from here and install it via package manager by browsing http://<server>:<port>/lc/crx/packmgr. For details see package manager help.

Now download the FormSubmission LiveCycle process and import it following the instructions. You can create your own process as well. The important part is to get the REST url of the process. The rest url of the process turns out to be http://localhost:8080/rest/services/<ApplicationName>/<ProcessName>:1.0 as shown in the screenshot of workbench.

process1

 

If you hit the REST url in the browser, it will ask for credentials of a user that can run this service or process. You can also disable the authentication required for running this process, for details look for adobe help.

http://localhost:8080/lc/content/xfaforms/profiles/default.html with the following parameters:

  • contentRoot repository:///Applications/FormSubmission/1.0
  • template=SimpleForm.xdp
  • submitUrl=Encode the URL and then pass(http://localhost:8080/lc/content/xfaforms/submission/default.lcprocess?postProcess=http://localhost:8080/rest/services/FormSubmission/archiveForm:1.0)

 

As you can see, the submitUrl is pointing to the custom servlet with a request parameter “postProcess” where custom servlet further posts data. The “postProcess” service could be any other servlet but in this case it is the REST url of the LiveCycle process.

The attached form in the Form Submission collateral has just two fields and the “archiveProcess” creates a flat pdf  from the submitted data. You can test the form by rendering it and when you submit the form, it triggers the LiveCycle process and generate pdf out of it and serve it in the browser.

 

 

 

Mobile Forms: LiveCycle Designer way

You want to quickly test your designed form on how it would look like as Mobile Form, you can do it right from the livecycle designer without any other application. You first need to point your designer to use an LiveCycle ES4 server. You can configure it in LiveCycle Designer menu Tools->Options->Server Options like the following:

designer_preview

 

 

Now open an existing form or a new form in the LC designer, you would notice a tab HTML Preview near by Design View, Master Pages and Preview PDF. If you cannot see that tab don’t worry just locate HTML Preview in the view menu option and enable it. When you click on the HTML Preview tab, you would see the html preview of the currently opened form in the designer.

HTML_PREVIEW

 

 

See how easy it is to preview html forms while designing it. This will speed up the development of the form as one can preview both PDF as well as HTML right from the designer itself. In the next post I’ll share how one can test templates outside of the designer and in the browser.

Accessible Mobile form

An accessible form is one that a wide range of people can use, including those who may have disabilities that affect how they are able to interact with the form on the computer screen. For example, the form user may have a visual impairment or reduced mobility.

Mobile form uses ARIA html5 accessibility standard to support a number of features and capabilities that enhance the usability of forms for users with a range of disabilities, and assist form authors and create forms that are more accessible to people with disabilities.

When you design forms for a wide audience, you should consider that some users may have disabilities that affect how they interact with the form. Some users may have vision impairment, reduced mobility, or other disabilities. To accommodate the needs of all users, you may find it worthwhile to include certain practical design features in your forms and to test forms using various assistive technologies.

Setting a meaningful tabbing order is very important when designing forms that are accessible to users with vision impairment or users with disabilities. These users typically do not use a mouse to navigate through a form, so they depend on the keyboard. A logical tabbing order sequence ensures that they have full access to all the fields on the form and that they can navigate the form in a way that is sensible and efficient. Screen readers and other assistive technology also make use of the tabbing order.

In order to access spoken information about a form, users with vision impairment need to use a screen reader. Screen readers speak information about where the cursor is located on the form. As the form author, you must specify the text for the screen reader to read.

To provide an accessible form, you need to understand how screen readers work. You also need to know how to use the Designer Accessibility palette to specify information that the screen reader will speak for the objects on forms. Keep in mind these considerations related to implementing accessible forms that can support screen readers:

  • Establish a logical tabbing order that includes all fields and buttons. Setting the tabbing order is important because screen reader tags are ordered top-to-bottom, left-to-right. The screen reader will generally read through an entire page, including any boilerplate objects. When the user begins to tab through the form, the screen reader reads text for each field as it becomes active.
  • Announce the names of buttons and fields, as well as their purpose.
  • Users cannot tab into protected fields. Calculation fields, such as a field that totals values entered in other fields, are an example of a protected field. For the screen reader to read the value of a protected field, you can place an empty Read Only field either on top of or next to the protected field to speak the value of the protected field.

LiveCycle ES Designer includes a number of options that support screen readers. For each object in a form, you can specify one of several settings for the screen reader text:

  • Custom screen reader text, which you set in the Accessibility palette.
  • Tooltips for objects on the finished form, which you set in the Accessibility palette.
  • Captions for fields on the form.
  • Names of objects, as specified in the Name option of the Binding tab.

accessibility
Only one setting is spoken for a single object. The screen reader searches for the presence of these settings to determine what is spoken. The default search order is Custom Text, Tooltip, Caption, and Name. When the screen reader finds one of these options, it speaks that text. You can override this default order using the Screen Reader Precedence option in the Accessibility palette.