Using the iOS Renderer

iOS Project Requirements

The minimum requirements are:
  • iOS 14
  • Swift 5.0

Installing the library

The iOS Renderer is available through Cocoapods dependency manager.

Prerequisites

  • Cocoapods gem installed

Cocoapods private trunk setup

Add the private trunk repo to your local Cocoapods installation with the command:
1
pod repo add repo-specs-name [email protected]/[repo-specs-name].git
Copied!

Adding the dependency

Add the source of private repository in the Podfile
1
source '[email protected]/[repo-specs-name].git'
Copied!
Add the pod and then run pod install
1
pod 'FlowX'
Copied!

Library dependencies

  • Socket.IO-Client-Swift
  • Alamofire
  • SVProgressHUD
  • SDWebImageSwiftUI

Library configuration

The SDK has 3 types of configurations, available through 3 shared instances.
It is recommended to call the configuration methods at app launch.
Otherwise, make sure you do it before the start of any FlowX process.

FXConfig

This config is used for general purpose properties.

Properties

Name
Description
Type
Requirement
baseURL
The base URL used for REST networking
String
Mandatory
socketBaseURL
The URL user for socket networking
URL
Mandatory
stepViewType
The type of the custom step view class
FXStepViewProtocol.Type
Optional
logEnabled
Value indicating whether console logging is enabled. Default is false
Bool
Optional
Sample
1
FXConfig.sharedInstance.configure { (config) in
2
config.baseURL = environmentConfig.baseURL
3
config.socketBaseURL = environmentConfig.socketBaseURL
4
config.logEnabled = true
5
config.stepViewType = CustomStepView.self
6
}
Copied!

FXSessionConfig

This config is used for providing networking or auth session specific properties.
The library expects a session instance managed by the container app. Request adapting and retrying is handled by the container app.

Properties

Name
Description
Type
sessionManager
Alamofire session instance used for REST networking
Session
token
JWT authentication token
String

Sample

1
FXSessionConfig.sharedInstance.configure { config in
2
config.sessionManager = sessionManager()
3
config.token = environmentConfig.authorizationToken
4
}
Copied!

FXTheme

This config is used for providing custom theming properties, such as colors and fonts.
Name
Description
Type
primaryColor
UIColor
primaryDisabledColor
UIColor
blackColor
UIColor
whiteColor
UIColor
gray1Color
UIColor
gray2Color
UIColor
gray3Color
UIColor
gray4Color
UIColor
gray5Color
UIColor
accentColor
UIColor
successColor
UIColor
warningColor
UIColor
errorColor
UIColor
heading1Font
UIFont
heading2Font
UIFont
heading3Font
UIFont
heading4Font
UIFont
paragraph1Font
UIFont
paragraph2Font
UIFont
captionFont
UIFont
buttonFont
UIFont
linkFont
UIFont
smallButtonFont
UIFont

Sample

1
FXTheme.sharedInstance.configure { config in
2
config.primaryColor = UIColor(red: 60.0/255.0, green: 170.0/255.0, blue: 170.0/255.0, alpha: 1.0)
3
}
Copied!

Using the library

The following library's public APIs are called using the shared instance of FlowX, FlowX.sharedInstance.

How to start and end FlowX session

After all the configurations are set, you can start a FlowX session by calling the startSession() method.
This is optional, as the session starts lazily when the first process is started.
FlowX.sharedInstance.startSession()
When you want to end a FlowX session, you can call the endSession() method. This also does a complete clean up of the started processes.
You might want to use this method in a different scenario, for instance when the user logs out.
FlowX.sharedInstance.endSession()

How to start a process

You can start a process by calling the following method.
The container app is responsible with presenting the navigation controller holding the process navigation.
1
public func startOrRestartProcess(navigationController: UINavigationController,
2
name: String,
3
params: [String: Any]?,
4
isModal: Bool = false)
Copied!
navigationController - the instance of UINavigationController which will hold the process navigation stack
name - the name of the process
params - the start parameters, if any
isModal - a boolean indicating whether the process is modally displayed.

Sample

1
FlowX.sharedInstance.startOrRestartProcess(navigationController: processNavigationController,
2
name: processName,
3
params: startParams,
4
isModal: true)
Copied!
1
self.present(processNavigationController, animated: true, completion: nil)
Copied!

How to end a process

You can manually end a process by calling the stopProcess(name: String) method.

Sample

1
FlowX.sharedInstance.stopProcess(name: processName)
Copied!

How to run an action

The custom components which the container app provides will contains FlowX actions to be executed. In order to run an action you need to call the following method:
1
public func runAction(action: [String: Any],
2
params: [String: Any]? = nil)
Copied!
action - the action object provided in the original data dictionary
params - the parameters for the action

Handling authorization token changes

When the access token of the auth session changes, you can update it in the renderer using the func updateAuthorization(token: String) method.

FXDataSource

The library offers a way of communication with the container app through the FXDataSource protocol.
The data source is a public property of FlowX shared instance.
public weak var dataSource: FXDataSource?
1
public protocol FXDataSource: AnyObject {
2
func controllerFor(componentIdentifier: String) -> FXController?
3
4
func viewFor(componentIdentifier: String) -> FXView?
5
6
func navigationController() -> UINavigationController?
7
8
func errorReceivedForAction(name: String?)
9
10
func validate(validatorName: String, value: String) -> Bool
11
12
func dismissRequested(forProcess process: String, navigationController: UINavigationController)
13
14
}
Copied!
  • func controllerFor(componentIdentifier: String) -> FXController?
This method is used for providing a custom component view controller, by the component identifier.
  • func viewFor(componentIdentifier: String) -> FXView?
Thie method is used for providing a custom view used in a generated screen, by the component identifier
  • func navigationController() -> UINavigationController?
This method is used for providing a navigation controller. It can be either a custom UINavigationController class, or just a regular UINavigationController instance themed by the container app.
  • func errorReceivedForAction(name: String?)
This method is called when an error occurs after an action is executed.
  • func validate(validatorName: String, value: String) -> Bool
This method is used for custom validators. It provides the name of the validator and the value to be validated. The method returns a boolean indicating whether the value is valid or not.
  • func dismissRequested(forProcess process: String, navigationController: UINavigationController)
This method is called, on a modally displayed process navigation, when the user attempts to dismiss the modal navigation. Typically it is used when you want to present a confirmation pop-up.
The container app is responsible with dismissing the UI and calling the stop process APIs.

FXController

FXController is a protocol which helps the container app provide custom component screens to the renderer. It needs to be implemented by UIViewController instances.
1
public protocol FXController: UIViewController {
2
var data: [String: Any]? { get set }
3
func populateUI(data: [String: Any])
4
func updateUI(data: [String: Any])
5
}
Copied!
  • var data: [String: Any]?
data is a dictionary property, containing the two keys needed by the custom component, data and actions.
  • func populateUI(data: [String: Any])
This method is called by the renderer, after the controller has been presented, when the data is available.
This will happen asynchronously. It is the container app's responsibility to make sure that the initial state of the view controller does not have default/residual values displayed.
  • func updateUI(data: [String: Any])
This method is called by the renderer when an already displayed view controller needs to update the data shown.

FXView

FXView is a protocol which helps the container app provide custom subviews of a generated screen to the renderer. It needs to be implemented by UIView instances. Similarly to FXController it has a data property and a populate method.
1
public protocol FXView: UIView {
2
var data: [String: Any]? { get set }
3
func populateUI(data: [String: Any]?)
4
}
Copied!
  • var data: [String: Any]?
data is a dictionary property containing the information needed by the custom view.
  • func populateUI(data: [String: Any]?)
This method is called by the renderer, after the screen containing the view has been displayed.
It is the container app's responsibility to make sure that the initial state of the view does not have default/residual values displayed.
Last modified 1mo ago