|
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. |