Browse files

Updated LICENSE and README files

  • Loading branch information...
1 parent 7456d8f commit 05d4d31b533c49b430f4b15752bcbcabde019362 @shadowhand shadowhand committed Aug 15, 2009
Showing with 266 additions and 1 deletion.
  1. +19 −0 LICENSE.md
  2. +247 −1 README.md
View
19 LICENSE.md
@@ -0,0 +1,19 @@
+Copyright (c) 2009 Woody Gilk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
View
248 README.md
@@ -1 +1,247 @@
-Sprig data modeling system
+# Sprig
+
+A database modeling system for the [Kohana framework](http://kohanaphp.com/) (v3.0+).
+
+## Quick Start
+
+Each model must:
+
+* extend the `Sprig` class
+* define the database table name
+* define a public `init()` method and set the field mappings
+
+Example of a model:
+
+ class Model_Post extends Sprig {
+
+ protected $_table = 'blog_posts';
+
+ public function init()
+ {
+ $this->_fields += array(
+ 'id' => new Sprig_Field_Auto,
+ 'title' => new Sprig_Field_Char,
+ 'blog' => new Sprig_Field_ForeignKey(array(
+ 'model' => 'Blog',
+ )),
+ 'author' => new Sprig_Field_ForeignKey(array(
+ 'model' => 'User',
+ )),
+ 'body' => new Sprig_Field_Text,
+ 'published' => new Sprig_Field_Boolean,
+ );
+
+ parent::init();
+ }
+
+ }
+
+## Interacting with models
+
+Loading models is done with the `Sprig::factory($name)` method:
+
+ $post = Sprig::factory('post');
+
+### Data
+
+Model data is read using object properties:
+
+ $title = $post->title;
+ $body = $post->body;
+
+Model data is changed the same way:
+
+ $post->title = 'A New Title';
+
+You can also use the `values()` method set many fields using an associative array:
+
+ $post->values(array(
+ 'title' => 'A New Title',
+ ));
+
+### Create, Read, Update, and Delete (CRUD)
+
+Reading records is done by setting the search values, then calling the `load()` method:
+
+ $post = Sprig::factory('post');
+ $post->id = 5;
+ $post->load();
+
+ if ($post->loaded())
+ {
+ // Do something with the post
+ }
+
+It is also possible to pre-populate the model using an array of values:
+
+ $post = Sprig::factory('post', array('id' => 10))
+ ->load();
+
+Creating new records is done using the `create()` method:
+
+ $post = Sprig::factory('post', array(
+ 'title' => 'My First Blog Post',
+ 'body' => 'Created using a Sprig model!',
+ 'published' => FALSE,
+ ));
+
+ // Create a new blog post
+ $post->create();
+
+If the model data does not satisfy the validation requirements, a `Validate_Exception` will be thrown. This exception should be caught and used to show the end user the error messages:
+
+ try
+ {
+ // Create a new blog post
+ $post->create();
+ }
+ catch (Validate_Exception $e)
+ {
+ // Get the errors using the Validate::errors() method
+ $errors = $e->array->errors('blog/post');
+ }
+
+Updating a record is done using the `update()` method:
+
+ $post->values($_POST);
+
+ try
+ {
+ $post->update();
+ }
+ catch (Validate_Exception $e)
+ {
+ $errors = $e->array->errors('blog/post');
+ }
+
+Deleting a record is done using the `delete()` method:
+
+ $post->delete();
+
+## Forms
+
+It is possible to generate a complete form very quickly using the `inputs()` method:
+
+ <dl>
+ <?php foreach ($post->inputs() as $label => $input): ?>
+ <dt><?php echo $label ?></dt>
+ <dd><?php echo $input ?></dd>
+
+ <?php endforeach ?>
+ </dl>
+
+Each input will be populated with the current value of the field.
+
+If you need the field name as the `inputs()` key instead of the label, use `FALSE`:
+
+ $inputs = $post->inputs(FALSE);
+
+ echo $inputs['title'];
+
+## Field Object Reference
+
+Accessing a field object is done using the `field()` method:
+
+ $title = $post->field('title');
+
+An array of fields can be accessed using the `fields()` method:
+
+ $fields = $post->fields();
+
+### Types of fields
+
+Sprig offers most database column types as classes. Each field must extend the `Sprig_Field` class. Each field has the following properties:
+
+empty
+: Allow `empty()` values to be used. Default is `FALSE`.
+
+primary
+: A primary key field. Multiple primary keys (composite key) can be specified. Default is `FALSE`.
+
+unique
+: This field must have a unique value within the model table. Default is `FALSE`.
+
+null
+: Convert all `empty()` values to `NULL`. Default is `FALSE`.
+
+editable
+: Show the field in forms. Default is `TRUE`.
+
+default
+: Default value for this field. Default is `''` (an empty string).
+
+choices
+: Limit the value of this field to an array of choices. This will change the form input into a select list. No default value.
+
+column
+: Database column name for this field. Default will be the same as the field name,
+ except for foreign keys, which will use the field name with `_id` appended.
+
+label
+: Human readable label. Default will be the field name converted with `Inflector::humanize()`.
+
+filters
+: Validate filters for this field.
+
+rules
+: Validate rules for this field.
+
+callbacks
+: Validate callbacks for this field.
+
+#### Sprig_Field_Auto
+
+An auto-incrementing (sequence) field.
+
+Implies `primary = TRUE` and `editable = FALSE`.
+
+#### Sprig_Field_Boolean
+
+A boolean (TRUE/FALSE) field, representing by a checkbox.
+
+Implies `empty = TRUE` and `default = FALSE`.
+
+#### Sprig_Field_Char
+
+A single line of text, represented by a text input.
+
+Also has the `min_length` and `max_length` properties.
+
+#### Sprig_Field_Float
+
+A float or decimal number, represented by a text input.
+
+Also has the `places` property.
+
+#### Sprig_Field_Integer
+
+An integer number, represented with a text input (or a select input, if the `choices` property is set).
+
+Also has the `min_value` and `max_value` properties.
+
+#### Sprig_Field_Text
+
+A large block of text, represented by a textarea.
+
+#### Sprig_Field_Enum
+
+Extends `Sprig_Field_Char`, but requires the `choices` property.
+
+#### Sprig_Field_Email
+
+Extends `Sprig_Field_Char`, but requires a valid email address as the value.
+
+#### Sprig_Field_Timestamp
+
+Extends `Sprig_Field_Integer`, but requires a valid UNIX timestamp as the value.
+
+Also has the `format` and `auto_now` properties.
+
+#### Sprig_Field_ForeignKey
+
+Extends `Sprig_Field_Integer`, but references another model. Represented by a select input.
+
+Also has the `model` property, the name of another Sprig model.
+
+Implies `choices` will be set the the result of `$model->select_list()`.
+

0 comments on commit 05d4d31

Please sign in to comment.