@citydna/platform

The official SDK for creating apps for the Melbourne CityDNA platform.

Ecosystem

Works great with @citydna/common (branded component library), @citydna/maps (mapping components) and the @material-ui/core package for all your other UI needs. We've chosen to enforce typescript to avoid common mistakes, however, these packages can be used without it.

Installation

Only use this package with the citydna create-react-app template. It'll be relatively useless without it :)

$ yarn create react-app citydna-app-example --template=citydna
$ cd citydna-app-example
$ yarn add @citydna/platform

Usage

// src/Controller.citydna.tsx
import React from 'react'
import { CityDNAComponent, useDevices } from '@citydna/platform'

const MyControllerComponent:CityDNAComponent = () => {
  // 1. grab the emit function
  const { emit } = useDevices()

  // 2. set up your event handler
  const sendEventToScreen = () => emit("my-event", "Hello world")

  // 3. use your event handler.
  return <button onClick={sendEventToScreen}>Send event to screen</button>
}

// Platform annotation (see http://citydna.melbourne/cra-template)
MyControllerComponent.citydna = {...}
export default MyControllerComponent

// src/Screen.citydna.tsx
import React from "react"
import { CityDNAComponent, useDevices } from "@citydna/platform"

const MyScreenComponent: CityDNAComponent = () => {
  // 1. get event listener hook
  const { useEvent } = useDevices()

  // 2. use it to respond to events
  useEvent("my-event", data => {
    console.log(data) // => "Hello World"
  })

  return <>I am the screen!</>
}

---

API - TSDoc

You can check out the TSDoc for detailed information about types described below.

useDevices()

This hook gives your app access to devices in the room, which app components they are allocated to, as well as emitting to and listening for events within the room.

// API
const { devices, emit, myID, useEvent } = useDevices()

This will be the most commonly used hook when developing apps that communicate across devices.

devices:Device[] & {allocation: DeviceAllocation}[]

Returns an array of connected devices, including their name, type and any allocated app components.

emit<T>:(eventName:string, data:T) => void

Returns a function that allows you to emit events to all devices in the room.

myID:string

The device ID automatically generated when authorising with the Pusher service. Helps you find your own config in the devices array.

useEvent<T>:(eventName:string, callback:(data:T) => voidå) => void

Returns a hook that allows you to listen to events sent by emit.

---

useApp()

const { room, app, manifest, appSettings, setAppSettings } = useApp()