src/source/appconfig.rst
changeset 99 b2be9a32f3fc
equal deleted inserted replaced
-1:000000000000 99:b2be9a32f3fc
       
     1 .. _config:
       
     2 
       
     3 PyAMS configuration
       
     4 ===================
       
     5 
       
     6 .. Note::
       
     7 
       
     8     PyAMS application configuration is done via several complementary ways:
       
     9 
       
    10         - via **Pyramid's configuration** files located in 'etc/' folder
       
    11 
       
    12         - via **ZCML files** .
       
    13 
       
    14         - via **Site Management** to setup Local utilities defined into ZODB (see :ref:`appmanage`)
       
    15 
       
    16 
       
    17 Pyramid's configuration files
       
    18 -----------------------------
       
    19 
       
    20 PyAMS is using default Pyramid's ini_ configuration files to define settings. When using default PyAMS scaffold, these
       
    21 INI files are stored into *etc* folder. Two files are created by scaffold: a development file (*development.ini*) and
       
    22 a production file (*production.ini*) which contain nearly the same directives, except for debug toolbar (activated only
       
    23 in development), Fanstatic configuration and logging.
       
    24 
       
    25 .. _ini: https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/project.html#development-ini
       
    26 
       
    27 These files are actually documented, but here are a few important directives:
       
    28 
       
    29 - **zodbconn.uri**: (ex: zconfig:/zodb-relstorage.conf)
       
    30 
       
    31 - **pyams.application_name**: Name of your own application
       
    32 - **pyams.application_factory**: Configuration module path to your custom application.
       
    33 
       
    34 - **pyams_xxx.tcp_handler** :  Adress of the tcp handler for the service associated to the pyams package
       
    35 - **pyams_xxx.start_handler**: True / False
       
    36 
       
    37 - **pyams_content.config.xxx_tool_factory** and **pyams_content.config.xxx_tool_name**: You can override default factory by defining these settings or by providing your own adapters.
       
    38 
       
    39 
       
    40 
       
    41 Pyramid's configuration files powered by PyAMS_utils
       
    42 ----------------------------------------------------
       
    43 
       
    44 On application startup, if PyAMS_utils package is included into Pyramid configuration, several operations take
       
    45 place:
       
    46 
       
    47  - a custom **site factory** is defined
       
    48 
       
    49  - custom request methods are defined
       
    50 
       
    51  - a custom **traverser** handling **namespaces** is defined
       
    52 
       
    53  - a custom subscribers predicate based on interfaces support is defined
       
    54 
       
    55  - several adapters are registered, to handle annotations and key references
       
    56 
       
    57  - custom TALES extensions are registered.
       
    58 
       
    59 The site factory is an important component in this process. It is this factory which will define the application root
       
    60 and create a **local site manager**.
       
    61 
       
    62 Pyramid application is loaded from ZODB's root via a key defined in Pyramid's configuration file; the key is named
       
    63 *pyams.application_name* and it's default value is *application*.
       
    64 
       
    65 If the application can't be found, PyAMS is looking for an application class name in Pyramid's configuration file; the
       
    66 class name configuration key is called *pyams.application_factory* and defined by default as
       
    67 *pyams_utils.site.BaseSiteRoot*. PyAMS default site factory will then create the application, and add a local site
       
    68 manager to it (see :ref:`zca`).
       
    69 
       
    70 After application creation, a :py:class:`NewLocalSiteCreatedEvent <pyams_utils.site.NewLocalSiteCreatedEvent>` is
       
    71 notified. Custom packages can subscribe to this event to register custom components.
       
    72 
       
    73 
       
    74 
       
    75 ZCML configuration files
       
    76 ------------------------
       
    77 
       
    78 Adding more ZCML configuration directives is not mandatory in any way but can be useful in several use cases. For
       
    79 example, templates can't be overriden via Python annotations without creating a new subclass; this can be done
       
    80 easily via ZCML.