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 Fiori Design Language guidelines, but are also assigned one or more FioriStyle instances. These FioriStyle‘s 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 in SAPFiori, 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 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 , then 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 and tintColor_lightBackgrounfd also have another equivalent constant : tintColorDark . This has the last precedence. The dark background variant of it is tintColorLight, that is, tintColorLight and tintColor_darkBackground are equivalent.

Similarly tintColorTapStateDark is equivalent to tintColorTapState and tintColorTapState_lightBackground whereas tintColorTapStateLight and tintColorTapState_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:

Image

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.

  • Declaration

    Swift

    class UIFont : NSObject, NSCopying
  • An enum that represents the different component style classes for Fiori Design Language

    See more

    Declaration

    Swift

    public enum FDLStyle
  • An enum that represents the different font style classes for Fiori Design Language

    See more

    Declaration

    Swift

    public enum FDLFontStyle
  • An struct that represents style classes

    See more

    Declaration

    Swift

    public struct FioriStyle
  • Color styles for Fiori Design Language Palette:

    • primary1 (light background) Hex color: 3F3A3A
    • primary1 (dark background) Hex color: FFFFFF
    • primary2 (light background) Hex color: 4E4E52
    • primary2 (dark background) Hex color: D3D3D3
    • primary3 Hex color: 76767B
    • primary4 Hex color: CCCCCC
    • primary5 Hex color: F2F2F2
    • primary6 Hex color: FFFFFF
    • primary7 Hex color: 5E6972
    • primary9 Hex color: F9F9F9
    • tintColor (light background) Hex color: 3678AF
    • tintColor (dark background) Hex color: CAE4FB
    • tintColorLight Hex color: CAE4FB
    • tintColorDark Hex color: 3678AF
    • tintColorTapState (light background) Hex color: 295171
    • tintColorTapState (dark background) Hex color: 6191BA
    • tintColorTapStateLight Hex color: 6191BA
    • tintColorTapStateDark Hex color: 295171
    • navigationBar Hex color: 445E75
    • backgroundGradientTop Hex color: 445E75
    • backgroundGradientBottom Hex color: 3F566B
    • backgroundBase Hex color: E8E8ED
    • cellBackgroundTapState Hex color: F2F2F7
    • line Hex color: E8E8ED
    • chart1 (light background) Hex color: 5899DA
    • chart1 (dark background) Hex color: 74B3F0
    • chart2 Hex color: E8743B
    • chart3 Hex color: 19A979
    • chart4 Hex color: ED4A7B
    • chart5 Hex color: 945ECF
    • chart6 Hex color: 13A4B4
    • chart7 Hex color: 525DF4
    • chart8 Hex color: BF399E
    • chart9 Hex color: 6C8893
    • chart10 Hex color: EE6868
    • chart11 Hex color: 2F6497
    • negative (light background) Hex color: D9364C
    • negative (dark background) Hex color: FF9B9B
    • critical (light background) Hex color: FFA325
    • critical (dark background) Hex color: FFDB79
    • positive (light background) Hex color: 3A835B
    • positive (dark background) Hex color: 8EF79F
    • map1 Hex color: 2E4A62
    • map2 Hex color: 56840E
    • map3 Hex color: A63788
    • map4 Hex color: 0079C6
    • map5 Hex color: 6B4EA0
    • map6 Hex color: A16B00
    • map7 Hex color: 0B6295
    • map8 Hex color: D0R774
    • map9 Hex color: 1C857A
    • map10 Hex color: C45300
    • esriEdit Hex color: 1B6DD2
    See more

    Declaration

    Swift

    public enum FUIColorStyle : Int
  • The style class settings class that provides a list of static functions for applying-style-related functionalities

    See more

    Declaration

    Swift

    public class NUISettings : NSObject
  • The master renderer class that provides a list of static functions for individual component rendering

    See more

    Declaration

    Swift

    @objcMembers
    public class NUIRenderer : NSObject