AgileApps Support Wiki Pre Release

Difference between revisions of "Enumerated Fields"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Β 
(60 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[File:Movie-rating.gif|right|thumb|Graphic stars illustrate movie rating]][[File:Enumeratedstatus-text.gif|right|thumb|Color-coded Labels]]Enumerated fields provide powerful visual impact in [[Views]], by displaying a graphic image or color-coded label in place of field values. Enumerated fields have an associated numeric value, which can be used to group, sort or filter data in [[Views]] and [[Reports]]. In [[Reports]], enumerated fields can appear as color-coded labels, only. Β 
Enumerated fields can provide a powerful visual impact by displaying a graphic image or color-coded label in place of field values.


==About Enumerated Fields==
Enumerated fields have an associated numeric value, which can be used to group, sort or filter data in [[Views]] and [[Reports]].
===Enumerated Types===
These [[Field Display Types]] are enumerated:
These [[Field Display Types]] are enumerated:
:*Radio Buttons
:*Radio Buttons
Line 9: Line 13:
:*[[Multi Select Picklist]]s
:*[[Multi Select Picklist]]s


==About Enumerated Fields==
===Using Enumerated Fields with Other Platform Elements===
Enumerated Fields in [[View]]s provide users with visual indicators of a data metrics. In this example, a movie library View is enhanced with the addition of stars to rank the movies by preference. Although the ranking (Picklist Value) is not displayed, it is used to sort the list.
Because Picklist Values can contain alphanumeric characters, additional functionality becomes available, as listed here:


:{| border="0" cellpadding="25" cellspacing="0"
:;Sort order: Use the Picklist value in Views and Reports to define sort order
|[[File:Movie-name.gif|none|thumb|Sorted by Movie Name]]||[[File:Movie-rating.gif|none|thumb|Sorted by Movie Rating (Stars)]]
:;Grouping: Use the Picklist value to Group records in Views and Reports
|}
:;Display in Views: The Display Labels are shown when displaying a record and in Views. Based on the options selected, the image and the text colors are shown.
:;Color coding in Views:Criteria can be specified using Display Labels or Picklist values; The first match is done using the display label, followed by the Picklist value
:;Searches/Filters in Views:Criteria can be specified using display labels or Picklist values; The first match is done using the display label, followed by the Picklist Value
:;Global Search:Global search can use the Picklist values
:;Display in Reports:The Display Labels are shown (no images or color coding are displayed)
::Reports must not use the [[Report_Group|Group]] option
:;REST or JAVA API:The Picklist values are returned (not the display label)
:;Conditional Layouts:Layout rules can use the Picklist values


:The ranking (with 1-4 stars) is created by adding a series of images and values to eligible [[Field Display Types]]:


:{| border="0" cellpadding="15" cellspacing="0"
===Manage and Reorder Values===
|valign="top"|[[File:Enumeratedpicklist-setup-stars.gif|none|thumb]]
{{:Manage and Reorder Enumerated Values}}
|valign="top"|Because the Picklist Value is stored in the database, it can be used in these areas of the platform:
*''Sort order'' in Views and Reports
*''Filters'' in Views and Reports
*''Color coding'' criteria in Views and Reports
*''Grouping'' criteria in Reports


Learn more: [[#Using Enumerated Picklists with Other Platform Elements|Using Enumerated Picklists with Other Platform Elements]]
==Checkboxes and Radio Buttons==
|}
Working with Checkboxes and Radio Buttons is almost identical to the process for Working with Picklists, described next. The only real difference is in the way that values are displayed, and the number of selections a user can make.Β 


*Enumerated fields include these elements:
==Picklists==
:*;Display Label:Can be either an alphanumeric string or an image, or both
{{:Working with Picklists}}
:::*Alphanumeric string, with optional color coding for text and background color
:::*Image, optional, selected from the [[Documents]] object
:::*''Not'' used to group, sort, or filter records


:*;Item Value:
==Global Picklists==
:::*Stored as part of the record
:::*Used to group, sort, or filter records
:::*A number that can be used to define the display order


==Working with Enumerated Fields==
===Create a Global Picklist===
#Click '''[[File:GearIcon.png]] > Customization > Objects > {object} > Fields'''
#Click '''[New Field]'''
#Fill in the information in the sections below
#Click '''[Save]'''<br/>The field is added, and the field-definition is shown.
{{Note|To [[#Manage and Reorder Values|Manage and Reorder Values]], go to the field definition in the [[Global Picklists]]--but note that any changes made to a Global Picklist apply to all fields that reference it.}}


===Create an Enumerated Global Picklist===
====Basic Information====
#Click '''Designer > Global Resources > Global Picklists'''
:* '''Display Type -''' Global Picklist
#Click the [New Global Picklist] button and enter the following information:
:* '''Picklist -''' Select one of the predefined [[Global Picklists]], or one that you have created.
#;Name:The field label that will be displayed
{{:Common:Enumerated Field Sections}}
#;Type:Enumerated - Complete the following information:
#:*Show First Value as Default - Checkbox
#:*Sort List Alphabetically - Checkbox
#*Click the [Save] button to save your changes
{{:Manage Enumerated Values}}
#Optionally, click the [Reorder Picklist Values] button to change the order (applies only when ''Sort List Alphabetically'' option is unchecked)


===Managing Enumeration Values===
:[[File:EnumerationValues.png|none]]
===Setting Colors and Images for Enumeration Values===
When you create text labels in enumerated fields, you can specify the color of the text and/or the background color, as in this example:
:[[File:Enumeratedstatus-text.gif|none|Text and background colors]]
Or you can choose to display graphic images:
:[[File:Enumeratedstatuscheck.gif|none|Arrows indicate Status]]
===Use Label for Grouping===
[[File:Picklistgroupbylabel.gif|right|upright|thumb|''Fruit'' and ''Vegetable'' are group labels]]Use this option to group picklist values by label. The ''Use Label for Grouping'' option is useful when a picklist is long, and can be organized into groups.
To Use Label for Grouping:
#Create a [[Picklist]] (or [[Global Picklist]] with Type = Enumerated)
#:*Enter the values in the desired order
#:*Include the labels inline with the values
#::[[File:Fruitpicklist.gif|none|thumb]]
#In the Enumerated Values section, select the intended label
#::[[File:Enumeratedpicklist-label.gif|none|thumb|''Fruit'' and ''Vegetable'' are the intended group labels]]
#:Click the ''Use Label for Grouping'' checkbox
#::[[File:Picklistuselabel.gif|none|thumb]]
#Repeat for each intended label
==Additional Operations==
===Create a Dependent Picklist===
When the possible choices depend on selections made in other fields, use a [[Dependent Picklist]].
===Using Enumerated Fields with Other Platform Elements===
Because Picklist Values can contain alphanumeric characters, additional functionality becomes available, as listed here:
:;Sort order: Use the Picklist Value in Views and Reports to define sort order
:;Grouping: Use the Picklist Value to Group records in Views and Reports
:;Display in Views: The Display Labels are shown when displaying a record and in Views. Based on the options selected, the image and the text colors will be shown.
:;Color coding in Views:Criteria can be specified using Display Labels or Picklist Values; The first match is done using the Display Label, followed by the Picklist Value
:;Searches/Filters in Views:Criteria can be specified using Display Labels or Picklist Values; The first match is done using the Display Label, followed by the Picklist Value
:;Global Search:Global search will use only the Picklist Values
:;Display in Reports:The Display Labels are shown (no images or color coding are displayed)
::Reports must not use the [[Report_Group|Group]] option
:;REST or JAVA API:The Picklist Values are returned (not the Display Label)
:;Dependent Picklists:Learn more: [[Dependent Picklist]]
:;Conditional Layouts:Layout rules will use only the Picklist Values


==Considerations==
==Multi Select Picklists==
{{:Multi Select Picklist}}


:*The ''Use Label for grouping'' option is only available for Picklists
::*After the ''Use Label for grouping'' option is selected, the ''Sort List Alphabetically'' option is reset to ''NO''
::*If the ''Use Label for grouping'' option is selected, the enumerated values are not available for dependent field associations
::*After a dependent field association is created, the ''Use Label for grouping'' option cannot be enabled for any of the parent or dependent field values
:*A field cannot be deleted if it is a "parent" for a dependent field
:*If the "parent" field of a dependent field is changed, a confirmation message appears, requesting the user to acknowledge that data will be lost if the change is executed
:*Dependent picklist values cannot be reordered


:''Learn more:'' [[Enumerated Field Behavior For REST Web Services]]
==Dependent Picklists==
{{:Dependent Picklist}}

Latest revision as of 21:11, 25 June 2013

Enumerated fields can provide a powerful visual impact by displaying a graphic image or color-coded label in place of field values.

About Enumerated Fields

Enumerated fields have an associated numeric value, which can be used to group, sort or filter data in Views and Reports.

Enumerated Types

These Field Display Types are enumerated:

Using Enumerated Fields with Other Platform Elements

Because Picklist Values can contain alphanumeric characters, additional functionality becomes available, as listed here:

Sort order
Use the Picklist value in Views and Reports to define sort order
Grouping
Use the Picklist value to Group records in Views and Reports
Display in Views
The Display Labels are shown when displaying a record and in Views. Based on the options selected, the image and the text colors are shown.
Color coding in Views
Criteria can be specified using Display Labels or Picklist values; The first match is done using the display label, followed by the Picklist value
Searches/Filters in Views
Criteria can be specified using display labels or Picklist values; The first match is done using the display label, followed by the Picklist Value
Global Search
Global search can use the Picklist values
Display in Reports
The Display Labels are shown (no images or color coding are displayed)
Reports must not use the Group option
REST or JAVA API
The Picklist values are returned (not the display label)
Conditional Layouts
Layout rules can use the Picklist values


Manage and Reorder Values

The Enumerated Values section of the field-definition page, lets you specify the picklist values and the order in which they appear.

To specify which values appear:

  1. Click [Manage Values]
  2. Click the box under the Trash can to remove an item.
  3. Click [Add More Rows] to add additional items
  4. Click [Save] when done
Settings
  • Display Label - The label to display in the list.
  • Value - The actual value that is stored in a record (or returned to a program) when the item is chosen from the list. When the field is used to group, sort, or filter records, it is the value of the field that determines the outcome.

Notepad.png

Note: Alphanumeric Characters are allowed in labels and values, including special characters (+ / ' - _) and spaces.

Reorder Values

In the Enumerated Values section of the field-definition page, click [Reorder Values] to change the order in which the values appear:

Picklist ReorderValues.png

Notepad.png

Note: Reordering can be done only when the Sort List Alphabetically option is unchecked.

Checkboxes and Radio Buttons

Working with Checkboxes and Radio Buttons is almost identical to the process for Working with Picklists, described next. The only real difference is in the way that values are displayed, and the number of selections a user can make.

Picklists

A Picklist is a field that can contain a list of values. It appears as a dropdown list when displayed.

Create a Picklist

  1. Click GearIcon.png > Customization > Objects > {object} > Fields
  2. Click [New Field]
  3. Provide the information in the sections below.
  4. Click [Save]
    The field is added, and the field-definition is shown.

Basic Information

Specify the basic characteristics of the field:
  • Label - The text that appears as the field name
  • Display Type - Picklist
  • Picklist Values - For a simple Picklist that returns the same values it displays, with no special colors, images, or groups for the display values, you can simply enter the values, as shown here:
EnumeratedPicklist-new.png
Otherwise, wait until the Picklist has been created, then Manage and Reorder Values.
  • Maximum Storage Length - The String length of the longest value in the list.
  • Use First Value as Default - Otherwise, the field is initially empty.
  • Sort List Alphabetically - Otherwise, you manually arrange the order.
  • Skip Value Validation - When checked there is no validation of the Enumerated Values. By default, this option is unchecked.

Notepad.png

Note: This option is available only for custom fields and not for standard fields. For standard picklists, value validation cannot be turned off.

  • Always Required - A selection must be made when adding or updating a record.
  • Field Name - Automatically created by the system (but you can change it here)

Display Attributes

Determine where the field is displayed in the default form, and whether or not the field is required when adding or updating a record.

Default Value

In general, the default value you specify will be a simple String. For example: 'rush'. But it is also possible to select functions and specify arguments, creating a formula expression that returns the default value.

Picklist DefaultValue.png
Considerations
  • The default value must resolve to the value of an entry in the list of enumerated items (not a label).
  • If the value resolves to a string which is not in the list of the enumerated items, it is as though no default were specified. Nothing is pre-selected in the Enumerated Field.
  • Field Visibility determines which roles can see or edit the field.

Description Information

Include a description of the field and its use. This information is only visible to users with rights to customize this field.


Global Picklists

Create a Global Picklist

  1. Click GearIcon.png > Customization > Objects > {object} > Fields
  2. Click [New Field]
  3. Fill in the information in the sections below
  4. Click [Save]
    The field is added, and the field-definition is shown.

Notepad.png

Note: To Manage and Reorder Values, go to the field definition in the Global Picklists--but note that any changes made to a Global Picklist apply to all fields that reference it.

Basic Information

  • Display Type - Global Picklist
  • Picklist - Select one of the predefined Global Picklists, or one that you have created.

Display Attributes

Determine where the field is displayed in the default form, and whether or not the field is required when adding or updating a record.

Default Value

In general, the default value you specify will be a simple String. For example: 'rush'. But it is also possible to select functions and specify arguments, creating a formula expression that returns the default value.

Picklist DefaultValue.png
Considerations
  • The default value must resolve to the value of an entry in the list of enumerated items (not a label).
  • If the value resolves to a string which is not in the list of the enumerated items, it is as though no default were specified. Nothing is pre-selected in the Enumerated Field.
  • Field Visibility determines which roles can see or edit the field.

Description Information

Include a description of the field and its use. This information is only visible to users with rights to customize this field.


Multi Select Picklists

Multi Select Picklists provide options in a field to make multiple selections from a list of values in a Global Picklist.

In the global picklist, although the labels for the enumerated values may contain commas, the enumerated values may not contain commas.

For Multi Select Picklist fields where the labels include commas, vertical orientation is the better choice

Considerations
  • The value stored in the database is a comma-separated list of labels, one for each selection. So:
  • If you change the order of the values, new values may be stored differently than old ones.
  • To avoid a Data Truncation Error at runtime, make sure the field is large enough to contain all possible selections.
  • Calculate the size as the sum of the entry lengths, plus N-1 for the commas between them, where N is the number of entries.
  • Use an expression like this one to mark a single box in a Rule action:
IF( ISNULL(field), 'checkboxLabel', field+', checkboxLabel')
  • If the field is empty, the label is assigned to it. If the field has a value, the checkbox label is appended to it.
  • The checkbox label is case-sensitive, and must match the configured value exactly.
  • Spaces are allowed between items in the value-list (but be sure to size the field appropriately.)
  • To uncheck a box in a rule, you need one of two expressions:
REPLACE(field, ', checkboxlabel', '') - for multiple selections, or
REPLACE(field, 'checkboxLabel', '') - for a single selection
The expressions then need to be placed inside of a nested IF statement to see if either one applies:
IF (CONTAINS(field, ', checkboxLabel'), -first replacement-,
IF (CONTAINS(field, 'checkboxLabel'), -second replacement-, field) )
  • This expression does the appropriate substitutions of the label is present. Otherwise, it returns the original field.


Dependent Picklists

A Dependent Picklist provides a list of choices, where the available options are determined by some other value.

About Dependent Picklists

A Dependent Picklist can be based on a set of Radio Buttons or a standard Picklist. The value of that field is the triggering value. When that value is present in the record, or when the user selects a value in that GUI, the value determines which options are present in the Dependent Picklist.

For example, suppose you have a request management system for a software application. In that application, you might set up radio buttons to specify the kind of request: Software (coding) or Documentation. A Dependent Picklist could then be used to set up a different set choices for each kind of request:

Kind of Request Request Type
Software
  • Bug Report
  • Feature Request
Documentation
  • Bug Report
  • New Feature Writeup
  • Documentation Enhancement
    (for a new document, for example, or an improvement)

A single Request Type field can then be used for each kind of request, with an appropriate set of choices for each kind.

Learn more: Enumerated Fields
Considerations
  • A field cannot be deleted if it is the triggering value for a dependent field.
  • If the triggering field for a dependent field is changed, a message appears telling you that data will be lost if the change is executed. Confirmation is required to proceed.

Adding a Dependent Picklist

This is a four-step process:

  • Create the triggering field (also known as the parent field).
  • Create the dependent picklist.
  • Specify the complete collection of options that will be available.
  • For each possible triggering choice, specify which of the available options appear in the dependent picklist.

To add a dependent picklist:

  1. Create a triggering field with one of the following types, and add values to it:
  2. Create a new field of type Dependent Picklist
  3. Fill in the basic field settings:
    Label
    The field label that will be displayed
    Display Type
    Dependent Picklist
    Parent Field
    • Select the "parent" field (the triggering field)
    • Enter the picklist values
    Maximum Storage Length
    Specify a number of characters that is equal to or greater than the size of the longest value-string that can be selected. Otherwise, a Data Truncation Error may occur at runtime.
    Show First Value as Default
    This setting causes the first value in the presented list of values to be the default. Otherwise, there is no default.
    Sort List Alphabetically
    This setting causes the values in presented list to be sorted alphabetically. Otherwise, they are displayed in the order defined in the Manage Values section.
    Tip:
    It is the values that are sorted, not the display labels. A common practice is to add numbers to the values so the entries display in the order you want them.
    (The remaining attributes are standard Field properties.)
  4. Click [Save]
    A new section appears: Enumerated Values.
  5. In the new section, click [Manage Values]
  6. Specify the entire collection of possible values.
    In the example given above, the list would consist of:
    • Bug Report
    • New Feature Request
    • New Feature Writeup
    • Documentation Enhancement
  7. Click [Save]
    A new section appears: Dependent Picklist Assiciations.
  8. In the new section, click [Add Associations]
  9. In the Parent Values field, select one of the triggering values.
    Two list boxes appear.
    Note: Field values are shown, not their display labels.
  10. Move items from the Available Items list to the Selected Items list.
    Selected items appear as options in the dependent picklist, for that particular triggering value.
  11. Click [Save]
  12. Repeat the last few steps to add additional associations for each of the possible triggering values.
    Learn more: Enumerated Fields#Manage and Reorder Values