Pods

Overview

As your app grows, you may find that you repeatedly use the same UI elements across multiple PMD pages. At first, you might start by copying and pasting the widget code into each PMD file. But if your app's design or data model changes down the line, you'll be stuck making the same updates multiple times throughout your app.

Pods are a feature for reusing PMD code across your Workday Extend app. You can extract the shared widgets or logic into a single pod file, which you can then use in as many PMD files as you want.

Objectives

By the end of this chapter, you will be able to:

Create a pod file with reusable PMD code.

Use a pod widget in a PMD file.

Add a parameter to a pod definition and pass in its value from a PMD file.

Pods

A pod contains reusable PMD tags, which you can invoke from multiple pages. Pods are useful for implementing a common look and feel across the pages in your app.

For example, you might use a pod to:

Define a single footer for all your app pages.

Modularize a piece of logic into a pod and then reference it wherever it's appropriate in your app.

Pods are reusable, which makes your app code easier to maintain. Instead of updating the same code in multiple pages, you only need to update the code in a single pod.

Defining a Pod

A pod is defined in a

.pod

file. To create a new pod in App Builder, add a Reusable Pod component.

A pod definition contains the following top-level attributes:

Attribute	Type	Description
podId	String	Required. The unique ID of a pod. PMDs reference the podId to invoke the pod.
seed	Object	Required. Contains the template widget and invocation parameters.

The pod

seed

object contains the following attributes:

Attribute	Type	Description
parameters	Array	Optional. Contains parameter names used for passing variable data into the pod.
template	Object	Required. Contains the template widget that defines the structure and data of the pod.
endPoints	Array	Optional. Contains inbound endpoints that fetch data to display in the template widgets.

The following example shows a pod definition for a universal footer component:

{
  "podId": "myFooterPod",
  "seed": {
    "template": {
      "type": "footer",
      "children": [
        {
          "type": "richText",
          "value": "Universal footer for all pages.",
          "enabled": false
        }
      ]
    }
  }
}

To use multiple widgets in a pod template, define the

template

attribute as a

section

tag. Within the

section

tag's

children

array, you can add multiple widgets. The following example defines a pod to display a text widget and a button to redirect the user to the home page.

{
  "podId": "helpTextPod",
  "seed": {
    "template": {
      "type": "section",
      "children": [
        {
          "type": "text",
          "value": "For additional support, please contact the Customer Help Desk."
        },
        {
          "type": "button",
          "action": "PRIMARY",
          "label": "Back to Home",
          "taskReference": {
            "taskId": "home"
          }
        }
      ]
    }
  }
}

Note
: A

.pod

file has a maximum file size of 100 KB.

Using a Pod in a PMD File

Once your pod has been defined, you can use it in your PMD files. To invoke a pod from a PMD, use the

pod

tag within the

presentation

section of the PMD.

A

pod

tag has the following attributes:

Attribute	Type	Description
type	String	Required. Value: "pod"
podId	String	Required. The ID of the pod to invoke. Your app must contain a pod with the specified podId.
parameters	Object	Optional. Contains custom key/value pairs that define the parameter values passed to the pod. The parameter keys should match the names defined in the pod's parameters array.

The example below shows how to use the helpTextPod in a PMD file:

{
  "id": "myPage",
  "endPoints": [],
  "presentation": {
    "title": { ... },
    "body": {
      "type": "section",
      "horizontal": "false,
      "children": [
        {
          "type": "pod",
          "podId": "helpTextPod"
        }
      ]
    }
  }
}

Note
: During the preprocessing of a PMD, Presentation Components replace any

pod

tags with the corresponding pod template. Any parameter values passed by the invoking PMD replace the corresponding parameters within the pod template.

These replacements happen before any data fetch from the inbound endpoints.

Pod Parameters

Within a pod definition, you can define parameters for passing dynamic values into the pod. Pod parameters make your code more flexible, which means you can reuse your pod template in a wider variety of circumstances.

Add a Parameter to a Pod Definition

Pod parameters are similar to function parameters. In your pod definition, you need to:

Define your parameter by adding its name into the

seed.parameters

array.

Use the parameter value with your pod template by using the

@@parameterName@@

notation.

For example, the pod definition below defines a parameter called

valueParam

and uses it in the pod template to set the value of the text widget:

{
  "podId": "textPod",
  "seed": {
    "parameters": [
      "valueParam"
    ],
    "template": {
      "type": "text",
      "value": "<% @@valueParam@@ %>"
    }
  }
}

Pass in a Pod Parameter Value from a PMD

When using a pod tag, you can pass in a parameter's value via the

parameters

object. In the example below, a PMD file renders the

textPod

from earlier with a hard-coded string value:

{
  "type": "pod",
  "podId": "textPod",
  "parameters": {
    "valueParam": "Enter a description."
  }
}

When this PMD snippet renders on the page, the pod will be replaced with the following contents:

{
  "type": "text",
  "value": "Enter a description."
}

Important
: When passing in a parameter value, you can either use a hard-coded string (like in the previous example) or a binding (using the

<% %>

notation).

To use a PMD expression for your parameter value, use the

<% %>

notation. For example:

{ "type": "pod", "podId": "textPod", "parameters": { "valueParam": "<% 'Hello ' + currentUser.name %>" } }