Forem: Håvard Wormdal Høiby

I know you always wanted CSS for your desktop applications!

Håvard Wormdal Høiby — Wed, 19 Sep 2018 13:22:49 +0000

workflow + Yoga + react = css layouting for your desktop apps. Well technically only Flexbox. Now you always wanted that, right? Just look at those nicely spaced application windows!

Well maybe not, at least I never did. But hey, let us not get caught up in what we would like to build, and rather see what we can build.

If you are new to workflow, then the introduction post is a good place to start.

Using it

The desktop layout above is generated by listing all image files in a folder and opening them in the image viewer xv. The sizes and positions on the screen are defined using the style attribute, just like you would on the web. This is achieved with the following snippet. Check out the full example here.

<Workspace name={'workflow-pictures'}>
  <Flex
    style={{
      width: '100%',
      height: '100%',
      flexDirection: 'row',
      flexWrap: 'wrap',
   }}
  >
    {files.map(file => (
      <XV
        style={{ height: '300px', width: '450px', margin: '30px' }}
        file={join(folder, file)}
      />
    ))}
  </Flex>
</Workspace>

The workflow-layout-yoga package exports the two layout nodes Yoga and Flex which can be used to specify layouts using Flexbox. These nodes can be used anywhere inside a layout and mixed with the SplitV and SplitH nodes from workflow-layout-tiled.

The folder and files variables contains the path to a folder and an array of files within this folder.

Integrating workflow and yogalayout

Yoga takes a tree of nodes with Flexbox layout annotations and returns a tree with absolute positions on the screen. The internal layout module of workflow, lets us specify positions for applications on the screen with absolute coordinates. The custom layout node type lets workflow-layout-yoga pass a function to workflow-layout which will be evaluated to convert the Flexbox layouts to the internal workflow node format. If you would like to extend workflow with other ways of doing layouts, the workflow-layout-yoga package is a great example to build from.

Come join the fun at GitHub and Spectrum. :)

Photos by Andrés Gómez, Walter Cheung, Wang Xi, Benjamin Atchley, Agnieszka Kowalczyk, and Paweł Czerwiński on Unsplash

Spotify on Workflow

Håvard Wormdal Høiby — Mon, 17 Sep 2018 12:44:07 +0000

App modules are at the center of workflow. They are the important glue between the internals of workflow and actual applications running on your platform. If you are new to workflow, then the introduction post is a good place to start.

Updated code samples to support workflow@2.x.

This post will guide you through a practical example of extending workflow with support for Spotify. Workflow works cross platform, and the implementation for the various platform differs. If you need to make an app run on a specific platform, the other platforms can be skipped. This post will show how to write apps for osx and i3.

Running example

As a running example in this post we will create a new app component for Spotify. Spotify does not fall into the previously defined categories of applications that workflow supports, being Terminals, Browser and Text Editors. So lets pick a simple use case for our initial version of the Spotify app. Spotify has defined a uri specification which can be used for automation. Let us use the uri to open Spotify with a given playlist.

Initializing the application

To get started with writing applications there is a npm initializer called create-workflow-app. Lets run it with the npx cli.

npx create-workflow-app workflow-app-spotify

This will generate an example application which opens emacs it the terminal. The three notable files are flows/Example.js, cli.js and src/index.js. The cli.js implements a simple workflow config which lets us test our app, by default it will use workflow-wm-terminal. The yarn example command is set up to run the flows/Example.js.

Putting our example into code.

Lets start defining our interface by implementing the example. The spotify cli takes an uri parameter, one variant of this parameter lets us specify a playlist. The uri's format is spotify:user:<username>:playlist:<playlist-id>. So lets define an example of using this specification from jsx.

<Spotify minimized play>
  <Playlist user={'<username>'} id={'<playlist id>'} />
</Spotify>

We have given our top level Spotify component a parameter called minimized which will cause the Spotify application to be launched minimized. And we have given it a child for specifying the playlist to open. This component has the username and playlist id properties. The play prop on the Spotify component will trigger autoplay.

The application scaffold

In the src/index.js file we have the scaffold for making any app for workflow. The following properties are mandatory for any app.

const Spotify = {
  type: 'app',
  name: 'Spotify',
  params: ['minimized', 'play'],
  open: ({minimized, play}, context, children) => {
    // code for the app
  }
};

The type property is used by workflow to distinguish the app node from layout and workspace nodes. The name property is used in debugging information an is exposed to the wm adapter layer. The params is used to validate the arguments passed to the node in the open function. The open function is responsible for opening the application and making sure it is placed in the expected position on the screen. The parameters to the open function are the parameters to the node in the flow, a context variable which is specific to the underlying platform and windows manager, and any child nodes passed to the node. The application it self is free to define the specification of allowed children and arguments.

Supporting workflow-wm-i3

Let us start with adding support for the i3 windows manager. The i3 windows manager is identified by context = {platform: "linux", wm: "i3"}. It requires the app to define an additional property called xClass [1]. For Spotify this is simply Spotify. The open function should return a shell command which can be executed to open the application, this is specific to i3. workflow-wm-i3 will generate a layout tree based on the xClass which will match the various applications when opened [2].

const Spotify = {
  xClass: 'Spotify',
  open: ({ minimized, play }, context, children) => {
    if (children.length !== 1) {
      throw new Error('Spotify does not support more or less than one child node');
    }

    const [child] = children;
    const uri = child.open(child, context, child.children);

    return `spotify --uri='${uri}' &`;
  }
};

We do also need to define the Platform child node [3]. Inside the platform node we build up the uri which the spotify node will return to workflow-wm-i3. This design lets us easily add new types of child nodes, which will be called by the spotify node.

const Platform = {
  type: "app",
  name: "Platform",
  params: ["user", "id"],
  open: ({user, id}, context, children) => {
    return `spotify:user:${user}:playlist:${id}`;
  }
};

That is all it takes to add support for spotify running under workflow-wm-i3.

Note The example above does not actually trigger autoplay on linux. If you figure out how to activate it, please have a look at this issue.

Supporting `workflow-wm-osx`

The OSX integration follows a more standardized method of writing apps for workflow. workflow-wm-osx will call each apps open function with the arguments passed to the app and the absolute position on the screen. The app is responsible for opening the application and positioning it on the given position. This is usually done with JXA [4]. For convenience, workflow-wm-osx will pass a function called run through the context parameter which can be used to execute JXA code. The basic scaffold for psudo implementation is given below.

const Spotify = {
  open: async (app, context, children) => {
    const uri = getUri(children, context);

    await context.run(({ minimized, play, position }, uri) => {
      const spotify = Application("Spotify");

      spotify.activate();

      const window = spotify.windows[0];
      window.bounds = app.position;

      spotify.playTrack(uri);
    }, app, uri);
  }
};

Now the most notable thing about the code above is invocation of the run function. This will call into @jxa/run which executes the function parameter with osascript and returns a promise. This means that the function passed cannot be a closure and must only reference its parameters and the context provided by the osascript environment. The code opens spotify and sets the position of the window to the position in from the app. The Spotify specific function playTrack is used to start the playlist.

The api available on the Spotify application can be found in the Script Editor application on OSX. It is possible to generate TypeScript definitions for the api, check out this for getting started.

Now, the actual code to make this work properly on OSX is a bit more complex. Check out the source code for the working version.

Footnotes

[1]: This is the X11 WM_CLASS as found by the xprop utility.

[2]: This simplistic implementation causes this bug.

[3]: For now these nodes will either use the type layout or app. Where a layout node is used as a support node for positioning other nodes, and the app node denotes something that will be visible on the screen.

[4]: JXA, or Javascript for Automation, the OSX way of writing automation scripts using Javascript

Control your desktop layout with React

Håvard Wormdal Høiby — Thu, 30 Aug 2018 14:10:36 +0000

This post is a brief introduction to writing flow files for workflow. If you are new to workflow, then the introduction post is a good place to start. The next post shows you how to add support for new apps.

Updated code samples to support workflow@2.x.

Flow files are layout declarations, where you declare which applications you want to open and where on the screen they should be appear. This post will show you how to write a flow file as a small React application using the workflow-react package.

Running example.

As a simple example, we will build a flow file for writing unit tests. This flow will contain two text editors [1], and a terminal. The editors will open the source file and the corresponding test file, while the terminal will execute the tests in watch mode. We will assume that the project is using a file name convention, so that we can derive the location and name of the test file from the source file and vice-versa. We will also assume that the project is under source control.

Further more we assume that you are using a workflow-home folder which is derived or equivalent to the one created by workflow on the first execution.

The shell

Every flow file has a default export, the exported object should be a tree structure with a workspace node as the root node. When using workflow-react, this is achieved by calling render on a Workspace component.

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

export const flow = render(
  <Workspace name="workflow-watch-test" />
);

Accepting arguments

The workspace node has a property called args which can be used to pass a list of command line arguments that the flow will require. The parameter for our example will be the absolute path of either the test file or the source file. As we only have a single argument, we set the args prop of the component to the string name that we want to give the argument. An array of strings is passed if more values are needed. The position in this array denotes the position of the argument on the command line. [2]

<Workspace name="workflow-watch-test" args="path" />

Defining the layout

Workflow has two main packages for defining layouts. The workflow-layout-yoga package provides an api similar to Flexbox of the CSS language. The workflow-layout-tiled is a simpler approach which exposes two nodes; a vertical and a horizontal split (SplitV and SplitH). These can be used to split the parent node into a number of child nodes horizontally or vertically with the size given by the percent property. We will use one of each of these nodes to make a 80%-20% split between the terminal and the text editors and a 50%-50% split between the text editors.

import {requireComponent} from "workflow-react";

const {SplitV, SplitH} = requireComponent("workflow-layout-tiled");

export const flow = render(
  <Workspace ...>
    <SplitV percent={1.0}>
      <SplitH percent={0.8}>
        <... percent={0.5} />
        <... percent={0.5} />
      </SplitH>
      <... percent={0.2} />
    </SplitV>
  </Workspace>
);

Notice that the SplitV and SplitH components are imported with a custom require function which is exported by the workflow-react package. This function will internally require the npm package workflow-layout-tiled and wrap the contents into React components. This approach is used so that both layout and app definitions are in no way tied to React and can be shared with other frontends too, like workflow-angular. You can read more about this functionality here.

Instantiating the apps

Now the last piece of the puzzle is to pass the appropriate props into the app components so that they will be able to launch with the expected files and commands.

Importing the default apps

The first thing to take note of is the import. We are using the default application collection package called workflow-apps-defaults. This package exports TextEditor, Terminal, and Browser. These have defaults for each platform, but they can be overridden by the user in the workflow-home directory. By using this package, the flow file can be shared without modification by users on different platforms and with different preferences for applications.

const {Terminal, TextEditor} = requireComponent("workflow-apps-defaults");

Loading the source file

By default [3], workflow will call all properties in app nodes which are functions [4] with the command line arguments. In this example we gave the argument the name path. We thus pass a function to the file property of the TextEditor component to make it evaluate to the path to the source file from the command line argument. The function will handle the conversion from a path to the test file, if the argument was the test file.

function sourceFile({path}) {
  if (path.includes("src")) {
    return path;
  } else {
    return path.replace("test/unit", "src").replace("_tests.js", ".js");
  }
}

export const flow = render(
     <...>
        <TextEditor ... file={sourceFile} />
        <... />
      </...>
);

Loading the test file

The test file is loaded in exactly the same way as the source file. Just with the opposite conversion.

function testFile({path}) {
  if (path.includes("test/unit")) {
    return path;
  } else {
    return path.replace("src", "test/unit").replace(".js", "_tests.js");
  }
}

export const flow = render(
     <...>
        <TextEditor ... file={testFile} />
        <... />
      </...>
);

Launching the test in a terminal

The last component make use of the npm package execa to execute a git command to figure out the root of the repository. The root path is used as the current working directory when opening the terminal. We reuse the testFile function to compute the the test path. This is passed to the args property of the terminal. If a property is set to an array which contains functions, these functions are also called with the command line arguments.

import {dirname} from "path";
import execa from "execa";

function projectRoot({path}) {
  const cwd = dirname(path);
  const {stdout} = execa.sync('git', ["rev-parse", "--show-toplevel"], {cwd});
  return stdout.trim();
}

export const flow = render(
    <...>
      <Terminal 
        percent={0.2} 
        cwd={projectRoot}
        cmd={"npm run test -- --watch "}
        args={[testFile]}
      />
    </...>
);

Executing the flow

If you add the full example as the file WorkflowRunTest.js under your WORKFLOW_HOME/flows directory, and install the execa package with npm i execa. Then the following command will execute our example flow.

$  workflow WorkflowWatchTest.js /path/to/workflow-repo/packages/workflow-resolver-absolute/src/index.js

This should open packages/workflow-resolver-absolute/src/index.js and packages/workflow-resolver-absolute/test/unit/index_tests.js in the default editor and run the npm run test -- --watch /path/to/workflow-repo/packages/workflow-resolver-absolute/test/unit/index_tests.js command in /path/to/workflow-repo.

The full example

This is the full flow file for our example.

import {dirname} from "path";
import React from "react";
import execa from "execa";
import { render, Workspace, requireComponent} from "workflow-react";

const {SplitV, SplitH} = requireComponent("workflow-layout-tiled");
const {Terminal, TextEditor} = requireComponent("workflow-apps-defaults");

function sourceFile({path}) {
  if (path.includes("src")) {
    return path;
  } else {
    return path.replace("test/unit", "src").replace("_tests.js", ".js");
  }
}

function testFile({path}) {
  if (path.includes("test/unit")) {
    return path;
  } else {
    return path.replace("src", "test/unit").replace(".js", "_tests.js");
  }
}

function projectRoot({path}) {
  const cwd = dirname(path);
  const {stdout} = execa.sync('git', ["rev-parse", "--show-toplevel"], {cwd});
  return stdout.trim();
}

export const flow = render(
  <Workspace name="workflow-watch-test" args="path">
    <SplitV percent={1.0}>
      <SplitH percent={0.8}>
        <TextEditor percent={0.5} file={sourceFile} />
        <TextEditor percent={0.5} file={testFile} />
      </SplitH>
      <Terminal
        percent={0.2}
        cwd={projectRoot}
        cmd={"npm run test -- --watch "}
        args={[testFile]}
      />
    </SplitV>
  </Workspace>
);

Footnotes

[1]: You might be thinking that we would want one text editor with a split inside it. This is possible with workflow, but is currently only supported by a few applications like emacs. This is how:

<Emacs percent={0.8}>
  <SplitH >
    <File percent={0.5} file={sourceFile} />
    <File percent={0.5} file={testFile} />
  </SplitH>
</Emacs>

See a complete example here.

[2]: Due to a bug in argument parsing you might need to specify the arguments as <Workspace ... args={["ignore", "path]} /> for the example to work.

[3]: If you let workflow set up your home folder on the first execution you are using the default workflow-home. It contains the workflow-transformer-apply-arguments-to-fields. This transformer implemented the functionality which passes command line arguments into properties on the app nodes.

[4]: Except for the open function. This function will be described in detail in an upcoming post about creating new apps.

Introducing workflow

Håvard Wormdal Høiby — Tue, 28 Aug 2018 18:15:47 +0000

First posted on https://spectrum.chat/workflow?thread=7679137d-130c-4b8a-8eb2-09acf0d2b27c. Updated code samples to support workflow@2.x.

workflow is a node command line tool that turns declarative layouts into running applications on your screen.

Layouts can be declared as javascript objects or as React applications. Layouts contain apps and their position on the screen, in addition to arguments which are passed to the apps. The code example below is the layout used in the gif above, declared as a React application. The React application is evaluated into javascript objects by a custom reconciler in the render function.

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

const { SplitH, SplitV } = requireComponent('workflow-layout-tiled');
const { TextEditor, Browser, Terminal } = requireComponent('workflow-apps-defaults');

export const flow = render(
  <Workspace name={'workflow-react-example'}>
    <SplitV percent={1.0}>
      <SplitH percent={0.8}>
        <TextEditor percent={0.5} file={__filename} />
        <Browser percent={0.5} url={'https://github.com/havardh/workflow'} />
      </SplitH>
      <Terminal percent={0.2} cwd={__dirname} />
    </SplitV>
  </Workspace>
);

Support

workflow supports Linux using i3 and OSX. It has experimental support for Windows and Linux using wmctrl (Ubuntu and more). There is support for at least one terminal, browser and text editor for each platform. Upcoming posts will describe how to implement/improve windows manager support and adding support for more applications.

Getting started

$ npm install --global workflow
$ workflow ReactExample.js

When you run workflow for the first time, it will ask you to set up your workflow-home directory. This is the place where you will add all your layouts and supporting libraries. The default location for the workflow-home directory is ~/.workflow.

This post is the first in a series on how to use and extend workflow to suit your needs. The next post describes how to write your own layout declarations. Workflow is still experimental and incomplete, but the foundations are starting to come together. Come join me building the community at https://spectrum.chat/workflow and the development at https://github.com/havardh/workflow.

Forem: Håvard Wormdal Høiby

I know you always wanted CSS for your desktop applications!

Using it

Integrating workflow and yogalayout

Spotify on Workflow

Running example

Initializing the application

Putting our example into code.

The application scaffold

Supporting workflow-wm-i3

Supporting workflow-wm-osx

Footnotes

Control your desktop layout with React

Running example.

The shell

Accepting arguments

Defining the layout

Instantiating the apps

Importing the default apps

Loading the source file

Loading the test file

Launching the test in a terminal

Executing the flow

The full example

Footnotes

Introducing workflow

Support

Getting started

Supporting `workflow-wm-osx`