Forms: The Unsung Hero of WebCenter Content

By: Dwayne Parkinson - Solution Architect
& Dan Stitely - Application Consultant

We Don’t Need Forms!

Most IT folks don’t like to admit it, but we all have a little chip on our shoulder.  We all like solutions that have some sizzle.  Dealing with mundane things like forms processing is something we would rather leave to someone else.  Yet, in most businesses there exists an often overlooked mountain of inefficient effort around the daily collecting of information from someone about something.  Whether its warranty information from a consumer, open enrollment information for employee benefits or order information for a brand X widget, the need is always there.  I’ll bet if you think about it, your company has its very own mountain of “forms opportunity” just waiting to be explored.

From an IT perspective, this mountain of forms opportunity has been historically challenging because each form required the creation of database tables along with computer applications to perform create, read, update and delete actions and of course there are the security, search and maintenance issues.  In other words, it’s a lot of mundane IT work that really doesn’t have much sizzle.

Most companies try to address their mountain of forms processing opportunities in one of three ways: through an inadequate department level solution whipped up in office productivity software, by building mountains of custom applications or in some cases an entire “forms solution” is purchased just to handle forms processing for a company.

Thankfully, WebCenter Content comes to the rescue yet again with a very powerful forms processing capability!  Built right into WebCenter Content is an extremely powerful feature that simplifies forms processing and provides another way to leverage your WebCenter investment and add even more value to your business.

OK, I guess we could use forms.  How do they work?

Forms are a beautiful thing in WebCenter Content, but the details are buried deep in the Oracle documentation under the somewhat odd heading of Dynamic Server Pages.

http://docs.oracle.com/cd/E23943_01/doc.1111/e10807/c04_dyn_server_pages.htm

A form is a special HTML file created and checked into the WebCenter Content server with an extension of HCSF.  The file is very similar to a standard HTML form you’d find on any web page, but there are a few WebCenter Content specific hooks to make everything work and developers have the ability to use Idoc Script to customize the form behavior in addition to JavaScript.

Once the HCSF file is checked into the WebCenter Content server it serves as a template for form entry.  When someone “opens” the HCSF file, they will be presented with a form that is based on the HCSF file.  However, once the form is filled out and submitted, WebCenter Content server takes over and the real magic happens.

When an HCSF form is submitted WebCenter Content creates a copy of the HCSF file with an extension of HCSP and checks it in as a new content item.  The HCSP file is a unique instance of the HCSF form template and the new file contains all of the form fields and validation code that the HCSF had, but it also contains data that was supplied to fill in the form.  Every time the HCSF form is opened, filled in and submitted another HCSP file shows up in your content server.  When submitted, the HCSP respects all WebCenter Content security as well as content profile rules including validation!

A Little Planning Goes a Long Way

Rather than dive right in and build a form, it helps to stop and think about what’s going on and how you can leverage the technology.  From a programming perspective forms not only isolate design from functionality, but they also isolate database activity from functionality.  In other words, there’s no need to design specific tables and the associated create, read, update and delete functions!

Step 1:  Define the Searchable Fields

When designing forms one of the first things you must do is identify the form fields needed and then figure out which form fields must be searchable.  Those searchable fields should be created as new metadata fields.  Fields that won’t be searched won’t need an associated metadata field because that information will be stored in a special data section of the form.

In the example below we have a simple form which collects information about a state.  This example assumes that we need to search by state, but we rarely or never search by the source of information.  As a result, State has been added as a metadata field while the information source is stored in the form itself.

Step 2: Build the HCSF form template

In general each form template will include two significant parts: the data section and the design elements.  It’s important that the design elements are externalized via the use of includes.  For example, here is the entire HCSF for our sample form.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html lang="en" dir="ltr">

<head>

<!-- ----------------------------------------------------------------------------------------------------

Sample HCSF State Information Form

Copyright TEAM Informatics 2013

------------------------------------------------------------------------------------------------------ -->

<title>Sample Form Contribution</title>

<!--$docLoadResourceIncludes("dDocName=form_includes&amp;RevisionSelectionMethod=Latest")-->

<!--$include Contribution_Common_Header-->

<!--$idcbegindata-->

<idcformrules/>

<fInfoSource></fInfoSource>

<!--$idcenddata-->

</head>

<!--$include State_Info_Contribution_Body-->

<!--$include Contribution_Common_Footer-->

</body>

</html>

Notice that we have three includes: header, body and footer and that only the body is specific to this form.  The header and footer are common to all forms.  Obviously you could make as many includes as you need and have multiple headers, sub-headers or whatever is necessary, but the point is to make sure you externalize these things.  The reason for this is because all of the code in the form along with the data in the data section is checked in as a separate HCSP content item each time a new form is filled out.  So you may have thousands of instances of your original HCSF form checked into your content server as separate HCSP files.  By using includes as we have done, a year from now when it’s time to change the layout of the form or add another field you simply change the includes and all of the checked-in forms will inherit the updates whenever they are accessed.  If the form design is coded directly into the HCSF rather than using includes, any changes to the form will require updating each and every HCSP file independently.

The keys to the second step are defining what your standard form areas will be (header, footer, etc) and then defining which data should be stored in each of your forms vs. the data that will be stored as metadata (i.e. searchable).  Notice there is no reference to metadata even though our form is already complete and can be checked in.  When checking in the form it’s a good idea to have a separate document type so the forms are easy to find later.

Step 3:  Build the include file for your forms.

You probably noticed the docLoadResourceIncludes statement.  We’re storing all of our includes in a text file called form_includes which is checked in with the dDocName form_includes assigned.  Separating the form design elements into the includes file is a simple way to separate content from design in a forms implementation.  The entire form_includes is shown below and we will touch on the most significant parts starting from the bottom and working our way up.

[[% ----------------------------------------------------------------------------------------------------

TEAM Informatics Sample HSCF Contribution Form iDoc Includes.

Copyright TEAM Informatics 2013

------------------------------------------------------------------------------------------------------ %]]

[[% ------ Begin Common Includes ------ %]]

<@dynamichtml Contribution_Common_Header@>

<$include std_checkin_html_head_declarations$>

<style type="text/css">

table.layout td{padding-right: 15px;}

.idcFieldCaption {text-align:left; width: 135px;}

.fontNormal {}

</style>

[[% These actions get run during sumbit so good place for validation of fields.

Push functions to the sumbitActions array and return true to move to the next function

or false to prevent the form sumbitting to WCC %]]

<script type="text/javascript">

var isReadOnly = <$if isTrue(isReadOnly)$>true<$else$>false<$endif$>;

var submitActions = [];

function doSubmitActions(form){

for (var i=0;i<submitActions.length;i++){

var action=submitActions[i];

try{

var success=action();

if(!success){

return false;

}

}catch(err){

//do nothing, try next action

}

}

}

</script>

<@end@>

<@dynamichtml Contribution_Common_Body_Def@>

<$include body_def$>

<$include std_page_begin$>

<$include std_header$>

<@end@>

<@dynamichtml Contribution_Common_Form_Begin@>

<form name="Checkin" method="POST" action="<$HttpCgiPath$>" onSubmit="return doSubmitActions(this);" id="hcsf" >

<input type="hidden" name="IdcService" value="SUBMIT_HTML_FORM">

<input type="hidden" name="idcToken" value="<$idcToken$>">

<input type="hidden" name="dID" value="<$SourceID$>">

<input type="hidden" name="dSecurityGroup" value="Public">

<input type="hidden" name="xIdcProfile" value="<$formDocType$>">

<@end@>

<@dynamichtml Contribution_Common_Form_End@>

</form>

<@end@>

<@dynamichtml Contribution_Common_Footer@>

<$include std_page_end$>

<@end@>

[[% ------ End Common Includes ------ %]]

[[% ------ Begin Standard Form Field Definitions ------ %]]

<@dynamichtml std_form_field@>

<$if fieldCaption$>

<$m_fieldCaption = fieldCaption$>

<$endif$>

<$ret = rsFirst("DocMetaDefinition")$>

<$loop DocMetaDefinition$>

<$if strEquals(DocMetaDefinition.dName, fieldName)$>

<$include std_meta_field_display$>

<$break$>

<$endif$>

<$endloop$>

<$m_fieldCaption = ""$>

<$include clear_field_vars$>

<@end@>

[[%  fieldCaption, fieldName, fieldId, fieldValue%]]

<@dynamichtml std_form_input@>

<tr id="<$fieldName$>_row">

<td class="idcFieldCaption"><span id="<$fieldName$>_caption" class="tableEntry"><$fieldCaption$></span></td>

<td><input name="<$fieldName$>" id="<$fieldId$>" size="65" value="<$fieldValue$>"></td>

</tr>

<$include clear_field_vars$>

<@end@>

[[%  fieldCaption, fieldName, fieldId, fieldValue%]]

<@dynamichtml std_form_date_input@>

<tr id="<$fieldName$>_row">

<td class="idcFieldCaption"><span id="<$fieldName$>_caption" class="tableEntry"><$fieldCaption$></span></td>

<td>

<$fieldType="Date",fieldEditWidth="18", fieldId=fieldName$>

<$include std_edit_entry$>

</td>

</tr>

<$include clear_field_vars$>

<@end@>

<@dynamichtml std_form_text_input@>

<tr id="<$fieldName$>_row">

<td class="idcFieldCaption"><span id="<$fieldName$>_caption" class="tableEntry"><$fieldCaption$></span></td>

<td>

<$fieldType="Text",fieldEditWidth="18", fieldId=fieldName$>

<$include std_edit_entry$>

</td>

</tr>

<$include clear_field_vars$>

<@end@>

<@dynamichtml clear_field_vars@>

<$fieldCaption="", fieldId="", fieldName="", fieldType="", fieldValue="", fieldColumns="", fieldRows=""$>

<@end@>

[[% ------ End Standard Form Field Definitions ------ %]]

[[% ------ Begin Field Definition Includes ------ %]]

<@dynamichtml field_formDisplayTitle@>

<tr id="formDisplayTitle_row">

<td colspan="2"><span style="color:orange; font-size:16px; font-weight:bold;"><$formDisplayTitle$></span></td>

</tr>

<@end@>

<@dynamichtml field_dDocTitle@>

<$fieldCaption="Title", fieldName="dDocTitle", fieldValue=dDocTitle$>

<$include std_form_text_input$>

<@end@>

<@dynamichtml field_dInDate@>

<$fieldCaption="Release Date", fieldName="dInDate", fieldValue=dInDate$>

<$include std_form_date_input$>

<@end@>

<@dynamichtml field_fInfoSource@>

<$fieldCaption="Source Of Information", fieldName="fInfoSource", fieldValue=fInfoSource$>

<$include std_form_input$>

<@end@>

<@dynamichtml field_xState@>

<$fieldName="xState", fieldValue=xState$>

<$include std_form_field$>

<@end@>

<@dynamichtml field_xSubType@>

<$fieldName="xSubType", fieldValue=xSubType$>

<$include std_form_field$>

<@end@>

<@dynamichtml field_xComments@>

<$fieldName="xComments", fieldColumns="100", fieldRows="3",fieldValue=xComments$>

<$include std_form_field$>

<@end@>

<@dynamichtml field_Buttons@>

<tr id="fieldButtons_row">

<td colspan="2">

<input type="submit" value="Submit">

</td>

</tr>

<@end@>

[[% ------ End Field Definition Includes ------ %]]

[[% ------ Begin State Information Form Body ------ %]]

<@dynamichtml State_Info_Contribution_Body@>

<$formDisplayTitle="State Information Form"$>

<$formDocType="Document"$>

<$include Contribution_Common_Body_Def$>

<$include Contribution_Common_Form_Begin$>

<input type="hidden" name="xSubType" value="Other" >

<table align="left" class="contribution" >

<$include field_formDisplayTitle$>

<$include field_xState$>

<$include field_dDocTitle$>

<$include field_fInfoSource$>

<$include field_dInDate$>

<$include field_xComments$>

<$include field_Buttons$>

</table>

<$include Contribution_Common_Form_End$>

<@end@>

[[% ------ End State Information Form Body ------ %]]

1)      State Information Form

1. This section accounts for the entire State Information Form.  As you add more forms to your implementation, you will add more sections like this one.
2. Notice that the include for the state information form heavily relies on other includes.  In particular each field that is used is another include.  The reason for this is because there will likely be many forms and this makes including fields very simple without the need to have the same set of code repeated for each form.
3. xSubType is a Hidden field but is getting set.  This can be very useful for searching.

2)      Field Definition Includes Section

1. This is the section where we define the fields that will be used on the form.  We create one include for each field we will need.
2. Notice that we’re referencing more includes based on the type of field.
3. Notice the metadata fields are slightly different than form fields in that they use different includes.

3)      Standard Form Definition Fields

1. This section defines the different type of fields our forms will use.  For example many forms will have a date input somewhere so it makes sense to have a standard date input field definition.
2. Std_Form_Field is a little tricky because it loops through metadata to find a matching field and then applies a common form layout.  This eliminates the need for creating entries for each and every metadata field.

4)      Common Includes

1. Notice the information being set in the Contribution_Common_Form section.
2. We used very simple styling but it’s likely that you will have an extensive CSS to include.

Step 4: Make It All Work

Check in the HCSF and the includes file.  Be sure to make the includes file dDocName match the value in your HCSF include (in our case FORM_INCLUDES).  Once both are checked in you should have something like this in your content system.

If you click on the FORM_SAMPLE the content server magically serves up a form that looks like this.

Notice that the Title says FORM_SAMPLE.  For now we’ll just clear that value out, fill in some values for our form and submit them.

Now when the content item is submitted you’ll notice that there’s a new content item on your server.

If you click on that content item you will see that it brings up the form again, but if you notice it’s not an HCSF, it’s an HCSP document.  In other words, this is no longer your form template, it’s a separate instance of the form.

Now if you were to go to the content information for this item and download the native HCSP file you will see that it looks exactly like our HCSF except that it has a value for the fInfoSource tag.  The other values on the form are all stored in metadata.

Next Steps & Pitfalls

As you can see, it doesn’t take much to get a basic form working without having to worry about creating tables, search, security and validation; however there is more work to be done.  For example, code needs to be added so the document title is cleared out when the system is rendering the HCSF but not when it’s rendering the HCSP.  That way we won’t see FORM_SAMPLE when we click on the HCSF.  There are also profiles to be set up, rules to be created and a host of other considerations to addressed.

Alas, it’s not all milk and honey in the land of forms.  There are some rather irritating little pitfalls.  One of those pitfalls is that forms aren’t actually checked-out or checked-in like normal content items.  It’s possible for two people to update the same form simultaneously!  Also, there is the issue of validation.  While it’s great to use profiles and rules or the base field definitions, the user experience is less than pleasant if they must submit a form and then find out that a field is required.  What’s even less pleasant is when the user presses the back button and finds out that all the information they typed in is now wiped out due to an odd browser quirk.  Beyond that there are quirks and bugs with drop downs and DCL’s but all of this can be overcome relatively quickly.

Thankfully you don’t have to be a forms pioneer and take the arrows on your own.  The ultra talented folks who developed this unique enterprise forms approach using WebCenter Content are here to help you too.  Whether you would like an SME to review your project and point out the potential issues based on past experience or you need a full project team to go from inception to implementation, TEAM Informatics has some incredible people who can make it happen for you.

Conclusion

Henry David Thoreau was famously quoted as saying “Our life is frittered away by detail.  Simplify, simplify, simplify!”  Stop frittering away that forms opportunity because of the overwhelming details involved!  Oracle has done a great job of delivering a forms solution which simplifies much of the work associated with forms processing.  By extending the examples above, you will be able to simplify your enterprise forms implementation and finally realize the benefits that are waiting for you somewhere in that mountain of forms opportunities.

If you would like to learn more about the power of WebCenter and a forms solution, contact us!