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

     2 

     3 .. _components:

     4 

     5 Components

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

     7 

     8 What is a component

     9 -------------------

    10 

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

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

    13 others components.

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

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

    16 that you can start using right away.

    17 

    18 

    19 Standard library

    20 ----------------

    21 

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

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

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

    25 entities you can re-use.

    26 

    27 The available application entities are :

    28 

    29 * addressbook: PhoneNumber and PostalAddress

    30 

    31 * ebasket: Basket (like a shopping cart)

    32 

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

    34 

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

    36 

    37 * eclasstags: Tag (to tag anything)

    38 

    39 

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

    41 

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

    43 

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

    45   for its archives and its admin interface)

    46 

    47 * eperson: Person (easily mixed with addressbook)

    48 

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

    50 

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

    52   city in a state in a country)

    53 

    54 The available system entities are :

    55 

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

    57 

    58 

    59 

    60 Adding comments to BlogDemo

    61 ---------------------------

    62 

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

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

    65 

    66     included-yams-components=ecomment

    67 

    68 Will make the ``Comment`` entity available in your ``BlogDemo``

    69 application.

    70 

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

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

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

    74 

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

    76 

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

    78 

    79 Clear the datastore and restart.

    80 

    81 Component structure

    82 -------------------

    83 

    84 A complex component is structured as follows :

    85 ::

    86 

    87   mycomponent/

    88   |

    89   |-- schema.py

    90   |

    91   |-- entities/

    92   |

    93   |-- sobjects/

    94   |

    95   |-- views/

    96   |

    97   |-- test/

    98   |

    99   |-- i18n/

   100   |

   101   |-- data/

   102   |

   103   |-- migration/

   104   | |- postcreate.py

   105   | \- depends.map

   106   |

   107   |-- debian/

   108   |

   109   \-- __pkginfo__.py

   110 

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

   112 ::

   113 

   114   mycomponent/

   115   |

   116   |-- entities.py

   117   |-- hooks.py

   118   \-- views.py

   119 

   120 

   121 where :

   122 

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

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

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

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

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

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

   129   web interface)

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

   131   ...(web interface only)

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

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

   134   (``depends.map``)

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

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

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

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

   139   the component.

   140  

   141 At least you should have :

   142 

   143 * the file ``__pkginfo__.py``

   144 * schema definition

   145 

   146 [WRITE ME]

   147 

   148 * explain the component architecture

   149 

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