Which Workday Extend widget to use for what

Choose by the job, then check the page type

In a Workday Extend Page Metadata (PMD) file, use instanceList whenever the user picks a Workday or app record, dropdown or radioGroup for one value from a short fixed list, text or textArea for free text, and grid for rows. Then check the page type, because some widgets are edit-only or view-only: dropdown, radioGroup, checkBoxList, snapSlider and pageActionButton work only on edit pages, while hub, listDetailHub, editWizard and the classic chart tags work only on view pages. Workday's PMD Tags reference marks each tag view, edit or both, plus whether it's mobile-enabled.

Letting a user choose values

The instanceList is the Workday-native choice for anything that is a record. It searches as the user types. It can drill down through levels with monikerLevels. It can search a large source through searchEndPoint or an onSearch handler instead of preloading everything. On a view page, setting the instance's wid turns each value into a link with the related actions menu, the way Workday's own pages show workers and organizations. Use a dropdown or radioGroup only when the options are a short list you control, such as Low, Medium or High.

The instanceList, dropdown, checkBoxList and snapSlider widgets hold their value as a list of strings, even when only one value is selected. Read the first selection with value[0], and its display text with selectedEntries[0].descriptor. For lists that depend on each other, see cascading dropdowns and instance lists.

Letting a user enter data

The 255-character limit also applies to every widget's label. Use textArea for any field whose data can run past 255 characters, such as a description or a comment from an endpoint.

Showing records

• One value, read-only, on any page: readOnlyText (with formatAsDate for dates) or a text with enabled set to false on an edit page.
• Rows of data: grid. On an edit page users can add, change and remove rows. On a view page you can page large results with autoPaging or pagingInfo, and sort and filter columns.
• A list of panels, each with its own fields: panelList, editable on an edit page. Use it when each item needs a layout of its own, which a table row can't give.
• The same widget repeated per item, outside a table: loop. It creates no widget of its own and only iterates.
• Progress toward a total: progressIndicator.
• Charts: the chart tags on view pages. Charts 2.0 tags can also appear read-only on an edit page, and update with the data there only inside a dynamicSection.

For a grid that users edit, see posting every row of a grid and grid validation.

Laying out the page

Use section to group widgets, vertically by default or horizontal. Use fieldSet when the group needs a title, should be collapsible, or contains widgets you show and hide. Workday's best practices say a widget whose visibility changes should sit in a fieldSet, because setVisible inside a plain section can behave inconsistently. They also advise against nesting fieldSet inside fieldSet.

For the whole page body, Workday provides structured layouts that must be the top-level tag in body:

• basicFormLayout: bordered sections stacked down the page. It's a plain form.
• columnLayout: 1 to 3 responsive columns. A single column takes the centre two thirds of the page.
• areaLayout: a primary and a secondary area.
• multiStepLayout: up to 10 numbered steps, wizard-style.

For a hub of related pages, hub gives a left navigation pane with task pages on the right (view pages only), and listDetailHub builds those links from data. To guide a user through several independent tasks with an optional summary page, use editWizard. For how these combine into a page that looks native, see designing Extend pages that look like Workday.

Buttons and navigation

The three button widgets do different jobs:

• button navigates to another page of the app through taskReference (the task id from the AMD, not the page id; a wrong one returns a 404), or to a Workday task or report through workdayTaskReference. For a script, Workday points you to pageActionButton. Its action is PRIMARY for the main forward step, AUXILIARY (the default) for secondary actions, or LINK.
• pageActionButton runs an onClick script on the current edit page, on pages that use PMD Scripting. It always shows as a gray button.
• editButtonBar changes the edit page's OK button (its label, for instance Submit) and adds more submitting buttons. It can't change Cancel. To hide that, set standardEditButtonsHidden to true on presentation.

For a menu of navigation options, use buttonGroup or dropDownButton. For a URL outside the app, use externalLink.

Limits that change the choice

These limits from Workday's Presentation Components reference rule some designs out early. Inbound endpoints are capped at 30 non-deferred ones in PMDs and pods, and outbound endpoints at 30. Each endpoint times out at 24 seconds and each request at 60 seconds. An endpoint response can be up to 25 MB, and a presentation file up to 100 KB. A page with many lists that each load their own endpoint at page load hits the endpoint and timeout limits first. Mark endpoints that only feed later choices as deferred, and call them with invoke() when the user needs them.