byu-brownie-framework

BYU Brownie Framework

The purpose of this framework it to make it easy to write front end web applications that integrate the existing interoperability of C-Framework applications into a new generation of web applications.

Installation

It is recommended that you install this module globally as follows:

npm install -g byu-brownie-framework

If you choose to install locally within a directory you can issue this command:

npm install byu-brownie-framework

How to use this framework

If you installed globally then you can start the server by issuing the command:

byu-brownie-framework [OPTIONS]... [DIRECTORY]

If you installed locally within a directory then you can start the server by navigating to that directory and running the command:

npm start [OPTIONS]... [DIRECTORY]

If you want to start the server within your own NodeJS code you can do the following:

var server = require('byu-brownie-framework');
server(directory [, options]);

For a full list of options either omit the directory or use the -h flag with the command. Each of the following lines are equivalent (depending on local or global install):

byu-brownie-framework
byu-brownie-framework -h
byu-brownie-framework --help
npm start    

If you are running this with pm2, which I highly recommend then you can issue one of the following commands:

pm2 start byu-brownie-framework [OPTIONS]... [DIRECTORY]       //global install
pm2 start bin/byu-brownie-framework [OPTIONS]... [DIRECTORY]   //local install

Why Do I Want this Framework?

Interoperability with Legacy Code

The C-Framework wanted a way to persist data within a single tab or window when navigating to other loosely coupled web applications. Cookies could not be used because they are shared by all tabs and windows for that browser. If a user had more than one tab or window open at the same time then the persistent data would be overwritten by whichever tab or window last wrote to the cookie.

As a solution to this, the C-Framework incorporated a system of brownies (similar to cookies). Essentially this data was passed around by submitting a form that posted the persistent data to the C-Framework with every navigational change. In other words, if you clicked on a link, you were actually posting data from a hidden form, and that data was received by the C-Framework to build the next page with the data that you wanted persisted.

This same functionality can now be implemented with JavaScript's sessionStorage. With the advent of sessionStorage, and due to the increasing importance of decoupling server side code from front end code, this framework came into being.

This framework keeps interoperability with the C-Framework, but also is liberated from the need to post persistent data between web applications by using sessionStorage instead.

Static File Server

Because this framework is for front end applications, it also comes with a static file server. This server will automatically serve up any files that are in the distribution directory (as specified by the configuration).

Navigation Links

One of the tools provided by this framework is that all link clicks will automatically be intercepted and analyzed before being followed. If the link is going to a C-Framework application then the brownie will automatically be encoded and posted to that URL. If it is not going to a C-Framework application then the link will function as normal.

How to use the Brownie

The brownie is defined as a global JavaScript variable. When your application loads, it will already have the decrypted brownie data, whether it was supplied from the C-Framework or if it was stored in the sessionStorage.

You can get or manipulate the data in the brownie using one of these functions:

• brownie.clear() - this function will clear all current brownie data
• brownie.get(key) - this will get the value for a particular piece of data from the brownie
• brownie.list() - get a copy of all of the brownie data.
• brownie.navigateTo(url , target) - this function is used to manually navigate to a URL using the brownie's persistence methods. The URL is that page that will be navigated to and the target specifies which window to target for the navigation (defaults to _self).
• brownie.set(key, value) - this will set the value for a particular piece of data for the brownie.

CORS Proxy

As of the time of this release, most of BYU's servers do not support CORS. To facilitate the creation of front-end applications, a CORS proxy service is also provided by this framework. You can make any requests to this proxy and they will be passed directly onto the specified endpoint.

// Request format: /bbf/<protocol>/<url>
/bbf/http/someurl.com/resource              //http request
/bbf/https/someurl.com/resource             //https request

Limitations

The C-framework stores a cookie in the browser named "brownie" for the domain *.byu.edu. That cookie is used as part of the key for encrypting and decrypting the brownie. Therefore, in order for this framework to work property it must also run on the byu.edu domain.

A second limitation is that the directory "/bbf" (short for BYU brownie framework) is reserved by the server. In other words, if you add files for your application to /bbf they will be inaccessible.