workflow-react v0.1.0-beta.1

React frontend for workflow

This module contains a react binding library for writing workflow configuration files. The example below shows how to configure a 50-50 split between a text editor and a browser.

import React from 'react';
import render, { Workspace, Layouts, Apps } from 'workflow-react';

const { SplitH } = Layouts;
const { TextEditor, Browser } = Apps.defaults;

export default render(
  <Workspace name={'workflow-react-example'}>
    <SplitH percent={1}>
      <TextEditor percent={0.5} file={__filename} />
      <Browser percent={0.5} url={'https://google.com'} />
    </SplitH>
  </Workspace>,
);

Api

The workflow-react package exports four distinct concepts.

• The render function
• Low level Components (Workspace, Layout, App)
• High level Components (Layouts, Apps)
• The createComponent Component factory function

The render function

The render function is used to transform a React component definition into a workflow definition. The return value of this function should be the default export of a flow defined with workflow-react, as shown in the example above.

Example

import render from "workflow-react";

export default render(...);

Low Level Components

workflow-react exports three low level Components to build more complex React components with. They are analogous to the div, span etc found in react-dom and Text, View found in react-native.

Workspace

The Workspace component is the top level component in a workflow-react flow. It is a container which holds the flow and defines the name of the flow and the list of command line arguments the flow accepts. The command line arguments are passed to each app after the flow configuration has been translated into a workflow configuration.

If you are reading this document and do not intent to develop your own Layout and App definitions, then you can skip the section covering those topics.

Definition

<Workspace
  name={<name of the workspace>}
  args={[<list of command line arguments>] | <name of single argument>}
>
  <children>
</Workspace>

Example

import React from 'react';
import render, { Workspace, Apps } from 'workflow-react';

const { TextEditor } = Apps.defaults;

export default render(
  <Workspace
    name={'editor'}
    args={"file"}
  >
    <TextEditor percent={0.5} file={({file}) => file} />
  </Workspace>,
);

Notice that the file property on the TextEditor takes a function. This function is passed an object containing all the named command line arguments. The function passes the name of the file to the TextEditor.

Usage

workflow <name of flow file> /path/to/file

Layout

The Layout component is used to group App and other Layout components together to be able to tell workflow how the Applications should be placed on the screen.

workflow only supports tiling layouts for now. This will change in the future and this will probably change this Api.

Definition

<Layout
  layout={"splith" | "splitv"}
  percent={<number in range 0.0-1.0>}
>
  <children>
</Layout>

Example

import React from 'react';
import render, { Workspace, Layout, Apps } from 'workflow-react';

const { TextEditor, Terminal } = Apps.defaults;

export default render(
  <Workspace name={'editor'}>
    <Layout
      layout={"splitv"}
      percent={1}
    >
      <TextEditor percent={0.5} />
      <Layout
        layout={"splith"}
        percent={0.5}
      >
        <Terminal percent={0.5} />
        <Terminal percent={0.5} />
      </Layout>      
    </Layout>
  </Workspace>,
);

Usage

workflow <name of flow file>

App

The App component is used to generate an app definition. These are the only Components which actually consumes space on the screen. To describe the App component we need to go into some of the implementation details of workflow. We need to know how workflow opens and communicates with the applications. Now these details does depend on the underlying windows manager, but we can generalize some concepts.

workflow will 1) open applications, 2) pass arguments to the applications and 3) tell the window manager how to position the application on the screen.

The details we need to be concerned with here are the two first. In the simplest form, both of these are a command line call to the application. This call will return the PID of the opened program and workflow will handle the rest. However, not all programs expose a sufficient command line interface. For the more complex cases we need to resort to platform or application specific scripting.

Note: i3 uses the xClass property for applying the layout. This can be found with the xprop command.

Definition

<App
  params=[<list of parameters>]
  xClass={<x window class>}
  name={<display name of the application}
  <prop-name>={<function(args)>}
  open={<function returning a command> | <platform specific object>}
/>

Example

import React from 'react';
import render, { Workspace, App } from 'workflow-react';

export default render(
  <Workspace name={'editor'} >
    <App
      params={['file']}
      xClass="Atom"
      open={({file}) => `atom -n ${file}`}
    >
  </Workspace>,
);

Usage

workflow <name of flow file> /path/to/file

High level Components

For ease of use workflow-react exposes a few predefined Layouts and Apps. These are direct re-exports of the definitions found in workflow-core. These are implemented using the low level Layout and App Components.

Layouts

The Layouts module contains two Components, <SplitH/> and <SplitV/>. These are shorthand for the <Layout/> component described above.

Definition

<SplitH percent={}><children></SplitH>

<SplitV percent={}><children></SplitV>

Example

import React from 'react';
import render, { Workspace, Layouts, Apps } from 'workflow-react';

const { SplitH, SplitV } = Layouts;
const { TextEditor, Terminal } = Apps.defaults;

export default render(
  <Workspace name={'editor'}>
    <SplitV percent={1}>
      <TextEditor percent={0.5} />
      <SplitH percent={0.5} >
        <Terminal percent={0.5} />
        <Terminal percent={0.5} />
      </Layout>      
    </Layout>
  </Workspace>,
);

Usage

workflow <name of flow file>

Apps

The Apps module defines four different collections of App Components applications. These applications are defined in workflow-core and reexported with an Component wrapper from workflow-react To generate the wrapper the createComponent factory method is applied.

The four collections are a default collection which can be use for platform independent flows and one collection for each supported platform.

• defaults {Terminal, Browser, TextEditor}
• linux {Atom, Code, Emacs, XTerm, Chrome, Chromium, Firefox, Gedit}
• osx {Atom, iTerm, Terminal, Safari}
• windows {Notepad, IExplorer, PowerShell}

Example

import {Apps} from "workflow-react";

const {Terminal, Browser, TextEditor} = Apps.defaults;
const {XTerm, Chrome, Atom} = Apps.linux;
const {iTerm, Safari, Atom} = Apps.osx;
const {PowerShell, IExplorer, Notepad} = Apps.windows;

For now apps are divided into these three categories, Terminals, Browsers, and Text Editors. For each of these categories the parameters for each application are somewhat standardized as follows:

Terminal

• cwd - the current working directory of the launched terminal
• cmd - the command to execute in cwd
• args - the list of arguments to pass to the command

Browser

• url - the url to open in the browser (should start with protocol to work on osx)

Text Editor

• file - the name of the file to open in the editor

The createComponent function

The createComponent function is a factory function which takes an object definition of an application and creates a React Component for the application. It can be used to easily provide both the workflow-core compliant object definition and the workflow-react Component for third party application definitions. However, this function is not mandatory to use to provide a React Component. The App can easily be used directly.

Example

import React from "react";
import render, {Workspace, createComponent} from "workflow-react";

const Intellij = {
  params: ["file"],
  open: ({file}) => `intellij ${file}`,
  xClass: "netbrains-intellij"
};

const IntellijComponent = createComponent(Intellij);

export default render(
  <Workspace
    name={'intellij'}
    args={"file"}
  >
    <Intellij percent={0.5} file={({file}) => file} />
  </Workspace>,
);