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
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.
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:
install
creates an installation of sapphire in the current directory. This will create the server.js file.app
creates a new application. This will create the basic file structure for the application. This application can be run immediately, although it is not very interesting. It also creates a batch or bash file to setup default values fornode_env
andnode-config
based on the current directory.page
creates a new page in the specified application.dialog
creates a new dialog in the specified applicationwindow
creates a new window in the specified applicationfeature
creates a new feature in the specified applicationvc
creates a new empty view and controller, can specify the path to the assets folder
These features are explained here.
The following describe the various parameters used in these commands
app
the name of the applicationname
the name of the page/dialog/feature/vcpath
used for vc to set the parent path of the assets folder. This is useful when using the site feature which is explained later.
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.
node_config
this specifies the base directory where the config.js file can be found. When a new installation is created using the sapphire CLI, a default config file will be created.node_env
this specifies the name of an environment sapphire has been deployed on. Typical values would bedev
,qa
orprod
. The value of this variable will be used to construct the name of a configuration file that can override default values in config.js. The override file must be namedconfig.<env>.js
. This override is implemented in the default config.js file that is created when the installation is created using the Sapphire CLI.
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.
port
This is the port the server will run on. The default is8080
.server
This is the full domain name that Sapphire will use to recognize itself. The default islocalhost
baseUrl
This is the baseUrl for the server. This value will be passed to the client application within the application's namespace. The default value is'http://localhost:8080/'
basePath
This is the file system directory for the Sapphire installation. The default value isprocess.cwd()
sessionStore
This is the type of storage for session information. This must be one ofmemcacheStore
,redisStore
orcookieStore
.sapphireEncryptKey
This is the key that will be used to encrypt sessions that are stored in cookies. There is a default value, but it should always be overridden.sapphireEncryptCipher
This specifies a symmetric key cipher that will be used to encrypt cookie sessions. This must be a value supported by crypto.js. The default value is'aes-256-cbc'
cookiePrefix
An application specific confiuration that will prepend the specified string to the session cookies. This allows each deployed application to keep its own sessionmcServer
If a memcache session store is used for sessions, then this specifies the memcache server. The default is'localhost:11211'
mcOptions
This value is passed to thememcached
module when creating the memcache client. The default value is{}
defaultApp
if set, this is the name of an application that will be used, if no application is given on the url request.useCompression
If true, then all responses will be gzipped. Default isfalse
.builderCache
: If true, then all files that are read when building an application will be cached in memory. This should be set to false when developing an application so that files that may be changed are not cached.minify
If true, then javascript and css files are combined and minified before being delivered to the client.cors
to support Cross Origin Resource Sharing, Sapphire uses the Express/Connect middleware cors.https
Sapphire also supports deployment as an https server. To do so, use this configuration key, which will be an object with these two fields:key
The PEM file for the certificate key {statement
}cert
the PEM file for the certificate
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'}),
}
};