bladerunnerjs / brjs

BladeRunnerJS (BRJS) is an open source development toolkit and framework for modular construction of large single-page HTML5 apps. It consists of a set of conventions, supporting tools and micro-libraries that make it easy to develop, test, deploy and maintain complex JavaScript apps.

BladeRunnerJS (BRJS)

Divide & conquer complex web apps

Getting Started

The best way to get started depends on why you're here.

• I want to build an application with BRJS.
• I want to learn more about BRJS.
• I'm already familiar with BRJS and want to write a plugin.
• I'd like to get the core BRJS development environment set up.

Documentation

The main documentation for BRJS can be found via http://bladerunnerjs.org/docs. The source code for the documentation can be found via https://github.com/BladeRunnerJS/brjs-site so if you find any error or have any suggestions please submit a pull request.

API reference guides are coming soon.

BRJS Core Toolkit Development

If you are interested in contributing to the BRJS core toolkit then the following information is of use.

How to build BRJS

Get the code

git clone [email protected]:BladeRunnerJS/brjs.git
cd brjs

Install JDK

BRJS is written and compiled using Java 8. Before running the build you will need to do the following:

• Install Java 8 JDKs.
• Configure JAVA_HOME to point to the Java 8 JDK home directory, as you prefer.
• Configure the path environment variable to include $JAVA_HOME/bin.

If you install Java using the Windows installer than it places a 'java' executable in 'C:\windows\system32' that proxies to the most recently installed version of Java. You will either need to install your preferred implementation of Java last, or ensure that the path to the Java 'bin' directory appears before 'C:\windows\system32'.

Build a Distributable Zip

From the root brjs source directory:

$ ./gradlew brjs-sdk:distZip

The built zip file will be found in BRJS_ROOT/brjs-sdk/build/distributions/ in the format BladeRunner-VERSION.zip.

More information

See the BRJS Developer Setup Guide for more information. See how the BRJS team use Github and git.

brjs's Issues

The create-app command should default a namespace to something based on the app name

Another Sprint.ly test

help the CaplinTrader team get their first BladeRunnerJS release out of the door

fix the js-test-driver json bug that often prevents you seeing your errors

originally raised by @thanhc - see https://github.com/BladeRunnerJS/brjs-private/issues/199 for the original issue

"This is the issue when the JSON is corrupt and as a result you get a js test driver error instead of what test failed"

Aspects should be optional

As per the title - Aspects should be optional.

This means that the contents usually found in an aspect should be able to reside within the root of an application.

From an upcoming blog/tutorial about BRJS and Angular:

---

Create the Todo App

Use the create-app command to scaffold a BRJS application.

$ ./brjs create-app brjstodo

For now, applications need to reside within an apps folder within the BladeRunnerJS directory. The above command will create an application called brjstodo within the apps directory. That directory will have the following contents:

apps/brjstodo
├── app.conf    # Application configuration
├── index.html  # Application entry point
├── src         # For app-level JavaScript
├── resources   # For other app resources
├── themes      # CSS and images
├── libs        # Other app libraries

---

Does this provide enough as an acceptance criteria?

populate brjs-testing and create compatibility stubs

BladeSets should be optional

BladeSets are a concept that have their uses, but aren't required to start of with.

Internally this may mean that there is a default BladeSet that doesn't reside within a bladeset- directory. But for the developer PoV there isn't a BladeSet.

Update create command plugin doc's

update with gradle build option, also review if a step is missing somewhere regarding the eclipse jar building

---

comment from @leggetter :
It's going to need a general overhaul since the CommandPlugin interface may get a new method (getUsageHelp) and the namespace has changed to org.bladerunnerjs.

It may break the doc flow to say "oh, you can do this with gradle too". So, may be worth considering another doc for gradle. I'll know more once I try it out.

Definitely worth having this issue to keep track.

comment from @thanhc :

Dom's made the changes now I believe, but on another note, I have followed the instructions but for some reason my command is not shown when running help, is there a step missing?

comment from @leggetter :
@thanhc I'll look at this when I get to this doc again. Probably late next week.

Blog/FAQ: why not use Node.js and Grunt

Let's address the elephant in the room :)

Alias brjs command "start" to "serve"

serve is used to start the development servers in other toolkits, so we should try to be consistent.

See: yeoman/yeoman#1183

Allow separate JS files in tests to enable JS Code Coverage

Once BRJS can support generating individual .js files as an option, instead of bundling them all.

Currently code coverage cannot be generated as the js bundle cannot be instrumented. Once the individual file option is available, then the files can be instrumented. At that time we should enable the production of UT code coverage, and if possible AT code coverage.

rename event-hub to async-service-hub

update the js-bundler so it uses the minifier as a plugin

copied across from https://github.com/BladeRunnerJS/brjs-private/issues/169

AFAIK, with the new architecture, this probably needs to be made a plugin rather than being built in. @dchambers can you clarify?

update the bundlers so thay they can now be used in conjuction with the logical tag transform

comment from @andyberry88 :

@dchambers has this not already been done? bundle tags work, and will cause a request to be made to a bundler.

update the logical-tag-transform so that it co-ordinates with any bundler plugins that it can find via the plugin locator

check this is still needed with @dchambers new plugin architecture.

copy event emitter class to brjs codebase

jsdoc event emitter class

Simplified application directory structure

Let's use this space to keep track of the possible options - and final decision. Please add any additional ideas structure ideas here (after discussion, if required).

And use comments to discuss (or a meeting if required).

1. No Default Aspect directory & -blade directories

This is probably more aligned with current simple application structures. The Aspect content is shifted into the root of the app. Blades are in directories in the root of the app with the directories having a suffix of -blade (similar to the -aspect and -bladeset suffixes).

+- myapp
|   \- <bladename>-blade
|   \- <bladename>-blade
|   \- <bladename>-blade
|   \- libs
|   \- src (JS source for Default Aspect)
|   \- themes (themes for Default Aspect)
|   -- app.conf
|   -- index.html (Default Aspect seed file)

2. Default Aspect directory & -blade directories

+- myapp
|   \- <bladename>-blade
|   \- <bladename>-blade
|   \- <bladename>-blade
|   \- default-aspect
|   \- libs
|   -- app.conf

3. No Default Aspect directory & blades directory for all Blades

In this example the blades go underneath a blades directory. This is consistent with blades that reside within BladeSets.

+- myapp
|   \- blades
|       \- blade1
|       \- blade2
|       \- blade3
|   \- libs
|   \- resources (resources for Default Aspect)
|   \- src (JS source for Default Aspect)
|   \- themes (themes for Default Aspect)
|   -- app.conf
|   -- index.html (Default Aspect seed file)

4. Default Aspect directory & blades directory for all Blades

In this example the blades go underneath a blades directory. This is consistent with blades that reside within BladeSets.

We keep default-aspect.

+- myapp
|   \- blades
|       \- blade1
|       \- blade2
|       \- blade3
|   \- default-aspect
|   \- libs
|   -- app.conf

Blades Simplified Directory Structure

This is actually issue #80.

The main suggested change here is to .js files directly under the src directory to use the blade require prefix (remove the need to repeat the app directory structure).

+- myblade
|   \- resources
|       \- html
|       \- 18n
|       \- xml
|       -- aliases.xml
|   \- src
|       -- MyBlade.js
|       -- MyClass.js
|   \- tests
|   \- themes
|   \- workbench

Note: I've left out #880 (simplify tests directory structure) from this.

update code to fix any new better-logging tests for logical request handling

Support additional test runners via TestPlugin

As covered in the Model & Plugin Design and to facilitate #7 it would be great to support additional TestPlugin implementations.

• - create the ability for TestPlugins
• - change the current test command so it uses the plugins
• - create a WebDriver test plugin - #87
• - ensure the WebDriver plugin works with any browser and with absolute paths - #628
• - create a JSTD test plugin - #85

create a J2EE filter that allows the bundlers to be addressed with URLs that have the correct file extensions

update the jsdoc for all brjs classes so that they no longer refer to CaplinTrader

update the js-test-driver plugin so that it no longer has explicit knowledge of the various bundlers

As a developer I expect plugins to have a .jar file extension

raised by @leggetter

At the moment any file type/extension in the conf directory seems to be picked up. There should be a simple way of disabling a funky plugin which doesn't involve moving it from that directory.

see https://github.com/BladeRunnerJS/brjs-private/issues/262 for history.

update code to fix any new better-feedback tests for logical request handling

Improve developer debug experience by allowing individual JS files to be served in an app

JavaScript (and other) files are always bundled. This makes debugging JavaScript very difficult:

1. Very large files make finding code difficult
2. The files are so large that browser debuggers can't find the source of exceptions and keep track of breakpoints

This also impacts #7.

Technical task:
Update js bundler servlet to serve files individually in dev by default, but with a configuration switch in app.conf to turn it back to the old way

comment from @andyberry88
'can we have a command line switch so this can be done easily as a one off? e.g. in CI i might want a bundle but in dev single files.'

see https://github.com/BladeRunnerJS/brjs-private/issues/170 for original issue

[EPIC] Improve unit test developer experience

At the moment it seems like the process is as follows:

1. Start the test server using the CLI: ./bladerunner test-server
2. Connect one or more browsers via http://localhost:4224/capture
3. In another console/terminal tab run ./bladerunner test <test_location_to_scan>

In theory this doesn't seem to bad. However, based on my experience:

• Working out why a test fails is very difficult if the error occurs in js.bundle
• Running the tests sometimes gets stuck in a <browser_name>: reset slow cycle
• Running the tests sometimes results in the tests executing but the process not exiting
• Firefox sometimes hangs
• The server seems to take a long time to detect a browser has disconnected (30 seconds?)
• The debug experience is very difficult as the browser frequently doesn't actually know which line you are debugging (due to the size of js.bundle).
• CLI lists a Java exception when the JavaScript tests fail, which is confusing. It should just list the JavaScript test results and exceptions.

This is a very important part of the development workflow, so we make some improvements here.

Support for Static File deployment

BRJS currently only supports deployments as WAR files. We need to support deployments in simple flat files for deployment to hosting such as GitHub pages or any CDN.

• create an export command for flat-file export
• create a filter so that the bundles can be referred to using their proper extension type, in preparation for flat file export
• Remove WEB-INF (#90 and #91)

Related:

• #289
• #530
• #348

CLI to support packaged/namespaced commands e.g. app:create, app:delete

I like the Heroku toolbelt CLI usage.

heroku help

heroku help
Usage: heroku COMMAND [--app APP] [command-specific-options]

Primary help topics, type "heroku help TOPIC" for more details:

  addons    #  manage addon resources
  apps      #  manage apps (create, destroy)
  auth      #  authentication (login, logout)
  config    #  manage app config vars
  domains   #  manage custom domains
  logs      #  display logs for an app
  ps        #  manage dynos (dynos, workers)
  releases  #  manage app releases
  run       #  run one-off commands (console, rake)
  sharing   #  manage collaborators on an app

Additional topics:

  account      #  manage heroku account options
  certs        #  manage ssl endpoints for an app
  db           #  manage the database for an app
  drains       #  display syslog drains for an app
  fork         #  clone an existing app
  git          #  manage git for apps
  help         #  list commands and display help
  keys         #  manage authentication keys
  labs         #  manage optional features
  maintenance  #  manage maintenance mode for an app
  pg           #  manage heroku-postgresql databases
  pgbackups    #  manage backups of heroku postgresql databases
  plugins      #  manage plugins to the heroku gem
  regions      #  list available regions
  stack        #  manage the stack for an app
  status       #  check status of heroku platform
  update       #  update the heroku client
  version      #  display version

heroku help apps

heroku help apps
Usage: heroku apps

 list your apps

Example:

 $ heroku apps
 === My Apps
 example
 example2

 === Collaborated Apps
 theirapp   [email protected]

Additional commands, type "heroku help COMMAND" for more details:

  apps:create [NAME]   #  create a new app
  apps:destroy         #  permanently destroy an app
  apps:info            #  show detailed app information
  apps:open            #  open the app in a web browser
  apps:rename NEWNAME  #  rename the app

update code to fix any new better-feedback tests for bundler plugin tag

Node.js module-style code support

As we all know, this is a priority.

We want to be able to write code so that the auto-generated classes look as follows:

var br = require( 'br' );

var Property = require( 'br/presenter/Property');
var PresentationModel = require( 'br/presenter/PresentationModel' );

function ExampleClass() {
  this.message = new Property( "Hello World!" );
};
br.extend(ExampleClass, PresentationModel);

ExampleClass.prototype.buttonClicked = function() {
  console.log( 'button clicked' );
};

Relies on #227 and #230.

brjs command global install

Make brjs a globally installed command, where the apps and sdk live independently of each other.

To achieve this I'm assuming that the CLI commands may also need to be context-aware (#885) e.g. run brjs create-blade from within an application directory to create a Blade for an app

• - context aware commands - #885 [deprioritised]
• - change BRJS.initialize so it no longer scans upwards to find the BRJS dir - #95
• - update the BRJS.initialize() method to take two directories instead of one in preparation for making BladeRunnerJS a global command - see #93
• - Allow BRJS to be run from outside of the SDK directory by putting brjs on the PATH - #1130
• - allow apps to live seperately from the sdk - #1154

update templates so example JS file uses new JS style

Auto-generated class files should be named based on the Blade name

If you generate a blade called todo-input the auto-generated file should be TodoInput.js and the class definition should be something like:

var br = require( 'br' );

var Property = require( 'br/presenter/Property' );
var PresentationModel = require( 'br/presenter/PresentationModel' );

function TodoInput() {
  this.message = new Property( 'Hello World!' );
};
br.extend( TodoInput, PresentationModel );

TodoInput.prototype.buttonClicked = function() {
  console.log( 'button clicked' );
};

Create a default blade when a new application is created

When I run brjs app-create I'd like a default blade to be created.

I may want to run brjs app-create --no-blade to disable the creation of the default blade.

Which EventHub do we ship as the BRJS default?

This was removed as part of the decoupling process and needs to be added back as a priority.

update code to fix any new better-logging tests for bundlers

create new test for logical request handling

allow event emitter to be used with legacy classes that use the observer pattern

update docs to use async-service-hub

Make JSDocs available

It would also be awesome if the docs could point to their respective source files. This wasn't possible when we were close source - tis now! Woop!

Writing JavaScript in a BRJS App Docs

• how do I write an App?
• overview of choice of JS style

create bundler plugin tag test

ensure all relevant tests so far are complete and shiny before continuing

create bundlers test

ensure all relevant tests so far are complete and shiny before continuing

update code to fix any new better-logging tests for bundler plugin tag

update the model so it can handle logical requests by passing them to the relevant bundler

update the model so it can handle logical requests by passing them to the relevant bundler, ensuring that the request parser is used in a sensible way now that bundlers are plugins

Update CommandPlugin User Guide

see https://github.com/BladeRunnerJS/brjs-private/issues/258 for history

@leggetter commented:
This hasn't been 100% completed. It needs updated based on a number of changes that have been made.

update dashboard so it no longer has a reset-db concept

clean up the jsdoc for brjs-core classes

update code to fix any new better-feedback tests for bundlers