SAPUI5 Best Practices for Beginners – Part 1

As a follow-up article to my “Commonly Used SAPUI5 Controls” and “Design-to-Development of SAPUI5 Application”, this week I’ll share my SAPUI5 best practices. A curation of project setup and coding practices, which can help you improve your development style and process.

In part 1, I will focus on the project level best practices that I usually apply to my project.
This post will cover more on the project creation, git setup, modularization, and linting.

Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve this code so that this comment is not needed?’ – Steve McConnell

Project Creation

Before starting development, the starting point of any sapui5 application is the project creation. This can be done several ways, via SAP Web IDE wizard, Eclipse IDE wizard, manually from scratch, or by a third-party tool (e.g. Godiva).

SAP Web IDE Wizard
SAP Web IDE Wizard
Eclipse Wizard
Eclipse Wizard
Godiva Plugin
Godiva Plugin

During project creation, on SAP Web IDE, you will be asked for the following:

  • project name
  • project namespace
  • view type (JS, JSON, XML, HTML)

It is important to properly name and choose the right option for the application as it will affect the whole project directory.

I recommend beforehand that you have a well-documented naming convention for the project name and namespace. For the view type, standardize to keep a common format. For example, if you started with XML views, try to keep most of your SAPUI5 views to XML.

XML Views are also preferred view type, as most of Fiori applications are written in this format. XML format is also declarative, which makes it easy to read and understand.

Project Name & Project Namespace

Wizard Basic Information
Wizard Basic Information

There are few things to consider in naming your project and namespace. The following items will keep your project easy to maintain and have a common identifier across different platform and tools, may it be on SAP deployment (SICF) or Git repository.

Try to limit project name to 15 characters
Wizard Project Name
Wizard Project Name

Keeping the project name under 15 characters will make it easy to read. It will also help you on your deployment to SAPUI5 ABAP Repository. SAPUI5 ABAP Repository has a limit of 15 characters for the new application name.

Deploy to SAPUI5 ABAP Repository
Deploy to SAPUI5 ABAP Repository
Keep the project name and SAPUI5 ABAP repository name the same

Having the same project name and SAPUI5 ABAP repository name makes it easy for you to search for the application in your gateway system.

Maintain Service (SICF)
Maintain Service (SICF)

 

Keep project name and Git repository name similar

In addition, it is also a good practice if you can name the Git repository in the same manner.

Git Repository
Git Repository

NOTE: SAP Web IDE Git only accepts lowercase alphanumeric characters.

Git Repository Naming
Git Repository Naming

 

Project namespace should follow the company or project reverse-DNS

Reverse-DNS identify resources quickly. It helps avoid naming collision and duplicates. It also organizes the applications in a modular manner.

Example:

 

Try to limit the project namespace to 3 segments

Keeping the project namespace to 3 segments helps readability and maintainability. This also helps keep the application simple, since you limit the purpose of the application to small units, rather than having nesting namespaces.

Keep project namespace descriptive or contain abbreviations of the app

Project namespace can be a short description of the app, like:

or an abbreviation if the short description is not enough:

NOTE: rename all namespace due to web IDE auto-naming feature (no period after namespace)

SAP Web IDE Auto Namespace
SAP Web IDE Auto Namespace

You can see from the image above that the namespace was added to the project name on the source code, which is fine, but the dot(.) or period is missing.

which should be:

or

You must rename all of the occurrences on your project. You can use the search function in the top right corner of the workspace.

Rename Namespace
Rename Namespace

This is as of Version 170330

SAP Web IDE Version 170330
SAP Web IDE Version 170330

Fiori related configurations (Catalog, Groups, Semantic, and Action)

The following recommendations are more related to Fiori objects. Similarly, like naming the project and namespace, it is a good practice if you can easily trace the relationships of these objects by using a convention.

Catalog

Try to keep catalog name descriptive and provide which module the catalog is related to

Example:

 

Grouping

Like catalogs, keep group names descriptive and provide the SAP module as well

Example:

 

Semantic Objects

Semantic Objects are thoroughly discussed in this link.

Represents a business entity such as a customer, a sales order, or a product. Using semantic objects, you can bundle applications that reflect a specific scenario. They allow you to refer to objects in a standardized way, abstracting from concrete implementations of these objects.

You can either use semantic objects shipped by SAP, or create new semantic objects

Masayuki Sekihara also posted a more definitive guide on the launchpad relationships.

Launchpad objects relationships
Launchpad objects relationships
Actions

Actions are more specific to what the task being performed by the user.

Describes which operation (such as display or approvePurchaseOrders) is intended to be performed on a semantic object (such as Purchase Order or Product).

Intents have the following pattern:

Example:

 

SAPUI5 Version

Aside from project setup and Fiori configurations, it is a good practice to verify the SAPUI5 version. This keeps the supported libraries correct and the expected look-and-feel of the controls exactly was it expected.

Check the index.html

Although index files are only used for stand-alone applications, it is a good practice to check the default SAPUI5 version. In the example below, the project will use the latest build from the cloud platform since there’s no specific version provided by the project.

Index SAPUI5 Version
Index SAPUI5 Version

 

Check the manifest for minimum and auto-loaded libraries (date picker etc.)

After checking the index file, also validate that the manifest.json  uses the correct version. manifest.json  are used by launchpad based applications, the component.js  loads this file for default setup of the application.

manifest.json
manifest.json

It is also good to pre-load and identify the libraries that you will use on your project here. The commonly loaded controls or libraries are the sap.ui.layout  (i.e. containers) and sap.ui.unified  (i.e. date ranges).

 

The project settings for default version

Additional setting that you might be interested in, is the Project Settings.

SAP Web IDE Project Settings
SAP Web IDE Project Settings

In the project settings, you can specify the libraries you want to load and the specific version. Its a convenient way of changing the version for testing and deployment.

SAPUI5 Versions
SAPUI5 Versions
SAPUI5 Libraries
SAPUI5 Libraries

 

Base Controllers & Parent Controllers

One of the major enhancements that SAPUI5 got in the previous years is the ability to use parent controllers. This gave way to reusability across files and functions. It is a must to utilize this feature to avoid code redundancy and promote reusability. Aside from reusability, this also promotes an organization, keeping the related controllers to correct scope. It also allows flexibility, to change a single controller feature and apply it to multiple sub-controllers.

Note: The SAPUI5 controller extension concept does not use inheritance

You can find a more detailed discussion of this parenting here.

Routing (Paths, Patterns, and Parameters)

Targets

Targets are the actual representation of a view file. It contains the details of the file, you can also define target level transitions and view levels.

It is a good practice to provide the viewLevel to help the framework know the routing flow of the current view.

A coherent transition is also a must since you don’t want unnecessary transition or animation for your application. Any unnecessary transition will only distract the user experience.

Always provide fallback targets, some example of these are message pages, 404 or not found pages.

Routes

Route name should be descriptive by itself.

Example:

Route patterns should optimize parameters and patterns. Your route parameters should only contain URL safe and only necessary parameters.

Bad Example:

Is this example param1  can generate unparseable results due to URL decoding. The expected value may differ from the passed parameters. Common unsafe URL characters may include:

It is a common practice as well to have the target name as the route name. So if you have a home target, chances are is that you might have a route called  home as well.

ESLint setup

Lastly, it is always a good practice to follow a coding standard. SAPUI5 projects use ESLint as a baseline. You can view a more detailed documentation here.

The ESLint file configuration can be found here.

ESLint Configuration File
ESLint Configuration File

Summary

In summary, always go back to the guidelines and review your project setup. Make coherent naming across files and resources so that you can associate them easily. After reviewing everything, you can now start standardizing and creating your own set of conventions to follow.

Share this...
Share on Facebook0Tweet about this on TwitterShare on LinkedIn11Email this to someonePrint this page

Leave a Reply