1 .. -*- coding: utf-8 -*-

     2 

     3 .. _components:

     4 

     5 Components

     6 ===========

     7 

     8 XXXFIXME TURN THIS INTO A CHAPTER

     9 

    10 What is a component

    11 -------------------

    12 

    13 A component is a model grouping one or more entity types and/or views associated

    14 in order to provide a specific feature or even a complete application using

    15 others components.

    16 You can decide to write your own set of components if you wish to re-use the 

    17 entity types you develop. By default, LAX comes with its owns set of components

    18 that you can start using right away.

    19 

    20 

    21 Standard library

    22 ----------------

    23 

    24 A library of standard components is part of the `LAX` release (look at

    25 ``lax/skel/ginco-apps``). Components provide entities and views. With

    26 ``lax-0.4``, you should get a set of application entities and system

    27 entities you can re-use.

    28 

    29 The available application entities are:

    30 

    31 * addressbook: PhoneNumber and PostalAddress

    32 

    33 * ebasket: Basket (like a shopping cart)

    34 

    35 * eblog: Blog (a *very* basic blog)

    36 

    37 * eclassfolder: Folder (to organize things but grouping them in folders)

    38 

    39 * eclasstags: Tag (to tag anything)

    40 

    41 

    42 * efile: File (to allow users to upload and store binary or text files)

    43 

    44 * elink: Link (to collect links to web resources)

    45 

    46 * emailinglist: MailingList (to reference a mailing-list and the URLs

    47   for its archives and its admin interface)

    48 

    49 * eperson: Person (easily mixed with addressbook)

    50 

    51 * etask: Task (something to be done between start and stop date)

    52 

    53 * ezone: Zone (to define places within larger places, for example a

    54   city in a state in a country)

    55 

    56 The available system entities are:

    57 

    58 * ecomment: Comment (to attach comment threads to entities)

    59 

    60 

    61 

    62 Adding comments to BlogDemo

    63 ---------------------------

    64 

    65 To import a component in your application just change the line in the

    66 ``app.conf`` file. For example::

    67 

    68     included-yams-components=ecomment

    69 

    70 will make the ``Comment`` entity available in your ``BlogDemo``

    71 application.

    72 

    73 Change the schema to add a relationship between ``BlogEntry`` and

    74 ``Comment`` and you are done. Since the ecomment component defines the

    75 ``comments`` relationship, adding the line::

    76 

    77     comments = ObjectRelation('Comment', cardinality='1*', composite='object')

    78 

    79 to the definition of a ``BlogEntry`` will be enough.

    80 

    81 Clear the datastore and restart.

    82 

    83 Component structure

    84 -------------------

    85 

    86 A complex component is structured as follows:

    87 ::

    88 

    89   mycomponent/

    90   |

    91   |-- schema.py

    92   |

    93   |-- entities/

    94   |

    95   |-- sobjects/

    96   |

    97   |-- views/

    98   |

    99   |-- test/

   100   |

   101   |-- i18n/

   102   |

   103   |-- data/

   104   |

   105   |-- migration/

   106   | |- postcreate.py

   107   | \- depends.map

   108   |

   109   |-- debian/

   110   |

   111   \-- __pkginfo__.py

   112 

   113 We can also define simple Python module instead of directories (packages), for example:

   114 ::

   115 

   116   mycomponent/

   117   |

   118   |-- entities.py

   119   |-- hooks.py

   120   \-- views.py

   121 

   122 

   123 where:

   124 

   125 * ``schema`` contains the definition of the schema (server side only)

   126 * ``entities`` contains entities definition (server side and web interface)

   127 * ``sobjects`` contains hooks and/or notification views (server side only)

   128 * ``views`` contains the web interface components (web interface only)

   129 * ``test`` contains tests related to the application (not installed)

   130 * ``i18n`` contains messages catalogs for supported languages (server side and

   131   web interface)

   132 * ``data`` contains data files for static content (images, css, javascripts)

   133   ...(web interface only)

   134 * ``migration`` contains initialization file for new instances (``postcreate.py``)

   135   and a file containing dependencies of the component depending on the version

   136   (``depends.map``)

   137 * ``debian`` contains all the files managing debian packaging (you will find

   138   the usual files ``control``, ``rules``, ``changelog``... not installed)

   139 * file ``__pkginfo__.py`` provides component meta-data, especially the distribution

   140   and the current version(server side and web interface) or sub-components used by

   141   the component.

   142  

   143 At least you should have:

   144 

   145 * the file ``__pkginfo__.py``

   146 * schema definition

   147 

   148 [WRITE ME]

   149 

   150 * explain the component architecture

   151 

   152 * add comments to the blog by importing the comments component