Changeset 1902

Show
Ignore:
Timestamp:
05/06/2007 11:17:37 PM (20 months ago)
Author:
wei
Message:

Update Active Record docs.

Location:
trunk
Files:
1 added
32 modified

Legend:

Unmodified
Added
Removed

  • trunk/UPGRADE

    r1892 r1902  
    1818- Comment tag <!-- ... ---> (introduced in v3.1a) is changed to <!--- ... ---> 
    1919- When TDataList.RepeatLayout is Raw, the items will render <div> instead of <span> 
     20 
    2021- TActiveRecord finder methods will always return a new object instance (identity mapping was removed). 
     22- TActiveRecord::findBySql() will return an object rather than an array 
     23- TActiveRecord::findAllBySql() will return an array of objects. 
    2124 
    2225Upgrading from v3.1a 

  • trunk/build.xml

    r1901 r1902  
    1515<!--  <taskdef name="prado-test" classname="PradoTestTask" classpath="buildscripts/phing/tasks"/>--> 
    1616  <taskdef name="compact-package" classname="PradoPackageTask" classpath="buildscripts/phing/tasks"/> 
     17  <taskdef name="prado-quickstart-docs" classname="PradoQuickStartDocs" classpath="buildscripts/phing/tasks" /> 
    1718 
    1819  <!-- generates ${prado.version} and ${prado.revision} --> 
    … …  
    151152  </target> 
    152153 
     154   
    153155<!-- bulid compact prado package definitions --> 
    154156 
    155157  <target name="compact-collections" description="Collections"> 
    156158    <mkdir dir="${build.compact.dir}" /> 
     159        <mkdir dir="${build.compact.dir}/docs" /> 
    157160    <compact-package output="${build.compact.dir}/collections.php" strip="${compact-strip-comments}"> 
    158161      <filelist dir="framework" files="PradoBase.php,TComponent.php,Exceptions/TException.php,interfaces.php" /> 
    … …  
    164167    <copy file="HISTORY" tofile="${build.compact.dir}/HISTORY" /> 
    165168    <delete file="${build.compact.dir}/readme.txt" /> 
    166     <append text="PRADO Framework for PHP 5, version ${prado.version}. See http://www.pradosoft.com/ for Documentation." 
     169    <append text="PRADO Framework for PHP 5, version ${prado.version}. See docs/ directory for documentation." 
    167170      destFile="${build.compact.dir}/readme.txt" /> 
     171 
     172        <prado-quickstart-docs output="${build.compact.dir}/docs"  
     173                pages="Advanced/Collections.page,Fundamentals/Components.page"/>   
    168174  </target> 
    169175 
    … …  
    175181        files="TDbTableInfo.php, TDbTableColumn.php, TDbCommandBuilder.php, TDbMetaData.php" /> 
    176182    </compact-package> 
     183        <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/DAO.page" /> 
    177184  </target> 
    178185 
    … …  
    224231    <append file="framework/Data/ActiveRecord/Exceptions/messages.txt" 
    225232      destfile="${build.compact.dir}/messages.txt" /> 
     233        <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/ActiveRecord.page" /> 
    226234  </target> 
    227235 
    … …  
    238246    <append file="framework/Data/SqlMap/DataMapper/messages.txt" 
    239247      destfile="${build.compact.dir}/messages.txt" /> 
     248        <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/SqlMap.page" /> 
    240249  </target> 
    241250 

  • trunk/buildscripts/chmbuilder/ChmQuickstartBuilder.php

    r1826 r1902  
    1414        { 
    1515                $this->base = $base; 
    16                 $this->output_dir = $output.'/quickstart'; 
    17  
    18                 if(!is_dir($this->output_dir)) 
    19                 { 
    20                         mkdir($this->output_dir); 
    21                         mkdir($this->output_dir.'/assets/'); 
     16                $this->output_dir = $output; 
     17 
     18                if(!is_dir($this->output_dir) || !is_dir($this->output_dir.'/assets')) 
     19                { 
     20                        @mkdir($this->output_dir); 
     21                        @mkdir($this->output_dir.'/assets/'); 
    2222                        copy(dirname(__FILE__).'/chm_style.css', $this->output_dir.'/assets/chm_style.css'); 
    2323                } 
    … …  
    5959        } 
    6060 
    61         protected function getApplicationContent() 
     61        public function getApplicationContent() 
    6262        { 
    6363                ob_start(); 
    … …  
    6969        } 
    7070 
    71         protected function parseHtmlContent($content) 
     71        public function parseHtmlContent($content) 
    7272        { 
    7373                $html = preg_replace('/<input.*name="PRADO_PAGESTATE" [^>]+\/>/m', '', $content); 
    … …  
    9090                $html = str_replace('http://www.pradosoft.com/docs/manual', '../manual/CHMdefaultConverter', $html); 
    9191                $html = str_replace('target="_blank">View Source', '>View Source', $html); 
     92                $html = preg_replace('/action="[^"]+"/', '', $html); 
     93                $html = preg_replace('/<script[^>]+><\/script>/', '', $html); //remove js 
     94                $html = preg_replace('/href="C:[^"]+"/', 'href="#"', $html); 
     95 
    9296                $html = preg_replace_callback('/href="\?page=ViewSource&(amp;){0,1}path=([a-zA-z0-9\.\/]+)"/', 
    9397                        array($this, 'update_source_url'), $html); 

  • trunk/buildscripts/chmbuilder/build.php

    r1620 r1902  
    5454 
    5555 
    56         $quickstart= new ChmQuickstartBuilder($base,$output_dir); 
     56        $quickstart= new ChmQuickstartBuilder($base,$output_dir.'/quickstart'); 
    5757        $quickstart->buildDoc($pages); 
    5858 

  • trunk/buildscripts/chmbuilder/chm_style.css

    r1464 r1902  
    628628        color: red; 
    629629} 
     630 
     631div.last-modified 
     632{ 
     633        font-size: 0.8em; 
     634        color: #999; 
     635        margin-top: 5em; 
     636        margin-bottom: -3em; 
     637} 
     638 
     639p.since-version, p.requires-version 
     640{ 
     641        display: none; 
     642} 
     643 
     644div.languages 
     645{ 
     646        display: none; 
     647} 

  • trunk/buildscripts/texbuilder/Page2Tex.php

    r1653 r1902  
    175175                //text modifiers 
    176176                $html = preg_replace('/<(b|strong)[^>]*>([^<]*)<\/(b|strong)>/', '\textbf{$2}', $html); 
    177                 $html = preg_replace('/<i[^>]*>([^<]*)+?<\/i>/', '\emph{$1}', $html); 
     177                $html = preg_replace('/<i [^>]*>([^<]*)+?<\/i>/', '\emph{$1}', $html); 
    178178                $html = preg_replace_callback('/<tt>([^<]*)<\/tt>/', array($this,'texttt'), $html); 
    179179 
    … …  
    214214                $html = preg_replace('/<div class="last-modified">((.|\n)*?)<\/div>/', '', $html); 
    215215 
     216                //since 
     217                $html = preg_replace('/<com:SinceVersion[^>]+>/', '', $html); 
    216218 
    217219                $html = html_entity_decode($html); 

  • trunk/buildscripts/texbuilder/quickstart/build.php

    r1618 r1902  
    4343                $content .= $parser->get_section_label($section); 
    4444                $file_content = file_get_contents($page); 
    45                 $tex = 
     45                //$tex = 
    4646                $content .= $parser->parse_html($page,$file_content); 
    4747        } 

  • trunk/demos/quickstart/protected/pages/Advanced/Performance.page

    r1695 r1902  
    3434</p> 
    3535 
    36 <p> 
     36<p id="840059" class="block-content"> 
    3737Since v3.1.0, a new control called <a href="?page=Controls.OutputCache">TOutputCache</a> has been introduced. This control allows users to selectively cache parts of a page's output. When used appropriately, this technique can significant improve pages' performance because the underlying controls are not created at all if the cached versions are hit. 
    3838</p> 

  • trunk/demos/quickstart/protected/pages/Advanced/Scripts3.page

    r1846 r1902  
    22<h1 id="6801">Javascript in PRADO, Questions and Answers</h1> 
    33<h2 id="6802">How do I include the Javascript libraries distributed with Prado?</h2> 
    4 <p>The javascript libraries distributed with Prado can be found in the 
     4<p id="880060" class="block-content">The javascript libraries distributed with Prado can be found in the 
    55<tt>framework/Web/Javascripts/source</tt> directory. The <tt>packages.php</tt> 
    66file in that directory defines a list of available package names available 
    … …  
    3737        your custom Javascript code to the page.</p> 
    3838 
    39 <h2>Publishing Javascript Libraries as Assets</h2> 
     39<h2 id="176028">Publishing Javascript Libraries as Assets</h2> 
    4040<com:SinceVersion Version="3.1b" /> 
    4141<p class="block-content">Use <a href="?page=Controls.ClientScriptLoader">TClientScriptLoader</a> to publish and combine multiple existing javascript files (e.g. javascript libraries distributed with Prado or otherwise) 

  • trunk/demos/quickstart/protected/pages/Configurations/Templates1.page

    r1865 r1902  
    4242&lt;/prop:PropertyName&gt; 
    4343</com:TTextHighlighter> 
    44 <p> 
     44<p id="200007" class="block-content"> 
    4545Since version 3.1.0, the property initialization tag can also be used to initialize a set of subproperties who share the same parent property. For example, the following is equivalent to <tt>HeaderStyle.BackColor="black"</tt> and <tt>HeaderStyle.ForeColor="red"</tt>. 
    4646</p> 

  • trunk/demos/quickstart/protected/pages/Controls/Validation.page

    r1866 r1902  
    3232</ul> 
    3333 
    34 <h1>Prado Validation Controls</h1> 
     34<h1 id="116008">Prado Validation Controls</h1> 
    3535<a name="TRequiredFieldValidator"></a> 
    3636<h2 id="4902">TRequiredFieldValidator</h2> 
    … …  
    161161 
    162162<h1 id="123123">Interacting the Validators</h1> 
    163 <h2>Resetting or Clearing of Validators</h2> 
     163<h2 id="116009">Resetting or Clearing of Validators</h2> 
    164164<p id="1212323"> 
    165165Validators can be reset on the client-side using javascript by calling the 

  • trunk/demos/quickstart/protected/pages/Database/ActiveRecord.page

    r1899 r1902  
    44<com:SinceVersion Version="3.1a" /> 
    55<p id="690478" class="block-content">Active Records are objects that wrap a row in a database table or view, 
    6     encapsulates the database access and adds domain logic on that data. 
    7     The basics of an Active Record is a business object class, e.g., a  
     6    encapsulate the database access and add domain logic on that data. 
     7    The basics of an Active Record are business classes, e.g., a  
    88    <tt>Products</tt> class,  that match very closely the record structure 
    99    of an underlying database table. Each Active Record will be responsible for 
    1010    saving and loading data to and from the database. </p> 
    1111<div class="info"><b class="note">Info:</b> 
    12     The data structure of an Active Record should  match exactly that of a table  
     12    The data structure of an Active Record should  match that of a table  
    1313    in the database. 
    14     Each field in the class must correspond to one column in the table. 
     14    Each column of a table should have a corresponding member variable or property in the 
     15    Active Record class the represents the table. 
    1516</div> 
    1617 
    … …  
    3334        Prado provides a complimentary choice between Active Record and  
    3435        <a href="?page=Database.SqlMap">SqlMap Data Mapper</a>.  
    35         A SqlMap Data Mapper can be used to load Active Record objects, in turn, these 
     36        A SqlMap Data Mapper can be used to load Active Record objects, in turn; these 
    3637        Active Record objects can be used to update the database.  
    3738        The "relationship" between Active Records and <a href="?page=Database.SqlMap">SqlMap</a> is illustrated in the 
    … …  
    4243     
    4344    <p id="690482" class="block-content"> 
    44         The Active Record class has methods that do the following: 
     45        The Active Record class has functionality to perform the following tasks. 
    4546    </p> 
    4647    <ul id="u1" class="block-content"> 
    47         <li>Construct an instance of the Active Record from a SQL result set row.</li> 
    48         <li>Construct a new instance for later insertion into the table.</li> 
     48        <li>Create, Retrieve, Update and Delete records.</li> 
    4949        <li>Finder methods to wrap commonly used SQL queries and return Active Record objects.</li> 
    50         <li>Update existing records and insert new records into the database.</li> 
     50        <li>Fetch relationships (related foreign objects) such as "has many", "has one", "belongs to" and "has many" via association table.</li> 
     51        <li>Lazy loading of relationships.</li> 
    5152    </ul> 
    52 <h2>Database Supported</h2> 
     53<h2 id="142010">Database Supported</h2> 
    5354<p id="p1" class="block-content"> 
    5455The Active Record implementation utilizes the <a href="?page=Database.DAO">Prado DAO</a> classes for data access.    
    … …  
    6162    <li><a href="#">MS SQL 2000 or later</a></li> 
    6263</ul> 
    63 <p>Support for other databases can be provided when there are sufficient demand.</p> 
     64<p id="710009" class="block-content">Support for other databases can be provided when there are sufficient demands.</p> 
    6465 
    6566<h1 id="138048">Defining an Active Record</h1> 
    6667<p id="690483" class="block-content">Let us 
    67     consider the following "users" table that contains two columns named "username" and "email",  
    68     where "username" is also the primary key.  
     68    consider the following "<tt>users</tt>" table that contains two columns named "<tt>username</tt>" and "<tt>email</tt>",  
     69    where "<tt>username</tt>" is also the primary key.  
    6970<com:TTextHighlighter Language="sql" CssClass="source block-content" id="code_690147"> 
    7071CREATE TABLE users 
    … …  
    7677</com:TTextHighlighter> 
    7778</p> 
    78 <p id="690484" class="block-content">Next we define our Active Record class that corresponds to the "users" table. 
     79<p id="690484" class="block-content">Next we define our Active Record class that corresponds to the "<tt>users</tt>" table. 
    7980<com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690148"> 
    8081class UserRecord extends TActiveRecord 
    … …  
    9596</com:TTextHighlighter> 
    9697</p> 
    97 <p id="690485" class="block-content">Each property of the <tt>UserRecord</tt> class must correspond to a 
    98     column with the same name in the "users" table. The class constant 
     98<p id="690485" class="block-content">Each column of the "<tt>users</tt>" table must have corresponding  
     99    property of the same name as the column name in the <tt>UserRecord</tt> class. 
     100    Of course, you also define additional member variables or properties that does not exist in the table structure. 
     101    The class constant 
    99102    <tt>TABLE</tt> is optional when the class name is the same as 
    100103    the table name in the database, otherwise <tt>TABLE</tt> must 
    … …  
    124127} 
    125128</com:TTextHighlighter> 
     129<p id="710010" class="block-content">More details regarding TComponent can be found in the <a href="?page=Fundamentals.Components">Components documentation</a>. 
     130Later we shall use the getter/setters to allow for lazy loading of relationship objects. 
     131</p> 
    126132 
    127133<div class="info"><b class="note">Info:</b> 
    … …  
    135141    The static method <tt>finder()</tt> returns an <tt>UserRecord</tt> instance 
    136142    that can be used to load records from the database. The loading of records 
    137     using the finer methods is discuss a little later. The <tt>TActiveRecord::finder()</tt> 
    138     static method takes the name of the current Active Record class as parameter. 
     143    using the finer methods is discussed a little later. The <tt>TActiveRecord::finder()</tt> 
     144    static method takes the name of an Active Record class as parameter. 
    139145</p> 
    140146 
    … …  
    143149    A default database connection for Active Record can be set as follows. 
    144150    See <a href="?page=Database.DAO">Establishing Database Connection</a> for 
    145     futher details regarding creation of database connection in general. 
     151    further details regarding creation of database connection in general. 
     152</p> 
    146153<com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690150"> 
    147154//create a connection and give it to the Active Record manager. 
    … …  
    150157TActiveRecordManager::getInstance()->setDbConnection($conn); 
    151158</com:TTextHighlighter>  
    152 </p> 
    153  
     159 
     160<p id="710011" class="block-content">Alternatively, you can create a base class and override the <tt>getDbConnection()</tt> 
     161method to return a database connection. This is a simple way to permit multiple 
     162connections and multiple databases. The following code demonstrates defining  
     163the database connection in a base class (not need to set the DB connection anywhere else). 
     164</p> 
     165<com:TTextHighlighter Language="php" CssClass="source block-content"> 
     166class MyDb1Record extends TActiveRecord 
     167{ 
     168    public function getDbConnection() 
     169    { 
     170        static $conn; 
     171        if($conn===null) 
     172            $conn = new TDbConnection('xxx','yyy','zzz'); 
     173        return $conn; 
     174    } 
     175} 
     176class MyDb2Record extends TActiveRecord 
     177{ 
     178    public function getDbConnection() 
     179    { 
     180        static $conn; 
     181        if($conn===null) 
     182            $conn = new TDbConnection('aaa','bbb','ccc'); 
     183        return $conn; 
     184    } 
     185} 
     186</com:TTextHighlighter>  
     187 
     188 
     189<h3 class="prado-specific">Using <tt>application.xml</tt> within the Prado Framework</h3> 
     190<div class="prado-specific"> 
    154191<p id="690488" class="block-content"> 
    155192    The default database connection can also be configured using a <tt>&lt;module&gt;</tt> 
    … …  
    168205    meta data, that is, the table columns names, indexes and constraints are 
    169206    saved in the cache and reused. You must clear or disable the cache if you 
    170     wish to see chanages made to your table definitions. A <a href="?page=Advanced.Performance#6402">cache 
     207    wish to see changes made to your table definitions. A <a href="?page=Advanced.Performance#6402">cache 
    171208    module</a> must also be defined for the cache to function. 
    172209</div> 
    … …  
    191228</com:TTextHighlighter>      
    192229</p> 
     230</div> 
    193231 
    194232<h2 id="138050">Loading data from the database</h2> 
    195233<p id="690490" class="block-content"> 
    196234    The <tt>TActiveRecord</tt> class provides many convenient methods to find 
    197     records from the database. The simplest is finding records by matching primary keys. 
     235    records from the database. The simplest is finding one record by matching a primary key or a  
     236    composite key (primary keys that consists of multiple columns). 
    198237    See the <com:DocLink ClassPath="System.Data.ActiveRecord.TActiveRecord" /> for 
    199238    more details. 
    200239</p> 
    201     <h3 id="138055"><tt>findByPk()</tt></h3> 
    202     <p id="690491" class="block-content">Finds one record using only the primary key or composite primary keys. 
     240 
     241<div class="info"><b class="note">Info:</b> 
     242All finder methods that may return 1 record only will return <tt>null</tt> if no matching data 
     243is found. All finder methods that return an array of records will return an empty array if no 
     244matching data is found. 
     245</div> 
     246 
     247        <h3 id="138055"><tt>findByPk()</tt></h3> 
     248    <p id="690491" class="block-content">Finds one record using only a primary key or a composite key. 
    203249<com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690153"> 
    204250$finder = UserRecord::finder(); 
    205251$user = $finder->findByPk($primaryKey); 
    206252 
    207 //when the table uses composite keys 
     253//when the table uses a composite key 
    208254$record = $finder->findByPk($key1, $key2, ...); 
    209255$record = $finder->findByPk(array($key1, $key2,...)); 
    … …  
    212258 
    213259    <h3 id="138056"><tt>findAllByPks()</tt></h3> 
    214     <p id="690492" class="block-content">Finds multiple records using a list of primary keys or composite primary keys. 
    215 The following are equivalent for scalar primary keys (primary key consisting of only one column/field). 
     260    <p id="690492" class="block-content">Finds multiple records using a list of primary keys or composite keys. 
     261The following are equivalent for primary keys (primary key consisting of only one column/field). 
     262</p> 
    216263<com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690154"> 
    217264$finder = UserRecord::finder(); 
    218 $users = $finder->findAllByPk($key1, $key2, ...); 
    219 $users = $finder->findAllByPk(array($key1, $key2, ...)); 
     265$users = $finder->findAllByPks($key1, $key2, ...); 
     266$users = $finder->findAllByPks(array($key1, $key2, ...)); 
    220267</com:TTextHighlighter> 
    221268The following are equivalent for composite keys. 
    … …  
    226273$keys = array(  array($key1, $key2), array($key3, $key4), ... ); 
    227274$record = $finder->findAllByPks($keys); 
    228  
    229 </com:TTextHighlighter> 
    230 </p> 
     275</com:TTextHighlighter> 
    231276 
    232277 
    … …  
    271316</com:TTextHighlighter> 
    272317 
     318<div class="note"><b class="note">Note:</b> 
     319For MSSQL and when <tt>Limit</tt> and <tt>Offset</tt> are positive integer values. The  
     320actual query to be executed is modified by the  
     321<com:DocLink ClassPath="System.Data.ActiveRecord.Common.Mssql.TMssqlCommandBuilder"  
     322Text="TMssqlCommandBuilder" 
     323/> 
     324class according to  
     325<a href="http://troels.arvin.dk/db/rdbms/#select-limit-offset">http://troels.arvin.dk/db/rdbms/</a> 
     326to emulate the <tt>Limit</tt> and <tt>Offset</tt> conditions. 
     327</div> 
     328 
    273329<h3 id="138058"><tt>findAll()</tt></h3> 
    274330<p id="690495" class="block-content">Same as <tt>find()</tt> but returns an array of objects.</p> 
    275331 
    276332<h3 id="138059"><tt>findBy*()</tt> and <tt>findAllBy*()</tt></h3> 
    277 <p id="690496" class="block-content">Dynamic find method using parts of method name as search criteria. 
    278 Method names starting with <tt>findBy</tt> return 1 record only. 
    279 Method names starting with <tt>findAllBy</tt> return an array of records. 
     333<p id="690496" class="block-content">Dynamic find method using parts of the method name as search criteria. 
     334Method names starting with <tt>findBy</tt> return 1 record only 
     335and method names starting with <tt>findAllBy</tt> return an array of records. 
    280336The condition is taken as part of the method name after <tt>findBy</tt> or <tt>findAllBy</tt>. 
    281337 
    … …  
    299355     
    300356<div class="tip"><b class="note">Tip:</b> 
    301 You may also use <tt>OR</tt> as a condition in the dynamic methods. 
     357You may also use a combination of <tt>AND</tt> and <tt>OR</tt> as a condition in the dynamic methods. 
    302358</div> 
    303359     
    304 <h3 id="138060"><tt>findBySql()</tt></h3> 
    305 <p id="690497" class="block-content">Finds records using full SQL, returns corresponding array of record objects.</p> 
    306  
     360<h3 id="138060"><tt>findBySql()</tt> and <tt>findAllBySql()</tt></h3> 
     361<p id="690497" class="block-content">Finds records using full SQL where <tt>findBySql()</tt> 
     362return an Active Record and <tt>findAllBySql()</tt>returns an array of record objects. 
     363For each column returned, the corresponding Active Record class must define a member variable or 
     364property for each corresponding column name. 
     365<com:TTextHighlighter Language="php" CssClass="source block-content"> 
     366class UserRecord2 extends UserRecord 
     367{ 
     368    public $another_value; 
     369} 
     370$sql = "SELECT users.*, 'hello' as another_value FROM users"; 
     371$users = TActiveRecord::finder('UserRecord2')->findAllBySql($sql); 
     372</com:TTextHighlighter> 
     373</p> 
    307374<h3 id="138061"><tt>count()</tt></h3> 
    308 <p id="690498" class="block-content">Find the number of matchings records.</p> 
     375<p id="690498" class="block-content">Find the number of matchings records, accepts same parameters as the <tt>findAll()</tt> method.</p> 
    309376 
    310377<h2 id="138051">Inserting and updating records</h2> 
    … …  
    328395For example, if you insert a new record into a MySQL table that has columns 
    329396defined with "autoincrement", the Active Record objects will be updated with the new  
    330 incremented values.</div> 
     397incremented value.</div> 
    331398 
    332399<p id="690500" class="block-content"> 
    … …  
    342409</p> 
    343410 
    344 <p> 
     411<p id="710012" class="block-content"> 
    345412Active Record objects have a simple life-cycle illustrated in the following diagram.