Pipe Storyboard

Set of components to create storyboards from pipe queries

Installation

npm install pipe-storyboard

Usage

1pipe-storyboard = require \pipe-storyboard
2Layout = create-factory pipe-storyboard.Layout
3Story = create-factory pipe-storyboard.Story
4Storyboard = create-factory pipe-storyboard.Storyboard
5
6# used for creating custom componenets
7LabelledComponent = create-factory pipe-storyboard.LabelledComponent
8
9Storyboard do 
10
11    # the pipe-server to get queries from
12    url: \http://localhost:4081
13
14    # a list of ui controls corresponding to the parameters of the child queries
15    controls: 
16        * name: \conversions
17          label: \Conversions
18          type: \number
19          default-value: 0
20          client-side: true
21        ...
22
23    # this tells the Storyboard component to load the ui-values from query-string
24    state: @props.location.query
25
26    # this function is invoked whenever a ui-value changes & updates the state
27    on-change: (new-state) ~> 
28        react-router.hash-history.replace-state null, (update-querystring window.location.href, new-state)
29
30    # A layout component is used to position queries in a Storyboard
31    Layout do 
32        style: width: \100%
33
34        # A Story component takes a query-id or branch-id and renders it
35        # the values from the ui-controls (passed as controls prop above) will be mapped to parameters
36        # and passed to each child query / layout
37        Story branch-id: \pztAHkd
38        Story branch-id: \pqucBWe

Usage (css / stylus)

@require 'node_modules/pipe-storyboard/src/index.css'

Components

• Storyboard

Connects ui controls & queries by mapping ui values to parameters, and propagating these parameters to its children. Story, Layout or a Storyboard component itself can be passed as child. A Storyboard component also propagates the pipe api server url to its children, this can be overriden by setting the url prop on the child.

1Control :: {
2    
3    # name of the control, used for fetching and updating value from state
4    name :: String 
5
6    # optional parameter, enum of standard html input types, used internally to render the ui-control
7    # if undefined the render method must be implemented
8    type :: String 
9    label :: String
10
11    # optional parameter works in conjunction with type, for example, if type is text and placeholder is 'hello'
12    # a html input element with type text and placeholder 'hello' will be rendered in the form
13    placeholder :: String
14
15    # optional parameter works in conjunction with the type value 'select'
16    options :: [String]
17    multi :: Boolean
18    tether :: Boolean
19
20    # the default ui value
21    default-value :: a
22
23    # optional parameter, false by default. 
24    # A value of true implies that only the transformation and presentaiton function will be executed (no ajax request will be made),
25    # whereas a value of false implies that an ajax request will be made to the pipe api server to re-execute the query before running the transformation & presentation functions
26    client-side: true
27
28    # optional parameter, specifies how to extract the value of the ui-control from the `State`
29    # the `State` object is passed as a prop to the `Storyboard` component, 
30    # default-implementation = (state) ~> state[name]
31    ui-value-from-state :: State -> UIValue
32
33    # optional parameter, specifies how to update the state using the new value of the ui-control
34    # the result of this function is folded (with the result from other controls) to obtain the full `State` object
35    # default implementation = (new-ui-value) ~> "#{name}" : new-ui-value
36    state-from-ui-value :: UIValue -> State' 
37
38    # optional parameter, specifies how to convert the ui-value into a parameter for the query
39    # default implementation = (ui-value) ~> "#{name}" : ui-value
40    # the result of this function is folded (with the result from other controls) to obtain the full `Parameters` object
41    # example usage: converting between local and gmt timezones
42    parameters-from-ui-value :: UIValue -> Parameters', where Parameters' :: Map Name, Value
43
44    # optional parameter, allows you to provide a custom implementation for rendering the ui-control, 
45    # the default implementation uses a combination of type, placeholder & options props
46    render? :: UIValue -> (UIValue -> ()) -> ReactElement
47}

Property	Type	Description
cache	Boolean	Number
controls	[Control]
extras	object	combines and propagates to Children
state	State	an object that stores the state of the ui controls, this can be the state of the hosting component or the query string (for example)
on-change	State -> ()	fired whenever the value of a ui-control changes, here you MUST update the state prop, above, to complete the data flow
on-execute	Parameters -> Boolean -> ()	fired whenever the user executes either by clicking on search or using (ctrl + enter / command + enter) hotkeys
on-reset	() -> ()	fired whenever the user resets the form, either by clicking or using (alt + r, option + r) hotkeys
url	String	the url of the pipe api server, propagated to the children

• Story

Renders a pipe query

Property	Type	Description
cache	Boolean	Number
branch-id	String	the branch id of the pipe query, if specified the latest query for that branch will be rendered
extras	object	extras are static parameters that are merged with the dynamic Parameters object, they help in reuse of queries
query-id	String	the query id of the pipe query to be rendered
url	String	the url of the pipe api server, usually propagated by the Storyboard component
class-name	String	custom class name for styling the component externally
style	object	custom css styles useful in combination with Layout and flexbox
title	String	title for the query, defaults to the query-title property of the pipe document
render-links	object -> ReactElement	a function that receives {query-id, branch-id, url, cache, parameters} and must return a ReactElement that renders the links on top-right corner of the query
show-title	Boolean	defaults to true
show-links	Boolean	defaults to true (setting it to false will hide the links to edit, share, .. query/result)

• Layout

Property	Type	Description
cache	Boolean	Number
class-name	String	custom class name for styling the component externally
extras	object	combines and propagates to Children
style	object	custom css styles
url	String	the url of the pipe api server, usually propagated by the Storyboard component