Pipe Storyboard

Set of components to create storyboards from pipe queries

Installation

npm install pipe-storyboard

Usage

pipe-storyboard = require \pipe-storyboard
Layout = create-factory pipe-storyboard.Layout
Story = create-factory pipe-storyboard.Story
Storyboard = create-factory pipe-storyboard.Storyboard

# used for creating custom componenets
LabelledComponent = create-factory pipe-storyboard.LabelledComponent

Storyboard do 

    # the pipe-server to get queries from
    url: \http://localhost:4081

    # a list of ui controls corresponding to the parameters of the child queries
    controls: 
        * name: \conversions
          label: \Conversions
          type: \number
          default-value: 0
          client-side: true
        ...

    # this tells the Storyboard component to load the ui-values from query-string
    state: @props.location.query

    # this function is invoked whenever a ui-value changes & updates the state
    on-change: (new-state) ~> 
        react-router.hash-history.replace-state null, (update-querystring window.location.href, new-state)

    # A layout component is used to position queries in a Storyboard
    Layout do 
        style: width: \100%

        # A Story component takes a query-id or branch-id and renders it
        # the values from the ui-controls (passed as controls prop above) will be mapped to parameters
        # and passed to each child query / layout
        Story branch-id: \pztAHkd
        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.

Control :: {
    
    # name of the control, used for fetching and updating value from state
    name :: String 

    # optional parameter, enum of standard html input types, used internally to render the ui-control
    # if undefined the render method must be implemented
    type :: String 
    label :: String

    # optional parameter works in conjunction with type, for example, if type is text and placeholder is 'hello'
    # a html input element with type text and placeholder 'hello' will be rendered in the form
    placeholder :: String

    # optional parameter works in conjunction with the type value 'select'
    options :: [String]
    multi :: Boolean
    tether :: Boolean

    # the default ui value
    default-value :: a

    # optional parameter, false by default. 
    # A value of true implies that only the transformation and presentaiton function will be executed (no ajax request will be made),
    # 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
    client-side: true

    # optional parameter, specifies how to extract the value of the ui-control from the `State`
    # the `State` object is passed as a prop to the `Storyboard` component, 
    # default-implementation = (state) ~> state[name]
    ui-value-from-state :: State -> UIValue

    # optional parameter, specifies how to update the state using the new value of the ui-control
    # the result of this function is folded (with the result from other controls) to obtain the full `State` object
    # default implementation = (new-ui-value) ~> "#{name}" : new-ui-value
    state-from-ui-value :: UIValue -> State' 

    # optional parameter, specifies how to convert the ui-value into a parameter for the query
    # default implementation = (ui-value) ~> "#{name}" : ui-value
    # the result of this function is folded (with the result from other controls) to obtain the full `Parameters` object
    # example usage: converting between local and gmt timezones
    parameters-from-ui-value :: UIValue -> Parameters', where Parameters' :: Map Name, Value

    # optional parameter, allows you to provide a custom implementation for rendering the ui-control, 
    # the default implementation uses a combination of type, placeholder & options props
    render? :: UIValue -> (UIValue -> ()) -> ReactElement
}

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