Design best practice

This document is intended to list our combined project experience together with basic design guidelines to give beginners and advanced Neptune DXP - Open Edition developers guidance on how to design and structure your app(s) with the Neptune DXP - Open Edition.

As a start, we would like to emphasize the following basics:

  • Single point of entry is the Cockpit, which is the home page and central location of all Neptune DXP - Open Edition tools.

  • A launchpad can be downloaded from the Neptune DXP Marketplace to launch apps.

  • It is also possible to deploy and run each Neptune DXP - Open Edition application individually and stand-alone.

  • We recommend designing all UI5 apps stateless.

  • We recommend designing your apps as split-apps, using the App Designer. The following design best practices are a recommendation and do not necessarily include all relevant guidelines for a project.

App settings

  • We recommend using the standard Belize theme by default. Design adjustments can be added by applying custom CSS properties directly in the Theme Designer.

  • We recommend defining the Title/Group attribute in your app settings as this is the wording that is displayed on the browser tab.

App basics

  • Every app should start with the sap.m.Shell control, which is typically named Shell.

  • Beneath sap.m.Shell, always place the sap.m.App or sap.m.SplitApp control as a sub-node. You should add the SplitApp template while creating an app. The App/SplitApp control is the de-facto root control of your app that controls all navigation and busy-state of your app. For example, you can name it App. You can have multiple App/SplitApp controls under one shell.

  • As sub-nodes to the App/SplitApp control, it is recommended to define a set of sap.m.Page controls that determine the needed screens of your app. Hierarchically, all pages should be placed at the same level. It is possible to navigate from one page to another throughout the app.

  • The page control should be the first sub-node of your App/SplitApp control. It is the starting page which is displayed when the app starts.

  • If you are adding a SplitApp template, you need to specify the position parent-property in the attribute section of your page controls. You have to define if a page is shown in the Master or the Detail section of your SplitApp.

Naming conventions

  • Every object of an app must have a unique name.

  • We recommend the following notation: starting uppercase and using uppercase letters for all leading characters of the composite name.

  • We recommend the following naming composition: Obj + Purpose + [Action]

  • In the HTML5 hierarchy, Pages should be the leading controls on naming.

  • As an example, if you design a page with the name PageCustomerData, any sub-node to this page should follow the following naming:

    • sap.m.Table: TabCustomerData

    • sap.m.Button: ButCustomerDataSave

    • sap.m.Button: ButCustomerDataBack

  • Rule of thumb: Define a naming convention at the beginning of a project and do not change it.

  • Do not just use UI5 names with numbers for your objects.

  • Name your sap.m.Shell control Shell.

  • Name your sap.m.App/SplitApp control App.

Look and feel

  • As a rule, the design of your app should be based on sap.m.Page as your primary design container.

  • Every page should include a header section.

  • Every page should include a footer section.

  • All process-specific design, for example, forms, tables, tabs, should be placed between the header and footer of a page.

  • The necessary process triggers, like buttons to save, cancel, submit, should be placed in the right section of the footer.

  • Back buttons should be placed in the left section of the page header or footer. It is important to stay consistent throughout your app(s).

  • In a SplitApp environment:

    • The master page should be the leading function, providing, for example, a list of (searchable) items, or an input form to define or search for datasets, or a list of subfunctions.

    • The detail page should display process or data details and functional triggers, for example, information on a specific dataset selected on the master page, sub-items of a dataset, or input fields to create a new dataset.

    • Both sections should have a footer, displaying buttons to trigger further actions.

  • Buttons should follow a basic color concept, which can be set via the property type:

    • Blue (type: Emphasized): Core function trigger of a page, for example, Search, Submit. In general, used to emphasize a particular button object in contrast to no styled buttons on the same footer or toolbar.

    • Green (type: Accept): Positive function trigger, used mostly in combination with a negative trigger, for example, Save or Delete.

    • Red (type: Reject): Negative function trigger, used mostly in combination with a positive trigger, for example, Decline or Approve.

    • None (type: default/none): Used for standard functions. Button blends in with footer/toolbar, for example, Settings.

API calls

  • To successfully design an API call, you need to define the following parts:

    • Bind your corresponding app controls to the model source.

      • In online scenarios, we recommend that you use the main receiving UI5 controls to bind with the API. For example, if you want to fetch a table data from the API, bind the API method with the corresponding UI5 control in which you want to get the table content.

      • In offline scenarios, the binding concept is working in the same way as in online situation scenarios.

    • If you want to use one data modal among the application, use multimodel binding, which allows you to use one data model source among multiple application objects.

Customized JavaScript

To define JavaScript code, we recommend to use the custom JS helpers component in the Neptune DXP - Open Edition. You can use code snippets created there in your application, when required.

design guidelines1