Configuring Custom Sections

Objective

After completing this lesson, you will be able to Configure custom sections and fields.

Custom Sections

A custom section is housed within the element <custom-sect>. Its sub-element, <fm-sect>, has all of the same attribute options as any other section. Not all of the attributes apply to your custom section, and you can configure only those that are applicable.

The figure, custom-sect, shows the code for a custom section that has not had fields added yet. Everything from the opening tag <custom-sect> to </fm-sect-config> should look familiar, as these are the same elements and attributes that are available in every section.

Custom sections may be added as many times as you need them and can be a combination of nine different field types.

You may configure most of the custom section elements and attributes in Manage Templates. However, some elements that you make specific customizations to in XML may no longer be editable in the instance.

Custom fields may be added to other sections (goals, competencies, and so on.) that support <fm-element> tags. Currently, custom fields may be added to the competency and goal sections in the instance. The overall summary section also supports custom fields, but those must be added in XML.

Custom Fields

Creating a custom section is similar to creating any other kind of section, except that you need to indicate the kinds of fields to appear, and configure those fields. You can create custom fields within a custom, objective, or competency section.

The process to create custom fields is exactly the same in each type of section, but the visibility of those fields differs across different sections.

Watch this video to learn how custom fields display in each section of the performance form.  

In a custom section, the fields appear as frequently as specified. In a competency or objective section, the custom fields repeat for each item in that section. You can see an example in the figure titled Example of Custom Fields in a Goal Section.

Note

Remember that the custom fields appear in the order indicated by the index value in each <fm-element>, starting with index="0".

For each custom field, four elements must be defined:

  • Element Key – ID for the field. Must be one word, unique per form template, and can be used for permissioning.

  • Element Name – Label that appears on the form; some basic HTML functionality.

  • Element Type – Defines the kind of element and dictates the kind of data allowed. Indicated in element attributes as type="x". You can find all the available types in the table titled Custom Field Element Types.

  • Element Value <evalue> – Used to pre-populate a value in the field – can also be reportable.

    • There is more flexibility to create <evalue> in XML, because in Manage Templates you are restricted to the field type.

    • For example, if the field type is Integer, which only supports a whole number, you may only populate the <evalue> field with a whole number. In XML, you are able to use text to pre-populate the field instead than being restricted to a whole number.

Types of Custom Fields

FieldDefinition
<ekey>This is the id for the field, and is used for permissioning and other functions. The element key must be unique per form template, and can only be one word.
<ename>This is the label that appears on the form. Limited HTML tags may be used in this field, such as <b></b> for bold, etc.
<type>This defines what kind of element this field will be, and what type of data is allowed. It is indicated in the sub-element attributes as type="x," where x is the number indicating the type of element.
<evalue>

This is used to pre-populate a value in the field.

  • Only required if using the element type of checkbox.

  • The value within this element is chosen to match the content of the checkbox (for example, True, Yes, or Approved).

  • Allows the value to be reportable.

  • If a value is not specified, then no value is stored in the database, and nothing shows up on reports.

  • If an <evalue> is entered, and the user does not change that default value, the <evalue> is what will be reported.

Custom Field Element Types

Element Type (XML)Element TypeDescription
1SectionDo not use – not a valid fm-element type
2LabelLabel in bold text
3TextSingle line text box
4TextareaMulti-line text box – Will be a rich text editor with legal scan and spell check if those features are enabled for the form.
5DateDate box
6ListDrop-down list
7IntegerText box for a whole number only
8DoubleText box for a number with decimals
9CheckboxCheckbox labeled item – Must specify the <evalue>, otherwise no data will be stored when checked.
10HiddenHidden value – static value that will be included in an export.

Note

Custom section elements of type Text, Textarea, and Checkbox are now editable during form launch.

Text Example: Manage Templates Text Custom Fields

Text Example: XML Custom Field

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="6" type="3">
   <ekey><![CDATA[ele_5]]></ekey>
   <ename><![CDATA[Text Example]]></ename>
   <evalue><![CDATA[]]></evalue>
</fm-element>

Textarea Example: Manage Templates Custom Field

Textarea Example: XML Custom Field

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="7"type="4" mime-type="html">
   <ekey><![CDATA[ele_6]]></ekey>
   <ename><![CDATA[Textarea Example]]></ename>
   <evalue><![CDATA[]]></evalue>
</fm-element>

Date Example: Manage Templates Custom Field

Date Example: XML Custom Field

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="4" type="5">
   <ekey><![CDATA[ele_3]]></ekey>
   <ename><![CDATA[Date Example]]></ename>
   <evalue><![CDATA[]]></evalue>
</fm-element>

List Example (elist): Manage Templates Custom Field

List Example (elist): XML Custom Field

Code Snippet
Copy code
Switch to dark mode
123456789101112131415
<fm-element index="5" type="6">
   <ekey><![CDATA[ele_7]]></ekey>
   <ename><![CDATA[Elist Example]]></ename>
   <evalue><![CDATA[]]></evalue>
   <elist elist-value-type="3" elist-default-name="" elist-devault-value="0">
     <elist-element elist-index="0" elist-selected="false">
     <elist-name><![CDATA[No]]></elist-name>
     <elist-value>![CDATA[]]></elist-value>
     </elist-element>
   <elist-element elist-index="1" elist-selected="false">
     <elist-name><![CDATA[Yes]]></elist-name>
     <elist-value><![CDATA[]]></elist-value>
    </elist-element>
</elist>
</fm-element>

Integer Custom Field

The Integer field supports numerical values, so in Manage Templates, you can only type a number in the Value field.

In XML, you can type text into the Value (evalue in XML) field that pre-populates the field with text that is visible to the end user.

Integer Example: XML Custom Field

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="2" type="7">
   <ekey><![CDATA[ele_2]]></ekey>
   <ename><![CDATA[Integer Example]]></ename>
   <evalue><![CDATA[]]></evalue>
</fm-element>

In XML, type text into the Value (evalue in XML) field that pre-populates the field with text that is visible to the end user.

Double Custom Field

The Double field supports numerical values, so in Manage Templates, you can only type a number in the Value field.

Double Example: XML Custom Field

In XML, you may type text into the Value (evalue in XML) field that pre-populates the field with text that is visible to the end user.

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="1" type="8">
   <ekey><![CDATA[ele_1]]></ekey>
   <ename><![CDATA[Double Example]]></ename>
   <evalue><![CDATA[]]></evalue>
</fm-element>

In XML, you may type text into the Value (evalue in XML) field that pre-populates the field with text that is visible to the end user.

Checkbox Custom Field

Checkbox Example: XML Custom Field

Code Snippet
Copy code
Switch to dark mode
12345
<fm-element index="3" type="9">
   <ekey><![CDATA[ele_4]]></ekey>
   <ename><![CDATA[Checkbox Example]]></ename>
   <evalue><![CDATA[Y]]></evalue>
</fm-element>

Custom element types are noted in the figure titled Custom Element Types. Match the numbers in the figure with the items in the list below:

  1. Label

  2. Double

  3. Integer

  4. Date

  5. Checkbox

  6. Elist

  7. Text

  8. Textarea

Custom Element Error

What caused the error in the figure titled Custom Element Error?

Custom Element Error Explanation

The error in the figure Custom Element Error was caused by the following issues:

  • The values for Double and Integer are not consistent with a decimal number or a whole number.

  • In Manage Templates, the Value field only supports values that align with the type of the field.

Introduction Text for Custom Sections

It is possible to add an introduction text to a custom section. In Manage Templates, just add the necessary paragraph in the Description area just as you would for the Introduction section. It can also be added in the XML after </fm-sect-name>, with the code <fm-sect-intro><![CDATA[Intro text example]]></fm-sect-intro> which should be placed.

There is an option to make this introduction text editable when we mass create forms and this option is also supported with the Launch Forms tool.

In Launch Forms, the introduction text can be edited.

Configure Custom Sections and Fields

Business Example

Your client requests that you configure a custom section, Evaluation of Potential, for their Performance Management form template. This section will not be visible to the Employee, and you will hide this section on a later exercise. You must configure the section to look like the following:

Task 1: Configure a Custom Section in Manage Templates

Learn how to configure a custom section and add custom fields from Manage Templates.

ExerciseStart Exercise

Steps

  1. Create a custom section entitled Evaluation of Potential.

    1. Log in to the Instance and navigate to Manage Templates using Action Search.

    2. Select the Performance Review tab to display the performance form template list. Choose your Performance Management form template.

    3. Open the form template, and select to expand Edit Fields and Sections dropdown menu on the left-hand side of the screen.

    4. Select Add New Section.

    5. In the Add new section dialog box, select Custom from the Section type dropdown menu, and select Add.

    6. In the Section Name field, enter Evaluation of Potential.

    7. Place the custom section above the signature section, and select Save.

  2. Configure the Evaluation of Potential custom section according to the requirements listed in the following table:

    Element / FeatureConfigurationPrepopulated Text
    Label fieldMust display first in the list of custom fieldsPlease complete the following fields:
    Enter Calculated Rating fieldAllow both whole numbers and decimalsDecimals OK
    Enter Manager Rating fieldAllow whole numbers onlyWhole Numbers Only
    1:1 Meeting Date field MM/DD/YYYY
    Verify 1:1 Meeting occurred checkboxMust be deselected by default 
    Future Potential dropdown menuMust contain three prepopulated valuesLow Potential, Medium Potential, and High Potential.
    Potential Mentor field Full Name
    Additional Comments fieldMust have spellcheck and legal scan enabledAny additional comments about this employee’s potential?

    1. Click 0 Custom Element(s) defined. Click to modify.

      Note

      The Management Only (mgt-only="true") checkbox should not be enabled. It is an obsolete PMv11 feature, and it will skip required field validation, if we plan to use required fields. If you don’t intend to display this section to employees, you should use section-permissions instead to hide visibility (see the exercise in Unit 11).

    2. Configure the Label field, as follows:

      FieldValue
      TypeLabel
      NamePlease complete the following fields:

    3. Configure the Enter Calculated Rating field, as follows:

      FieldValue
      TypeDouble
      Minimum Value 
      Maximum Value 
      NameEnter Calculated Rating

    4. Configure the Enter Manager Rating field, as follows:

      FieldValue
      TypeInteger
      Minimum Value 
      Maximum Value 
      NameEnter Manager Rating

    5. Configure the 1:1 Meeting Date field, as follows:

      FieldValue
      TypeDate
      Name1:1 Meeting Date
      ValueMM/DD/YYYY

    6. Configure the Verify 1:1 Meeting occurred checkbox, as follows:

      FieldValue
      TypeCheckbox
      Editable during mass creation of formsSelect
      NameVerify 1:1 Meeting occurred
      Custom Element’s titleNot selected

    7. Configure the Future Potential dropdown menu, as follows:

      Note

      To add fields for extra dropdown menu options, select +Add Element to List.
      FieldValue
      TypeList
      NameFuture Potential
      Custom Element’s list’s value typeInteger
      Custom Element’s list’s default name radio buttonSelect
      Custom Element’s list’s default nameSelect one
      Custom Element’s list’s default value0
      Custom Element’s list’s default name radio buttonNot selected
      List Element's nameLow Potential
      List Element's value1
      Custom Element’s list’s default name radio buttonNot selected
      List Element's nameMedium Potential
      List Element's value2
      Custom Element’s list’s default name radio buttonNot selected
      List Element's nameHigh Potential
      List Element's value3

    8. Configure the Potential Mentor field, as follows:

      FieldValue
      TypeText
      Minimum Value1
      Maximum Value500
      Editable during mass creation of formsSelect
      NamePotential Mentor
      ValueFull Name

    9. Configure the Additional Comments field, as follows:

      FieldValue
      TypeTextarea
      Minimum Value1
      Maximum Value1000
      Writing AssistantNot selected
      Mime TypePlain Text
      Editable during mass creation of formsSelect
      NameAdditional Comments
      ValueAny additional comments about this employee’s potential?

      Note

      The minimum and maximum values for some of these fields in the custom section are set blank (which equals to -1) meaning that you can enter any number of characters. However, it is important to note that reports will only support the first 4,000 characters. For more information, please refer to the implementation guide that explains how to configure character count limitations.

      If you intend to make any of these fields as required in a particular step, a minimum value of at least 1 should be set for custom textor textarea fields or the required field validation will be skipped.

Task 2: Modify the Custom Section in XML

Learn how to make additional changes to your custom section from XML.

ExerciseStart Exercise

Steps

  1. Open the Performance Management form template in your XML editor.

    1. Log in to the Instance and navigate to Form Template Settings from the Action Search bar.

    2. Click the name of your Performance Management form template from the list.

    3. On the Performance Management form template screen, select Download Form Template.

    4. Save the template locally in a folder with the relevant DTD file.

    5. Open the Performance Management form template with your preferred XML editor.

  2. Verify how the XML code looks for the newly section Evaluation of Potential created in the previous steps. You may need to do some minor changes that were not possible from Manage Templates

    1. Review the Evaluation of Potential custom section introduction:

      Code Snippet
      Copy code
      Switch to dark mode
      1234567891011121314
      <custom-sect>
      <fm-sect index="8" mgt-only="false" split-cmt="false" cmt-opt="0">
    <fm-sect-name><![CDATA[Evaluation of Potential]]></fm-sect-name>
        <fm-sect-intro><![CDATA[]]></fm-sect-intro>
        <fm-sect-config>
          <rating-label><![CDATA[Rating]]></rating-label>
          <rating-label-others><![CDATA[Rating]]></rating-label-others>
          <default-rating><![CDATA[unrated]]></default-rating>
          <hidden-strength-threshold>0.0</hidden-strength-threshold>
          <blind-spot-threshold>0.0</blind-spot-threshold>
         <num-decimal-places>2</num-decimal-places>
          <publish-button-label><![CDATA[Publish Content]]></publish-button-label>
        </fm-sect-config>
</custom-sect>

    2. Review the label field code:

      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="0" type="2">
          <ekey><![CDATA[ele_9]]></ekey>
          <ename><![CDATA[Please complete the following fields:]]></ename>
          <evalue><![CDATA[]]></evalue>
</fm-element>

    3. Add a default text in <evalue> to display for the Enter Calculated Rating field using this code example:

      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="1" type="8">
          <ekey><![CDATA[ele_7]]></ekey>
          <ename><![CDATA[Enter Calculated Rating]]></ename>
          <evalue><![CDATA[Decimals OK]]></evalue>
        </fm-element>

      Note

      Double and Integer custom fields do not allow a value other than a number when creating the custom field in Manage Templates . For that reason, you need to make the changes in XML, which allows to use any text for the <evalue> element, and the end-user will be able to see the pre-populated text.

    4. Add a default text in <evalue> to display for the Enter Manager Rating field using this code example:

      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="2" type="7" min="-1" max="-1">
          <ekey><![CDATA[ele_6]]></ekey>
          <ename><![CDATA[Enter Manager Rating]]></ename>
          <evalue><![CDATA[Whole Numbers Only]]></evalue>
</fm-element>

    5. Review the Verify 1:1 Meeting occurred field code, and add a default value in <evalue> to make sure that it is reportable.

      Hint

      The checkbox field ename does not appear bolded as per design. However, as an optional step, you can make it appear as bold text by adding the HTML tag <b>YOUR TEXT</b>. See this example: <ename><![CDATA[<b>Verify 1:1 Occurred</b>]]></ename>
      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="4" type="9" checked="false" edit-in-mass-create="true">
          <ekey><![CDATA[ele_11]]></ekey>
          <ename><![CDATA[<b>Verify 1:1 Occurred</b>]]></ename>
          <evalue><![CDATA[N]]></evalue>
</fm-element>

    6. Review the Future Potential field code:

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910111213141516171819
      <fm-element index="5" type="6">
          <ekey><![CDATA[ele_8]]></ekey>
          <ename><![CDATA[Future Potential]]></ename>
          <evalue><![CDATA[]]></evalue>
          <elist elist-value-type="7"  elist-default-name="Select one"  elist-default-value="0">
              <elist-element elist-index="0" elist-selected="false">
                <elist-name><![CDATA[Low Potential]]></elist-name>
                <elist-value><![CDATA[1]]></elist-value>
              </elist-element>
              <elist-element elist-index="1" elist-selected="false">
                <elist-name><![CDATA[Medium Potential]]></elist-name>
                <elist-value><![CDATA[2]]></elist-value>
              </elist-element>
              <elist-element elist-index="2" elist-selected="false">
                <elist-name><![CDATA[High Potential]]></elist-name>
                <elist-value><![CDATA[3]]></elist-value>
              </elist-element>
          </elist>
</fm-element>

    7. Review the Potential Mentor field code:

      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="6" type="3" min="1" max="500" edit-in-mass-create="true">
          <ekey><![CDATA[ele_5]]></ekey>
          <ename><![CDATA[Potential Mentor]]></ename>
          <evalue><![CDATA[Full Name]]></evalue>
</fm-element>

    8. Review the Additional Comments field code:

      Code Snippet
      Copy code
      Switch to dark mode
      12345
      <fm-element index="7" type="4" waca="false" edit-in-mass-create="true" mime-type="plain-text">
          <ekey><![CDATA[ele_1]]></ekey>
          <ename><![CDATA[Additional Comments]]></ename>
          <evalue><![CDATA[Any additional comments about this employee's potential?]]></evalue>
</fm-element>

    9. Validate the XML template, and save as a new version.

    10. Navigate to Provisioning → Form Template Administration, and choose your performance form template from the Template Name list.

    11. Select Update by upload , and Choose File to select your updated XML template.

    12. Choose Upload Form Template to confirm.

Result

Once the XML modifications are completed, your section will look like the image Evaluation of Potential Custom Section - Updated above.

Log in to track your progress & complete quizzes