Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

Introduction

The UltraCart engine is a Java based checkout using a custom form processor.  We mention that because it's different from many popular templating systems.   As such, there will be some unfamiliar ways of naming form elements as well as some additional things a template form must do to make everything run smoothly.   The system is nearly two decades old, battle hardened, and lightning fast.   So, we apologize for the learning curve, but we trust you'll be able to overcome it with enough examples.

 

Simple Fields

For simple fields, name the form element the same as the $form property.   Use the $! notation to fill in the value of the form element.

Example: $form.address1

<input type='text' name='address1' value='$!form.address1' />   <!-- there's something wrong here... -->

You should use $!form.address1 instead of $form.address1.   The exclamation point instructs the renderer to output an empty string if the variable doesn't exist or is null.  It's a clean way to say "if there is a value, write it out".

The above example is suspect to cross-site scripting attacks. Whenever you output a variable in a template, you should consider whether that output should be html escaped.

The proper way to render the input field above is this:

<input type='text' name='address1' value='$i18n.escape($!form.address1)' />   <!-- this is safe. -->

The I18nWriter will escape any html properly to avoid attacks or page breakage.

 

Hidden Example

<input type='text' name='merchantId' value='$i18n.escape($!form.merchantId)' />


Checkbox Example

<input type="checkbox" name="mailingList" #if($form.mailingList)checked#{end}/>

The checkbox requires the checked attribute to be true, but must omit it completely for false.  The clean way to handle that is using an inline-if statement.

 

Textarea Example

<textarea id="comments" name="comments">$i18n.escape($!form.comments)</textarea>

 

Select Example

The select is more complex, because it will usually need a list of options.   Those options need to be iterated and the current option properly flagged with the selected attribute.

<select name="creditCardExpMonth">
 #foreach($expMonth in $form.creditCardExpMonths)
  <option value="$expMonth.value" #if(${formatHelper.equalsIgnoreCase($expMonth.value, $form.creditCardExpMonth)})selected#{end} >
   ## the first blank value should read 'Month' to help customers understand what this field is.
   #if ($expMonth.value == "")
    Month
    #else
    $expMonth.description
   #end
  </option>
 #end
</select>

 

 

Complex Fields

Complex fields extend the dot notation as far as needed to dive down into the object hierarchy.  Realistically, few of the UltraCart system forms extend below two levels.  When displaying and collecting a value from a nested object, fully reference the object and the engine will do the rest.

<input type='text' name='address.phone.mobile' value='$i18n.escape($!form.address.phone.mobile)' /> 

Working with collections of fields

In traditional http parameters, array fields all have the same name.

For example:

<input type='text' name='notifications' value='sms' /> 

<input type='text' name='notifications' value='email' /> 

<input type='text' name='notifications' value='chat' /> 

and the resulting url would be ?notifications=sms&notifications=email&notifications=chat

The big difference between traditional http cgi and the UltraCart engine is that the UltraCart engine treats all arrays as arrays of objects. To manage this, each array must provide its ordinal position.

 

 

 

  • No labels