brightwheel

Build beautiful Electron user interfaces with Photon and Etch

About

Brightwheel is a JavaScript library that lets you use Etch and Photon to construct and manage the state of user interfaces for Electron applications.

Getting Started

Installation

Add Brightwheel and Photon to your project's dependencies.

$ npm install --save brightwheel photonkit

Usage

Include Photon styles in your HTML file's <head>.

<link rel="stylesheet" href="node_modules/photonkit/dist/css/photon.css">

To use Brightwheel, simply import the library in any modules that use components from it.

// Import and namespace all components
const UI = require('brightwheel')

Creating Components

Expressive construction with JSX

Brightwheel works with JSX, which allows you to be more expressive about nested component construction and application layout. Extending Brightwheel components allows you to create more complex applications and is the recommended way to use this library.

To use JSX:

Make sure your project includes all of the necessary presets and plugins for transpiling JSX. There are several tutorials available online depending on your particular setup.
Create custom components that extend the BrightwheelComponent class and define their structure by overriding the render() method.
Implement custom behavior in your components via additional methods.

Note: As of v0.2.0, Brightwheel supports Etch's ref functionality, which allows you to access nested components programmatically via their associated ref. Event handling via Etch's on property will be available in a future release. More info about these Etch features is available here.

// The pragma below instructs etch to preprocess the JSX in this file
//
/** @jsx etch.dom */

// Require Brightwheel library and Etch for the preprocessing JSX
const UI = require('brightwheel')
const etch = require('etch')

// Import other custom components
const ToolBarTop = require('./components/toolbar-top')
const NavPane = require('./components/nav-pane')

// Define your own custom components by extending BrightwheelComponent.
// Override the render method to define the structure of your component.
// You can nest components within components and mix stock Brightwheel
// components with custom components.
// You can also create custom Etch components and use those as well.
class MainWindowLayout extends UI.BrightwheelComponent {
  render () {
    return (
      <UI.Window>                 // Stock component
        <ToolbarTop>              // Custom components
            <AddFileButton />     // ...
        </ToolbarTop>             // ...
        <UI.WindowContent>
          <UI.PaneGroup>
            <NavPane />
            <UI.Pane classNames='padded-more' />
          </UI.PaneGroup>
        </UI.WindowContent>
      </UI.Window>
    )
  }
}

// You can also extend individual components to add custom behavior
// for state management and event handling
class AddFileButton extends UI.Button {
  constructor (properties, children) {
    super(properties, children)
    this.properties.icon = 'plus'
    this.properties.size = 'large'
    this.update(this.properties, this.children)
  }

  loadFile(target) {
    // define custom component behavior
  }
}

// To a use component, add its element to the DOM
let mainWindowLayout = new MainWindowLayout()
let pagebody = document.querySelector('body')
pagebody.insertBefore(mainWindowLayout.element, pagebody.firstChild)

With JavaScript

Because Brightwheel components are just JavaScript objects, you can manage them programmatically like other objects. While this approach will work for simple scenarios, it can make your code unwieldy in a more complex application.

let mySubmitButton = new UI.Button({
  type: 'positive',
  size: 'mini',
  text: 'Submit'
  // specify other properties as needed
}, []);

let myCancelButton = new UI.Button({
  type: 'default',
  size: 'mini',
  text: 'Cancel'
  // specify other properties as needed
}, []);


// Nest components within parent components
let myActions = new UI.FormActions({
  // specify properties as needed
}, [
  mySubmitButton,
  myCancelButton
]);

// Nest the elements within the DOM
document.querySelector('#form-1').appendChild(myActions.element);

Contributing

Pull Requests are welcome!

For an outline of the overall development priorities, have a look at the current ROADMAP.md file.

Please follow the steps below to contribute to this project:

Look for an open issue (or open one if it doesn't already exist)
Fork this repository
Be sure to write tests for the changes you're proposing
Open a Pull Request and mention @loranallensmith
To help with discoverability down the road, it helps to reference the original Issue your changes address in the body of your Pull Request

How to Test

Run one, or a combination of the following commands to lint and test your code:

$ npm test              # Run unit tests with Mocha

loranallensmith/brightwheel