Flexible block

This block has three primary use cases:

1. Show an optionally editable form.
2. Show a list of data. Each list item may have its own detail form, which, again, is optionally editable.
3. Show some read-only HTML.

Alternatives to the flexible block

Historically, the app has used flexible blocks extensively. However, new functionality rarely uses this block because there are often better alternatives to address each use case. Before creating a flexible block, consider your use case and the recommendations below:

Use-case	Recommendation
I want to show a list of items that come from the database (typically multiple rows in a database table)	Use the List block instead
I want to show some fields from the database (typically a single row in a database table)	Use the Form block
I want to show some static text, such as instructional advice or a bullet-pointed list of static hyperlinks	Use the HTML block
I want to show a chart or some embedded analytics	Use the Chart block
I want to create a custom form that a user completes	Use the Form block
I want to copy an existing flexible block but use different Fast Formula	Use the Flexible block
I want to configure standard Applaud functionality based on a flexible block	Use the Flexible block

Flexible block settings

The block has these additional settings:

Parameter	Example Usage	Description
Layout	FORM LIST HTML	FORM: show a form, which is optionally editable LIST: Show a list of data. Each list item may have its own detail form, which again is optionally editable HTML: Show some read-only HTML
Data source	Applaud HR Person EIT	The Data source that populates the FORM or LIST block. For a FORM layout, the Data source is expected to return a single database row. For a LIST layout, the Data source is expected to return one or more database rows. If using a FORM layout, you can opt not to use a Data Source. In this case, the View formula will need to hard-code the data or use Database Items and Fast Formula functions. Not relevant for HTML layouts.
Order by	pei_information15_meaning DESC	The order to return the items from the Data source. This should be a valid SQL ORDER BY clause that only contains columns available in the Data source. The Example here is relevant to the example Data source. Not relevant for HTML layouts.
Joining columns	Checked with joining columns overridden	Advanced users only. You will not need to use this unless you use your own custom Data source and you change the column names or aliases for any of these joining columns. If you do, you should select the renamed column here from the customized Data source. Not relevant for HTML layouts.
View formula	XXX_BK_PASSPORT_VIEW	The Fast Formula controls the display of each item in a LIST, or the contents of a FORM. See Defining the View formula.
No items text	Looks like we don't have your passport on file. Add it here now.	The text to display when no items are returned by the Data source, or when the user does not have permission to view any items from the Data source.
Read only	Checked Unchecked	When selected, the FORM or LIST is non-editable. When unchecked, additional details will be needed to enable editing of a FORM or LIST items. Not relevant for HTML layouts.
Form	Person EIT (/public/xxas/emp/view/personeit.xml)	The Form that's used when editing the data in FORM layout, or when editing an individual item in LIST layout. This must be compatible with the Form handler; see Choosing the right form. Not relevant for HTML layouts.
Form handler	xxas_person_eit_pkg	The PL/SQL package name that accepts, validates, handles and saves the Form input. Only enter the package name and do not add the procedure or function name here. Note: this is different to entering Form handlers in the Form block. In most cases this is defaulted for you automatically. If you change this value, it must be compatible with the Form's definition; see Choosing the right form. Not relevant for HTML layouts.
Edit personalization formula	XXX_BK_PASSPORT_EDIT	Optional Fast Formula to set form field properties using advanced conditions. See Form personalization formulas. Not relevant for HTML layouts.
Base Oracle function	XXX Extra Information Types (XXX_HR_EIT_SS)	The Base Oracle function that has been configured for this process. This function is used to determine the AME Transaction and Workflow Process that will be used when saving. In particular, it expects this function to have the pAMETranType, pAMEAppId and pProcessName parameters set. Not relevant for HTML layouts.
Extra information type	XXX_MY_DFF_INFO_TYPE	The Extra Information Type DFF information type. Only applicable for EITs. See Special and Extra Information Types (SITs an EITs).
Special information type	XXX_MY_DFF_STRUCTURE_CODE	The Special Information Type DFF structure code. Only applicable for SITs. See Special and Extra Information Types (SITs an EITs).
Include search	item1_html item30_html	When selected, the list will provide an in-list search facility. You specify which fields (item1_html to item30_html) the app will search through to find results. You must ensure your Fast Formula returns the items you specify here, otherwise the search won't find any results. You cannot search for items that are not displayed; if you wish to make hidden attributes searchable consider using the List block.
Include filters	Field: item1_html Title: Absence type Type: Select multiple	When selected, the list will provide in-list filtering. You specify one row per filter that you wish to include. Field: the name of the item property that contains the value to be filtered. You can choose from any of item1_html through to item30_html. Title: a title for the filter, which is seen by the end-user Type: the type of filter: Select single is presented as a radio group and the user can only select one at a time. Select multiple is presented as checkboxes; the user can select any combination of values. Range allows a numeric range to be displayed. This item's value must return integers, not decimals or text strings.
Include sorts	Field: item1_html Title: Absence type Direction: ascending Selected by default: true	When selected, the list will allow the user to specify an alternative sort to the default sort. You specify one row per sort you wish to provide. Field: the name of the item property that contains the value to be sorted. You can choose from any of item1_html through to item30_html. Title: a title for the sort, which is seen by the end-user Direction: whether to sort ascending or descending. The list will sort according to the item's data type (string, boolean, number). Dates will be sorted as strings. Selected by default: select the sort that is the default sort when the list items are returned. Only one sort should have this checked.

Choosing the right form

When creating a Flexible block that is editable, you will need to specify the Form and in most cases, the Form handler defaults in automatically. The form handler looks for a particular set of fields with certain field Ids on the form; if any unexpected fields are present or if expected fields are removed it will result in run-time errors when saving.

These are the correct set of Forms and Form handler pairs that are available for use in the Flexible block:

Form	Handler(s)	Description
Attachments (/public/xxas/emp/view/attachments.xml)	xxas_attachment_pkg	Used for resumes
Contact details (/public/xxas/emp/view/contactdetails.xml)	xxas_per_contact_pkg	Used for creating contacts and updating contact basic details
Leave of absence (/public/xxas/emp/view/leaveofabsence.xml)	xxas_absence_management_pkg xxas_leave_of_absence_pkg	Used for absences. xxas_absence_management_pkg is for absences using the HR_GENERIC_APPROVAL_PRC workflow (new in R12); xxas_leave_of_absence_pkg is used for the HR_LOA_JSP_PRC workflow (11i onwards).
Payment methods (/public/xxas/emp/view/paymentmethods.xml)	xxas_payment_methods_pkg	Used for Bank details.
Person EIT (/public/xxas/emp/view/personeit.xml)	xxas_person_eit_pkg	Used for Person Extra Information
Assignment EIT (/public/xxas/emp/view/asgeit.xml)	xxas_asg_eit_pkg	Used for Assignment Extra Information
Person SIT (/public/xxas/emp/view/personsit.xml)	xxas_person_sit_pkg	Used for Person Special Information
Person address (/public/xxas/emp/view/personaddress.xml)	xxas_per_address_pkg xxas_per_contact_address_pkg	Used for person and contact addresses
Person basic details (/public/xxas/emp/view/personbasicdetails.xml)	xxas_per_basic_details_pkg	Used for person basic detail changes
Person phones (/public/xxas/emp/view/personphones.xml)	xxas_per_phone_pkg xxas_per_contact_phone_pkg	Used for person and contact phones
Qualifications (/public/xxas/emp/view/qualifications.xml)	xxas_qualifications_pkg	Used for professional and academic qualifications

Defining the View formula

The View formula is required and must be an existing Fast Formula. It is used to control the information displayed in the flexible block. The contents of your View formula will change depending on the layout you are using:

• If using a FORM layout, refer to Defining Formula for FORM layout
• If using a LIST layout, refer to Defining Formula for LIST layout
• If using an HTML layout, refer to Defining Formula for HTML layout

Defining Formula for FORM Layout

The Form layout consists of up to 30 pairs of Prompts and Data fields. The formula expects prompt-data pairs in the form of Item1_Prompt, Item1_HTML. Each Data field can support basic HTML markup, although in many cases you will simply pass plain text for a simple, unformatted display.

An example of setting prompt and data can be seen in the following sample formula:

/*====================================================
Formula Name: XXX_BK_ASSIGNMENT_VIEW
Formula Type: Applaud Assignment
Description:  Viewing basic assignment information
=====================================================*/

  Default for ASG_ORG            is 'Unknown'
  Default for ASG_JOB            is 'Unknown'
  Default for ASG_GRADE          is 'Unknown'
  Default for ASG_LOCATION       is 'Unknown'
  Default for ASG_SUP_FULL_NAME  is 'Unknown'
  Default for EMP_HIRE_DATE      is '0001/01/01 00:00:00' (date)
 
  Item1_Prompt = 'Department'
  Item1_HTML   = ASG_ORG
  Item2_Prompt = 'Job'
  Item2_HTML   = ASG_JOB 
  Item3_Prompt = 'Grade'
  Item3_HTML   = ASG_GRADE
  Item4_Prompt = 'Location'
  Item4_HTML   = ASG_LOCATION
  Item5_Prompt = 'Hire Date'
  Item5_HTML   = to_char(EMP_HIRE_DATE, 'Month ddth, YYYY')
  Item6_Prompt = 'Supervisor'
  Item6_HTML   = ASG_SUP_FULL_NAME
 
  RETURN Item1_Prompt, Item1_HTML,
         Item2_Prompt, Item2_HTML,
         Item3_Prompt, Item3_HTML,
         Item4_Prompt, Item4_HTML,
         Item5_Prompt, Item5_HTML,
         Item6_Prompt, Item6_HTML

This example does not use any data that may be available in the block's data source. Here's a second example that uses data from the Data source:

/*====================================================
Formula Name: XXX_BK_PASSPORT_VIEW
Formula Type: Applaud Assignment
Description:  Basic passport view
=====================================================*/

  Default for Passport_Number  is 0
  Default for Country_of_Issue is 'Unknown'
  Default for Nationality      is 'Unknown'
  Default for Issue_Date       is '0001/01/01 00:00:00' (date)
  Default for Expiry_Date      is '0001/01/01 00:00:00' (date)
 
  Inputs are Passport_Number
            ,Country_of_Issue
            ,Nationality
            ,Issue_Date
            ,Expiry_Date
 
  Item1_Prompt = 'Passport number'
  Item1_HTML   = to_char(Passport_Number)
  Item2_Prompt = 'Country of Issue'
  Item2_HTML   = Country_of_Issue 
  Item3_Prompt = 'Nationality'
  Item3_HTML   = Nationality
  Item4_Prompt = 'Issue Date'
  Item5_HTML   = to_char(Issue_Date, 'Month ddth, YYYY')
  Item5_Prompt = 'Expiry Date'
  Item5_HTML   = to_char(Expiry_Date, 'Month ddth, YYYY')
 
  RETURN Item1_Prompt, Item1_HTML,
         Item2_Prompt, Item2_HTML,
         Item3_Prompt, Item3_HTML,
         Item4_Prompt, Item4_HTML,
         Item5_Prompt, Item5_HTML

This example assumes that the underlying Data source contains the columns PASSPORT_NUMBER (Number), COUNTRY_OF_ISSUE (Varchar2), NATIONALITY (Varchar2), ISSUE_DATE (date), and EXPIRY_DATE (date).

Defining Formula for LIST Layout

The LIST Layout formula is very similar to the FORM layout formula, with these notable differences:

• A Data source is required for LIST layout and the Fast Formula runs for every row returned by the Data source
• The LIST layout can set additional Formula outputs not available to the FORM layout

These are the Fast Formula Outputs available in a LIST layout.

Output	Description
Summary_Context	Optional. This is the top row of text on a list item.
Summary_Text	Required. This is the main row of text on a list item.
Summary_Message	Optional. This is the bottom row of text on a list item.
Summary_Icon	Optional. Name of the icon to show on a list item.
Status_Color	Optional. Color behind the icon. This can be one of the mood colors (Balanced, Assertive, Positive, Energized; see Branding) or a hex color such as #FF00CC. Tip: use a color from our recommended palette using the Formula Function XXAS_GET_COLOR_BY_NAME. Ex: Status_Color = XXAS_GET_COLOR_BY_NAME('red') This Output is ignored if Summary_Icon is not specified.
Status_Text	Optional. Text to show in the tooltip when hovering over the Summary_Icon.
Summary_Decorator	Optional. A small piece of text that is right-aligned on a list item. Keep this very small, eg, 10 characters.
Timeline_Text	Optional. When specified the item is rendered in a timeline view and shows this piece of text. It's typically a date value.
Calevent_Title	Optional. When specified the LIST automatically renders a calendar view. Each event in the calendar shows this title. The calendar requires Calevent_Title, Calevent_Start and Calevent_End to be specified for all items for the calendar to render correctly.
Calevent_Start	Optional. A date value containing the Start Date of the event in the calendar. This can also contain a time component; leave as 00:00:00 for an all-day event. If a time component is specified, it must also be specified for Calevent_End. The calendar requires Calevent_Title, Calevent_Start and Calevent_End to be specified for all items for the calendar to render correctly.
Calevent_End	Optional. A date value containing the End Date of the event in the calendar. This can also contain a time component; leave as 00:00:00 for an all-day event. If a time component is specified, it must also be specified for Calevent_Start. The calendar requires Calevent_Title, Calevent_Start and Calevent_End to be specified for all items for the calendar to render correctly.
Calevent_Color	Optional. The background color of the calendar event. This is ignored if Calevent_Title, Calevent_Start or Calevent_End are not specified.
Update_Allowed	Optional. Whether the item can be updated or not. Set this to Y when this is an editable block and the user has access to update this particular item. This defaults to N.
Delete_Allowed	Optional. Whether the item can be deleted or not. Set this to Y when this is an editable block and the user has access to delete this particular item. This defaults to N.
Detail_Header_Context	Optional. When specified, this is the first line of text that is displayed when a user drills into an item.
Detail_Header_Text	Optional. When specified, this is the main line of text that is displayed when a user drills into an item.
Detail_Header_Message	Optional. When specified, this is the third line of text that is displayed when a user drills into an item.
Show_Attachments	Optional. Controls whether any workflow attachments are displayed or not when drilling into an item. This defaults to Y.
Show_Attachments_Label	Optional. Sets the title label for attachments. This defaults to Attachments.
Item1_Prompt..Item30_Prompt	Optional. Up to 30 pairs of prompt-data values. This is the same as the FORM layout. These are shown when drilling into a particular list item.
Item1_HTML..Item30_HTML	Optional. Up to 30 pairs of prompt-data values. This is the same as the FORM layout. These are shown when drilling into a particular list item.

Defining Formula for HTML Layout

The HTML Layout does not use a Data source; the formula accepts a single Html output. Here is an example of a simple Formula designed for the Html layout:

/*====================================================
Formula Name: XXX_BK_LEAVE_ELEARNING_VIEW
Formula Type: Applaud Assignment
Description:  Pre-requisite e-learning courses for leave booking
=====================================================*/

  Default for ASG_ORG is 'Unknown'

  Html = 'Please take these eLearning courses before booking for the first time: <ul>'

  
  If ASG_ORG = 'Sales' Then
  (
    Html = Html + '<li>Course Id 12345</li>'
    Html = Html + '<li>Course Id 67890</li>'
    Html = Html + '<li>Course Id 54321</li>'    
  )
  Else
  (
    Html = Html + '<li>Course Id 09876</li>'
    Html = Html + '<li>Course Id 43210</li>'
    Html = Html + '<li>Course Id 87654</li>'
  )
  
  Html = Html + '</ul>'
  
  RETURN Html
  

Setting Outputs that may exceed 255 characters

Fast formula imposes a limit of 255 characters on the length of any Fast Formula outputs. This length limit will include the length of any data strings retrieved from the database (e.g., someone’s name). 255 characters may not be long enough for your output, particularly if you are using any HTML markup. To counter this, we provide a Fast Formula function called XXAS_EMP_SET_LONG_OUTPUT which allows you to specify an output of up to 4000 characters long. The function takes the following form:

<Output_variable> =  
  xxas_emp_set_long_output
    ('<Output_Variable>',
    ,'<Application Short Code>',
    ,'<Message_Name>’
    ,'<TOKEN1>', <data for token 1>
    ,'<TOKEN2>', <data for token 2>
    ,..
    ,’<TOKENN>’, <data for token N>)

The data is then passed into a Tokenized FND Message; each piece of data is passed in as a Token. An example of this is as follows:

Func_Result = xxas_emp_set_long_output
  ('ITEM1_HTML'
  ,'XXAS', 'XXAS_COM_TEXT',
   'TEXT', XXX_GET_PASSPORT_WARNING(Passport_Number))

In this case, Item1_HTML is set to the result of a custom formula function called XXX_GET_PASSPORT_WARNING, which sets a piece of text warning the user that their passport is soon going to expire. XXAS_COM_TEXT is a pre-defined message that you can use, and just contains a single Token: &TEXT. Note that you don’t need the ampersand when specifying the Token in the call to xxas_emp_set_long_output. Using XXAS_EMP_SET_LONG_OUTPUT has another important advantage: it negates the need to return outputs set this way in the Fast Formula. The Function will set <Output Variable> in memory. In the above example, ITEM1_HTML will be set to the appropriate value and there will be no need to return ITEM1_HTML in the Fast Formula's Return statement.

Translating prompts and data

If you have a multi-language environment, you may wish to display prompts and data in the language appropriate to the user’s setting. In this case, you can use XXAS_EMP_SET_LONG_OUTPUT to display the contents of any FND Message. To do this, simply call the function and specify your own message instead of XXAS_COM_TEXT. If the Message is translated it will be returned to the user in their selected language.

Any data fields that have translated data, e.g., Organization Name, will automatically display in the correct language.

Handling a variable number of fields

Sometimes you may wish to only set certain prompt-data pairs using a condition. For example: only show a Passport warning if there is a warning that needs displaying. You can XXAS_EMP_SET_LONG_OUTPUT in conjunction with a counter to display a variable number of fields. An example is shown below:

Current_Form_Item = 1

If <Some_Condition> Then
(
  Func_Result = xxas_emp_set_long_output
    ('ITEM' + to_char(Current_Form_Item) + '_HTML'
    ,'XXAS', 'XXAS_COM_TEXT',
     'TEXT', XXX_GET_PASSPORT_WARNING(Passport_Number))
 
  Current_Form_Item = Current_Form_Item + 1
)

Here a Current_Form_Item counter is only incremented if <Some_Condition> is satisfied.

Displaying an Image in a data field

It is possible to display an image in a data field because they support basic HTML markup. You can use images in the app to replace of supplement words, helping users consume information more quickly. This approach is used in various places in the app's default pages:

• A Google Static Image chart is sometimes used for an accrual balance display
• A Nationality flag is shown in Personal Information
• An image is shown in the Tip of the day on a welcome page
• Images are used to show performance indicators on a performance history view

To show images, you need to arrange to have the image files placed on your Application Tier file system(s). These are typically copied to $OA_MEDIA/xxas/custom/. Once the image is uploaded, you can code the Fast Formula. This is a simple example that show a male/female gender icon instead of a Male/Female label:

Host_URL = xxas_get_host()
Image_URL = Host_URL + '/OA_MEDIA/xxas/'
 
Gender = PER_SEX
if Gender = 'Male' then
  ( Image_Name = 'icon_genderMale.gif' )
 Else
  ( Image_Name = 'icon_genderFemale.gif')
 
Image_URL = Host_URL + '/OA_MEDIA/xxas/' + Image_name
 
Func_Result = xxas_emp_set_long_output
                ('Item1_HTML',
                'PER', 'XXX_XXAS_IMAGE',
                'IMAGE_URL', Image_URL)

The message XXX_XXAS_IMAGE would have message text similar to the below: <img src="&IMAGE_URL" width="24" height="24"/>

Using Simple HTML to format data

Sometimes you may wish to draw a user's attention to important items. For example, if no email address is on record you may want to display some text in red to indicate that an email address should be entered to ensure you can be reached in an emergency.

In the following example, there are up to four task fields to display: Task1, Task2, Task3, Task4. Task1 is mandatory, so will always be set, the other tasks are optional. These could simply be displayed separately, e.g., Item1_Prompt = ‘Task 1’, Item1_HTML = <Task1>, etc. However, a better presentation of the same information is to display them in a single Task field with a numbered list. The sample below achieves this:

/* Set combined display field for Tasks */
Item1_Prompt = 'Tasks'
Item1_HTML   = '<ol><li>' + Task1 + '</li>'

If Task2 was not defaulted then
  (Item1_HTML = Item1_HTML + '<li>' + Task2 + '</li>')

If Task3 was not defaulted then
  (Item1_HTML = Item1_HTML + '<li>' + Task3 + '</li>')

If Task4 was not defaulted then
  (Item1_HTML = Item1_HTML + '<li>' + Task4 + '</li>')

Item1_HTML   = Item1_HTML + '</ol>'

Another common example is the Date fields, where Start Date and End Date are often separated by consultants. For display purposes these can be combined together into a single display field using logic as follows:

Item1_Prompt = 'Project Dates'
Item1_HTML   = to_char(Project_Start_Date, 'dd Month YYYY')
               + ' - ' +
               to_char(Project_End_Date, 'dd Month YYYY')

Writing your own Formula functions

The Applaud Assignment Formula Type uses the following Fast Formula contexts:

1. ASSIGNMENT_ID
2. BUSINESS_GROUP_ID
3. DATE_EARNED (Effective Date)

You can write your own Fast Formula Functions that use any of these contexts to retrieve information from the Oracle database. For more information on writing Fast Formula functions, please read the standard Oracle Fast Formula Implementation Guide.