• You cannot apply a conditional section to a rich area field.
• You can only apply a conditional section to a Smart Form configuration. You cannot apply a conditional section to Smart Form content created from a configuration. But, authors working that content see conditions
  —Image—

  

Validation

Validation ensures that the user completing an XML form enters the right type of data. You can decide if the user’s input should be a number, boolean, date, string, zip code, and so on. If you do not specify type attributes using validation data, the field is a string.

Validation is especially important when users search XML data, because it helps the search find the correct information. For example, if a field collects a zip code but you set its type to plain text, a user completing the form can insert anything into the field. If the user inserts the letter “o” instead of the number zero (0), the field accepts that input but the search will not find that record. On the other hand, if you set validation to zip code, the user can only insert 5 or 9 digits—any other entry is rejected.

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The Indexed field may or may not appear, depending on how your administrator has set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this field.
• Formula. Enter the calculation that this field will perform. See also: Using the Formula Field
• Select Field. Click this button to select a field to reference in the calculation.
• Examples. Click the down arrow next to this field to see sample calculations. If you select an example, it is copied into the Formula field. See also: Formula examples
• Validation. Select the kind of validation to apply to this field. Your choices are:
  • No validation. the user’s response is not checked
  • Non-negative number (required). the result of the calculation must be a positive number
  • Custom Validation. See Creating custom validation criteria

  If you assign any value other than No validation, the field is surrounded by red dashes in Data Entry mode. If the user’s response does not meet the validation criteria, the field remains surrounded by red dashes. Your system administrator determines if a user can save a screen with invalid data.

• Error message. If you select Non-negative number, insert text that appears on the screen if the user’s response does not meet this criterion.

• Advanced tab. This is the same as the Group Box Advanced tab.

Using the Formula Field

1. Copy a sample calculation into the Formula field by clicking the Examples field.
2. Select an operation from the drop-down list. For example, if you click Examples Add 2 numbers {X}+{Y}, {X}+{Y} appears in this field.
   —Image—

   

3. Replace the variables with fields on the screen. Be sure to select the curly brackets ({}) with the letter between them. Then, when the user enters data into those fields, the calculation is performed using the current field values.
4. Select the first variable to replace. To continue the example, select {X}.
5. Select a field to replace that variable in the calculation.
   —Image—

   

6. Click Replace X in Formula.
7. Replace all variables in the formula.

Important information about calculated variables

Important information about calculated variables

• If the user does not replace all variables, validation will fail.
• If a variable appears more than once in a formula (for example, {X} * number({X}<= {Y}) + {Y} * number({X}>{Y}), you only need to replace the first occurrence—the editor replaces subsequent occurrences for you.
• If a calculated field tries to perform a numerical calculation with a value that is blank or contains letters, NaN appears in the field. (NaN stands for “not a number.”)
• If a calculated field tries to divide by zero, Infinity appears.
• If an XML document contains several occurrences of a field that is referenced in a formula, the value is derived as follows:
  • When using the XPath functions sum() and count(), all values with the field name are considered. For example, a document includes 3 books whose prices are $10, $20 and $30. In this case, sum’s value is $60.
  • When using all other functions, the first value is used. For example, a document includes 3 books whose prices are $10, $20 and $30. If a calculation formula refers to <price>, its value is $10.
• You can replace a variable with a number instead of a field. For example, replace
  {X} * {Y} with ../price * 1.15.
• The expression can be complex, such as
  (round(Field1 * 0.80) + (1 div Field2)) - 2.
• You can use a string expression that creates a text message. For example, to calculate a full name from its parts: concat( title, ' ', givenname, ' ', familyname), which could produce “Dr. Jonathan Smythe”.
• A calculated field can only reference other calculated fields that appear before it in a document. For example, a document collects a series of numbers.
  • One calculated field counts the number of numbers.
  • Another totals their values.
  • A third computes the average by dividing the total by the count.

  In this example, you must place the third field below or to the right of the first 2 fields. Calculated fields that are defined later in a document do not appear in the Select Field or Group dialog.

Formula examples

These formulae appear in the Examples drop-down list of the Calculated Field dialog. Your system administrator can customize the list.

• Add 2 numbers. Add the value in the first field (X) to the value in the second field (Y).

  {X} + {Y}

• Subtract 2 numbers. Subtract the value in the second field (Y) from the value in the first field (X).

  {X} - {Y}

• Multiply 2 numbers. Multiply the value in the first field (X) by the value in the second field (Y).

  {X} * {Y}

• Divide 2 numbers. Divide the value in the first field (X) by the value in the second field (Y).

  format-number({X} div {Y},'0.###')

• Format as a percentage. Determine what percentage one number (X) is of another (Y). For example, if {X}=10 and {Y}=100, the result of the calculation is 10%.

  format-number({X} div {Y},'#0%')

• Absolute value of a number. The number regardless of the sign (negative or positive).

  {X} * (number({X} > 0)*2-1)

• Minimum of 2 numbers. The smaller of 2 field values.

  {X} * number({X} <= {Y}) + {Y} * number({X} > {Y})

• Maximum of 2 numbers. The larger of 2 field values.

  {X} * number({X} >= {Y}) + {Y} * number({X} < {Y})

• Zero if subtraction is negative. Subtract one number (Y) from another (X). If the difference is less than zero, insert zero.

  ({X} - {Y}) * number(({X} - {Y}) >; 0)

• Multiply by another number if checkbox is checked.

  {X} * ( {Y} * number( {Z} ='true') + number( {Z} !='true'))

  • X is a numeric field.
  • Y is another numeric field to multiply by X if a checkbox is checked.
  • Z is the checkbox.

  For example, {X}=2 and {Y}=3

  • if the checkbox is checked, the result is 2 * 3, which is 6
  • If the checkbox is not checked, the result is 2
• Round a decimal number. Rounds the number to the nearest integer. For example, round(3.14). The result is 3.

  round({X})

• Round up a decimal number. Returns the smallest integer that is greater than the number. For example, ceiling(3.14). The result is 4. For negative numbers: ceiling(-3.14) = -3

  ceiling({X})

• Round down a decimal number. Returns the largest integer that is not greater than the number argument. For example, floor(3.14). The result is 3. For negative numbers: floor(-3.14) = -4

  floor({X})

• Format decimal number 0.00. Rounds a value either up or down to the hundredth place. As examples, 100 becomes 100.00, and 3.14159265 becomes 3.14.

  format-number({X},'0.00')

• Total numeric values from multiple fields. Add the values in all referenced fields. Only elements that contain a value are summed. Empty elements are excluded.

  sum({X}[text()] | {Y}[text()] | {Z}[text()]))

• Total a list of numeric values. Total all values in a single repeating field.

  sum({X}[text()])

  For example:

  Plain Text Field properties

  • Name: Miles
  • Allow: more than one
  • Validation: non-negative whole number

  XML Data

  <root>
              <Miles>89</Miles>
              <Miles>12</Miles>
    <Miles>23</Miles>              
    <Miles>19</Miles>
  </root>

  Sum(Miles) equals 89+12+23+19=143

  Only elements that contain a value are summed. Empty elements are excluded.

• Average a list of numeric values. Calculate the average of all values in a single repeating field.

  format-number(sum({X}[text()]) div count({X}),'0.###')

  To continue the example from the Total a list of numeric values field:

  Plain Text Field properties

  • Name: Miles
  • Allow: more than one
  • Validation: non-negative whole number

  XML Data

  <root>              
    <Miles>89</Miles>              
    <Miles>12</Miles>              
    <Miles>23</Miles>              
    <Miles>19</Miles>             
  </root>

  Average=89+12+23+19=143

  divided by the number of values (4)= 35.75

  Only elements that contain a value are summed. Empty elements are excluded.

• Count the number of values in a list. Calculate the number of values in a single repeating field.

  count({X})

  To continue the example from the Total a list of numeric values field:

  Plain Text Field properties

  • Name: Miles
  • Allow: more than one
  • Validation: non-negative whole number

  XML Data

  <root>              
    <Miles>89</Miles>              
    <Miles>12</Miles>              
    <Miles>23</Miles>              
    <Miles>19</Miles>             
  </root>

  Count = 4

• Lowercase text. Replace all uppercase characters with the lowercase version of that character.

  translate({X},'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz')

• Uppercase text. Replace all lowercase characters with the uppercase version of that character.

  translate({X},'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')

• Remove extra spaces. Remove extra space characters from content.

  normalize-space({X})

• Concatenate text. Link text strings together into a single string. For example, concat('The',' ','XML') yields The XML.

  concat({X}, ', ', {Y})

• Size of a text string. Count the number of characters in a selected field’s value. For example, if the referenced field’s value is Hello, string-length = 5.

  string-length({X})

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The Indexed field may or may not appear, depending on how your administrator has set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this field.
• Default value. If you want this screen to have a default date when the user first sees it, click the calendar icon to the right and select a date. The user can change the date in Data Entry mode. Check Default to Current date if you want to use the date on which the content is created or edited.

  NOTE: If you enter a default date, you cannot later remove it. You can change it. If necessary, you can delete the field and enter a new one.

• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears to the left of the field. If the user clicks the icon, a drop-down menu provides an option to remove the field.

  If the user removes the field, field name replaces the field on the data entry screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user entering data add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you are allowing the user to insert an entirely new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field (see the Use field). So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Validation. If you want to require the user using the calendar to enter a response, click the down arrow to the right of this response field and select Cannot be blank. You can also choose a date in the past/future option or Custom.
• Error Message. If you select Cannot be blank, insert text that appears on the screen if the user’s response does not meet this criterion.
• Custom Validation. You can ensure the user’s input is greater or less than the date you are inserting on the Data Design screen.
  —Image—

  

  • Message. Displays in Data Entry mode when the user inserts an invalid value. Your system administrator determines if a user can save the invalid data.
  • Data Type. Shows Date.
  • Condition. Displays the validation logic.
  • Examples. Drop-down list shows validation expressions that you can apply to the field.
  • Select a Field to Insert area. Displays fields that can be inserted into the Condition field. You must choose a calendar type field (note the calendar icon to the left of these fields).
• Advanced tab. This is the same as the Group Box Advanced tab.

Creating a custom validation

As an example of custom validation, assume a field collects the date when a patient’s health insurance policy expires. You want to make sure the date is later than today. To accomplish this:

1. Create a calendar field that prompts for today’s date.
2. Create another calendar field that prompts for a patient’s health insurance policy expiration date.
3. While creating the second field, in the Validation section, click Custom Validation. The Custom validation screen appears.
4. Click the down arrow to the right of the Examples field to see sample logic.
   —Image—

   

5. Click Date After (not(. >={X}). This option lets you specify that the user’s response must be later than a specified date.
6. In the Condition field, select {X} and click the Select Field button. The Select Field or Group screen appears.
7. Select the field that prompts for today’s date, which you created in Step 1. That field replaces {X} in the Condition field.
8. Move the cursor to the Error Message field and compose an error message. For example: Must be after today. Your screen should look like this.
   —Image—

   

9. Click OK.
10. Click OK to save that dialog and test the validation on the date field. To do this, switch to Data Entry mode and enter a date earlier than today to verify that validation works as expected.

• Descriptive Name. Enter text to guide the user’s response to this field. To continue the example, the caption would be Check if you are over 65. After you insert this field onto the screen, the Descriptive Name appears to the right of the checkbox. You can use the editor's formatting capabilities to modify its size, font, color, and other attributes.

  NOTE: The Descriptive Name field only appears on this dialog when you create the Check Box field. If you later try to edit the field, it is not on the dialog. However, you can edit the Descriptive Name text within the editor.

• Indexed. Check if you want to index this field. See also: Searching XML information. The Indexed field may not appear, depending on how your administrator set up your system.
• Field Name. Enter the field’s element name. This will define the field in the XML.
• Tool Tip Text. Enter text that appears when a user hovers the cursor over this field.
• Default value. If you want this field to be checked when the screen first appears, click True. Otherwise, click False.
• Validation tab. You can use this screen to specify if the checkbox must be checked or unchecked.
• Advanced tab. This is the same as the Group Box Advanced tab.

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The Indexed field may or may not appear, depending on how your administrator set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this choice list.
• List. Select from a standard list or choose Custom to create your own.
• Allow selection. Click More than one to let the data entry user select more than one item on the data entry screen. Otherwise, click Only one. For example, if you click More than one, and the choices are: music, art, sports, the user could select all 3 choices.
  • A selection is required. Check this box if the user must select at least one list item.
  • First item is not a valid selection. Check here if the first list item is text that prompts the user to respond to the field. An example of such text for a list of states is Select a state. If you check this box and the user selects the first value on the list (most likely by default), an error appears when he tries to save the screen.
• Appearance. Determine the style of list.
  List options

  List type	Example	Description
  vertical		All choices appear, arranged vertically.
  horizontal		All choices appear, arranged horizontally.
  list box		All items appear. The default one is selected when the screen first appears, but can be changed.
  drop list		Only the top item appears. To its right, a down arrow appears (circled). The user clicks the arrow to display all items and select one.

• Item List. See Creating a custom choice list.
• Value. Enter the value collected when a data entry user selects this item. For example, if Interests appears in the Name field, and you want music to be collected when the data entry user selects this item and saves the page, enter music here.

• Advanced tab. This is the same as the Group Box Advanced tab.

Creating a custom choice list

To create your own set of list options, accept the List field’s default value, Custom. Then, enter the list values using the Item List section of the screen.

—Image—

To indicate an option is the default choice, check the Selected checkbox.

• In the Display Text field, enter text to describe this item on the data entry screen. After you insert this field onto the screen, you can format it. For example, you can apply bold, assign a style, and so on.
• In the Value field, enter the value that is collected when the data entry user selects this item.

  For example, if Interests appears in the Name field, and you want music to be collected when the data entry user selects this item and saves the page, enter music here.

To add a new choice, delete an existing choice, or move a choice up or down within the list, click the menu icon () next to that choice. Then select a menu option.

Creating a custom choice list in a configuration file

Although you can create a custom list of choices using the Item List area of the Choices Field dialog, that list is only available in that field of that screen. If you want to insert the same list in another section of the screen or a different screen, you must re-enter all options. However, if you create a list according to the following steps, your custom list is stored in the configuration file (along with the standard choice lists, such as Countries). As a result, any user connected to your server can insert the list into any Choices Field on any screen.

To insert a custom list of choices:

1. Open the Ektron configuration file, siteroot/workarea/contentdesigner/DataListSpec.xml.
2. Insert the new list following the pattern of the other lists in the file, like the following list.

   <datalist name="MyNewList"> 
     <schema datatype="string" /> 
     <item default="true" value="Green" /> 
     <item value="Red" /> 
     <item value="Blue" />
   </datalist>

   NOTE: You can specify a data type of value: string, nonNegativeInteger, date, decimal. You also can specify a default value (as shown in the third line).

Creating a dynamically populated choice list

You specify the elements of the custom options list described in the configuration data. You can also create a dynamically-populated list from any XML source. The source can be on your server or on a remote website. Follow these steps to add a dynamic data list to the Choices field.

1. Open the Ektron configuration file, siteroot/workarea/contentdesigner/DataListSpec.xml.
2. Insert the new list following the pattern of the other lists in the file, like the following list.

   <datalist name="MyNewList"> 
     <schema datatype="string" /> 
     <item default="true" value="Green" /> 
     <item value="Red" /> 
     <item value="Blue" />
   </datalist>

3. Insert a new datalist item according to this pattern.

   <datalist 
     name="MyNewList" 
     src="{url to xml data source}" 
     select="{xpath to data item element}" 
     captionxpath="{relative xpath to data item's display text}" 
     valuexpath="{relative xpath to data item's value}">

   IMPORTANT: The datalist name must match the listchoice data attribute.

   For example

   <datalist 
     name="USPS-CA" 
     src="[eWebEditProPath]/uspsca.xsd" 
     select="/xsd:schema/xsd:simpleType/xsd:restriction/xsd:enumeration" 
     captionxpath="xsd:annotation/xsd:documentation"\ 
     valuexpath="@value" 
     namespaces="xmlns:xsd='http://www.w3.org/2001/XMLSchema'" 
     validation="select-req">

In this example, the data list is stored in the uspsca.xsd file, located within the ewebeditpro folder. However, it could be in any XML data source.

Group Box General tab

• Descriptive Name. Enter the name of this field, which is used internally as the field’s caption. By default, the Data Designer assigns a name made up of Field followed by the next available number. So, the first field’s default name is Field1, the second field’s default name is Field2, and so on. You can change the default if you want.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears to the left of the field. If the user clicks the icon, a drop-down menu provides an option to remove the field.

  If the user removes the field, field name replaces the field on the data entry screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user entering data add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you are allowing the user to insert an entirely new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field. So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Appearance. Click Show border and caption if you want to surround the fields in this group with a box. You can also create a caption to appear in the top line of the box. Click No border if you do not want to surround the fields in this group with a box.
• Caption. If desired, enter text to describe this group of fields on the data entry screen. For example:

  

  After you insert this field onto the screen, you can use the editor's formatting capabilities to modify its size, font, color, and other attributes.

  NOTE: The Caption field only appears on this dialog when you create the Group Box field. If you later try to edit the field, the Caption field is not on the dialog. However, you can edit Caption text within the editor.

• Advanced tab. See Group Box Advanced tab.
• Relevance. See Group Box Relevance tab.

Using a tag other than <root>

Using a tag other than <root>

By default, Ektron surrounds your Data Design with <root> tags. To replace <root> tags with another element name:

1. After creating a new Data Design screen, insert a Group Box as the first field.

2. In the Group Box dialog’s Field Name field, enter the root text.

3. On the Group Box Dialog box, click the Advanced tab.

4. In the Root tag section, select Use this element as the Root tag and press OK.

5. Place all other screen elements within the Group Box field.

Group Box Advanced tab

The Advanced tab lets you generate XML microformats made up of standard XHTML tags and attributes that contain a specific structure and values.

Show an example microformat of an event

For example, the microformat of an event looks like this.

<span class="event">
<a class= 
  "url" href="https://www.lisa.org/events/2006nyc/
  package_registration.html?from=fn1206 ">
  LISA Global Strategies Summit</a>
</span>

NOTE: If the element is a Group Box or table, its type must be Element because it surrounds other elements. If the element is a Rich Area field, its type must be Element or Content.

• Element. A unique tag. The user’s response to the field becomes its value.

  <Lastname>Rogers</Lastname>

• Attribute. An attribute of the containing field. The containing field is typically a Group Box. If you insert an Attribute field type, the Field Name field on the dialog box is grayed out. The field name and type can only be edited on the Advanced Field properties screen.

  <PtInformation Lastname="Rogers">
</PtInformation>

• Content. The content of the containing field, typically a Group Box. Note that, in this case, field name is not used (it's is grayed out). The field name and type can only be edited on the Advanced Field properties screen. Because most fields define their own content, this option is typically used to define a value to a Group Box that contains other fields defined as attributes.

  NOTE: Only one Content type field is valid within a containing field.

  <PtInformation>
Rogers
</PtInformation>
  

Data entry and data design views

Data entry view

Data design view

Replacing the XML <root> tag

Replacing the XML <root> tag

By default, Ektron surrounds your Data Design with <root> XML tags. You can replace the <root> tags with another element name by following these steps.

1. After creating a new Data Design screen, insert a Group Box as the first field.
2. In the Group Box dialog box Field Name field, enter the root text. For example, "state" to replace <root> with <state>.
3. Click the Advanced tab.
4. In the Root tag section of that screen, select Use this element as the Root tag and click OK.
   —Image—

   

5. Place all other screen elements within the Group Box field.

Group Box Relevance tab

The Relevance tab allows a group of fields to appear or disappear according to the value of other fields in the configuration. It appears on both the Group Box and Tabular Data Box dialogs.

Here are some example uses.

• Questions about pregnancy that appear only if the patient is female.
• A list of states that appears only if the user selects United States as the person's country.
• A list of car manufacturers. When a user chooses one, all of its models appear in a second list.

Fields that can be used in relevance conditions

Only the following field types can be used in a Relevance condition.

• Check box
• Text
• Calculated
• Choices

NOTE: If using a Choices field, in the Appearance area of the dialog, you can only choose List Box or Drop Box. Vertical List and Horizontal List are not supported.

Applying relevance to a Group Box field

Applying relevance to a Group Box field

1. Edit a Smart Form configuration in Data Design mode to which you want to apply Relevance.
2. If necessary, insert the field(s) on which the Group Box’s appearance depends.
3. Insert a Group Box field. See also: Group Box

   NOTE: The location of the Group Box field is independent of the location of the fields to which you will apply conditions.

4. Click the Group Box dialog’s Relevance tab.
5. The Relevance tab appears.
6. Scroll through the list of sample conditions to determine which one best fits your situation.
   —Image—

   

7. Select a field from the lower half of the screen to replace the first variable (X or Y) in the condition. For example, if the condition is A checkbox field is checked ({X} = 'true'), click the check box field whose value must be true for this group to appear.
8. Click Replace {X} in Condition.
   —Image—

   

9. Notice that, in the Condition field, the variable was replaced by the selected field.
   —Image—

   

10. If the condition has another variable, repeat Steps 7 and 8.
11. Click OK.

You should switch to Data Entry mode and test the Relevance conditions.

Example of applying relevance to a Group Box field

Example of applying relevance to a Group Box field

Assume you want a list of states in the United States to appear only if a user selects United States from the Country field.

—Image—

To accomplish this:

1. Create a Choices field and assign it 3 values:
   • United States
   • Canada
   • Other

   See also: Choices

2. Create a Group Box field and name it States.
3. With that Group Box field, create a new Choices field.
   • Name it US States.
   • In its List field, select U.S. States & Territories.
   • In Allow Selection, check First item is not a valid selection
   • In the Appearance field, select Drop List.
4. Click OK. The field appears on the form.
   —Image—

   

5. Place the cursor on the States Group Box field and click Group Box.
6. Click its Relevance tab.
7. Pull down the Examples list.
8. Click A field has a given value ({X} = 'value').
9. Scroll through the lower half of the screen until you see the country Choices field.
10. Click Replace '{X}' in Condition. Notice that the Condition field now reads /root/Country = 'value'.
11. In the Condition field, replace Value with United States.
    —Image—

    

    IMPORTANT: The text that replaces Value must exactly match the desired value of the selected field.

12. Click OK.

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The Indexed field may or may not appear, depending on how your administrator has set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this field.
• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears to the left of the field. If the user clicks the icon, a drop-down menu provides an option to remove the field.

  If the user removes the field, field name replaces the field on the data entry screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user entering data add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you are allowing the user to insert an entirely new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field. So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Value. Whether the value is an element or plain text.
  • Value is an element renders the field as <img src=”url” alt=”text” /> for an image.
  • Value is plain text renders the field as just the url.
• Default Image Location. If desired, you can insert a default image, which might be the most common image or a reminder that an image needs to be inserted. To find the image, click From File and go to image file. The image file's extension must appear between the <validext> tags in the configdatadesign.xml file. For example:

  <validext>gif,jpg,png,jpeg,jpe,doc,txt

  </validext>

• Cannot be blank. To require the user to enter a response, check this box.
• Description. Enter the image’s alt text, which is used as a replacement for an image whenever it cannot be seen. For example, a visually impaired person is using a screen reader.

• Advanced tab. This is the same as the Group Box Advanced tab.

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The indexed field may or may not appear, depending on how your administrator has set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this field.
• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears to the left of the field. If the user clicks the icon, a drop-down menu provides an option to remove the field.

  If the user removes the field, field name replaces the field on the data entry screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user entering data add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you are allowing the user to insert an entirely new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field. So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Value. Whether the value is an element or plain text.
  • Value is an element renders the field as <img src=”url” alt=”text” /> for an image.
  • Value is plain text renders the field as just the url.
• Default Location. If desired, you can insert a default link, which can be the most common link or simply an example. To help find the link, click the Select button and go to a file. You can only insert a file whose extension appears between the <validext> element of the configdatadesign.xml file. For example:

  <validext>gif,jpg,png,jpeg,jpe,pdf,doc</validext>

• Cannot be blank. If you want to require the user completing this field to enter a response, click this check box.
• Description. If desired, enter text that the user can click to access the linked file.
• Target Frame. Use this field to indicate how the hyperlinked files will appear when clicked.
  • New Window(_blank). In a new browser window, on top of the current browser.
  • Same Window(_self). In the same position within the browser window. The new window replaces the current one.
  • Parent Window(_parent). If your page contains frames, in the frame that contains the frame with the hyperlink.
  • Browser Window(_top). If your page contains frames, in the full display area, replacing the frames.

• Advanced tab. This is the same as the Group Box Advanced tab.

These steps summarize how to use a Resource Selector on a Smart Form.

1. Create a Smart Form configuration.
2. Edit its Data Design, placing a Resource Selector field on it.
3. Set the Resource Selector properties. For example, determine whether the content author can select content, a taxonomy category, a collection, or a folder.
4. Assign the configuration to an Ektron folder. See also: Assigning a Smart Form to a folder
5. An author creates a Smart Form based on that configuration.
6. The author adds content, a collection, a taxonomy category, or a folder to the Smart Form, along with other field types.
7. A site visitor browses to the page and views the assigned content.

General tab

• Descriptive Name. Enter the name of this field. Internally, the name is used as the field’s caption. By default, the Data Designer assigns the name Field followed by the next available number. So, the first field’s name is Field1, the second field is Field2, and so on. You may change the default.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over the field.
• Resource Type. Select Content, Folder, Taxonomy, or collectionA list of Ektron content links for display on a Web page..

  IMPORTANT: You can place content from these folder types on a Smart Form: standard, root, site, blog, and eCommerceAs of Ektron version 9.10, Ektron has discontinued new development on its eCommerce module. If you have a license to eCommerce, you will continue to receive support, but if you need to upgrade, contact your account manager for options. catalog. You cannot place content from Community, Discussion Board, or WebCalendar folders on a Smart Form.

• Default Value. Select the default content, folder, taxonomyA content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors go content independent of the folder structure. or collectionA list of Ektron content links for display on a Web page. item by clicking the folder icon and selecting. The following example shows a taxonomy default item. The author can accept the displayed default or change it by clicking on the folder icon.

  

• Minimum Number. Define the minimum number of content items that can appear where you insert the Resource Selector.
• Maximum Number. Define the maximum number of content items that can appear where you insert the Resource Selector.

  These settings affect the content author’s work with this field on a Smart Form in the following way. Assume you set a minimum of 1 and a maximum of 2. After the content author adds 2 content items for this resource selector, the only options are to remove or rearrange fields; you cannot add more.

Type tab

Use the Type tab to limit the type of content that a content author may choose. It is available only if the Resource type is Content Resource.

NOTE: eCommerceAs of Ektron version 9.10, Ektron has discontinued new development on its eCommerce module. If you have a license to eCommerce, you will continue to receive support, but if you need to upgrade, contact your account manager for options. products are also known as catalog entries.

—Image— 

Configuration tab

The Configuration tab determines how a content author may select content or a folder on a Smart Form. It is available only if the Resource Type is Content or Folder.

—Image— 

• Check Browsing folders to let content authors select content or a folder by browsing through folders.
  • If you want to set a beginning folder from which an author can browse, use the Starting Folder field. Otherwise, browsing begins at the Root folder.
• Check Browsing taxonomy categories to let a content author select content by browsing through taxonomies. (Available only if the Resource Type is Content.)
• Check Searching for key words to let a content author select content using the Workarea search. (Available only if the Resource Type is Content.)

Appearance tab

The Appearance tab determines the default appearance of the resource on your website.

Show the content resources Appearance tab and effects of each option

Content option

Content Title option

Title followed by content option

Quicklink option

QuickLink with Summary option

Show the folder resources Appearance tab and effects of each option

List Quicklinks and summary of folder contents option

List Quicklinks of folder contents option

Breadcrumb option

The folder’s breadcrumb path appears, as defined on the folder Properties screen’s Breadcrumb tab. See also: Creating a sitemap breadcrumb trail

Show the taxonomy resources Appearance tab and effects of each option

This is the only option if the Resource Type is Taxonomy Resource.

Show the collection resources Appearance tab and effects of each option

List Quicklinks and summary of collection items option

List Quicklinks of collection items option

• Descriptive Name. Enter the name of this table. By default, the Data Designer signs a name made up of Field followed by the next available number. So, the first field’s default name is Field1, the second field’s default name is Field2, and so on. You can change the default if you want.
• Field Name. Enter the table’s element name. This will define the table in the XML. See also: Tabular data creates 3 levels of XML tags:
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over the table’s column headers.
• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears to the left of the field. If the user clicks the icon, a drop-down menu provides an option to remove the field.

  If the user removes the field, field name replaces the field on the data entry screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user entering data add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you are allowing the user to insert an entirely new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field. So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Row display name. Enter the text that appears when a user hovers the cursor over the table’s cells. Use this field to describe the kind of information to be inserted into the table’s cells.
• Row name. Enter the name of the XML tag used to collect data for each entry in the table.
• Minimum number. If desired, enter the minimum number of rows for this table. If you enter a number and the data entry user tries to save the screen without inserting at least the minimum number of rows, the user is informed that Element content is incomplete according to the DTD/Schema. By default, the user is allowed to cancel or save the screen anyway. However, the system administrator determines whether or not the user can save an invalid document.
• Maximum number. If desired, enter the maximum number of rows for this table. If you don’t want to assign a maximum number, check Unlimited. When this table appears on a data entry screen, if a user adds the maximum number of rows, the Insert Above and Insert Below menu options are grayed out.
  —Image—

  

• Columns. Enter the number of columns to appear in the table.
• Caption. Optionally enter text to describe this table on the data entry screen. The caption appears centered above the table. After you insert this field onto the screen, you can use eWebEditPro+XML’s formatting capabilities to modify the caption’s size, font, color, and other attributes.
• Advanced tab. This is the same as the Group Box Advanced tab.
• Relevance. This is the same as the Group Box Relevance tab.

Tabular data creates 3 levels of XML tags:

• inner level: each field in the table
• middle level: each row in the table
• outer level: the entire set of table data

To explain how this works, use the following contact list as an example.

• John Doe, 555-1212, [email protected]
• Mary Smith, 555-8765, [email protected]

When you insert a field into a table, a dialog helps you define the field type. For example, when inserting a plain text field, the Plain Text Field dialog appears. On that dialog, the value of the Phone field defines the tags that enclose that field’s contents.

—Image—

To continue the example, every contact is represented in XML as:

<Name>John Doe</Name>
<Phone>555-1212</Phone>
<Email>[email protected]</Email>
	and
<Name>Mary Smith</Name>
<Phone>555-8765</Phone>
<Email>[email protected]</Email>

Each row of the table collects information for one contact. On the Tabular Data Box dialog, the Row Name field defines the XML tag that groups information for each contact. For example, the Row Name field value is Contact.

<AddressBook>
  <contact>
    <Name>John Doe</Name>
    <Phone>555-1212</Phone>
    <Email>[email protected]</Email>
  </contact>
  <contact>
    <Name>John Doe</Name>
    <Phone>555-1212</Phone>
    <Email>[email protected]</Email>
  </contact>
  <contact>
    <Name>Mary Smith</Name>
    <Phone>555-8765</Phone>
    <Email>[email protected]</Email>
  </contact>
</AddressBook>

• Descriptive Name. Enter the name of the field.
• Indexed. Check if you want to index this field. For more information, see Searching XML information. The Indexed field may or may not appear, depending on how your administrator set up your system.
• Field Name. Enter the field’s element name. This defines the field in the XML.
• Tool Tip Text. Enter the text that appears when a user hovers the cursor over this field.
• Default Value. If you want to set a default value for this field, enter it here. The default value appears in Data Entry mode, where the user can accept, change, or delete it. For example, if this field collects a city, and most users enter New York, enter New York as the value.
• Dimensions. Set the size of the text field in characters.
  • Size (or Width). Enter the width of this textbox in characters. This field is available only if Allow Rich Formatting is not checked.
  • Height. Enter the height of this textbox in characters. This field is available only if Allow Multiple Lines is checked and if Allow Rich Formatting is not checked.
• Use. Click May not be removed if this field must be included on the screen. Otherwise, click May be removed.

  If you check May be removed, when this field appears on a data entry screen, an icon () appears next to the field. If the user clicks the icon, a menu provides a remove option.

  If the user removes the field, field name replaces the field on the screen to indicate that the field was removed and can be re-added if necessary. For example, if the field’s display name is street address, and the user removes the field, appears in place of the field.

  NOTE: The menu icon () can also indicate that the user can add instances of a field (see the Allow field). So, if a field is required, the icon could appear but omit a Remove option.

• Allow. Check more than one if you want to let the user add instances of this field. Otherwise, check only one. For example, if a screen is collecting names and addresses and you want to let the user enter several of them, check more than one. If you check More than one here, you allow the user to insert a new table, not an additional table row.

  IMPORTANT: Do not insert a calendar field into a Smart Form that allows multiple entries (using the Allow more than One option on the dialog). If you do, you cannot search the Smart Form using that field.

  If the user entering data clicks , a menu appears, which lets the user click Duplicate to add instances of the field to the screen.

  NOTE: The menu icon () can also indicate that the user can remove a field (see the Use field). So, even if a field allows only one instance, the icon could appear but the menu would only display Remove.

• Allow Rich Formatting. Check this box if you want to let the Smart Form author format text in this field. If you do not check the box, the author can enter plain text only.
  If you allow rich formatting, a content author uses the editor selected in either the web.config file's ek_EditControlWin key (for Windows computers) or the ek_EditControlMac key (for Apple computers). Or, if UserPreferred is the web.config value, the author uses the editor selected in the user profile.
  
• Keep Single Blocking Tag. This checkbox is active only if Allow Rich Formatting is checked. Check this box if you want the editor to maintain <p> tags around a single line of text. Uncheck this box if you want the editor to strip <p> tags from a single line of text.

  NOTE: This checkbox has no effect if text that allows rich formatting consists of more than one line.

  Sample Results
  Checked: <p>Here is sample text</p>
  Unchecked: Here is sample text

• Allow Multiple Lines. Check here to let this text box expand to accommodate the user’s input. If you do not check this box, a single line box appears on the screen to accept user input.
• Cannot be Changed. Check here to make this field read-only. You might use this option to provide instructions for completing the screen.
• Invisible. Check to make this field hidden in Data Entry mode. This option lets you store unseen information in an XML document. An example might be putting a version number for the data design so that XML documents can be upgraded to newer versions using an XSL transform.
• Validation. Select the kind of validation to apply to this field. Your choices are:
  • No validation. the user’s response is not checked.
  • Cannot be blank. the user must enter a response.
  • Custom. You can create custom validation. See also: Creating custom validation criteria

  If you assign to this field any value other than No validation, the field is initially surrounded by red dashes in Data Entry mode. If the user’s response does not meet the validation criterion, the field remains surrounded by red dashes. The system administrator determines whether or not the user can save an invalid document.

• Advanced tab. This is the same as the Group Box Advanced tab.