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:
- Create a subdirectory
extensions/mysite/public - Add a new file
index.htmlwith some HTML content - Visit http://localhost:8080
- Your new page should be displayed
Conventions
Static content
- Create a
publicdirectory within the extension - 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.