configuration-details.gtw

~~LANG:FR@frman:details-configuration~~


===== project.xml =====

The file @@F@project.xml@@ contains some informations on the application. Some of these are important because they are used by the installer.

It is an XML file with a @@E@<project>@@ as root element, and which contains 4 elements:

<code xml>
<project xmlns="http://jelix.org/ns/project/1.0">
    <info id="testapp@jelix.org" name="testapp" createdate="2005-01-01">
     ...
    </info>
    <dependencies>
     ...
    </dependencies>
    <directories>
     ...
    </directories>
    <entrypoints>
     ...
    </entrypoints>
</project>
</code>


==== info ====

Int the element @@E@info@@, there are some informations indicative only about the application, like its name, a description, the copyright, the creator name etc. Note that this element can be used also in @@F@module.xml@@ files to identify a module. Here is an example:

<code xml>
<info id="testapp@jelix.org" name="testapp" createdate="2005-01-01">
    <version>1.0</version>
    <label lang="en_US">Testapp</label>
    <description lang="en_US">Application to test Jelix</description>
    <licence URL="http://www.gnu.org/licenses/gpl.html">GPL</licence>
    <copyright>2005-2010 Laurent Jouanneau and other contributors</copyright>
    <creator name="Laurent Jouanneau" email="laurent@jelix.org" active="true" />
    <contributor name="Superman" email="superman@superville.com" active="true" since="" role=""/>
    <homepageURL>http://jelix.org</homepageURL>
</info>
</code>

Only the @@E@<version>@@ element and attributes  @@A@id@@ and @@A@name@@ on @@E@<info>@@ are required. Others are optionals.

The id attribute should be a unique identifiant. That's why it is recommanded to use an email as an identifiant (or a UUID but it is less readable).

The attribute @@A@name@@ should be a "technical" name (the name of the directory of the application or of the module for instance). The @@E@label@@ element can contain a displayable name. 

==== dependencies ====

The element @@E@<directories>@@ should contain informations about dependencies of the application. For the moment, only the jelix version is required.

<code xml>
<dependencies>
     <jelix minversion="1.3.0" maxversion="1.3.*" />
</dependencies>
</code>

This element can be used in a @@F@module.xml@@ file, and can contain additionnaly one or more @@E@<module>@@ elements, which indicate modules that the installer should install in order to execute correctly the modules.

<code xml>
  <module name="testurls" minversion="2.2" maxversion="2.3" />
  <module name="jauthdb" />
  <module name="jacl2db" />
</code>

==== directories ====

This element indicate paths of some directories. all elements in this example are required:
<code xml>
    <directories>
        <config>var/config</config>
        <log>var/log</log>
        <var>var</var>
        <www>www</www>
        <temp>../temp/testapp</temp>
    </directories>
</code>

==== entrypoints ====

The @@E@entrypoints@@ element list all entry points of the application (in @@F@www/@@ or @@F@scripts/@@), with their configuration file and their type.

<code xml>
    <entrypoints>
        <entry file="index.php" config="index/config.ini.php" />
        <entry file="soap.php" config="soap/config.ini.php" type="soap"/>
        <entry file="jsonrpc.php" config="jsonrpc/config.ini.php" type="jsonrpc"/>
        <entry file="cmdline.php" config="cmdline/config.ini.php" type="cmdline"/>
    </entrypoints>
</code>


===== module.xml =====

A @@F@module.xml@@ file must be present in each directory of modules. It contains a root element @@E@module@@ which should contain a @@E@<info>@@ element and @@E@<dependencies>@@ element. See above to know how to write these elements.

<code xml>
<module xmlns="http://jelix.org/ns/module/1.0">
    <info id="jelix_tests@testapp.jelix.org" name="jelix_tests">
        <version>1.0</version>
        <label>Jelix tests</label>
        <description>unit tests for jelix</description>
    </info>
    <dependencies>
        <jelix minversion="1.3" maxversion="1.3.*" />
        <module name="testurls" minversion="1.0.2" maxversion="1.1b1" />
        <module name="jauthdb" />
        <module name="jacl2db" />
        <module name="jacldb" />
    </dependencies>
</module>
</code>



===== configuration ini files=====

See @@F@lib/jelix/core/defaultconfig.ini.php@@ for the whole list of parameters. This file is the "source" of the identically-named file you find in @@F@var/config@@ of your application.

Below is a tour of all configuration sections.

==== global section ====

Usually its parameters are at the beginning of file. They define default or global values of the framework.


<code ini>
startModule = "jelix"
startAction = "default:index"
locale = "en_US"
charset = "UTF-8"
timeZone = "US/Pacific"

pluginsPath = lib:jelix-plugins/,app:plugins/
modulesPath = lib:jelix-modules/,app:modules/

theme = default
use_error_handler = on
</code>

Parameters in details :
  * **startModule, startAction** : default module and action (generally re-defined for each response type. see  [[config#organization|preceding section]])
  * **locale, charset** : default language and encoding of responses 
  * **timeZone** : set the time zone for every date and time functions
  * **pluginsPath** : path list to plugins. learn more in [[plugins|plugins]] documentation. 
  * **theme** : default selected theme. Read [[themes|theme]] system description.   
  * **use_error_handler** : this option shoud stay //on// for Jelix to return useful and detailed errors or exceptions.

==== modules section ====

Contains the list of all used modules, and their access level

   * 0 means the module is not used and must not be installed
   * 1 means the module is used, but only by other modules (its daos, forms etc), but is not accessible directly from the web (so it has no controllers or existing controllers will never be called)
   * 2 means the module is installed and usuable normally.


==== coordplugins section ====

List all coordinator plugins Jelix has to activate. They will be loaded from the list of path defined by the pluginsPath option.


The example below demonstrates the activation of an authentication plugin. Its own set of options are defined in @@F@auth.coord.ini.php@@ file. Learn more about [[authentification|authentication]].

<code ini>
[coordplugins]
;plugin name = ini filename
auth = "auth.coord.ini.php"
</code>


==== responses section ====

this section allows to customize each response type and its alias. 
each line consists of a couple <response alias>=<response class>.

As for example, it is usual to overload html default response (jResponseHtml) by such a line : //html=myhtmlresponse//. Find more details in [[common-processes#customizing-common-response|customizing common response]] 

Below are the default alias and response types:
<code ini>
[responses]
html = jResponseHtml
redirect = jResponseRedirect
redirectUrl = jResponseRedirectUrl
binary = jResponseBinary
text = jResponseText
jsonrpc = jResponseJsonrpc
json = jResponseJson
xmlrpc = jResponseXmlrpc
xml = jResponseXml
zip = jResponseZip
rss2.0 = jResponseRss20
atom1.0 = jResponseAtom10
css= jResponseCss
tcpdf = jResponseTcpdf
</code>


==== error_handling section ====

Those parameters are used to configure notifications occuring during an application script execution. Details can be found in [[errormanager|error manager]] documentation.

Notifications have different levels. Jelix defined levels corresponding to PHP error_reporting levels: 
  * //default//     = selected level if no other level corresponds
  * //error//       = notify an error stopping a script execution
  * //warning//     = notifu an error which doesn't stop a script 
  * //notice//      = notify a possible error  
  * //deprecated//  = notify a deprecated function (php 5.3)
  * //strict//      = notify core PHP messages about compatibility and interoperability 

Below are the whole list of parameters:
<code ini>
[error_handling]
messageLogFormat = "%date%\t%ip\t[%code%]\t%msg%\t%file%\t%line%\n"
logFile = error.log
email = root@localhost
emailHeaders = "Content-Type: text/plain; charset=UTF-8\nFrom: webmaster@yoursite.com\nX-Mailer: Jelix\nX-Priority: 1 (Highest)\n"
quietMessage="A technical error has occured. Sorry for this trouble."

showInFirebug = off

; keywords you can use : ECHO, ECHOQUIET, EXIT, LOGFILE, SYSLOG, MAIL, TRACE
default      = ECHO EXIT
error        = ECHO EXIT
warning      = ECHO
notice       = ECHO
deprecated   = ECHO
strict       = ECHO
; exceptions implicitly use EXIT
exception    = ECHO
</code>

  * **messageLogFormat** and **logFile** configure a log file output (LOGFILE or SYSLOG)
  * **email** et **emailHeaders** configure mail ouptut (MAIL)
  * **quietMessage** defines a neutral message for user (ECHOQUIET)
  * **showInFirebug** : if //on//, all notifications will be redirected to firebug extension of firefox browser using its //console// api.

The last set of options allows to associate ouptut formats to each level of notification.  Each level can have more than one output format. 
For example, in production, you'll probably want to set ://error = ECHOQUIET EXIT LOGFILE// and so on.



==== compilation section ====

Defines the template behavior of Jelix template engine. And more precisely of its compilation step. Find in-depth details in [[templates|templates]].

<code ini>
[compilation]
checkCacheFiletime  = on
force  = off
</code>

  * **checkCacheFiletime ** : if //on// template will be compiled if its file modification date is more recent than its already PHP compiled file.
  * **force** : if //on//, template is systematically compiled

==== section zone ====

There is an option to globally disable zone caching. It is useful during development environment but should be set to off in production.

To disable zone caching : 
<code ini>
[zones]
disableCache = on  // default to off
</code>

==== urlengine section ====

@TODO : to complete






==== logfiles section ====

This section defines how log calls through [[debugging|jLog]] api will be output.
Log files are created and stored in @@F@var/log/@@ application folder. 

A per-module log file can be defined by setting a couple @@<module name>=<log filename>@@ and calling jLog methods with <module name> as last argument.

<code ini>
; default log
  default = messages.log

; log for "news" module
  news = news.log
</code>

Another example shows how you can use firebug extension as a log output (useful for quickly debugging). Still you can log to a classic file calling jLog methods with //file// as last argument (for dumping huge content for example).
<code ini>
[logfiles]
default="!firebug"
file = "messages.log"
</code>

Learn more about Jelix debugging through [[debugging|jLog]] documentation.


==== mailer section ====
Parameters required to send mails through application scripts. As for example, authentication or notifications can send emails.

<code ini>
[mailer]
webmasterEmail = root@localhost
webmasterName =

; How to send mail : "mail" (mail()), "sendmail" (call sendmail), or "smtp" (send directly to a smtp)
mailerType = mail
; Sets the hostname to use in Message-Id and Received headers
; and as default HELO string. If empty, the value returned
; by SERVER_NAME is used or 'localhost.localdomain'.
hostname =
sendmailPath = "/usr/sbin/sendmail"

; if mailer = smtp , fill the following parameters

; SMTP hosts.  All hosts must be separated by a semicolon : "smtp1.example.com:25;smtp2.example.com"
smtpHost = "localhost"
; default SMTP server port
smtpPort = 25
; SMTP HELO of the message (Default is hostname)
smtpHelo =
; SMTP authentication
smtpAuth = off
smtpUsername =
smtpPassword =
; SMTP server timeout in seconds
smtpTimeout = 10

</code>




==== acl section ====
Defines options of access control list (ACL) or rights management. See [[/rights2|rights management]]. You can use jAcl ou jAcl2, but not both at the same time. Indicate a driver to enable it.

<code ini>
[acl]
; example of driver : "db"
driver =

[acl2]
; example of driver : "db"
driver =

</code>

==== sessions section ====
Determines how PHP sessions are stored (file or databse). Find more details in [[/classe-utilities/jsession|sessions]] documentation. 

<code ini>
[sessions]
shared_session = off
; Use alternative storage engines for sessions
;
; usage :
;
; storage = "files"
; files_path = "app:var/sessions/"
;
; or
;
; storage = "dao"
; dao_selector = "jelix~jsession"
; dao_db_profile = ""
</code>