Creating and Configuring Drop Zones

This topic provides an overview of drop zones on fluid pages and discusses how to:

  • Create configurable drop zones for subpages.

    Note: Typically, as an Oracle customer, you can skip this step. PeopleSoft application teams have already added one or more configurable drop zones on selected fluid pages.

  • Create subpages for dynamic injection into drop zones.

  • Configure drop zones.

Configurable drop zones allow you to add fields to delivered fluid pages without customizing the component or fluid page definition. Your fields are displayed and processed along with fields from the main fluid page definition and any nested fluid subpages.

At design time, a placeholder subpage stub (PT_ERCSUBPAGE_STUB) is inserted into a related content group box on the fluid page definition, creating what is referred to as a “drop zone.” Drop zones can be added to a main fluid page, to fluid subpages at any nesting level, and to fluid secondary pages. Typically, PeopleSoft application teams (PeopleSoft HCM, PeopleSoft FSCM, and so on) have identified which delivered fluid pages can be extended by customers and have already added one or more configurable drop zones on these fluid pages, subpages, and secondary pages. Then, you create subpage definitions and associate your subpages to one or more drop zones. Finally, at runtime during the component build process, the configured subpage dynamically replaces the subpage stub. The records and fields defined on your subpage are loaded into the component buffer along with the records and fields from the main page definition.

The complete procedure for creating and configuring drop zones includes three tasks described within this topic:

  1. (Optional) Creating configurable drop zones.

    If you merely want to take advantage of the drop zones delivered with your PeopleSoft application, you can skip this step. Otherwise, if you want to create additional drop zones, see Creating Configurable Drop Zones for Dynamic Subpages.

  2. Creating subpages for these drop zones.

    See Creating Subpages for Dynamic Injection into Drop Zones.

  3. Configuring a selected drop zone by associating a subpage to it.

    See Configuring Drop Zones.

Note that adding a related content group box on a fluid page creates a “drop zone.” These drop zones can be configured for two purposes:

  • Embedded related content only.

    Note: The absence of the PT_ERCSUBPAGE_STUB subpage means that such a group box can be configured for embedded related content only.

    Embedded related content was introduced in PeopleTools 8.55. While the procedure for creating and configuring embedded related content has not changed, the group box itself is now also referred to as a drop zone. See Working with Embedded Related Content.

  • Dynamically injected subpages or embedded related content.

    A related content group box created for dynamically injected subpages could be configured for embedded related content instead. However, both uses cannot coexist simultaneously. If a drop zone already configured with embedded related content is reconfigured with a subpage, then the embedded related content configuration is overridden. If a drop zone is already configured with a subpage, it will not be available for configuration with embedded related content.

Typically, PeopleSoft application teams have already added one or more configurable drop zones on selected fluid pages, subpages, and secondary pages; therefore, creating drop zones is not a usually a task you would undertake. However, in some cases, you may want to add drop zones to other fluid pages. To do so, you would follow the same steps used by PeopleSoft application development teams.

Note: Adding a drop zone to a page definition delivered by Oracle is considered a customization.

Guidelines for Creating Configurable Drop Zones for Dynamic Subpages

Note: The following guidelines are valid for conventional components only. For “derived components”—that is, components with a derived record structure—you must carefully evaluate the derived record and key structure and database fetch, save, and commit mechanisms since these will not necessarily rely on the built-in processing of the PeopleTools component processor. Depending on the fluid component’s architecture, adding a drop zone may or may not work and must be tested thoroughly.

Adhere to the following guidelines when creating configurable drop zones for dynamic subpages:

  • Insert the PT_ERCSUBPAGE_STUB subpage stub (which is identified on the PeopleTools Options page).

  • Do not insert any other page controls within the related content group box.

  • If you add a drop zone on a secondary page, then you must also insert a secondary page control on the main page or subpage that launches the secondary page.

  • If you add a drop zone on a subpage or a secondary page rather than on the main fluid page, then you must ensure that each drop zone that will be displayed along with the main fluid page at runtime can be uniquely identified. The PeopleSoft system uses the combination of occurs_lvl.RECORD_NAME.FIELD_NAME.Field_ID to identify each group box as a page record field. By associating each group box to a unique RECORD.FIELD, you will ensure that each can be uniquely identified.

    Image: Unique page field identifier

    The information that uniquely identifies page field can be found on the page definitions Order tab. In the following example, Top of Page Drop Zone is uniquely identified as 0.MYQKCONT_WRK.MQC_DZ_1.2.

    Unique page field identifier

    Important! Because the PeopleSoft system uses the combination of occurs_lvl.RECORD_NAME.FIELD_NAME.Field_ID to identify each drop zone, you cannot make any updates that would change any of the elements of this unique identifier such as moving the drop zone to a different occurs level, changing the associated RECORD.FIELD, or deleting the drop zone. Any such change will orphan and break existing configurations based on that drop zone. If you need to make any such updates, delete any existing configurations first so that they are not orphaned. Make the required changes. Then, re-establish the configuration.

Adding a Related Content Group Box for Dynamic Subpages

To add a related content group box for dynamic subpages:

  1. Insert a group box on your fluid page in the general position you would like to display the content from the dynamic subpage.

  2. Double-click the group box to open the Group Box Properties dialog box. Then, on the Fluid tab, set the Group Box Type to Related Content.

  3. (Optional) Apply styling, if needed, to this group box that will only be rendered if a subpage is configured for this drop zone.

  4. Select the Label tab and enter a descriptive label to identify this related content group box as a drop zone. Enter a label that describes the position, purpose, or both for this drop zone. The label is not rendered at runtime, but it will help at design time by:

    • Differentiating this drop zone from any others on this page as well as any associated subpages or secondary pages.

    • Providing a label on the drop zone during fluid page preview.

    • Providing a label for the drop zone during the drop zone configuration task, which displays all available drop zones from the component.

  5. Associate a record field to this drop zone to ensure that it has a unique page field identifier.

  6. Insert the PeopleTools-defined PT_ERCSUBPAGE_STUB subpage stub into the related content group box:

    • The upper left corner of the subpage must be located within the group box.

      Image: PT_ERCSUBPAGE_STUB subpage

      In this example, the upper left corner of the PT_ERCSUBPAGE_STUB subpage is located within the related content group box.

      PT_ERCSUBPAGE_STUB subpage within a related content group box

    • The subpage must be listed immediately after the group box on the Order tab for the page definition.

      Image: Page definition: Order tab

      In this example, the PT_ERCSUBPAGE_STUB subpage immediately follows the Data Area Drop Zone (Level 1) group box on the Order tab.

      Page definition: Order tab

      Important! If you insert multiple drop zones on the same page, always inspect and fix the order of group boxes and subpages on the Order tab.

  7. Save your changes.

  8. (Optional) Use the page preview in Application Designer to preview the page with related content drop zones.

Considerations for Creating Dynamically Injected Subpages

Consider the following when creating subpages for dynamic injection into drop zones:

  • The records and fields defined on your subpage will be loaded into the component buffer along with the records and fields defined on the page containing the drop zone.

  • Multiple updatable tables are allowed at level 0.

  • If you add a grid or scroll area to the subpage, you must add a horizontal rule after it to reset the level to 0.

  • Unlike when a subpage is added directly as a page control on a main page definition, with this sort of dynamically injected subpage you cannot perform a record name substitution (that is, identify a from record on the subpage and a to record from the main page).

  • Record field PeopleCode defined on your subpage will execute as part of the events in the component processor flow. If your implementation requires other scenarios or PeopleCode events, (for example, page Activate, PreBuild, PostBuild, component record, or component record field events), then you should use PeopleCode event mapping to avoid customizing delivered components and pages. See Mapping Application Class PeopleCode to Component Events for more information.

  • The fields from your subpage that are dynamically added to the component buffer at runtime are not available in the component’s search record.

Creating a Subpage Definition

To create a subpage definition:

  1. In Application Designer, select File, New.

  2. Select Page (Fluid) in the New Definition dialog box, and click OK.

  3. Select PSL_SIMPLE_SBP to create a fluid subpage.

  4. Click Choose and enter the page name in the Save As dialog box.

  5. Indicate whether you’d like to save the PeopleCode associated with the layout page for your new page (Yes/No).

    Note: Typically, click Yes to include any PeopleCode from the layout page.

  6. Open the Page Properties dialog box.

  7. On the Use tab, select Subpage to specify this as a fluid subpage.

  8. Add page controls on your subpage definition.

Use the Configure Drop Zones component to search for, select, and configure components containing configurable drop zones.

Navigation

PeopleTools > Portal > Configure Drop Zones

Image: Configure Drop Zones search page

This example illustrates the fields and controls on the Configure Drop Zones search page. You can find definitions for the fields and controls later on this page.

Configure Drop Zones search page

You must enter one or more search criteria to perform a search using this page. You may use % as a wildcard.

Field or Control

Definition
Component

Enter a definition name for the component as search criteria.
Description

Enter the description as defined on the General tab of the Component Properties dialog box as search criteria.
Market

Select the market for the component from the drop-down list.
Object Owner ID

Select the object owner ID for the component from the drop-down list.
Configured Subpage

Enter the definition name for an already configured subpage as search criteria.

Important! Search results may include components that cannot be configured because no drop zones are available in the component. Clicking such a component in the list will display a message that no drop zones are available.

In the search results, click a row to configure the available drop zones for that component.

Image: Configure Drop Zones configuration page

This example illustrates the fields and controls on the Configure Drop Zones configuration page. You can find definitions for the fields and controls later on this page.

Configure Drop Zones configuration page

Field or Control

Definition
Page Name

Displays the name of the main fluid page that contains a drop zone or that contains a subpage with a drop zone, or it displays the name of a secondary fluid page that contains a drop zone.

Note: Subpage names are not displayed in the grid; only the name of the main page that contains the subpage or nested subpage is displayed.

Note: If you are attempting to configure a secondary page and that page does not appear on the list for this component, then there is no definitional chain of page definitions to open the secondary page. If you add a drop zone on a secondary page, then you must also insert a secondary page control on the main page or subpage that launches the secondary page.
Tab Order

Displays the tab order number for the drop zone from the Order tab of the page definition (page or subpage) where the related content group box is physically defined.
Drop Zone

Displays the label for the drop zone, which is derived from these values in descending order of precedence:

  • The label for the related content group box.

  • The default label for the RECORD.FIELD associated with the group box.

  • A string that is the concatenation of the page definition (page or subpage) where the related content group box is physically defined plus the field ID for the group box as found on the Order tab. For example:

    PAGE_NAME_ID.Field_ID

Important! If the label of a field other than the drop zone group box is displayed, then the PT_ERCSUBPAGE_STUB subpage is positioned incorrectly on the page definition. In particular, check the Order tab.

Used By Related Content

Indicates that this drop zone has been configured for embedded related content. Reconfiguring it with a subpage overrides the embedded related content configuration.
Subpage Name

Select a fluid subpage to associate with the drop zone.

To remove a subpage configuration, clear the Subpage Name field and save your changes.
Reconfigured

Indicates that an existing subpage configuration has been changed.