peak-front-end

PEAK Experiential Application Kit (PEAK)

PEAK is based on loosely on the ethos of Backbone.js, but has eliminated functionality that is unnecessary in a fully compiled, self contained build. We have extended it to be a full framework supporting multiple languages running on node.js.

Environment setup

npm falafel currently only supports a very old version of acorn that doesn't work well with es6 files. You'll need to manually bump versions in falafel, and acorn inside node_modules :(

We prefer Atom as our IDE and have provided a number of package and configuration files to help ensure we're all using the same coding standards.

You will need node.js and git to be able to setup, build and run this project.

Requirements on OS X

On OS X it's easy to install if you have Homebrew. (if not you should definitely get it!)

brew install nodejs git

Requirements on Ubuntu

Ubuntu is also fairly easy to setup:

sudo apt-get update && sudo apt-get install nodejs git

Requirements on Windows

Windows is a but more difficult to setup due to poor availability of package managers. We strongly recommend upgrading to the most recent version of windows and enabling the new "Windows Subsystem for Linux"

With this method, you can use the same commands as ubuntu to install your build dependencies:

apt-get update && apt-get install nodejs git

Project setup

After you've cloned the repo, you'll want to also install all the project dependencies. From the project root, run the following command to get up and running.

npm install -g gulp && npm install && apm install --package-file atom-packages.txt

Fundamentals

TASK is a way of organizing a project as much as it is a helper framework. There are a number of assumptions conventions that will make running the project go very smoothly.

TASK is built to be a front-end framework that is a quick-start for a page that has some basic needs. We know that, for most sites we need to start with a menu, header, footer and the concept of multiple pages of content. TASK provides these components pre-built and ready to use.

Languages

TASK uses a build system and compiles es2015, PUG & Sass to es5 Javascript, HTML and CSS respectively, for the site front-end.

We chose PUG & Sass because the syntaxes are similar enough that once you've created your PUG markup, you can mostly copy and paste that code directly to create Sass code, instantly giving you an identical hierarchy to style against.

Views

Anything you can interact with, or that is contains dynamic content, should be made into a view. Views are made up of 3 parts distributed into three locations. The file name and folder structure of each location should be identical.

• js/views A Javascript Class file that subclasses _TASK/View.
• /pug A template that defines the objects in your view (markup). /pug/static if your markup will only be included once (something you don't intend to make multiples of), it doesn't need to be made into a dynamic template. Instead, it is rendered and placed at compile-time. We can render multiple passes with multiple copy decks. This is what makes TASK able to support multiple languages, and greatly improves /pug/dynamic if your component must be created dynamically with dynamic data, you
• /sass A stylesheet that makes it look pretty.

Inside of the /sass and /pug/static folders there are index files.

These index files must reference any that define your components.

Conventions

Common Files

Inside of the /js/ folder there are files named server.js & index.js. The application is spawned (and compiled from) index.js while the server is optionally deployable, but mainly intended for development purposes.

Separate concerns, uniform organization

Javascript, stylesheets and template files are included for each part of the application, nested in their appropriate folders. Each file tree follows the same basic structure so files that are necessary for different modules are easy to find.

Filenames for all elements of the same component should match

Modules should use a consistent naming scheme throughout the application from the module name itself, to the related sass and pug files, to the classnames and IDs in the HTML itself. A custom node module is included to create new Pages for convenience npm add-page pagename. This script will create necessary folder structure and add the created files to their relevant index files.

TODO: add a 'remove page' custom module

Abstract classes

TASK provides basic MVC components via Abstract Classes in the TASK foler. They are meant to be subclassed for convenience and framework functionality. To access TASK classes via import or require() refer to the _TASK package. ex import Base from '_TASK/Base'

PEAK Class Structure

Base

PEAK Components all inherit from the Base class. It primarily provides the event system ( backbone-events-standalone ) and a few utilities.

Extending the prototype of the Base class is a convenient way to inject global variables into all TASK objects.

Base -> View

Views are used to control pixels on screen, and receive user input.

Localization

TODO: UPDATE THIS SECTION TO HAVE ACCURATE PATHS TO COPY OBJECT

PEAK supports multiple locales that can be defined by adding sub-folders to the ./data/copy folder with the locale designation as the folder name. JSON files in this folder will be concatenated and accessible through the window.GLOBALS.COPY variable. Each locale must use a consistent variable name structure to ensure that templating works across all locales.

At compile-time each locale has a localized version of the static template files rendered for that locale, accessed to the root of the dist folder. For "en" or "es", you would get: index.en.html or index.es.html. Additionally, the hero language for the site is copied to index.html.

Javascript and CSS are shared between locales. The rendered pages are given a a class to designate their locale <html class="en"> in order to account for any styling tweaks that need to happen between locales.

Development & Deployment

You can spin up a local server equipped with livereload and file system watchers by using $ npm run watch

Running the gulp command will build the site and place compiled files into the appropriate domain folders in /dist.

There are presently three separate environments available, dev, stage, and prod. These have settings inside ./src/shared/data/env/*.js. The js files that make up the settings for each environment all are extended from a default.js to keep the process as DRY as possible.

Simply pass the gulp --env=dev (or stage or prod) to build the site with the appropriate settings.