FAB (Fiori App Builder) standards / conventions / best practice guide

We suggest the following conventions/standards when working in FAB:

ABAP Code

For naming standards and conventions in ABAP, please navigate here.

Data model - naming fields

We recommend different naming strategies for naming data model fields, depending on the source/target of the data field in question.

1. When using an OData Service, we recommend matching the name and case of the data model field to that of the corresponding field in the OData Service.

2. When using ABAP fields (imported from an SAP Function Module / Screen / BDC / Structure or Table) we recommend matching the name of the data model field to the name in the corresponding SAP source/target field. We recommend keeping the name in the UPPER CASE.

3. When defining these during development, we recommend capitalizing the first letter of every word - something like:
   MyDataFieldName.

Data model - description fields

We often have two fields where the first field contains a code and the second field (used as a label, description, or tool-tip, for example) contains the name/description for the code contained in the first field. To avoid variation (Name vs Description vs Desc vs Descr vs Text vs XXXX) we recommend always using 'Name'. Therefore:

1. In most instances, we recommend that the two fields should be named the same, but the description field has the word 'Name' appended to the end. For example:

   1. CostCenter and CostCenterName

   2. ControllingArea and ControllingAreaName
      
      

2. In instances where a field is named XxxCode or YyyKey (or similar) we recommend dropping the 'Code' or 'Key' and replacing it with 'Name' for the description field, for example:

   1. CompanyCode and CompanyName

   2. CurrencyKey and CurrencyName
      Exception: where the word 'Key' is part of the name, as opposed to simply an indication that the field contains a code/key, it may remain part of the description field name:

   3. PostingKey and PostingKeyName

Data model - explicit typing

It is important to remember that the data model is the 'area of exchange' through which data is effectively passed from the front-end to the back-end and vice versa. During this process, conversion takes place between the data as it is declared in the front-end and the equivalent data as it is declared in the back-end (in ABAP).

Creating your data model field with the correct types ensures that FAB can create the fields correctly for use in both JavaScript and ABAP.

To avoid conversion issues (especially with numbers and dates) where we then have to manually handle conversions in ABAP or JavaScript, we recommend that all fields should be typed explicitly with both ABAP and Javascript types, whenever possible.

The exception to this is where the field should be declared as a text-type field in both the front- and back-end. In this instance, FAB will assume both to be text in the absence of explicit typing.

Component / Element ID - naming 

Please remember that components/elements in your project do not always have to be named explicitly - if no ID is assigned, FAB will assign one at run-time. Where you do want to name these (for readability, for example, or to be able to refer to the component in code) we recommend a flexible approach, using a simple set of rules to determine a 2- or 3-character prefix:

1. Where the component name consists of a single word, use the first 3 characters, all lowercase, as the prefix. Examples:
   Button - but
   Select - sel
   Input - inp
   Panel - pan
   Slider - sli
   :

2. Where the component name consists of two (2) or three (3) words, use the first character of every word, all lowercase, as the prefix. Examples:
   Grid Table - gt
   Date Picker - dp
   Date Time Picker - dtp
   Upload Collection - uc
   Radio Button - rb
   Object Page Section - ops
   :

3. In the unlikely event that there are clashes between IDs created with this standard, or where the name of the component consists of 4 words, you may consider adding a 4th character to avoid ambiguity. Example:
   Object Page SubSection - opss

Using the above rules to create a prefix and combining it with a descriptive name for a field one will be able to understand, at a glance, what type of component is represented by an ID. For example:

• inpCompanyCode represents an Input field for a Company Code, but

• selCompanyCode represents a Select (dropdown) where a Company Code can be selected from a list.

Icons

We recommend the following with regards to icon usage:

Where?	Icon Name	Icon	Suggested tooltip

Where?	Icon Name	Icon	Suggested tooltip
Button to exit from an App	system-exit sap-icon://system-exit	Open	Exit
Button to return to Fiori (or FAB) Launchpad	home sap-icon://home	Open	Home
Application help (provided by the developer)	message-information sap-icon://message-information		More information

JavaScript variables 

We recommend naming your variables using descriptive names, and using the following guidelines:

OData Sets

1. FAB generates the GET_ENTITY_SET method in the Data Provider Class for you automatically, with a built-in CASE statement to deal with the Entity Sets that the code needs to handle. While it is tempting to keep all logic (for every Entity Set) in this method, it is not considered good (OO) practice - it is hard to maintain, difficult to find code and the method does not conform to the principle of "do one thing, and one thing well".
   Instead, we recommend that you code the logic for every Entity Set in its own (appropriately named) method, and simply call these methods under the relevant WHEN of the CASE statement. The GET_ENTITY_SET method should therefore simply act as a switching mechanism to direct the processing to the relevant method.

2. We recommend naming your Entity with the singular version of the noun (like Customer or Company) and the Entity Set as the plural (Customers or Companies). An acceptable alternative would be using the pattern EntitySet, for example, CustomerSet or CompanySet instead.

3. Please remember to implement manual pagination of the Entity Set for performance reasons when the method could return a large volume of data.

Approach to storing text values (to be used in error messages, help text, etc.)

Where possible, the use of hard-coded text in JavaScript code should be avoided, especially from a maintenance point of view. Instead of capturing the actual text in your code (like MessageToast.show("My Toaster Message") ) you should rather publish the text strings in the Properties file used for Internationalisation (i18n).

Benefits:

1. The file is pre-loaded with the other resources specified in the Component-preload. Therefore, the file is already cached on the front-end, ensuring good performance.

2. Ease of maintenance - all text is stored in one place, which means changes can be done easily and quickly.

For stand-alone Apps, you will see that the Properties file is automatically included in the Component-preload:

To edit the Properties file, log on to the Gateway and navigate to transaction SE80. Open the Repository Browser and choose the BSP Application option from the drop-down. Enter your stand-alone App name - in this case, it is ZTEXT_DEMO.

You will find the file under Page Fragments → WebContent → i18n → i18n.properties.

Simply add your help/message text underneath the other options generated by the FAB App Builder. Some sample messages (highlighted) are shown above for demonstration purposes. When used in an App, it can look something like this:

Sample Toaster:

Dialog:

Popover:

Note that this can be achieved by using the {i18n>xxxx} notation, for example for the Form label above:

One notable exception is that you need to retrieve these values as a Property from a Model if you want to use them in JavaScript (like in a Toaster). For example, to display the Toaster shown above, the JavaScript (triggered by the first button being pressed):

FAB Application help

First and foremost, please check that the messaging that you want to display fits into the Fiori guidelines for messaging - see here:

https://experience.sap.com/fiori-design-web/messaging/

For simple Application Help, we will consider the following things:

1. Where to store the help texts.
   It is preferable to store the help texts in the Properties file, as described above.
   
   

2. How to display the help texts.
   It is preferable to use a popover message box (not modal) to display any help texts related to a field (or closely related set of fields). This way the ‘arrow’ of the popover control gives context to the help shown.
   
   

   For any help displayed for a whole section/page, a modal dialog should be used. Alternatively, consider well-placed Message Strips that show when the page is loaded, although this does consume some real estate.
   
   To display formatted text, ensure that you select a component that can handle formatting (like a Message Strip - see example). Alternatively, apply formatting options to the entire control and therefore all its contents.
   
   Where lots of information needs to be displayed, and especially if the text needs to remain on screen after clicking in/on another screen element (since Popovers disappear automatically) you should consider a Message Strip that can be hidden programmatically (setting the visible property) or utilizing the showCloseButton property, as is shown here:
   
   

   Note that a Message Strip (and a few other select components) will allow you to use a limited subset of HTML tags to format the text in the component. You can find more information here:
   https://sapui5.hana.ondemand.com/#/api/sap.m.MessageStrip

    

3. Where to position the help icon.
   For help related to a field (or closely related set of fields), the icon should be placed next to the field that the help is provided for (see above).
   For a whole section/page, the icon should be placed as close as possible to the title of that section/page, or in a toolbar that containing other form actions.

Transport Guidelines

For OneList and FAB Product developments in the IQX systems, specify the Jira Ticket and the Jira Version in the attributes of the transport. These request attributes are used in querying and identifying the related transports via SE03 for the product packaging.

My Forms Guidelines

The My Forms App enables users to view and process workflows of all the requests raised in Fiori. There are different versions of the My Forms app that can be deployed based on the client setup and requirements: