Changeset 6970

Show
Ignore:
Timestamp:
08/31/07 04:12:30 (1 year ago)
Author:
nicobn
Message:

Jaws_StaticConfig documentation

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • doc/jaws2/en/books/internals/coress/sections/cnf.xml

    r6923 r6970  
    77<sect1> 
    88 <title>Static configuration subsystem</title> 
     9 
     10 <partintro> 
     11  <formalpara> 
     12   &reftitle.subsystem.synopsis; 
     13    
     14   <informaltable> 
     15    <tgroup cols="2"> 
     16     <row> 
     17      <entry><emphasis>File</emphasis></entry> 
     18      <entry><filename>api/Jaws/StaticConfig.php</filename></entry> 
     19     </row> 
     20 
     21     <row> 
     22      <entry><emphasis>Classes</emphasis></entry> 
     23      <entry> 
     24       <classname>Jaws_StaticConfig</classname>,  
     25       <classname>Jaws_StaticConfig_Driver</classname>, 
     26       <classname>Jaws_StaticConfig_Import</classname> and 
     27       <classname>Jaws_StaticConfig_Export</classname>. 
     28      </entry> 
     29     </row> 
     30 
     31     <row> 
     32      <entry><emphasis>Additional classes</emphasis></entry> 
     33      <entry> 
     34       <classname>Jaws_StaticConfig_Import_XML</classname> and 
     35       <classname>Jaws_StaticConfig_Export_XML</classname>. 
     36      </entry> 
     37     </row> 
     38 
     39     <row> 
     40      <entry><emphasis>Object</emphasis></entry> 
     41      <entry><varname>Jaws::$Cnf</varname></entry> 
     42     </row> 
     43    </tgroup> 
     44   </informaltable> 
     45 
     46  </formalpara> 
     47  <formalpara> 
     48   &reftitle.intro; 
     49   Most configuration options and user preferences are stored in a database.  
     50   However, some vital settings cannot be stored that way and from there  
     51   rises the need of static configuration. 
     52  </formalpara> 
     53   
     54  <para> 
     55   The static configuration subsystem provides basic facilities to access, 
     56   modify, import and export static configuration options. It is very extensible 
     57   and can be used for just any static configuration file. 
     58  </para> 
     59 </partintro> 
     60 
     61 <sect2> 
     62  &reftitle.classes; 
     63  <para> 
     64   The static configuration subsystem is made of 1 class and 3 abstract classes. 
     65  </para> 
     66  <formalpara> 
     67   <title><classname>Jaws_StaticConfig</classname></title> 
     68   The subsystem class. The class can also be used outside of the subsystem  
     69   context. 
     70  </formalpara> 
     71 
     72  <formalpara> 
     73   <title><classname>Jaws_StaticConfig_Driver</classname></title> 
     74   This abstract class is a common derivative of the importation and exportation 
     75   drivers and instructs them on basic functionalities they should provide. 
     76  </formalpara> 
     77 
     78  <formalpara> 
     79   <title><classname>Jaws_StaticConfig_Import</classname></title> 
     80   Abstract class used by configuration importation drivers. 
     81  </formalpara> 
     82 
     83  <formalpara> 
     84   <title><classname>Jaws_StaticConfig_Export</classname></title> 
     85   Abstract class used by configuration exportation drivers. 
     86  </formalpara> 
     87 </sect2> 
     88  
     89 <sect2> 
     90  &reftitle.internals; 
     91  <sect3> 
     92   <title>Parent class</title> 
     93   <para> 
     94    <classname>Jaws_StaticConfig</classname>'s parent class is  
     95    <classname>Jaws_Accessible</classname>. This greatly facilitates many tasks 
     96    like data access and hierarchical data handling, which gives us the  
     97    possibility to access configuration options using a cascade syntax like 
     98    <literal>Jaws::$Cnf->section->subsection->option</literal>. 
     99   </para> 
     100  </sect3> 
     101   
     102  <sect3> 
     103   <title>File configuration format</title> 
     104   <para> 
     105    Internally, static configuration files are stored in a serialized array.  
     106    The main advantage in using a serialized array is that it loads faster than 
     107    a standard array. However, the main disadvantage is that the configuration 
     108    file is not human readable and editable. To help with this task, an 
     109    importation and an exportation interface was created. You can also find 
     110    a tool to edit the configuration file directly under the  
     111    <filename>tools</filename> directory in the distribution. 
     112   </para> 
     113  </sect3> 
     114   
     115  <sect3> 
     116   <title>Option and subsection names encoding</title> 
     117   <para> 
     118    Internally, the option and subsection names are stored as <type>binary</type> 
     119    variables. This is to avoid any sort of complications if Unicode semantics 
     120    are turned on or off. You should not have any problems using Unicode 
     121    characters for option and subsections names but it is not recommended. 
     122   </para> 
     123  </sect3> 
     124 </sect2> 
     125 
     126 <sect2> 
     127  <title>Configuration file</title> 
     128  <para> 
     129   The default configuration file is <filename>cnf/config.php</filename>. When 
     130   <classname>Jaws_StaticConfig</classname> is initiated as a subsystem, this 
     131   configuration file is automatically loaded. 
     132  </para> 
     133    
     134  <sect3> 
     135   <title>Loading a different configuration file</title> 
     136   
     137   <para> 
     138    It is possible to load a different configuration file. To do this, you have 
     139    to use the following method. 
     140   </para> 
     141     
     142   <para> 
     143    <methodsynopsis> 
     144     <type>void</type><methodname>Jaws_StaticConfig::load</methodname> 
     145     <methodparam><type>string</type><parameter>$file</parameter></methodparam> 
     146     <methodparam choice="opt"><type>boolean</type><parameter>$force</parameter></methodparam> 
     147    </methodsynopsis> 
     148   </para> 
     149      
     150   <para> 
     151    <variablelist> 
     152     <varlistentry> 
     153      <term><parameter>$file</parameter></term> 
     154      <listitem>Path to the configuration file to load</listitem> 
     155     </varlistentry> 
     156 
     157     <varlistentry> 
     158      <term><parameter>$force</parameter></term> 
     159      <listitem> 
     160       Force the loading to occur even if a previous configuration file was  
     161       loaded 
     162      </listitem> 
     163     </varlistentry> 
     164    </variablelist> 
     165   </para>    
     166  </sect3> 
     167 </sect2> 
     168  
     169 <sect2> 
     170  <title>Creating a subsection</title> 
     171   
     172  <para> 
     173   As <classname>Jaws_StaticConfig</classname> implements the  
     174   <classname>Jaws_Accessible</classname> object, subsections can be easily  
     175   handled in the configuration file. To create a subsection, you need to use 
     176   the <methodname>Jaws_StaticConfig::createSubsection</methodname> method. 
     177   It takes one argument, <varname>$name</varname>, which is the name of the 
     178   new subsection to create. 
     179  </para> 
     180 </sect2> 
     181  
     182 <sect2> 
     183  <title>Read and write in a static configuration file</title> 
     184    
     185  <para> 
     186   The data in a static configuration file is separated into hierarchical  
     187   sections, which can be accessed with a cascade syntax once the file is loaded. 
     188   &refexp.ie;, to access the option called <literal>bar</literal> in the  
     189   subsection <literal>foo</literal> in the section <literal>jaws</literal>, the 
     190   following syntax is allowed: 
     191  </para> 
     192 
     193  <para> 
     194   <example> 
     195    <programlisting role="php">     
     196<![CDATA[ 
     197Jaws::$Cnf->jaws->foo->bar = 1223; 
     198echo Jaws::$Cnf->jaws->foo->bar; 
     199]]> 
     200    </programlisting> 
     201   </example> 
     202  </para> 
     203   
     204  <para> 
     205   If the <literal>bar</literal> option does not exist, it will be created. On 
     206   the other hand, the <literal>jaws</literal> and the <literal>foo</literal> 
     207   subsections need to be created explicitly. 
     208  </para> 
     209   
     210  <para> 
     211   You can also use the <methodname>Jaws_Accessible::get</methodname> and  
     212   <methodname>Jaws_Accessible::set</methodname> methods to read and write 
     213   configuration options. 
     214  </para> 
     215 </sect2> 
     216  
     217 <sect2> 
     218  <title>Delete an option or a subsection</title> 
     219   
     220  <para> 
     221   To delete an option or a subsection, you need to use the  
     222   <methodname>Jaws_StaticConfig::delete</methodname> method, inherited from 
     223   <classname>Jaws_Accessible</classname>. It takes a single argument,  
     224   <varname>$name</varname>, which is the name of the option or the subsection 
     225   to suppress. 
     226  </para> 
     227 </sect2> 
     228  
     229 <sect2> 
     230  <title>Configuration options verification</title> 
     231 </sect2> 
     232  
     233 <sect2> 
     234  <title>Importing and exporting configuration files</title> 
     235 </sect2> 
    9236</sect1>