Configuration

The command ‘grace new’ will create a project folder with the following structure and content, if you chose default skeleton:

Gauge
|-- assets
    |-- Icon-dark.svg
    |-- Icon.svg
    |-- Preview.png
|-- help
    |-- help.md
    |-- ScreenshotPlaceholder_400x275.jpg
|-- manage.py
|-- project.cfg
|-- src
    |-- application.js
    |-- index.html
    |-- style
        |--style.scss

The file structure of the joose skeleton are as follows:

Gauge
|-- assets
    |-- Icon-dark.svg
    |-- Icon.svg
    |-- Preview.png

|-- help
    |-- help.md
    |-- ScreenshotPlaceholder_400x275.jpg
|-- manage.py
|-- project.cfg
|-- src
    |-- application.js
    |-- index.html
    |-- javascript
        |-- Main.js
        |-- Dizmo.js
    |-- lib
        |-- joose
            |-- joose.min.js
        |-- jquery
            |-- jquery.min.js
        |-- jquery-ui
            |-- css (folder)
            |-- jquery-ui-1.10.3.custom.js
            |-- jquery-ui-1.10.3.custom.min.js
    |-- style
        |--style.scss
|-- test
    |-- index.html
    |-- javascript
        |-- CustomAssertions.js
        |-- test_dizmo.js
    |-- lib (folder)
    |-- test
        |-- test_ExampleTest.js

Files

File Function Mandatory
project.cfg The configuration file for your dizmo. Refer to Project-to-project configuration with project.cfg below for a more detailed description Yes
manage.py The executable that asks Grace to provide services like building, testing or deploying your dizmo. See subchapter Using manage.py for a more detailed description (provided by grace)
Icon.svg Default icon displayed in the dizmoViewer (vector) Yes
Icon-dark.svg Icon displayed if the background of the dizmo is dark e.g. settings side No
Preview.png For dizmoStore, replace this with a screenshot of your dizmo, size 150x150px Yes for store upload
help.md User documentation, refer to User documentation for a more detailed description Yes for user help documentation
ScreenshotPlaceholder_400x275.jpg User documentation, refer to User documentation for a more detailed description Yes for user help documentation

Note: If you wish to have your files available in your built project, they have to be under their respective folders: For any files regarding styles (icons, images, stylesheets, etc.) you should use the folder src/styles/ and src/styles/images, for any other files that are important during runtime of your project you can use the assets/ folder in the root of your project. Any files that are not in these folders, and are not part of a JavaScript include or your index.html file will not be copied over.

The global Grace configuration file

After running the command ‘grace new’ for the first time, Grace creates a global configuration file named .grace.cfg and places it in the folder .grace in your user directory. This configuration file .grace/grace.cfg sets the default option settings for all your Grace projects the tool. This file will never be rewritten automatically so once created it must be edited by hand.

The options set in .grace/grace.cfg are global to all projects built with Grace.

However every option can, if needed, be overwritten on a per-project basis in the project.cfg file in each project. See subchapter below Project-to-project configuration with project.cfg.

This file contains the following information

parameter description
deployment_path The deployment path: build target location if "deploy" is specified
zip_path The zip path: zip target location if "zip" is specified
doc_path Doc files target location besides the default location in the build directory
minify_js Specify if Grace should try to minify your JavaScript files (default is false)
minify_css Specify if Grace should try to minify your CSS files (default is false)
urls The following is a collection of URLs used by the upload command. If the ‘login’ URL is not specified, the upload URL is used for login purposes.
username Default username for store upload (optional)
password Default password for store upload (optional)

Note: The default path for the parameters ‘deployment_path’, ‘zip_path’ and ‘doc_path’ are in ‘your_project/build/’. The folder ‘your_project/build’ will be created when you first run any of the python manage.py <command> commands.

Project-to-project configuration with project.cfg

After initializing a new project, the configuration file project.cfg will be placed into your project directory. This configuration file has a few mandatory parameters and can be used to customize the global Grace option settings to your needs on a project-to-project basis. Open ‘project.cfg’ with a text editor e.g. vi, nano, sublime text, notepad++.

The following is a list with mandatory and optional keys:

parameter description Mandatory
name The name of your project, will be prefilled with what you type into the command line when creating a new project with the command ‘grace new’ Yes
version The version of your dizmo, will be prefilled with “0.1” Yes
type Type of Grace project. This is always "dizmo" No
js_name Name the output of your application. Omit the ‘.js’, it will be added automatically. Set to "application" by default. There is usually no need to change this. No
autolint Default is autolint on, if you don’t want that uncomment the following line. No
lintoptions Provide options for linting. Check http://jshint.com/docs/options/ if you’re using JSHint (the default) or check https://github.com/douglascrockford/JSLint if you’re using jslint. No
deployment_path The path where your project should be deployed to with the command ‘python manage.py deploy’. This can usually be left blank to use the value from the global configuration file see The global Grace configuration file below No
zip_path The path where the zip file should be placed upon calling ‘python manage.py zip’. This can usually be left blank to use the value from the global configuration file see The global Grace configuration file No
zip_name The name of the generated zip file. Do not include a paths here, but only the name of the zip file to be generated. No
doc_path The path where the JavaScript docs will be placed upon calling ‘python manage.py doc’. This can usually be left blank to use the value from the global configuration file see The global Grace configuration file No
minify_js Specify if Grace should try to minify your JavaScript. This will usually be overwritten by the value from the global configuration file see The global Grace configuration file No
minify_css Specify if Grace should try to minify your CSS files. This will usually be overwritten by the value from the global configuration file see The global Grace configuration file No
display_name Display name of the dizmo (title) Yes
bundle_name The readable name of the bundle Yes
description Short description of the dizmo. Please note that this will be the description that will be publicly displayed in the dizmoStore to describe your dizmo if you publish it there. Yes
change_log Changes made for this version of the dizmo Yes
min_space_version The minimum version of dizmoViewer needed to use this dizmo. Set this to "0.0.0" if your dizmo runs on any version of dizmoViewer Yes
tags Array containing the tags describing your dizmo. Please note that these tags will be the publicly displayed in the dizmoStore to describe your dizmo if you publish it there. Yes
category The category in which you want your dizmo to be published in the dizmoStore. This must be one of the following: books_and_references, comics, communication, education, entertainment, finance, games, health_and_fitness, libraries_and_demo, lifestyle, media_and_video, medical, music_and_audio, news_and_magazines, personalization, photography, productivity, shopping, social, sports, tools, transportation, travel_and_local, weather Yes
bundle_identifier The bundle identifier should not contain anything else then letters and ".". To make sure there are no duplicates, use a domain which you control or to which you belong in reverse order and add your name and the name of the dizmo without spaces at the end: e.g. com.mycompany.myname.mydizmo. The bundle identifier can not be changed later as it is used to specify this particular dizmo Yes
width Initial width of the dizmo No
height Initial height of the dizmo No
elements_version dizmoViewer provides a library that makes it easy for you to add interaction elements like buttons, text fields, drop downs and more. This parameter defines the version of the library to be used. At the moment this is always "1.0". You may choose to omit this parameter, in which case the dizmoElements library will not be loaded for your dizmo (which is usually not a good idea). See chapter DizmoElements for a more detailed description No
box_inset_x Do not change this option, unless you know exactly what you are doing No
box_inset_y Do not change this option, unless you know exactly what you are doing No
api_version The version of the dizmo API you use; 1.3 is the current version. Yes
main_html The name of the main HTML file to be loaded by dizmoViewer when creating an instance of your dizmo. Do not change this option, unless you know exactly what you are doing Yes
hidden_dizmo Default is false. If set to true the dizmo will be hidden in dizmoViewer. Do not change this option, unless you know exactly what you are doing No
allow_resize Default is false. If set to true a user can not resize the dizmo. No
title_editable Default is true. If set to false a user can not give the dizmo an new title. No
force_update Default is false and a user can only update the dizmo over dizmoStore. No
urls Default store api URL Yes (DizmoStore)
embedded_projects A list of built dizmos that should be included with your dizmo. See chapter Embedding and installing dizmos for further information. No
additional_plist_values Any values that need to be put into the plist that are not specified by individual values here can be added to this dict. No

Note: Possible key:value combinations for additional_plist_values are:

  • CookieJarToUse : "none,dizmo,bundle,viewer" Details
  • LoadMainPageWithScheme "dizmo,https" Details
  • "HelperVersion" : "1.0" Details

Note: The default path for the parameters ‘deployment_path’, ‘zip_path’ and ‘doc_path’ are in ‘your_project/build/’ if you do not specify them in either your .grace.cfg or in your project.cfg file. The folder ‘your_project/build’ will be created when you first run any of the python manage.py <command> commands. Please see subchapter Using manage.py

The mandatory parameters are required so that you can publish a dizmo in the dizmoStore. For more on uploading to and publishing in the dizmoStore, checkout the chapter dizmoStore.

External resources