Branding and Theming¶
The SAPFiori framework embeds a fork of the open source NUI
project, which enables styling of UI controls using a CSS-like stylesheet (the .nss
file).
The UI components in SAPFiori are styled during initialization according to the SAP Fiori Design Language Guidelines, but are also assigned one or more FioriStyle
instances. These instances are similar to a CSS class
attribute, such that at runtime, if a style definition override exists in the .nss
file for that FioriStyle
, it will be applied on top of the default attributes.
Each styleable component in SAPFiori is assigned style class references by default, so that developers can define style overrides for those class references, without invoking Swift API's. These default style classes are assigned, according to the following standard:
"fdl" + <#ComponentClassName#> + "_" + <#PropertyName#>
For example, to assign an override styles for the FUIObjectTableViewCell
, using the following style classes:
fdlFUIObjectView_headlineLabel {
font-style: subheadline;
font-color: #1EE68A00;
}
fdlFUIObjectTableViewCell {
background-color-selected: negative_darkBackground;
}
Refer to the header documentation for controls, to check for exceptions to these patterns.
Usage¶
Activate Styling¶
To activate the theming engine, add your ".nss"
resource to the application project.
The
NUI
library is embedded inSAPFiori
, so no dependency management is required.
In your AppDelegate
, invoke the static initializer in didFinishLaunchingWithOptions:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
// setup logger (requires `import SAPCommon`)
let logger = Logger.root
logger.logLevel = .info
// initialize stylesheet by name
NUISettings.initWithStylesheet(name: "Palette")
return true
}
Color Palette Customization¶
Every time a UIColor
is set in the SAPFiori framework, the color is obtained from the extension method:
func preferredFioriColor(forStyle style: FUIColorStyle, background scheme: FUIBackgroundColorScheme = .lightBackground) -> UIColor
The FUIColorStyle
cases correspond to the colors of the Fiori for iOS Design Guidelines palette. It is important to note the distinctions between the "base" color (UIColor.preferredFioriColor(forStyle: .primary1)
), the "dark" variant which is displayed on a "light" background (also UIColor.preferredFioriColor(forStyle: .primary1)
, or UIColor.preferredFioriColor(forStyle: .primary1, background: .lightBackground)
), and the "light" variant which is displayed on a "dark" background (UIColor.preferredFioriColor(forStyle: .primary1, background: .darkBackground)
)
To remember easily, keep in mind that: lighter colors are brighter on dark backgrounds, and dark colors have better contrast on light backgrounds.
Because all colors are set through this API, it is possible to override the global constants used for the FUIColorStyle
case. The technique for this is to add these definitions to the head of your ".nss"
file, using the regular nss @global_constant
pattern. The strings used as the global_constant
should match the string values of the FUIColorStyle
enums, and optionally append _lightBackground
or _darkBackground
, to specialize the background
parameter passed to the preferredFioriColor(forStyle: background:) -> UIColor
invocation.
For example:
@tintColor: blue; /* equivalent to @tintColor_lightBackground */
@tintColor_darkBackground: cyan;
@tintColorTapState_lightBackground: purple; /* equivalent to @tintColorTapState */
@tintColorTapState_darkBackground : magenta;
Like style definitions, palette global overrides only modify their corresponding attributes; all other color definitions for which an override is not provided retain their original values.
As per the Fiori guidelines, when the background is not explicitly specified it defaults to the light background. For example, the global constants, tintColor
and tintColor_lightBackground
are equivalent. Similarly, primary1
and primary1_lightBackground
are equivalent. When overriding global constants in the .nss
file, if two equivalent constants are overridden, then the order of precedence is as shown below, where UIColor.cyan
will be used for all invocations of UIColor.preferredFioriColor(forStyle: .tintColor)
or UIColor.preferredFioriColor(forStyle: .tintColor, background: .lightBackground)
:
@tintColor_lightBackground: cyan; /* This takes precedence over tintColor */
@tintColor: blue;
@tintColorDark: green;
tintColor
andtintColor_lightBackground
also have another equivalent constant :tintColorDark
. This has the last precedence. The dark background variant of it istintColorLight
, that is,tintColorLight
andtintColor_darkBackground
are equivalent. SimilarlytintColorTapStateDark
is equivalent totintColorTapState
andtintColorTapState_lightBackground
whereastintColorTapStateLight
andtintColorTapState_darkBackground
are equivalent.
Using SAPFiori Colors in Style Definitions¶
There are two patterns that may be used to refer to the FUIColorStyle
definitions in the ".nss"
file:
1) The @global_constant
pattern, detailed above. Here, the .nss
file parser physically finds all instances of the @global_constant
in the style definitions and substitutes the global value. This is the appropriate pattern when overriding the color value of the palette.
@tintColor: blue; /* `UIColor.blue` is used for all invocations of `UIColor.preferredFioriColor(forStyle: .tintColor)` */
fdlFUIObjectTableViewCell {
tint-color: @tintColor; /* the string `"blue"` is stored into the style model */
}
2) Invoke the string constant directly, as one would for the simple color strings (for example: "blue"
, or "orange"
). Each FUIColorStyle
case is supported, with the optional _lightBackground
or _darkBackground
suffix. This is the appropriate pattern, when not overriding the color value of the palette, but when you wish to use an alternate color for the attribute.
fdlFUIObjectTableViewCell {
tint-color: tintColor; /* the standard `FUIColorStyle.tintColor` is used */
}
The two patterns are compatible, so that in the previous example, if @tintColor
is overridden to "blue"
, the color UIColor.blue
will be used, instead of FUIColorStyle.tintColor
.
SAPFiori Component Style Customization¶
The screenshot below illustrates the FUIWelcomeScreen
before (default) and after setting different styles in NUI
, by modifying the text color and logo:
The stylesheet file can include a set of generic Fiori Design Language style definitions for font-style and font-color. Then, for each control, an individual style class configuration can be included; this per-component
style setting can override the style declared in the global definition and add other styles.
The stylesheet should follow these conventions for naming the style strings starting with fdl
which represents Fiori Design Language
-
For global definitions:
fdl<lower-camel-case enum name>_<property name>
For example:fdlFontStyle_subheadline
-
For per-component definitions:
fdl<class name>_<property name>
For example:fdlFUIWelcomeScreen_demoLabel
fdlFontStyle_subheadline {
font-style: subheadline;
font-color: #33cc33;
}
fdlFUIWelcomeScreen_headlineLabel {
font-color: #FF0000;
}
fdlFUIWelcomeScreen_primaryActionButton {
/* alpha value should be in 0% to 100% range. If value is more than 100% (64 in hex value), the system resets the value to 100%. */
font-color: #1EE68A00; /* where `1E` is the hex value of 30% in alpha value, and `E68A00` is the hex value for RGB. */
font-color-highlighted: green;
}
fdlFUIWelcomeScreen_logoImageView {
image-name: ProfilePic.png;
}
See the
NUI
README
for additional information about setting style syntax in the stylesheet.