Customer Portal

Get Involved. Join the Conversation.


    Lawrence Morrisroe
    Best Practices for CP: How do I simplify my Ask a Question...
    Topic posted September 18, 2014 by Lawrence MorrisroeBlue Ribbon: 750+ Points 
    1034 Views, 2 Comments
    Best Practices for CP: How do I simplify my Ask a Question pages?

    Great web service is a delicate balancing act. You have to keep the experience simple enough that anyone can use it, but you also need to make sure that you get the information you need as a business to get the end-customer to resolution as quickly as possible. Everyone loves fast, right? Of course they do! 

    That tricky balancing act is particularly evident on Ask a Question pages. While you may want the user to fill out a ton of information, not all fields may be relevant for every inquiry. How do you slim down the complexity to make sure that customers don't take one look at your high falutin' mega-form, abandon out of the web experience altogether and pick up the phone? Well, dynamic forms are one solution to long complex web forms, and in this How To? conversation we show you how easy building a simple dynamic form is as long as you aren't afraid of making some markup changes in your Customer Portal pages. 
    Let’s first discuss what is a Dynamic Form? Well, A dynamic form is a form with fields that change depending on selections in other fields. For example, when a customer selects a certain product, you may want to ask for additional information that would not be relevant if the customer had selected a different product. A dynamic form identifies the customer-selected product and displays the additional fields for that product selection. 

    Historically, writing a dynamic form was pretty intensive work - prone to error and, in some cases, difficult to upgrade. For every 100 dynamic forms we reviewed on customer sites, we saw 100 different ways that they were built out, some being good and some being bad. How could we lower the bar in terms of effort and increase our ability to encourage best practices in form development & management? That was the task we set ourselves.

    With the introduction of Dynamic Forms capabilities for Customer Portal in February 2014, form management is now much more straightforward. Even better, any dynamic form you create is a snap for us to upgrade for you on your behalf. 

    Below we've illustrated the end-result. As you can see in step 1, the user is selecting an option from the drop down list. Upon selecting an item from the drop down, the form will dynamically update the form fields for both visible/hidden and required or not required. In Step 3 five new fields have appeared asking for additional information.
    Sounds great, right? but also sounds really  hard. Well, you'll be glad to know that it isn't, and even though it still takes some XML and basic programming skill to accomplish (so don't hand off this responsibility to your marketing intern!) , the technical requirements have been narrowed. You don't need to write widgets from scratch (but will likely need to use and  extend existing widgets), nor do you need to know AJAX or any other  buzzwords that the exclusive realm of the technocrati.
    Essentially what you do need to do is to  understand how your form should work, and what fields need to be hidden or displayed etc based on where the end-user is in the experience. If you can get that far at least then great. You can easily write the requirements for how your form works. If you don't have the technical skills to do the implementation work, the next key task is to find someone that does. 
    Task 1: (Non Technical)
    Write out the rules for your form in your favorite tool (Excel is certainly sufficient for this task), identifying all form fields that 'could be' present in your dynamic form. In succeeding columns, identify the nature of the field, whether the field is persistent or not, and if not, what are the conditions that apply for 'changing the field'. The conditions that we support in the dynamic forms capability are required, not required, hidden, visible or hidden This is a very similar task to your initial steps in defining the requirements for your workspaces within the tool.
    Transition to the Technical Stuff. How how does this work?
    Because creating traditional dynamic forms can be a complex coding task, the Customer Portal includes a change handler for the Field.js module (used by input widgets) in the Customer Portal JavaScript API. Input widgets subscribe to this change handler, which is called anytime the widget changes. When you want a widget for a dynamic form, you extend the corresponding standard input and override the onChange function. All input widgets have a hide_on_load attribute to let you hide forms that should appear only when the input value of another widget matches the condition you define.

    Although product selection is a primary use case for dynamic forms, the change handler is triggered by changes to any form field, not just products or categories. In addition to changing a field’s visibility, you can also change whether it is required based on a previous field. The setConstraints method indicates whether customers must add a value to the field.

    The general steps for creating a dynamic form include the following.
    1. Create a new widget by extending one of the following standard input widgets (DateInput, FileAttachmentUpload, MobileProductCategoryInput, PasswordInput, ProductCategoryInput, SelectionInput, or TextInput).
    2. Edit the widget you created so it subscribes to the change event handler.
    3. Use the findField method to retrieve the field that should change (the Incident.Product field in this example).
    4. Call the setContraints method with a JavaScript object (for example, constraint = {required:true}) to change the field.
    For an in depth look on how this is done check out our Code Sample:
    February 2014
    Code Snippet:



    • Bastiaan van der Kooij

      Hey Lawrence,

      good to see this functionality added, I think it would be nice if there was a way to target groups of fields as well instead of single fields only. This way you could define different versions of additional 'fields groups' at the bottom of the page and enable a group based on a category or product. Since many times customers have large sets of additional fields, but they appear only in a couple of unique variations. In the current setup if you have 50 categories and 20 additional fields you could end up with 1000 statements on the category field. Also having a default would be nice.

      By adding the ability to call 'groups' of form variations and the ability to comma seperate ID's of the cat / prod, the whole setup could be much easier in a lot of situations.

      Code could be then something like;

      <rn:widget path="input/DynamicProductCategoryInput"


      <rn:tag "Group.FormVariation1" type="start">
        <rn:widget path="input/FormInput" name="Field1">
        <rn:widget path="input/FormInput" name="Field2">
        <rn:widget path="input/FormInput" name="Field3">
      <rn:tag "Group.FormVariation2 type="end">


      <rn:tag "Group.FormVariation2" type="start">
        <rn:widget path="input/FormInput" name="Field3">
        <rn:widget path="input/FormInput" name="Field4">
        <rn:widget path="input/FormInput" name="Field5">
      <rn:tag "Group.FormVariation2 type="end">

      <rn:widget path="input/FormInput" name="Field6">


    • Isca Mfe


      How do you indicate that the product category is a mandatory field? I followed the codes provided and realised that when user click "submit" before selecting a product would create an incident; which is undesired.


      Thanks & Best Regards