This block has three primary use-cases:
- Show a form, which is optionally editable
- Show a list of data. Each list item may have its own detail form, which again is optionally editable
- Show some read-only HTML
An example of a flexible - form block:
An example of a flexible - list block:
An example of a flexible - html 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:
|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|
The block has these additional settings:
|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:
|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.|
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.
The Form and the Form handler are very tightly integrated and must be specified correctly as a pair.
These are the correct set of Forms and Form handler pairs that are available for use in the Flexible block:
|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|
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
Regardless of the type of layout you are using, all formulas should be created with the Applaud Assignment Formula Type.
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.
The data fields can be formatted using simple HTML markup such as bold (<strong>) and italics (<em>) to help draw the user's attention to important points.
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).
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
When writing a LIST layout formula, be careful if using Database Items or Fast Formula functions: the Fast Formula is run for every row so functions and Database Items can really slow things down if they're not optimized.
These are the Fast Formula Outputs available in a LIST layout.
|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.|
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
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"/>
Give thought to when a data field can be converted into an image for extra impact.
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')
The Applaud Assignment Formula Type uses the following Fast Formula contexts:
- DATE_EARNED (Effective Date)
These contexts are always set to the Person's assignment who is being transacted, not the person who is logged on.
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.