Status: 2012-05-21 - work in progress!

The config.json, is file to make all adjustments for the build process of an application. It located in the root directory of every application. At the beginning of every build process the config.json is evaluated, if this fails - the build process is aborted with a message on the shell, describing the reason. As described, the config.json is used when running the espresso build and espresso server commands, so keep this file valid!

The format is JSON, so every property consists of a key-value pair. Below a sample config.json, with basic properties like, name or version. And entries for proxies and a list of files that should be excluded from caching on the device.

{  
    "name" : "Application Name",
    "displayName" : "AppName",
    "mode": "debug",
    "debugLevel": 1,
    "outputFolder": "staging",
    "minify": false,
    "preloadImages": false,
    "eliminate": false,
    "reachable": [],
    "application": {
        "version": "v0.0.1",
        "debugMode": "true"
    },
    "defaultDeployTarget": "test-server",
    "deploy": {
        "test-server": {
            "method": "ftp",
            "ftp": {
                "host": "ftp.example.com",
                "port": 42,
                "username": "foo",
                "password": "super-secret",
                "targetPath": "/",
                "debugLevel": 0
            }
        }
    },
    "supportedLanguages": [
        "en_us",
        "de_de"
    ],
    "defaultLanguage": "de_de",
    "proxies": [
        {
            "baseUrl": "https://some.remoteService.com:8080",
            "proxyAlias": "myRemoteService"
        }
    ], 
    "excludedFromCaching": [
        "someImage.png",
        "someFile.js"
    ],
    "cacheFallbacks": [
        "/ error.png",
        "/someFile.js someErrorFile.html"
    ],   
    "excludedFiles": [
        "someFile.js",
        "someCSS.css"
    ],
    "excludedFolders": [
        "someFolder"
    ] ,
    "target": {
        "manufacturer": "apple",
        "resolution": "640x960"
    },
    "libraries": [
        {"name": "<Name of the folder where the lib is placed>", "refs": ["*"]}
    ],
    "htmlHeader": [
        "<meta charset='utf-8'>",
        "<meta name='apple-mobile-web-app-capable' content='yes'>",
        "<meta name='apple-mobile-web-app-status-bar-style' content='default'>",
        "<link rel='apple-touch-icon' href='theme/images/Icon-72.png' />",
        "<link rel='apple-touch-icon' href='theme/images/Icon.png' />",
        "<link rel='apple-touch-icon' href='theme/images/[email protected]' />"
    ] 
}

Currently (see status, at the top of this page), this are used from the config file:

The name of the application, this is provided while running the espresso init command, so there is no need to modify it.

Define a name for the application, on the device. This will be the name, that is shown on the device (under the app icon). This property is only needed, if the name of the application should differ from the name property.

The build mode. Either "debug" or "production". If set to "debug" then the build process will emit messages according to "debugLevel". Default is: "debug"

The debug level determines how much output will be produced by the build process in "debug"-mode. The higher the value the more gets printed. Default is: 1

Name of the folder, where the builded application is written to when running espresso build Default is: "build"

When set to true, the source code will be minified by the build-in Google Closure-Compiler. http://code.google.com/intl/de-DE/closure/compiler/ Default is: false

This property can be used to advice The-M-Project to automatically preload all images located in your project directory. Default is: false

When set to true, then unused files are excluded from the building process. A file is unused if it contains no definitions that are referenced by the application. Default is: false

When set to an array of fully qualified object names (e.g. ["M.Math"]), then these names are interpreted as references by the application. This effectively whitelists any file that contains one or more of these names. Default is: []

When set then this value will be available in the application as M.Application.config. Within an application it can be accessed by calling e.g. M.Application.getConfig('version'). You can use this property to dispatch any json-based information into you application. By default this property contains two things: version, which is set to 0.0.1 when you initialize a new project. debugMode, which is set to true when you initialize a new project. This will cause The-M-Project to show logs that are pushed with M.Logger.log. If set to false, nothing will be logged. But note, that this does only affects logs that are pushed with M.Logger.log!

Deployment target definitions. Each key in the "deploy" property defines a target to which espresso deploy <key> can try to deploy the application. Each target property contains a "method" property that defines how to deploy and a property with the name of the method that configures the respective method like specifying where the application is to be deployed and what credentials to use. Default is: null

The "defaultDeployTarget" property is used when espresso deploy is called without argument such that it behaves identical to espresso deploy <defaultDeployTarget>. Default: not set.

The "ftp" deployment takes following properties:

• "host" the hostname or IP address (string) of the FTP server to deploy to.
• "port" the port (number) of the FTP server. Optional. Default: 21.
• "username" the username (string) to use.
• "password" the password (string) to use.
• "targetPath" the absolute directory name (string) to deploy to.
• "deleteTargetPath" if set to true, then "targetPath" gets deleted first. Optional. Default: false.
• "debugLevel" the output verbosity of the FTP deployment module. Optional. Default: 0 (quite quiet).

Note: The current implementation of this deployment module requires Python 2.

The "local" deployment takes following properties:

• "targetPath" the absolute or relative (to the $PWD when espresso deploy is called) directory name (string) to deploy to.
• "deleteTargetPath" if set to true, then "targetPath" gets deleted first. Optional. Default: false.
• "debugLevel" the output verbosity of the local deployment module. Optional. Default: 0 (quiet).

The "ssh" deployment takes following properties:

• "host" the hostname or IP address (string) of the SSH server to deploy to.
• "port" the port (number) of the FTP server. Optional. Default: 21.
• "username" the username (string) to use. Optional. Default: local $LOGNAME.
• "targetPath" the absolute directory name (string) to deploy to.
• "deleteTargetPath" if set to true, then "targetPath" gets deleted first. Optional. Default: false.

Note: The current implementation of this deployment module requires 1.) ${usernames}'s public key installed in the ${host}'s authorized_keys (see also ssh(1), ssh-copy-id(1), sshd(8)) and 2.) the tar archiving utility on the local and on the remote machine (see also tar(1)).

Array languages, the application should support. Make sure, that each of these files is present

By specifying a default language, you can advice The-M-Project what language to use. This is only relevant if you are using I18N.

An array of proxy-entries. Each entry takes two properties:

• baseUrl = the url to the remote service.

• proxyAlias = the proxy alias name, used in the applications code.

• Example:

  • Given a proxy entry { "proxyAlias": "foo", "baseUrl": "https://foobaz:23" } and an espresso server running at 127.0.0.1:8000, the request to http://127.0.0.1:8000/foo/bar would be proxied to https://foobaz:23/bar.

DEPRECATED!

Declare a list with file names. This files will not be stored in the application cache on the device, and will be requested from the server every time.

Declare a list of fallbacks for the HTML5 offline manifest.

Alle files, marked as excluded are not used during building, and also do not appear in the final builded application.

Same as excludedFiles, but for folders.

Target specifics, the build for a concrete target/device. This can be for example: "apple devices with the screen resolution of 640x960" - like in the config example above.

You can add any 3rd party lib to the project, just make a new folder in: <your-project>/frameworks/ and place the lib in this folder. To use the lib, open the config.json and add the libraries property, see example:

"libraries":[ {"name": "<Name of the folder where the lib is placed>", "refs": ["*"]} ]

** name is the name of the folder, that you just created, and placed the lib into.

** refs are the names of the files, you want to use from this lib, when typing: "refs": ["*"] all files are taken, otherwise specify the names of the files you want to use: like: "refs": ["file_a.js","file_b.js"] The sequence in which the files are specified in the refs array represent the order in which they are included in the index.html.

Via the htmlHeader the Header section of the generated index.html page can be customized. The property takes a array with valid HTML code entries, that are copied 1:1 into the html header.