Coral.js
Coral.js is an extensible, functional-reactive framework. The design of Coral.js encourages maintainable front-end code for your ambitious single-page applications.
Coral.js is an open source project of LockerDome. It is thanks to all these contributions that the Coral.js framework has reached the milestone of being open sourced.
Table of Contents
Getting Started
Prerequisites and Compatibility
- Coral.js generates JavaScript which can be used in any modern browser and IE9+.
- The Coral.js compiler supports versions of Node.js 0.8 and above.
Installation
$ npm install --save @lockerdome/coral.js
Demos
Visit and download our coral.js-tutorials repo. It contains:
- A sample Hello, world! app.
- A variety of demos which showcase some of the different features of the Coral.js framework.
Using Coral.js
This section is for those of you who want to make something with Coral.js.
There are two main steps:
- Write the app code.
- Run the compiler to build your app.
An Example Project
Using the example of a basic Hello, world! app, this section describes:
Directory Structure
This is a simple example of a directory structure for a web app that uses Coral.js:
- your_project/
- node_modules/
- @lockerdome/coral.js/
- app/
- static/
- index.html
- coral_shards/
- compiler_settings.js
- node_modules/
Overview of File Contents
static/index.html
<html>
<head>
<title>Your Coral.js App</title>
</head>
<body>
<div id="app"></div>
<script charset="utf-8" src="coral_shards/coral.js"></script>
<script>new Coral(document.getElementById('app'), {});</script>
</body>
</html>Explanation of the above example:
<div id="app"></div> is the entry point (a.k.a. "root") element. This is where the Coral.js app will be rendered.
<script charset="utf-8" src="coral_shards/coral.js"></script> coral.js is a script that Coral.js compiles from your app code. The compilation step is described here.
<script>new Coral(document.getElementById('app'), {});</script> places your Coral.js app in the DOM in the div with the id of 'app'.
app/elements/main.js:
In this example, 'main' is the root_element (see compiler_settings.js) of the Coral.js app.
var main = {
// ... more code for the 'main' element can go here
};This Element has a corresponding View file: app/views/main.hjs.
app/views/main.hjs
All Views correspond to an element. This one matches: app/elements/main.js
Views may contain HTML markup and HTML templates. The example below simply uses plain text.
Hello, world!compiler_settings.js
This is where compiler settings and Plugins are specified.
Top level keys:
-
app_directory:The path to the web app's framework code -
root_element:The name of the entry point (a.k.a. root) element. -
plugins:An array of compiler Plugins to use and their configurations. Plugins are where you are able to customize your app's behaviour. Read more about Plugins here.
This is enough to get you started:
var settings = {
app_directory: 'app', // Refers to your_project/app
root_element: 'main', // Refers to your_project/app/elements/main.js
plugins: [
{
// compile_client_app is a standard compiler Plugin that is included with Coral.js.
path: './node_modules/@lockerdome/coral.js/plugins/compile_client_app',
settings: {
shard_output_directory: 'static/coral_shards' // Where the generated coral.js goes.
}
}
]
};
module.exports = settings;Compiling Your App
The Coral.js app code you write needs to be compiled so that the appropriate script file(s) (e.g. coral.js) can be generated and referenced in a script tag (e.g. in static/index.html).
Front-end code generation is handled by one of Coral.js's standard compiler Plugins, compile_client_app, and the output script is specified in compiler_settings.js
Compilation is done from the command line like so:
$ node [path_to_coral/cli/cli.js] --s [path_to_compiler_settings.js]
Example:
$ node ./node_modules/@lockerdome/coral.js/cli/cli.js --s compiler_settings.js
Plugins
Coral.js apps and the Coral.js framework itself are extensible. Plugins enable you to customize your app and/or the framework's behaviour in many different ways.
Coral.js comes with two standard compiler Plugins:
- compile_client_app generates the front-end script file(s) for your web app.
- standard_optimizations is a standard set of optional optimizations
and run in the order listed in the plugins: array.
E.g. Specifying Plugins in compiler_settings.js:
var settings = {
...
plugins: [
...
{
path: './node_modules/@lockerdome/coral.js/plugins/standard_optimizations'
},
{
path: './node_modules/@lockerdome/coral.js/plugins/compile_client_app',
settings: {
shard_output_directory: 'static/coral_shards'
}
},
...
]
...
};
Learning More
To see more of Coral.js's features and get up to speed on building your own single page web app with Coral.js, visit the coral.js-tutorials repo and look through the demo app.
Contributing
Coral.js is an open source project and we gladly welcome contributions.
Before submitting a pull request, you'll need to make sure you sign the CLA.
Please read our guide on contributing for additional information.
License
Coral.js is MIT licensed.