[Sommaire] [Imprimer]

   1  {@toc}
   2  <refsect1 id="{@id naming}">
   3   <title>The Trax Naming Convention</title>
   4    <para>Trax uses naming conventions instead of explicit configuration
   5     to link the various parts of a Trax application.  From the name of
   6     a component, Trax can compute the names of related components.
   7     This lets you build an application faster because you need to do
   8     less.</para>
   9    <para>Conversion of names between singular and plural or between
  10     CamelCase and lower_case_underscore forms is done by methods of the
  11     {@link Inflector} class.</para>
  12  
  13   <refsect2 id="{@id naming_model}">
  14    <title>Names In the Model</title>
  15    <para><important>Database tables</important> have names which are
  16     English plural words in lowercase.  Where the name is two or more
  17     words, the words are connected by underscores ('_').
  18     Examples:</para> 
  19     <itemizedlist>      
  20      <listitem><literal>orders</literal></listitem>
  21      <listitem><literal>people</literal></listitem>
  22      <listitem><literal>approved_medications</literal></listitem>
  23     </itemizedlist>      
  24    <para>The primary key column of each table is called
  25     <literal>id</literal>.</para>
  26    <para>There is also a naming convention for foreign keys.  A foreign
  27     key which selects a row in a table by (only) the
  28     <literal>id</literal> column is the singular lower_case_underscore
  29     name of that table with suffix <literal>_id</literal>.  For
  30     example, a foreign key to the <literal>people</literal> 
  31     table's <literal>id</literal> column would be stored
  32     in a column named <literal>person_id</literal>.</para>
  33  
  34    <para>Column names containing the string <literal>password</literal>
  35     are treated specially by {@link ActiveRecordHelper}.</para>
  36  
  37    <para><important>{@link ActiveRecord} subclasses</important> have names
  38     which are English singular words in CamelCase.  Where the name is
  39     two or more words, the first letter of each word is capitalized.
  40     Each table in the database has a one-to-one relationship with a
  41     subclass of ActiveRecord whose name is the CamelCase singular of
  42     the table name.  Examples corresponding to the table names listed
  43     above:</para>
  44     <itemizedlist>      
  45      <listitem><literal>Order</literal></listitem>
  46      <listitem><literal>Person</literal></listitem>
  47      <listitem><literal>ApprovedMedication</literal></listitem>
  48     </itemizedlist>      
  49    <para>The subclass is contained in a file in the
  50     <literal>app/models</literal> area of the Trax work area.  The file
  51     name is the lower_case_underscore form of the subclass name.
  52     Examples corresponding to the subclasses listed above:</para>
  53     <itemizedlist>      
  54      <listitem><literal>order.php</literal></listitem>
  55      <listitem><literal>person.php</literal></listitem>
  56      <listitem><literal>approved_medication.php</literal></listitem>
  57     </itemizedlist>      
  58   </refsect2>
  59  
  60   <refsect2 id="{@id naming_controller}">
  61    <title>Names In the Controller</title>
  62  
  63    <para>The Controller is implemented as
  64     <important>{@link ApplicationController} subclasses</important> that
  65     have descriptive names in CamelCase.  The last
  66     word of a controller name is <literal>Controller</literal>.  The
  67     word(s) of the controller name before <literal>Controller</literal>
  68     describe the thing controlled.  For example:</para>
  69     <itemizedlist>      
  70      <listitem><literal>StoreController</literal></listitem>
  71      <listitem><literal>CreditAuthorizationController</literal></listitem>
  72     </itemizedlist>      
  73    <para>Each ApplicationController subclass is contained in a file
  74     whose name is the lower_case_underscore form of the subclass name.
  75     This file stored in the <literal>app/controllers</literal> area of
  76     the Trax work area.  For example, the files containing the
  77     subclasses listed above are:</para> 
  78     <itemizedlist>      
  79      <listitem><literal>store_controller.php</literal></listitem>
  80      <listitem><literal>credit_authorization_controller.php</literal></listitem>
  81     </itemizedlist>
  82    <para>Each ApplicationController subclass also has a helper file in
  83     the <literal>app/helpers</literal> area of the Trax work area with
  84     a file name which is the same as the name of the controller file with 
  85     <literal>helper</literal> substituted for
  86     <literal>controller</literal>.  For example, the helper files for
  87      the controllers listed above are:</para>
  88     <itemizedlist>      
  89      <listitem><literal>store_helper.php</literal></listitem>
  90      <listitem><literal>credit_authorization_helper.php</literal></listitem>
  91     </itemizedlist>
  92   </refsect2>
  93  
  94   <refsect2 id="{@id naming_view}">
  95    <title>Names In the View</title>
  96    <para>There is a view associated with each controller.  The
  97     templates for that view are stored in the
  98     <literal>app/views</literal> area of the Trax work area in a
  99     directory whose name is the desciptive part of the controller
 100     name.  For example, the view template files for the controllers
 101     listed above are stored in:</para> 
 102     <itemizedlist>      
 103      <listitem><literal>app/views/store/</literal></listitem>
 104      <listitem><literal>app/views/credit_authorization/</literal></listitem>
 105     </itemizedlist>
 106  
 107    <para>The layout for each view is stored in the
 108     <literal>app/views/layouts</literal> area of the Trax work area in
 109     a file whose name is the desciptive part of the controller
 110     name with a <literal>.phtml</literal> extension.  For example, the
 111     layouts for the controllers listed above are stored in:</para> 
 112     <itemizedlist>      
 113      <listitem><literal>app/views/layouts/store.phtml</literal></listitem>
 114      <listitem><literal>app/views/layouts/credit_authorization.phtml</literal></listitem>
 115     </itemizedlist>
 116   </refsect2>
 117   <refsect2 id="{@id naming_forms}">
 118    <title>Fields On Forms</title>
 119     <para>Input fields on forms that relate directly to elements of the
 120      model are named according to the ActiveRecord subclass and
 121      attribute represented by the field.  Simple elements are given
 122  <literal>id="</literal><arg choice="tute-comment">SubClassName_attribute_name</arg><literal>"</literal> and
 123  <literal>name="</literal><arg choice="tute-comment">SubClassName</arg><literal>[</literal><arg choice="tute-comment">attribute_name</arg><literal>]"</literal>.
 124      For example, a field to input the first name of a person which is
 125      attribute <literal>fname</literal> of subclass
 126      <literal>Person</literal> would appear as:
 127      <example>
 128  &lt;input id="Person_fname name="Person[fname]" type="text" ... /&gt;
 129      </example>
 130      When the form is POSTed to the server, the value entered into this
 131      field will be in <literal>$_REQUEST['Person']['fname']</literal></para>
 132  
 133      <para>Certain attributes, such as dates and times, are composites of
 134      individual fields representing year, month, day, hour, minute and
 135      second. Each field is named with the attribute name followed by a
 136      suffix describing which component is represented.  The suffixes
 137      for dates and times are:
 138      <itemizedlist>
 139        <listitem><literal>(1i)</literal> Year</listitem>
 140        <listitem><literal>(2i)</literal> Month</listitem>
 141        <listitem><literal>(3i)</literal> Day of the month</listitem>
 142        <listitem><literal>(4i)</literal> Hour</listitem>
 143        <listitem><literal>(5i)</literal> Minute</listitem>
 144        <listitem><literal>(6i)</literal> Second</listitem>
 145      </itemizedlist>
 146      For example, a group of three pulldown menus which specified 
 147      attribute <literal>birthdate</literal> of subclass
 148      <literal>Person</literal> would be named:
 149      <example>
 150  Month:
 151  &lt;select name="Person[birthdate(2i)]"&gt; ... &lt;/select&gt;
 152  
 153  Day:
 154  &lt;select name="Person[birthdate(3i)]"&gt; ... &lt;/select&gt;
 155  
 156  Year:
 157  &lt;select name="Person[birthdate(1i)]"&gt; ... &lt;/select&gt;
 158      </example>
 159      When the form is POSTed to the server, the selected values will
 160      appear in <literal>$_REQUEST['Person']['birthdate(2i)']</literal>,
 161      <literal>$_REQUEST['Person']['birthdate(3i)']</literal> and
 162      <literal>$_REQUEST['Person']['birthdate(1i)']</literal>
 163      respectively.  The value would be stored in the database in a
 164      column of type <literal>date</literal> and would be
 165      represented according to the SQL standard as
 166      <literal>YYYY-MM-DD</literal> .
 167  </para>
 168   </refsect2>
 169  
 170  <!--
 171  Local variables:
 172  mode: xml
 173  c-basic-offset: 1
 174  indent-tabs-mode: nil
 175  End:
 176  -->
 177  
 178  </refsect1>