platformjs-core

convention-based platform for custom Express + Handlebars + Mongoose + Passport + Bootstrap sites

npm install platformjs-core
9 downloads in the last week
36 downloads in the last month

platformjs-core

TR;DL: Platform for building custom Express + Handlebars + Mongoose + Passport + Bootstrap sites quickly.

A server-side node module that utilizes popular NPM modules and a set of simple file layout conventions to make putting together an efficient, new, custom site easy and efficient.

Disclaimer: Opinionated Software

PlatformJS qualifies as "opinionated" software. The primary purpose of the platform is to allow tie together existing, high-quality libraries into a new site very quickly; it is quite difficult to serve this purpose effectively without making presumptions about which libraries to use.

Usage

Basic Server (with no content)

The basic server is with no content or custom configuration isn't very interesting, however to get a minimal server going:

In a file server.js:

var platformjs = require("platformjs-core");    
var platform = new platformjs.Platform;
platform.start();

Then start the server with:

$ node server.js

If you visit http://localhost:8080, you should then get a message Cannot GET /. This is correct behavior as the site has no content.

Example Convention: Adding Static Content

All content, customization, and plug-ins are read in from the subdirectories of a special extensions subdirectory. Within that directory, there are conventions for content -- such as the public directory being used to directly server static content:

  1. Create a subdirectory extensions/mysite/public
  2. Add a new file index.html with some HTML content
  3. Visit http://localhost:8080
  4. Your new page should be displayed

Conventions

Static content

  1. Create a public directory within the extension
  2. Files will be served as-is

Note: if a public/favicon.ico file is located, it will automatically be special-cased to use the express favicon middleware for efficiency.

Generated Content

  • TBD: Less files, minified JS, Handlebars templates,
  • TBD: Browserify bundles

1:1 file name mappings

The protected/ sub-directory can be used similiarly to the public/ sub-directory, except for generated files. For example, a file named protected/user/dashboard.hb.html represents a Handlebars template that is automatically routed as a rendered template to /user/dashboard.

Manually routed content

TBD.

HTML Templates

Templates currently use a version of Handlebars with a few simple extensions.

Templates

Templates should end with an .hb.html extensions.

The built in extensions to the Handlebars include:

markdown

{{#markdown}}{{/markdown}} can be used to include markdown within the page.

context

{{#context}}{{/context}} text within this block is treated as JSON which is merged into the template context. This is useful to "locally" define variables in the template without modifying the code. This can be useful for generating tables of data or other repeated elements.

Partials

All files in the partials directory with a .hb.html are considered Handlebars partials.

For example, if there is a file partials/base-stylesheets.hb.html, it will can be inserted into another template via:

<head>
   {{> base-stylesheets }}
</head>

Note: The current implementation does not support nested sub-directories within this sub-directory.

Priority

In order to control the precedent of settings that overlap between extensions, each extension is given a priority.

npm loves you