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 | pipe query cache parameter, propagated to children | | 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 | pipe query cache parameter | | 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 | pipe query cache parameter, propagated to children | | 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 |