SAP BTP SDK for iOS Theming Support

The SDK framework allows developers to download a customized theme from the mobile services cockpit and apply it to a native app. You can either use the SAP BTP SDK Assistant for iOS to enable the customized theme, or the administrator can enable the feature in the mobile services cockpit. See Managing Application Themes for additional information.

Prerequisites

• If the feature is enabled using the SAP BTP SDK Assistant for iOS while generating the app, NUIStyleSheetApplyStep will be added in the onboarding and restoring steps with APIKeyAuthenticationConfig used as a parameter. Consequently, anonymous access is also enabled in the mobile services cockpit.
• If the feature is enabled using the mobile services cockpit, then the developer has to add the NUIStyleSheetApplyStep with the required parameters in the onboarding and restoring steps.

Initializing and Adding NUIStyleSheetApplyStep to Existing Steps

The FioriFlows onboarding step, NUIStyleSheetApplyStep, will download and apply theme colors to UIKit-based UI components built with SAPFiori.xcframework.

We recommend that you define this onboarding step as the first step in the onboarding flow to ensure that theme information is applied before any UI controls are visible. An API key is required, as the end-user still needs to be authenticated.

Use APIKeyAuthenticationConfig to download the theme from the mobile services cockpit and apply it. AppParameters.plist and ConfigurationProvider.plist have to be present for the app target to successfully download the theme configuration.

func configureNUIStyleSheetApplyStep() -> NUIStyleSheetApplyStep {
    let apiKeyAuthenticationConfig = APIKeyAuthenticationConfig(apikeys: [<#String#>], isAPIKeyAccessOnly: false, allowAnonymousAccessFlag: true)
    return NUIStyleSheetApplyStep(apiKeyAuthenticationConfig: apiKeyAuthenticationConfig)
}

public var onboardingSteps: [OnboardingStep] {
        return [
            configureNUIStyleSheetApplyStep(),
            WelcomeScreenStep(),
            CompositeStep(steps: SAPcpmsDefaultSteps.configuration),
            OAuth2AuthenticationStep(),
            ....
            ]
}

If you use the onboarding step after user authentication, you can use the following initializer. Then, no parameter is required, as the configured SAPURLSession and SAPcpmsSettingsParameters are provided from OnboardingContext.

public var onboardingSteps: [OnboardingStep] {
        return [
            WelcomeScreenStep(),
            CompositeStep(steps: SAPcpmsDefaultSteps.configuration),
            OAuth2AuthenticationStep(),
            NUIStyleSheetApplyStep(),
            ....
            ]
}

Note: NUIStyleSheetApplyStep prioritizes the parameters provided by initializers over the ones provided from OnboardingContext.

Theming of SwiftUI Views

If you use SwiftUI-based UI components from the cloud-sdk-ios-fiori open-source package, then additional steps are needed to apply theme colors to those UI components.

1. Create a custom onboarding step to call FioriThemeManager.loadStylesheetByURL(url:) with the previously downloaded theme file. The URL of the downloaded theme file can be obtained using SAPFioriFlows.SAPcpmsThemeManager.getThemeFileURL().

   import SAPCommon
   import SAPFioriFlows
   import FioriThemeManager // module from open-source package `cloud-sdk-ios-fiori`
   
   class ApplyStylingToFioriSwiftUIStep: OnboardingStep {
       var logger = Logger.shared(named: "StyleSheetStep")
       func onboard(context: SAPFioriFlows.OnboardingContext, completionHandler: @escaping (SAPFioriFlows.OnboardingResult) -> Void) {
           self.onboardOrRestore(context: context, completionHandler: completionHandler)
       }
       func restore(context: SAPFioriFlows.OnboardingContext, completionHandler: @escaping (SAPFioriFlows.OnboardingResult) -> Void) {
           self.onboardOrRestore(context: context, completionHandler: completionHandler)
       }
       func reset(context: SAPFioriFlows.OnboardingContext, completionHandler: @escaping () -> Void) {
           StyleSheetSettings.reset()
           completionHandler()
       }
       private func onboardOrRestore(context: SAPFioriFlows.OnboardingContext, completionHandler: @escaping (SAPFioriFlows.OnboardingResult) -> Void) {
           do {
               var url = try SAPcpmsThemeManager.getThemeFileURL()
               try StyleSheetSettings.loadStylesheetByURL(url: url)
           } catch {
               logger.warn("Cannot apply theming: \(error.localizedDescription)")
           }
           completionHandler(.success(context))
       }
   }
   

2. Add the onboarding step to your onboarding flow at any point after NUIStyleSheetApplyStep.

 public var onboardingSteps: [OnboardingStep] {
         return [
             WelcomeScreenStep(),
             CompositeStep(steps: SAPcpmsDefaultSteps.configuration),
             OAuth2AuthenticationStep(),
             NUIStyleSheetApplyStep(),
             // ...
             ApplyStylingToFioriSwiftUIStep(), // needs to run anytime after `NUIStyleSheetApplyStep`
             ....
             ]
 }

---

Last update: September 29, 2022