Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

184 lines (144 sloc) 9.762 kb
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
<html xmlns="" xml:lang="en" lang="en">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Read Me</title>
<link rel="stylesheet" href="templates/application.css" type="text/css" media="screen" charset="utf-8"/>
<style type="text/css" media="screen">
#PageDiv {
#logo {
position: absolute;
top: -6px;
right: 8px;
background: url(templates/images/logo.png) no-repeat top right;
width: 125px;
height: 100px;
<div id="PageDiv">
<h1 id="scaffold_generator_for_myactiverecord_and_myactionpack">Scaffold Generator for MyActiveRecord and MyActionPack</h1>
<p>This system creates a working database-backed application by reflecting over
your database and generating a set of folders and static PHP files containing
the basic CRUD operations for the selected tables.</p>
<p>This release lists stand-alone tables (not linking tables) and provides limited
support for parent/child relationships and many-to-many relationships. Each
model&#8217;s destroy method can clean up child and related records if you choose
that option in the generator form.</p>
<p>Version 0.5 - first public release.</p>
<h2 id="activerecord_and_myactiverecord">ActiveRecord and MyActiveRecord</h2>
<p>Active Record is a software design pattern popularized by Martin Fowler, and taken to its
logical conclusion in the Ruby on Rails framework. MyActiveRecord was written by Jake
Grimley in 2006, and has been extended and tended to by Walter Davis since 2009. Rather
than be a complete or perfect implementation of AR, MAR strives to be lightweight,
very fast, and deliberately limited. It is extremely easy to extend.</p>
<p>In order to achieve this simplicity, MAR requires that you follow these simple rules
when creating your models: </p>
<li>Each model class must have a database table named in the plural form of itself (except in
lower-case, for database portability). The class <strong>Person</strong> would have a database table named <code>people</code>.</li>
<li>Each model table must have an auto-incrementing integer field as its primary key, by default this is named <code>id</code>.</li>
<li>Relationships between models are expressed using specially-named &#8220;foreign key&#8221; fields
and join tables. (More about that below.)</li>
<h2 id="server_requirements">Server Requirements</h2>
<p>You will need a basic Apache server with the mod_rewrite engine installed and enabled,
and <code>AllowOverrides:all</code> set in the server&#8217;s configuration file, PHP 5.1 or better (preferably
installed as a DSO in Apache 2 or <code>mod_php</code> in Apache 1.3), and MySQL 4.1 or better (tested on 5.1).</p>
<p>You will need a MySQL user with the necessary privileges to
create new databases and/or tables.</p>
<p>The generated application uses PHP&#8217;s &#8220;short open tags&#8221; feature, which may be disabled on your
server. There is a configuration option in the <code>.htaccess</code> file which will attempt to turn
this on for you, but depending on your server&#8217;s basic configuration, you may need to make
this change in your <code>php.ini</code> file instead. See the <code>.htaccess</code> file for instructions.</p>
<h2 id="install_and_setup">Install and Setup</h2>
<p>To use, move the entire <code>generate</code> folder to a Web server, and check/change
permissions on the <code>generate/generated_code</code> sub-folder so that your Apache/PHP
process can write to that sub-folder.</p>
<p>Open the <code>scaffold.php</code> file with a text editor, and update the configuration
at the top of the file to match your server. These credentials will be copied
into the generated site, so you need to either run this on the same server as you
intend to use to serve the final project, or change the generated config file when you deploy. </p>
<p>Your site files will be generated (and re-generated) within a folder named
exactly the same as your database, within the <code>generated_code</code> directory.
So if you entered the following DSN for your database: <code>user:pass@localhost/test</code>
you would find a folder at <code>generated_code/test</code> containing all of your site
documents and and an <code>.htaccess</code> file after you generate from your first table.</p>
<p>For bonus points, set up your Web server to host a site from <code>generated_code/[dbname]</code>
so you can view your progress as you go. </p>
<p>Once you have finished the site generation process, you can move the <code>[dbname]</code>
folder anywhere you like on your Web server, and host your site from there.
Please note &#8212; the <code>.htaccess</code> and <code>_routing.php</code> files are configured to work in the
site root folder. You can change this, but by default, the site will only work
when run from a dedicated hostname, as opposed to a sub-folder.</p>
<h2 id="process_your_first_table">Process Your First Table</h2>
<p>Visit <a href="./scaffold.php">./scaffold.php</a> in a browser. You should see the names of
the tables in your database. Click on the first table you wish to work from
to begin. The system interprets the following field types when generating form inputs:</p>
<li>Varchar or Char or Int will become a text input</li>
<li>Tinyint(1) will become a boolean (checkbox)</li>
<li>Text will become a textarea</li>
<li>Date and DateTime columns will become a text input with a special HTML
classname for further processing with JavaScript</li>
<li>Any Date or DateTime column that ends in <code>_at</code> or <code>_on</code> will be treated as a special
timestamp. If the column is named <code>created_on</code> or <code>created_at</code>, or <code>updated_at</code> or
<code>updated_on</code>, it will have special setter functions in the Model&#8217;s <code>save()</code> method.</li>
<li>Any column that is named <code>[other table name in singular form]_id</code> will be treated as a foreign key from that table</li>
<li>Any table which has a foreign key in another table can choose to perform
cascading deletes in its <code>destroy()</code> method.</li>
<p>The <code>id</code> column is not editable, as it is always your primary key.</p>
<h3 id="validations">Validations</h3>
<p>The following validations are included:</p>
<li><code>validate_regexp()</code> Enter a regular expression, including delimiters, properly
escaped. The column must match this regexp in order to pass</li>
<li><code>validate_existence()</code> The field must not be empty to pass</li>
<li><code>validate_uniqueness_of()</code> The field must not match the same field in any
other records in the table (note &#8212; this does not include a test for empty,
combine with <code>validate_existence()</code> to also test for that)</li>
<li><code>validate_email()</code> This is a combo validator, which tests for presence and
<p>Mix and match the validations as you like.</p>
<h3 id="cascading_delete">Cascading Delete</h3>
<p>Dependent delete will be offered as an option if the table includes a field
named <code>[other table in singular form]_id</code>. If so, checking this option will include the
logic to clean up dependent records from that other table. For example, if
you delete a Blog Post, all of the Comments with a matching <code>post_id</code> will
be deleted at the same time. You don&#8217;t need to choose this if you don&#8217;t need it.</p>
<h2 id="generate_the_site">Generate the Site</h2>
<p>When you press the <strong>Generate</strong> button, all of your files will be created and
listed. Click the <strong>Start Over</strong> link to select another table and begin this
process again.</p>
<p>Once you have generated the files for a particular table, they will not be
overwritten unless you check the &#8220;Overwrite Existing Files&#8221; checkbox at the bottom of the screen.
If you make changes to your database (add, remove or change columns) you will
need to check this option to get a fresh set of interface files. I strongly recommend
that you place the <code>generated_code</code> folder in version
control so you can merge your edits or roll back any overwrites.</p>
<h2 id="install_the_site">Install the Site</h2>
<p>Move the generated folder <code>[table name]</code> into a new location in your Web server,
and update your Apache configuration files to serve your application from that new location.
The name of the containing folder is not important, and you can copy the contents of
the folder into your <code>htdocs</code> folder or local equivalent. Just be sure you copy the (hidden)
<code>.htaccess</code> file when you do.</p>
<p>You can edit any of the files, they are all static and do not rely on any
<em>magic</em> to work correctly. File <strong>naming</strong> is however very important. Just
as in Rails or its various clones, the location and name of files is used
to link up the various parts of the Model / View / Controller stack.</p>
<p>The content of the Model, View and Controller files is just a suggestion to
get you started. Feel free to add or delete methods to the controller, which
will be mapped automatically to matching URLs. <code>[model plural]/[controller method]/[id]</code>
is the basic idea. This strategy is set in the routing.php file, and can be
modified there.</p>
<div id="logo">
Jump to Line
Something went wrong with that request. Please try again.