docs/presentation.rst

   1 Etalage presentation
   2 ====================
   3
   4 Etalage is a part of `Comarquage.fr`_ solution.
   5
   6 It is the cartographic front-end page. Providing a **widget** wich can be implemented on any web pages of any websites
   7 despite technologies used.
   8
   9 .. _Comarquage.fr: http://www.comarquage.fr
  10
  11
  12 Structure
  13 ---------
  14
  15 This project don't use any known framework. It's structure diverge from pylons/pyramid project byt everything used in
  16 the project is writen within the project.
  17
  18 Metadata files:
  19
  20 * COPYING
  21 * README.md
  22
  23 Then, distutils files:
  24
  25 * setup.cfg
  26 * setup.py
  27
  28 In those two files, you'll find usefull informations, and most important the **entry point**
  29 This **entry point** will be followed my Apache mod_wsgi::
  30
  31     entry_points = """
  32         [paste.app_factory]
  33         main = etalage.application:make_app
  34         """,
  35
  36 This lead us in file `etalage/application.py` where the **make_app** method take configuration file in parameter and
  37 ubild a WSGI Middlewares pipe.
  38
  39 .. FIXME Explain middleware pipes or find a link to add here
  40
  41 Environment
  42 -----------
  43
  44 In the **make_app** method, you'll find a particular call to **load_environment**.
  45
  46 This functions consists of a big `biryani <http://gitorious.org/biryani>`_ converter wich transform raw configuration
  47 variables into a clean dict with usable values. It'll ensure that every information needed is correctly given to the
  48 process in order to run correctly.
  49
  50 A second converter is called in case some configuration variable had to be computed with previous ones.
  51
  52 In the same files you'll find logging, errors handler, templates and databases configurations, all set globally in
  53 **Etalage modules**
  54
  55 * Errors are using the standard **weberror ErrorMiddleware**
  56 * Logging configuration uses the standart **logging** module of python
  57 * Templates uses `**Mako templates** <http://www.makotemplates.org/>`_
  58 * Databases uses… see the next pages about databases.
  59
  60
  61 Specific important files
  62 ------------------------
  63
  64 Some file are very important in the project, knowing them can save you a large amount of time !
  65
  66
  67 development.ini
  68 ~~~~~~~~~~~~~~~
  69
  70 This is the *default* configuration files when you're in development mode. You'll need to adjust the content to make
  71 **Etalage** works but it reflect the minimal setting requirements.
  72
  73
  74 etalage/contexts.py
  75 ~~~~~~~~~~~~~~~~~~~
  76
  77 In this file is defined the **Context** class. This object is really important cause it will be pass in every call for
  78 every method of the project.
  79
  80 In each **controllers**, the first instruction is to build a **Context** object calles **ctx** to acquire all request
  81 data and application environement.
  82
  83 We use this object to store the `**Webob Request** <http://webob.readthedocs.org/en/latest/modules/webob.html>`_ itself
  84 and other usefull resources like **translator** method or **session** based storage.
  85
  86
  87 etalage/conv.py
  88 ~~~~~~~~~~~~~~~
  89
  90 Central system of **Etalage**. All converter are regrouped in this files, it means that a lot of specific code are
  91 written in it and it need to perfectly understand what a **biryani converter** is to read it.
  92
  93 .. FIXME Refer to biryani pages
  94
  95
  96 etalage/urls.py
  97 ~~~~~~~~~~~~~~~
  98
  99 You'll find **Etalage** router here. Once again, you don't have any framework in this project, the *router* too is
 100 writen within the project and can be found here.
 101
 102
 103 etalage/wsgihelpers.py
 104 ~~~~~~~~~~~~~~~~~~~~~~
 105
 106 Set of function used to build errors responses to clients.