<commit_before>

==================
Configuring Mojito
==================

Basic Information
#################

Mojito can be configured at the framework, application, and mojit levels. Each level is configured differently, but uses same general file format consisting of JSON.

File Format
###########

All configuration files in Mojito have a general top-level structure and are in JSON format. At the top level of each configuration file is an array. Each item of the array is 
an object that configures one component of Mojito, such as logging, assets, mojits, static resources, etc.

Each configuration object is required to have a ``settings`` property that specifies conditions for applying the configuration settings. These conditions could be used to determine 
the configurations in different environments. 

Below is the skeleton of a configuration file. See `Application Configuration`_ and `Mojit Configuration`_ for details about specific configuration files.

.. code-block:: javascript

   [
     // Configuration object
     {
       "settings": [ "master" ],
       "specs": {
         ...
       }
     },
     ...
   ]

.. _configure_mj-app:

Application Configuration
#########################

Both the server and client runtimes of an application can be configured. The application is configured in the ``application.json`` file in the application directory. 
The file consists of an array of zero or more ``configuration`` objects. Using the ``configuration`` object, you can configure the following for your application:

- port number
- location of routing files
- path to static assets
- YUI 3
- URL path for client and server communication
- declare mojit instances
- logging
- static resources

The tables below describe the ``configuration`` object and its properties. Those properties that have object values have tables below describing their properties as well except 
the ``config`` object, which is user defined.

.. _app-configuration_obj:

configuration Object
====================

+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| Property                                               | Data Type            | Default Value     | Description                                            |
+========================================================+======================+===================+========================================================+
| ``appPort``                                            | number               | 8666              | The port number (1-65355) that the application         |
|                                                        |                      |                   | will use.                                              |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `build <#build-obj>`_                                  | object               | N/A               | Specifies configuration for builds.                    |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``cacheViewTemplates``                                 | boolean              | true              | Specifies whether the view engine should attempt       |
|                                                        |                      |                   | to cache the view. Note that not all view engines      |
|                                                        |                      |                   | support caching.                                       |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``deferAllOptionalAutoloads``                          | boolean              | false             | Specifies whether optional YUI modules found in        |
|                                                        |                      |                   | the ``/autoload/`` directories are not shipped to      |
|                                                        |                      |                   | the client. This is an optimization setting and        |
|                                                        |                      |                   | should generally only be set if you are building       |
|                                                        |                      |                   | an offline application.                                |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``embedJsFilesInHtmlFrame``                            | boolean              | false             | When Mojito is deployed to the client, this property   |
|                                                        |                      |                   | specifies whether the body of the JavaScript files     |
|                                                        |                      |                   | should be embedded in the HTML page.                   |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``log``                                                | object               | N/A               | Specifies the configuration for the logging            |
|                                                        |                      |                   | subsystem. The configuration is given                  |
|                                                        |                      |                   | independently for the two different runtimes.          |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``middleware``                                         | array of strings     | []                | A list of paths to the Node.js module that exports     |
|                                                        |                      |                   | a Connect middleware function.                         |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``mojitDirs``                                          | array of strings     | []                | The list of directories specifying where to find a     |
|                                                        |                      |                   | single mojit type. The mojits specified by             |
|                                                        |                      |                   | ``mojitDirs`` are loaded after the mojits in           |
|                                                        |                      |                   | ``mojitsDirs``. If a directory doesn't start with      |
|                                                        |                      |                   | a "/", it is taken as relative to the application      |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``mojitsDirs``                                         | array of strings     | ['mojits']        | The list of directories specifying where to find       |
|                                                        |                      |                   | mojit types. If a directory doesn't start with a       |
|                                                        |                      |                   | "/", it is taken as relative to the application        |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``routesFiles``                                        | array of strings     | ['routes.json']   | The list of files specifying where to find routing     |
|                                                        |                      |                   | information. If a file doesn't start with a "/",       |
|                                                        |                      |                   | it is taken as relative to the application             |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``selector``                                           | string               | N/A               | The version of the resource. A resource is either a    |
|                                                        |                      |                   | file to Mojito or metadata to the `Resource Store <../ |
|                                                        |                      |                   | topics/mojito_resource_store.html>`_.                  |
|                                                        |                      |                   | See the `selector Propery <../topics/mojito_resource   |
|                                                        |                      |                   | _store.html#selector-property>`_ and `Selectors <../   |
|                                                        |                      |                   | topics/mojito_resource_store.html#selectors>`_ for     |
|                                                        |                      |                   | for more information.                                  |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``settings``                                           | array of strings     | ["master"]        | Defines the context of the configuration. The          |
|                                                        |                      |                   | context consists of a key-value pair that can          |
|                                                        |                      |                   | specify the environment and environment                |
|                                                        |                      |                   | configurations. These key-value pair corresponds       |
|                                                        |                      |                   | to the configuration objects that are elements of      |
|                                                        |                      |                   | the ``dimensions`` array in the ``dimensions.json``    |
|                                                        |                      |                   | file. For example, the following contexts could be     |
|                                                        |                      |                   | used to specify the testing environment and the        |
|                                                        |                      |                   | English language : ``"environment:testing"``,          |
|                                                        |                      |                   | ``"lang:en"``. See `Using Context Configurations       |
|                                                        |                      |                   | <../topics/mojito_using_contexts.html>`_.              |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``shareYUIInstance``                                   | boolean              | false             | Specifies whether the use of a single shared YUI       |
|                                                        |                      |                   | instance is enabled. Normally, each mojit runs in      |
|                                                        |                      |                   | its own YUI instance. To use the shared YUI            |
|                                                        |                      |                   | instance, each mojit has to be configured to use       |
|                                                        |                      |                   | the shared instance.                                   |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `specs <#specs-obj>`_                                  | object               | N/A               | Specifies the mojit instances. See the                 |
|                                                        |                      |                   | :ref:`specs_obj` for details.                          |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `staticHandling <#statichandling-obj>`_                | object               | N/A               | Gives details on the handling of static resources.     |
|                                                        |                      |                   | See the :ref:`staticHandling_obj`                      |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``tunnelPrefix``                                       | string               | "/tunnel/"        | The URL prefix for the communication tunnel            |
|                                                        |                      |                   | from the client back to the server.                    |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``tunnelTimeout``                                      | number               | 30000             | The timeout in milliseconds for the communication      |
|                                                        |                      |                   | tunnel from the client back to the server.             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `yui <#yui-obj>`_                                      | object               | N/A               | When Mojito is deployed to client, the                 |
|                                                        |                      |                   | :ref:`yui_obj` specifies where                         |
|                                                        |                      |                   | and how to obtain YUI 3.                               |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+



.. _build_obj:

build Object
============

+-----------------------------+---------------+------------------------------------------------+
| Property                    | Data Type     | Description                                    |
+=============================+===============+================================================+
| `html5app <#html5app-obj>`_ | object        | Specifies configuration for HTML5 applications |
|                             |               | created with ``$ mojito build html5app``.      | 
+-----------------------------+---------------+------------------------------------------------+


.. _html5app_obj:

html5app Object
===============

+------------------------+---------------+-----------+---------------+-------------------------------------------+
| Property               | Data Type     | Required? | Default Value | Description                               |
+========================+===============+===========+===============+===========================================+
| ``attachManifest``     | boolean       | no        | ``false``     | When ``true``, the ``manifest``           |
|                        |               |           |               | attribute is added to ``<html>``.         |
+------------------------+---------------+-----------+---------------+-------------------------------------------+
| ``forceRelativePaths`` | boolean       | no        | ``false``     | When ``true``, the server-relative paths  |
|                        |               |           |               | (those starting with "/") are converted   |
|                        |               |           |               | into paths relative to the generated      |
|                        |               |           |               | file.                                     |
+------------------------+---------------+-----------+---------------+-------------------------------------------+<commit_msg>Corrected the name of a config obj: build to builds.<commit_after>

==================
Configuring Mojito
==================

Basic Information
#################

Mojito can be configured at the framework, application, and mojit levels. Each level is configured differently, but uses same general file format consisting of JSON.

File Format
###########

All configuration files in Mojito have a general top-level structure and are in JSON format. At the top level of each configuration file is an array. Each item of the array is 
an object that configures one component of Mojito, such as logging, assets, mojits, static resources, etc.

Each configuration object is required to have a ``settings`` property that specifies conditions for applying the configuration settings. These conditions could be used to determine 
the configurations in different environments. 

Below is the skeleton of a configuration file. See `Application Configuration`_ and `Mojit Configuration`_ for details about specific configuration files.

.. code-block:: javascript

   [
     // Configuration object
     {
       "settings": [ "master" ],
       "specs": {
         ...
       }
     },
     ...
   ]

.. _configure_mj-app:

Application Configuration
#########################

Both the server and client runtimes of an application can be configured. The application is configured in the ``application.json`` file in the application directory. 
The file consists of an array of zero or more ``configuration`` objects. Using the ``configuration`` object, you can configure the following for your application:

- port number
- location of routing files
- path to static assets
- YUI 3
- URL path for client and server communication
- declare mojit instances
- logging
- static resources

The tables below describe the ``configuration`` object and its properties. Those properties that have object values have tables below describing their properties as well except 
the ``config`` object, which is user defined.

.. _app-configuration_obj:

configuration Object
====================

+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| Property                                               | Data Type            | Default Value     | Description                                            |
+========================================================+======================+===================+========================================================+
| ``appPort``                                            | number               | 8666              | The port number (1-65355) that the application         |
|                                                        |                      |                   | will use.                                              |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `builds <#builds-obj>`_                                | object               | N/A               | Specifies configuration for builds.                    |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``cacheViewTemplates``                                 | boolean              | true              | Specifies whether the view engine should attempt       |
|                                                        |                      |                   | to cache the view. Note that not all view engines      |
|                                                        |                      |                   | support caching.                                       |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``deferAllOptionalAutoloads``                          | boolean              | false             | Specifies whether optional YUI modules found in        |
|                                                        |                      |                   | the ``/autoload/`` directories are not shipped to      |
|                                                        |                      |                   | the client. This is an optimization setting and        |
|                                                        |                      |                   | should generally only be set if you are building       |
|                                                        |                      |                   | an offline application.                                |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``embedJsFilesInHtmlFrame``                            | boolean              | false             | When Mojito is deployed to the client, this property   |
|                                                        |                      |                   | specifies whether the body of the JavaScript files     |
|                                                        |                      |                   | should be embedded in the HTML page.                   |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``log``                                                | object               | N/A               | Specifies the configuration for the logging            |
|                                                        |                      |                   | subsystem. The configuration is given                  |
|                                                        |                      |                   | independently for the two different runtimes.          |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``middleware``                                         | array of strings     | []                | A list of paths to the Node.js module that exports     |
|                                                        |                      |                   | a Connect middleware function.                         |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``mojitDirs``                                          | array of strings     | []                | The list of directories specifying where to find a     |
|                                                        |                      |                   | single mojit type. The mojits specified by             |
|                                                        |                      |                   | ``mojitDirs`` are loaded after the mojits in           |
|                                                        |                      |                   | ``mojitsDirs``. If a directory doesn't start with      |
|                                                        |                      |                   | a "/", it is taken as relative to the application      |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``mojitsDirs``                                         | array of strings     | ['mojits']        | The list of directories specifying where to find       |
|                                                        |                      |                   | mojit types. If a directory doesn't start with a       |
|                                                        |                      |                   | "/", it is taken as relative to the application        |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``routesFiles``                                        | array of strings     | ['routes.json']   | The list of files specifying where to find routing     |
|                                                        |                      |                   | information. If a file doesn't start with a "/",       |
|                                                        |                      |                   | it is taken as relative to the application             |
|                                                        |                      |                   | directory.                                             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``selector``                                           | string               | N/A               | The version of the resource. A resource is either a    |
|                                                        |                      |                   | file to Mojito or metadata to the `Resource Store <../ |
|                                                        |                      |                   | topics/mojito_resource_store.html>`_.                  |
|                                                        |                      |                   | See the `selector Propery <../topics/mojito_resource   |
|                                                        |                      |                   | _store.html#selector-property>`_ and `Selectors <../   |
|                                                        |                      |                   | topics/mojito_resource_store.html#selectors>`_ for     |
|                                                        |                      |                   | for more information.                                  |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``settings``                                           | array of strings     | ["master"]        | Defines the context of the configuration. The          |
|                                                        |                      |                   | context consists of a key-value pair that can          |
|                                                        |                      |                   | specify the environment and environment                |
|                                                        |                      |                   | configurations. These key-value pair corresponds       |
|                                                        |                      |                   | to the configuration objects that are elements of      |
|                                                        |                      |                   | the ``dimensions`` array in the ``dimensions.json``    |
|                                                        |                      |                   | file. For example, the following contexts could be     |
|                                                        |                      |                   | used to specify the testing environment and the        |
|                                                        |                      |                   | English language : ``"environment:testing"``,          |
|                                                        |                      |                   | ``"lang:en"``. See `Using Context Configurations       |
|                                                        |                      |                   | <../topics/mojito_using_contexts.html>`_.              |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``shareYUIInstance``                                   | boolean              | false             | Specifies whether the use of a single shared YUI       |
|                                                        |                      |                   | instance is enabled. Normally, each mojit runs in      |
|                                                        |                      |                   | its own YUI instance. To use the shared YUI            |
|                                                        |                      |                   | instance, each mojit has to be configured to use       |
|                                                        |                      |                   | the shared instance.                                   |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `specs <#specs-obj>`_                                  | object               | N/A               | Specifies the mojit instances. See the                 |
|                                                        |                      |                   | :ref:`specs_obj` for details.                          |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `staticHandling <#statichandling-obj>`_                | object               | N/A               | Gives details on the handling of static resources.     |
|                                                        |                      |                   | See the :ref:`staticHandling_obj`                      |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``tunnelPrefix``                                       | string               | "/tunnel/"        | The URL prefix for the communication tunnel            |
|                                                        |                      |                   | from the client back to the server.                    |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| ``tunnelTimeout``                                      | number               | 30000             | The timeout in milliseconds for the communication      |
|                                                        |                      |                   | tunnel from the client back to the server.             |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+
| `yui <#yui-obj>`_                                      | object               | N/A               | When Mojito is deployed to client, the                 |
|                                                        |                      |                   | :ref:`yui_obj` specifies where                         |
|                                                        |                      |                   | and how to obtain YUI 3.                               |
+--------------------------------------------------------+----------------------+-------------------+--------------------------------------------------------+



.. _builds_obj:

builds Object
=============

+-----------------------------+---------------+------------------------------------------------+
| Property                    | Data Type     | Description                                    |
+=============================+===============+================================================+
| `html5app <#html5app-obj>`_ | object        | Specifies configuration for HTML5 applications |
|                             |               | created with ``$ mojito build html5app``.      | 
+-----------------------------+---------------+------------------------------------------------+


.. _html5app_obj:

html5app Object
===============

+------------------------+---------------+-----------+---------------+-------------------------------------------+
| Property               | Data Type     | Required? | Default Value | Description                               |
+========================+===============+===========+===============+===========================================+
| ``attachManifest``     | boolean       | no        | ``false``     | When ``true``, the ``manifest``           |
|                        |               |           |               | attribute is added to ``<html>``.         |
+------------------------+---------------+-----------+---------------+-------------------------------------------+
| ``forceRelativePaths`` | boolean       | no        | ``false``     | When ``true``, the server-relative paths  |
|                        |               |           |               | (those starting with "/") are converted   |
|                        |               |           |               | into paths relative to the generated      |
|                        |               |           |               | file.                                     |
+------------------------+---------------+-----------+---------------+-------------------------------------------+
{'fraction_non_alphanumeric': 0.2701478434859938, 'fraction_numerical': 0.0012783459315251222, 'mean_word_length': 0.4955737500519513, 'pattern_counts': {'":': 4, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 524, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7648886', 'n_tokens_mistral': 5114, 'n_tokens_neox': 4625, 'n_words': 1603}