Android

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

These docs use Kotlin for all the examples but of course it also supports using the it with Java.

Installation

To get started using Shard in your Android app just add the Shard core dependency.

dependencies {
implementation 'app.visly.shard:core:<latest version>'
}

Getting started

Hello world

Before starting you must initialize the Shard library globally. Create a custom application class if you don't already have one and call ShardViewManager.init(Application). This is required to initialize some of the native dependencies used by the library.

class MyApplication: Application() {
override fun onCreate() {
super.onCreate()
ShardViewManager.init(this)
}
}

Remember to also register this application subclass in your manifest

<application android:name=".MyApplication">

Once that is done we can start move on to our Activity. We start by creating a ShardRootView, this is the root view of a Shard. We ask the ShardViewManager.instance 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.

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val result = ShardViewManager.instance.loadJson(this, """{
"root": {
"kind": "flexbox",
"props": {"background-color": "#f00"},
"layout": {
"width": {"unit": "points", "value": 200},
"height": {"unit": "points", "value": 200}
}
}
}""")
val root = ShardRootView(this)
root.setRoot(result)
setContentView(root)
}

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.

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val result = ShardViewManager.instance.loadJson(this, """{
"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}
}
}
}""")
val root = ShardRootView(this)
root.on("open-url") {
val url = (it as JsonValue.String).value
startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
}
root.setRoot(result)
setContentView(root)
}

ShardViewManager

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

loadJson

fun loadJson(ctx: Context, json: JsonValue): ShardRoot
fun loadJson(ctx: Context, json: String): ShardRoot

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

loadUrl

fun loadUrl(ctx: Context, url: String, completion: (ShardRoot) -> Unit)

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

setViewImpl

fun setViewImpl(kind: String, implFactory: (ShardContext) -> ShardViewImpl<out View>)

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.instance.load*().

setRoot

fun setRoot(root: ShardRoot)

Set the ShardRoot instance to render.

on

fun on(action: String, callback: (JsonValue?) -> Unit)

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

fun off(action: String)

Remove an event listener for the given action.

ShardContext

class ShardContext: ContextWrapper

A ShardContext implements a standard android Context and adds some Shard specific methods which are useful when creating your own Shard views.

dispatch

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

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