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 APIs, behavior, and themes/CSS.

General Remarks

  • Keep things simple! Keep the number of entities created for a new control minimal.

  • Reuse is good, but carefully compare how many features of the reused control are needed, and how big the impact on performance would be. For example, if a control needs a clickable area, you can simply implement onclick and check where the click came from - this has zero impact on performance. Only if you need more features should you think about instantiating and aggregating. For example, you could use a Button control and use its press event, but this would cost performance.

API

For APIs, 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 autofill the available width instead of explicitly setting "100%" as the default width.

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

  • 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 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 the default aggregation; this facilitates the use in XMLViews.

  • Properties, associations, and aggregations should be preferred over 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.

  • Be careful about initial dependencies. The Input control, for example, should not always load the table library just because some inputs may show a value help table after certain user interaction

Behavior

For behavior-related development, 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.

  • Do not use oEvent.preventDefault() or oEvent.stopPropagation() without a good reason and clear documentation why it is 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 and fall back to no animation for legacy browsers; there are only a few exceptions 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.

  • When you modify the HTML of a control using the code in the control behavior file, make sure to escape any unchecked data you write with jQuery.sap.encodeHTML(...) to prevent cross-site scripting issues. For more information, see Cross-Site Scripting.

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 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. 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.

  • 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; this is also recommended for other significant theme aspects such as 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 (such as: * { color: black;}) in CSS, in particular without a "direct child" selector (">") in front of it (for performance reasons).

  • 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 should 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 distinguishable from "normal" CSS class names.

    • Controls that 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.