Repository files navigation

The NoFlo Development Environment is an offline-capable, client-side web applicationthat helps users to build and run flow-based programs built with FBP compatible systems such asNoFlo,MsgFlo,imgflo andMicroFlo.The NoFlo Development Environment is available under theMIT license.

This project was made possible by1205 Kickstarter backers.Check theproject ChangeLog for new features and other changes.

Flowhub is a hosted version of the NoFlo Development Environment.

If you just want to create applications, we recommend that you use this version instead of building your own from source.

Even though the UI itself is built with NoFlo, it isn't talking directly with NoFlo for running and building graphs.Instead, it is utilizing theFBP Network Protocol which enables it to talk toany compatible FBP system.Currently over 5 different runtimes are known to work.

By implementing the protocol in your runtime, you can program it with NoFlo UI.If you use WebSockets or WebRTC as the transport, you do not need to change anything on NoFlo UI.You can alsoadd support other transports.

The easiest way to pass user the connection information of your runtime is through thelive mode. With this, the connection details are passed to the app via URL parameters, like this:

http://app.flowhub.io#runtime/endpoint?protocol%3Dwebsocket%26address%3Dws%3A%2F%2F127.0.0.1%3A3569

The supported parameters for the endpoint include:

• protocol: the FBP protocol transport to use for the connection. Possible values includewebsocket,iframe, andwebrtc
• address: URL to use for the connection. Can be for instancews:// URL for WebSockets, or the signaller URL and connection identifier for WebRTC
• secret: secret to use for communicating with the runtime

These URLs can be shown on command line output, or provided to user via other mechanism. See avideo demonstration of opening the app in live mode via a NFC tag.

One canoptionally add component templates, syntax highlighting and a 'get started' link for new runtimes.

1. Add a new YAML file with runtime info as./runtimeinfo/myruntime.yaml.Example
2. Include it in./runtimeinfo/index.js
3. Commit the changes
4. Send aPull Request, so everyone benefits!

Only necessary if you want to hack on NoFlo UI itself. Not neccesary for making apps with FBP.

A Dockerfile has been provided that can be used to easily build/run the NoFlo UI. You can also get an automatically built imagefrom Docker Hub.

docker build -t noflo-ui.

docker run -d -p 9999:80 noflo-ui

Once it is built and the server is running you can access the UI athttp://localhost:9999/index.html

To be able to work on the NoFlo UI you need:

• A checkout of this repository
• A workingNode.js installation
• At least version 3 of the NPM package manager

Go to the checkout folder and run:

$ npm install

This will provide you with all the needed development dependencies. Now you can build a new version by running:

$ npm run build

You have to run this command as an administrator on Windows.

Serve the UI using a webserver, then open the URL it in a web browser. Example:

$ npm start

If you prefer, you can instead start a webpack dev server process that will do a rebuild whenever one of the files changes:

$ npm run dev

Once it is built and the server is running you can access the UI athttp://localhost:9999/index.html

In addition to this project, the other repository of interest is thethe-graph graph editor widget used for editing flows.

On high level, the noflo-ui architecture followsRedux conventions adapted to NoFlo. Here is how the main data flow looks like:

Store OUT -> IN Middleware     # Store sends actions together with application state to middlewareMiddleware NEW -> ACTION Store # Middleware can trigger new actionsMiddleware PASS -> IN Reduce   # Actions go from middleware to reducersReduce OUT -> STATE Store      # Reducers produce a new state object that gets sent to storeReduce OUT -> STATE View       # State also goes to the viewView ACTION -> ACTION Store    # View can trigger actions

The actual flow is more detailed. You can view and edit it ingraphs/main.fbp.

Note: the priciples outlined below are the architecture we're aiming towards. We're refactoring parts of the system to fit this architecture as we modify them. All new functionality should be implemented following this architecture.

The Store component keeps track of the latest application state. When it receives new actions, it sends the out to the middleware and reducer chain together with the latest application state.

noflo-ui middleware are components or graphs that can interact with particular actions. Each action passes through the chain of middlewares, and each middleware has two options on dealing with an action:

1. Pass the action along without modifying it
2. Capture the action and trigger new action(s)

Middleware are where side effects related to the application state are handled. This can include talking to external web services, FBP runtime communications, and loading or saving data to the local IndexedDB. Middleware do receive the current application state and can read from it, but they only manipulate state by the way of creating new actions.

Some middleware can also act asgenerators, creating new actions based on external input.

The middleware approach is explained further inthis blog post.

The job of the reducers is to receive actions and make changes to application state. The reducers must in effect be pure functions, where the same input state and action combination always produces the same new state.

The application's view layer is implemented asPolymer elements. The application view receives the state object produced by the reducers.

User interactions in the application view must not make direct state changes. Instead, the application view can trigger new actions by firing Polymer events. These then get processed by the middleware and reducers, causing the state to change.

NoFlo UI is using GitHub for authentication. We have a default application configured to work athttp://localhost:9999. If you want to serve your NoFlo UI from a different URL, you need to register your ownOAuth application with them. Make sure to match GitHub'sredirect URL policy.

To enable your own OAuth application, set the following environment variables and rebuild NoFlo UI:

• $NOFLO_OAUTH_CLIENT_ID: Client ID of your GitHub OAuth application
• $NOFLO_OAUTH_CLIENT_REDIRECT: Redirect URL of your GitHub OAuth application

For handling the OAuth Client Secret part of the login process, there are two options:

This is the easy option for local NoFlo UI development. Simply build the OAuth client secret into the NoFlo UI app by setting it via the$NOFLO_OAUTH_CLIENT_SECRET environment variable.

Note: this means anybody with access to this NoFlo UI build will be able to read your client secret. Never do this with a world-accessible URL. It is fine for local-only development builds, though.

You can deploy an instance of theGatekeeper Node.js app to handle the OAuth token exchange for you. Configure the Gatekeeper location to your NoFlo UI build with$NOFLO_OAUTH_GATE environment variable.

This is the more secure mechanism, since only the Gatekeeper server needs to know the Client Secret.