JSDoc: Home: bauplan

Bauplan is a front-end framework providing models, collection, views, template helpers and loading, internationalisation (i18n), localisation, CSS functions and automatic input validation

It is built on top of

Version

0.1.1

Getting it

npm install bauplan

git clone https://github.com/solidgoldpig/bauplan.git

Creating an app

The minimum to get an app up and running would be to include the following within the html of the single page app sent by the server

// AMD loader
<script src="//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.22/require.min.js"></script>
<script>
    // minimum config
    var BauplanConfig = {
        config: "path-to-app-config"
    };
</script>
<script>
    // initialises app
    require(["/js/bauplan.init.js"]);
</script>

Initialising the app

Loading bauplan.init.js initialises the app.

It achieves this by loading the config file[s] specified. processing them and then loading the resulting list of modules, templates and resource bundles

See bauplan.init for full details

Data provided by the app page

BauplanConfig

Provides additonal config values for the app

var BauplanConfig = {
    baseUrl: "/",
        // where config and modules should be loaded relative to
    config: "example/example.config.1.0.0",
        // path to config (NB. without .js extension)
    clientdefaults: {},
        // any client defaults for modules to use
    features: { x: true, y: false }, // hash of boolean values 
    callback: function() {}
        // a function to call once the app has been rendered
};

BauplanData

An optional object whose values are passed to bauplan.authentication

eg.

var BauplanData = {
    loggedIn: true,
    registered: true
};

Anatomy of a config file

Essentially an app config file is an extension of RequireJs config values with the same properties.

deps

Any further config files that the current configuration depends on, so an app's config (or its dependencies) should include the following:

"deps": "bauplan.config.0.1.0"

In turn bauplan.config.0.1.0 depends on core.config.0.1.0

paths

Files to be loaded as per standard RequireJS modules (ie. AMD-style)

NB. the extension .js will be added to the path.

eg.

"todo.model": "js/model/todo.model",
"todos.collection": "js/collection/todos.collection",
"todo.controller": "js/controller/todo.controller",
"todo.view": "js/view/todo.view"

Path key naming convention

models - {{name}}.model
collections - {{name}}.collection
controllers - {{name}}.controller
views - {{name}}.view

templates

Files to be loaded and processed for use as Handlebars templates

NB. the extension .hbs will be added to the path.

eg.

"main.layout": "template/layout/main.layout",
"control.view": "template/view/control.view",
"actions": "template/control/actions.template",
"checkbox.edit": "template/control/checkbox.edit.control"

Template key naming convention

layout views - {{name}}.layout
views - {{name}}.view
templates - {{name}}
controls - {{name}}.[edit|display]

langs

Files to be loaded and parsed for use in i18n

"key": "path"

These files should be formatted as resource bundle style properties files.

NB. the extension .properties will be added to the path.

eg.

"en.company": "app/lang/en.company"

Lang key naming convention

{{lang}}.{{type}}

defaultlang

The default language/locale to use for the app.

Defaults to "en"

Additional properties

Are standard RequireJS config properties and behave accordingly

eg.

waitSeconds
shim

Cross-domain requests

In the case of non-javascript resources (eg. templates and lang files), if the path requested is from another domain, it will be suffixed with .js too. It is expected that the server will wrap the response in a define function that returns the language string.

In other words, it is possible to serve any of the files of a CDN

Path key overriding and resolution

Where a later loaded config file has the same key as an earlier one, the first loaded value wins
This makes it possible (indeed encouraged) to override a more core module/template by simply redefining its path in the higher, more specific config file. The original module can still be required using a new key.

Modules

Models

Models are provided by extending bauplan.model

Collections

Collections are provided by extending bauplan.collection

Controllers

Controllers are provided by extending bauplan.controller

Views

Views are provided by extending bauplan.view module

Layout views

Layout views are provided by extending Bauplan.LayoutView in bauplan.thorax.patch.

This is handled automagically and should be handled by using the declarative layout template helper

Controls

Individual controls defined in the config are loaded by bauplan.controls and handled by bauplan.control.view module.

The default controls are defined in default.control.

Templates

Template files defined in the config are loaded and compiled by bauplan.templates

View templates are associated automatically with the view of the same name, unless that view's template option is set

Template helpers

Insert the view named "foo" - instantiates the foo.view module and uses the foo.view template

{{view "foo"}}

Insert a layout view, with the initial view set to the value of foo

{{layout view=foo}}

Insert the template named "foo"

{{template "foo"}}

Insert the text control with the control’s name set to "foo"

{{control "text" name="foo"}}

For more details on helpers, see bauplan.helpers

Internationalisation

Lang files defined in the config are loaded by bauplan.i18n

Internationalised phrases are inserted using the phrase helper (provided as part of Larynx)

{{phrase "foo"}}

Minimum configuration

Given that abstract views can be loaded

create app configuration
- modules
  - router
  - app models
  - app views
  - app.setput (optional)
- templates
  - views

Home bauplan