iOS

This documentation covers the usage of the iOS client library for adding Shard support to your iOS application. See the GitHub project to view the code, submit pull requests, and open issues.

These docs use swift for all the examples but of course it also supports using the it with Objective-C.

Installation

To get started using Shard in your iOS app start by adding the cocoapods dependency. Check the releases tab on github for the latest version number.

platform :ios, '11.0'
use_frameworks!
target 'ios' do
pod 'ShardKit', '~> <latest version>'
end

Getting started

Hello world

Open a view controller and start by creating a ShardRootView, this is the root view of a Shard. We ask the ShardViewManager.shared singleton to load a Shard payload and then set the result on our ShardRootView. In a production app we would instead use loadUrl to load this payload from a backend service.

import UIKit
import ShardKit
class ViewController: UIViewController {
override func loadView() {
self.view = ShardRootView()
}
override func viewDidLoad() {
let result = ShardViewManager.shared.loadJson("""
{
"root": {
"kind": "flexbox",
"props": {"background-color": "#f00"},
"layout": {
"width": {"unit": "points", "value": 200},
"height": {"unit": "points", "value": 200}
}
}
}
""")
let root = self.view as! ShardRootView
root.setRoot(result)
}
}

Responding to taps

A Shard view can emit events for under certain conditions defined by the view. For example if a on-click prop is specified, a view will emit an event when tapped. Responding to these events is as simple as adding an event listener to the root.

import UIKit
import ShardKit
import SafariServices
class ViewController: UIViewController {
override func loadView() {
self.view = ShardRootView()
}
override func viewDidLoad() {
let result = ShardViewManager.shared.loadJson("""
{
"root": {
"kind": "flexbox",
"props": {
"background-color": "#f00",
"on-click": {"action": "open-url", "value":"https://shardlib.com"}
},
"layout": {
"width": {"unit": "points", "value": 200},
"height": {"unit": "points", "value": 200}
}
}
}
""")
let root = self.view as! ShardRootView
root.on("open-url") {
let url = try! $0!.asString()
self.present(SFSafariViewController(url: URL(string: url)!), animated: true, completion: nil)
}
root.setRoot(result)
}
}

ShardViewManager

The root view of a Shard hierarchy. This view manages the lifecycle of a ShardRoot returned by ShardViewManager.shared.load*().

loadJson

func loadJson(_ json: JsonValue) -> ShardRoot
func loadJson(_ json: String) -> ShardRoot

Load a Shard json payload producing a ShardRoot which can be set on a ShardRootView.

loadUrl

func loadUrl(url: URL, onComplete: @escaping (ShardRoot) -> ())

Load a Shard payload from the given endpoint producing a ShardRoot which can be set on a ShardRootView.

setViewImpl

func setViewImpl(_ kind: String, _ factory: @escaping (ShardContext) -> ShardViewImpl)

Register a ShardViewImpl to handle the rendering of a view with the given kind. By default Shard handles rendering the built-in kinds such as 'flexbox', 'image', and 'text'.

ShardRootView

The root view of a Shard hierarchy. This view manages the lifecycle of a ShardRoot returned by ShardViewManager.shared.load*().

setRoot

func setRoot(_ root: ShardRoot)

Set the ShardRoot instance to render.

on

public func on(_ action: String, _ callback: @escaping (JsonValue?) -> ())

Add an event listener to be notified when an event of the given action is emitted. The callback contains a value object specific to the type of event being emitted.

off

public func on(_ action: String)

Remove an event listener for the given action.

ShardContext

A ShardContext manages keeping state for a Shard hierarchy and communicated with the hosting ShardRootView.

dispatch

func dispatch(action: String, value: JsonValue?)

Dispatch an event. Events are handled on the ShardRootView by registering callback with ShardRootView.on().