Show TOC

SAPUI5 Control Development GuidelinesLocate this document in the navigation structure

Content developers developing SAPUI5 controls should follow the guidelines outlined below with regard to API, behavior, and themes/CSS.

API

For API, the following guidelines apply:

  • Get the API right the first time, you will not be able to change it later (compatibility).

  • Control names start with an uppercase letter and use CamelCase for concatenated words.

  • Property, event, aggregation, association, method, and parameter names start with a lowercase letter and also use camelCase,

  • Do not use Hungarian notation for API parameters, as their type is documented in JSDoc.

  • Provide a reasonable default value for properties. Consider the most frequent use case.

    Let block elements "auto"-fill the available width instead of explicitly setting "100%" as default width.

  • "editable" and "enabled" are two different properties. "Not enabled" controls are not in the focus tab chain.

  • In general, check similar controls for consistent naming and modeling of public APIs.

    Controls for text input have a "value" property. Container controls with one generic area for child controls have a 1..n "content" aggregation. When the child controls are not generic, but have a specific semantics, arrangement, or type, the name should be chosen accordingly ("items", "buttons",…).

    When there is one most important aggregation, it should be marked as default aggregation; this facilitates the use in XMLViews.

  • Properties, associations, and aggregations should be preferred to API methods due to data binding support and easier usage in XMLViews.

  • Make sure not to break use in XMLViews; for example, types like sap.ui.core/object and sap.ui.core/any may not be used for mandatory properties.

Behavior

For behavior-related developement, the following guidelines apply:

  • Do not use hardcoded IDs. When creating internal subcontrols, their ID should be prefixed with this.getId() + "-".

  • Make sure not to break data binding.

  • Do not make assumptions about how your control is used. It will be used differently.

  • Do not use oEvent.preventDefault() or oEvent.stopPropagation() without a good reason and clear documentation why it is really required.

  • Use the SAPUI5 event handling methods when available instead of jQuery.bind()/.on(). When you use jQuery.bind() or jQuery.on(), always unbind them again, for example in onBeforeRendering() and in exit() and rebind after rendering.

  • Use CSS3 for animations, fall back to no animation for legacy browsers; only few exceptions exist where the animation is important.

  • Keep in mind that a control can be used multiple times in a page.

  • Provide immediate feedback for user interaction.

  • If an action takes a longer period of time, visualize this, for example by using a BusyIndicator.

Renderer

With regard to the renderer, the following guidelines apply:

  • Produce clean, semantic HTML5, as compact as reasonably possible.

  • Each control instance must have exactly one root HTML element and can have any HTML element structure below that.

  • Unknown strings such as values coming from string properties need to be escaped before writing to HTML; this avoids security risks via XSS attacks.

  • Use RenderManager.writeEscaped(…) or jQuery.sap.encodeHTML(…).

  • Container controls such as Panel or Page as opposed to layout controls with a generic "content" aggregation should render the children all directly next to each other with no additional HTML or layout applied.

  • Use the Icon pool for images.

  • Provide a sufficiently large touch area for interaction on touch devices (usually 3rem/48px).

  • When internal HTML elements of the control below the root element need an ID, construct the ID as follows: <control ID> + "-" + <someSuffix>.

  • The HTML should adhere to the basic XHTML rules; close all tags, enclose attribute values in quotes and do not use empty attributes without value.

  • Avoid <table>-based layouts when there is no logical table. If a table is used for layout, try to use "display:table" or even "table-layout:fixed" tables.

  • RenderManager.writeControlData() must be called in the root HTML element of the control (to make events work).

  • RenderManager.writeClasses() must be called in the root HTML element of a control; otherwise addStyleClass does not work; however, this does not need to be used in subelements.

Themes/CSS - General Guidelines
For themes and CSS, the following general guidelines apply:
  • Write semicolons even where optional.

  • In general, use "rem" for dimensions; use "px" only for dimensions that do not depend on the font size. Exception: Controls still supporting IE8 cannot use rem.

  • The root element of a control should come without outer margins; add any required padding inside. Root margins are owned by the parent control.

  • Do not hard-code any colors, use LESS parameters and color calculations instead; also recommended for other significant theme aspects like fonts and background images.

  • Use other LESS features moderately. The more LESS processing happens, the less clear it is where the runtime CSS originates from.

  • Do not style HTML elements directly; all selectors must include a SAPUI5-specific CSS class to avoid affecting non-owned HTML.

  • Avoid the star selector (like: * { color: black;}) in CSS, in particular without a "direct child" selector (">") in front of it (performance).

  • Only use inline CSS for control instance specific style, for example the button width.

  • Do not use !important as it makes custom adaptations more difficult; use more specific selectors instead.

    There are rare justified exceptions, but they need to be documented.

  • Put browser-prefixed properties before the un-prefixed variant.

  • When the visuals of certain controls are different depending on the context/container where they are used, use CSS cascades along with marker CSS classes in the parent control:

    • The area/container shall write a certain marker CSS class to the HTML and document this CSS class in its JSDoc.

    • The documentation should mention the purpose and contract/meaning of this class, for example, that it is meant to modify the appearance of children in a way that better fits table cells, toolbars or headers.

    • This CSS class may not have any CSS styles attached, it is a pure marker.

    • This CSS class has the suffix "-CTX" (e.g. "sapUiTable-CTX" or "sapUiBorderless-CTX") to make it discernible from "normal" CSS class names.

    • Controls which want to modify their appearance in such an area use the marker class in a cascade: .sapUiTable-CTX .sapUiInput { border: none; }

Themes/CSS - Naming Guidelines

The following naming guidelines apply:

  • All CSS classes must begin with the "sapUi" prefix (or "sapM" in the sap.m library). Exception: some global CSS classes used in the core start with "sap-".

  • For each control there must be one unique control-specific prefix for CSS classes.

    For example, sapUiBtn for a Button control, or sapMITB for an IconTabBar in the sap.m library. This class must be written to the HTML root element of the control. All CSS classes within the HTML of this control must append a suffix to this class name, for example. sapUiBtnInner or sapMITBHeader.