Content developers developing OpenUI5 controls should follow the guidelines outlined below with regard to APIs, behavior, and themes/CSS.
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.
OpenUI5 supports several data sources, such as JSON, XML, or OData. However, you need to make sure that the controls you develop work with the data models that the OpenUI5 application can be expected to use.
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 object and 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
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. At the same time, ensure also that given data containing curly braces are not accidentally interpreted as binding expressions, which can be achieved with sap/ui/base/ManagedObject.escapeSettingsValue. For more information, see Escaping Binding Syntax.
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 OpenUI5 event handling methods when available instead of jQuery.on(). When you use jQuery.on(), always register them in onAfterRendering() and deregister them by using jQuery.off() in onBeforeRendering() and in exit().
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 create HTML markup for a control outside a renderer, for example, by writing to the innerHTML property of a DOM element, or by calling jQuery.html() or similar helpers, make sure to escape any unchecked data first with the function provided by sap/base/security/encodeXML. This is mandatory to prevent cross-site scripting issues. For more information, see Cross-Site Scripting.
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 the function provided by module sap/base/security/encodeXML.
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.
For theming and CSS-related development, follow the comprehensive guidelines provided in the main theming documentation:
Creating Themable User Interfaces
This topic elaborates on best practices for theme-aware control development, including the following:
Using CSS custom properties for theme parameters
Proper CSS class naming conventions
Container context considerations
Local parameter naming guidelines
This topic elaborates on advanced theming features, such as the Parameters API and CSS math functions
Key Points for Control Developers:
Use CSS custom properties (for example, var(--sapButton_Background)) instead of hard-coded values
Follow semantic CSS class naming conventions with proper prefixes
Ensure theme-aware styling that works across all OpenUI5 themes
Test controls with different themes to verify proper appearance