Conventions Client API Server API Architecture Getting Started

Installing Sapphire

We're going to make a quick application to get up and running with Sapphire. Create a project directory to work in then execute the following commands at a command prompt within that directory.

npm install -g sapphire-express
sapphire install
npm install
sapphire app test
here #windows
. here #osx or linux
node server

In your browser, hit the following url: localhost:8080/test. Wee, wasn't that fun? Let's look at these commands one at a time and see what we did.

npm install -g sapphire-express

This installs the sapphire-express framework globally. This will give access to the sapphire command line tool which we will use heavily when developing an application. This tool is used to create boilerplate for a number of sapphire features.

sapphire install
npm install

These commands create a sapphire installation and then installs all the necessary dependencies. It creates a batch file (for Windows) and a shell script (for OSX and Linux) that configures the system variables which point to the sapphire installation. It also installs the server.js file that will be used to run sapphire applications. Although this file can be changed, it should not need to be.

sapphire app test

This creates a basic application named test.

Before running your server, call the here bash/bat file to point Sapphire at your configuration:

Windows
here
OSX or Linux
. here
node server

Now the server is running and can be reached at localhost:8080/test.

Using the Command Line Tool

In the installation walk through above, Sapphire was installed using the -g flag. When this flag is used, the command line interface of sapphire is installed. Use the CLI to create boilerplate for various features of the framework.

The command line syntax is as follows

sapphire [install] | [app] <app> | [page|dialog|feature|vc] <app> <name> | [vc] <app> <name> (<path>)

This first parameter is the command. The following commands are supported:

These features are explained here.

The following describe the various parameters used in these commands

Configuration Files

There are a number of configuration parameters that can be used with Sapphire right out of the box. These are specified in configuration files, which are JavaScript files that export an object containing these parameters. When processed, these configuration parameters can be accessed in the global variable CONFIG.

Sapphire uses two environment variables to find the configuration files.

In addition to the installation configuration file, each application itself gets a configuration file in a directory named sapphire-config. Variables defined in this configuration file will be available as sub objects in the CONFIG global object. For example, in an application name test, any variables in the configuration file can be accessed on CONFIG.test.

The following are the configuration variables that can be set.

This is an example of using this field:

    https: {
        key : fs.readFileSync('./apps/sparcade/sapphire-config/certs/dev/key.pem', {encoding: 'utf-8'}),
        cert : fs.readFileSync('./apps/sparcade/sapphire-config/certs/dev/certificate.pem', {encoding: 'utf-8'}),
    }

In addition to these configuration parameters, any other values that an application wants to use can be added to a configuration file. These variables will then follow the same env rules as the system variables and will be available in the global variable ``CONFIG```

Here is an example config file:

fs = require('fs');

module.exports = {
    useCompression: false,
    builderCache: false,
    minify : false,
    https: {
        key : fs.readFileSync('./config/certs/dev/key.pem', {encoding: 'utf-8'}),
        cert : fs.readFileSync('./config/certs/dev/certificate.pem', {encoding: 'utf-8'}),
    }
};