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
or
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
- modules