#13 - making structure more consistent across behavior pages

behaviors/controller-behaviors.md

@@ -1,7 +1,25 @@
 
 ## Controller Behaviors
 
-The core Controller package does a great job with handling the standard Browse, Read, Edit, Add and Delete (BREAD) requests and the action of rendering of those requests. Each of those expose before and after command chains, and we use a number of behaviors out of the box to augment Controller functionality and interface.
+The Framework controller package does a great job with handling the standard `browse`, `read`, `edit`, `add` and `delete` (BREAD) requests and the action of rendering of results of those requests where there is one. Each of those actions are exposed to before and after command chains, and we use a number of behaviors out of the box to augment Controller functionality and interface.
+
+We are able to separate out specialized controller logic and compose them as needed.
+
+```php
+class ComAcmeControllerBar extends KControllerModel
+{
+
+    protected function _initialize(KObjectConfig $config)
+    {
+        $config->append(array(
+            'behaviors' => array('editable', 'persistable')
+        ));
+
+        parent::_initialize($config);
+    }
+
+}
+```
 
 + [Findable](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/components/com_koowa/controller/behavior/findable.php) - Special Joomla-centric behavior that handles updating the search index in Joomla when an entity is updated itself
 + [Cacheable](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/components/com_koowa/controller/behavior/cacheable.php) - Another Joomla-centric behavior to handle the caching of requests based on state and the invalidation of that cache when an entity changes.

behaviors/database-behaviors.md

@@ -1,26 +1,26 @@
 # Database Behaviors
 
-Utilizing database behaviors lets us create [Trigger](http://en.wikipedia.org/wiki/Database_trigger) like procedures in our applications, without having to store them with the database. They provide a means to contextually affect change both before and after `select`, `insert`, `update` and `delete` actions performed in the database layer.
+Utilizing database behaviors lets us create [Trigger](http://en.wikipedia.org/wiki/Database_trigger) like procedures in our applications, without having to store them with the database. They provide a means to contextually affect change both before and after `select`, `insert`, `update` and `delete` actions performed in the database layer, specifically in the KDatabaseTableAbstract.
 
-These are strategies, and because they are separated out we can use them in many other table objects. Each one extends from `KDatabaseBehaviorAbstract` and thus, `KMixinAbstract`. Because they are [mixins](/essentials/mixin.md) they add methods and functionality to the row level objects.
+Behaviors are strategies, and because they are separated out we can use them in many other table objects. Each one extends from `KDatabaseBehaviorAbstract` and thus, `KMixinAbstract`. Because they are [mixins](/essentials/mixin.md) they add methods and functionality to the row level objects (See getAuthor in the [Example](#example) below).
 
-You can build your own database behaviors in your own applications, or adjust the logic of current ones to better match your needs by simply extending them.
+You can build your own database behaviors in your own applications, or adjust the logic of currently ones to better match your needs by simply extending them.
 
-If you choose to build new behaviors, simply place them in the `/database/behavior/` folder of your component. To get some inspiration look at some of the [Examples](#examples) below.
+If you choose to build new behaviors, simply place them in the `/database/behavior/` folder of your component. To get some inspiration look at some of the [Example](#example) below.
 
-## Examples
+## Example
 
 One of the easiest examples to understand is the [`KDatabaseBehaviorCreatable`](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/libraries/database/behavior/creatable.php) database behavior. Its purpose is to simply make sure that when we insert a record into a table, it adds the creation date (`created_on`), and the user id number (`created_by`) of the logged in user.
 
-Additionally, the behavior provides a `getAuthor` method to the row object and which grabs the created_by of the object and returns a system level user object, so you don't have to.
+Additionally, the behavior provides a `getAuthor` method to the row object and which grabs the `created_by` of the object and returns a system level user object, so you don't have to for example, get the user id and then create the user object yourself.
 
 ### Benefits
 
-+ We never have to rewrite the code that makes sure that we record those values.
-+ There is no question: "Where do we write that code?" In the controller, model because we are defining these actions at the table level? Controller logic is cleaner.
++ We never have to re-write the code that makes sure that we record those values in another table.
++ There is no question: "Where do we write that code?" In the controller, model or table classes? We are defining these actions at the table level and the logic is cleaner for each of those structures is cleaner.
 + It helps promote standardization of column names across tables for this information. In the `creatable` behavior user id is always saved as `created_by` and the date is always stored in `created_on`.
 
-### The Complete List
+### The Complete List of Database Behaviors
 
 Let's list all of the framework level behaviors and give some background about each.
 

behaviors/model-behaviors.md

@@ -2,9 +2,10 @@
 
 The ability to separate out strategies for building queries and models states helps to simplify model code. It also provides a number of opportunities to affect the input and the output of a given model at runtime.
 
-Like all Nooku behaviors, Model behaviors get fired before and after each major action that a model perform, `fetch`, `create`, `count` and `reset`.
+Like all Nooku behaviors, Model behaviors get fired before and after each major action that a model performs: `fetch`, `create`, `count` and `reset`.
+
+Getting to know what the core framework behaviors do is part of the learning curve of using the Framework. The content of the Model `$_state` is coupled to the contents of a request coming down the chain from the dispatcher to the controller. The principal work of the model to take those values which are relevant to it, building queries based on them and then return that result. The model needs to explicitly identify values are relevant to it by `inserting` them into its state. By encapsulating all that work into different behaviors a model definition can become very short:
 
-Getting to know what the core framework behaviors do is part of the learning curve of using Nooku. The content of the Model `$_state` is coupled to the contents of a request coming down the chain from the dispatcher to the controller. The principal work of the model to take those values are relevant to it, building queries based on them and return that result. The model needs to explicitly identify values are relevant to it by `inserting` them into the state. By encapsulating all that work into different behaviors a model definition can become very short:
 
 ```php
 class ComAcmeModelBars extends KModelDatabase {
@@ -17,10 +18,21 @@ class ComAcmeModelBars extends KModelDatabase {
         parent::_initialize($config);
     }
 
-
 }
 ```
-That example has all of the Model behaviors that exist as part of the Framework and we describe them in brief below.
+That example has all of the model behaviors that exist as part of the Framework and we describe them in brief below.
+
+Each behavior extends from the `KModelBehaviorAbstract` class, which is a descendant of `KMixinAbstract`. That means `public` methods in the behavior class can be added to a model object's interface. For example, the above mentioned `ComAcmeModelBars` model gets a `getPaginator` method mixed into its interface. Calling that method on the model, i.e. $model->getPaginator() creates a `KModelPaginator` object with the appropriate state values and returns it. This is all because we have said the model has the `paginatable` behavior.
+
+## Example
+
+Let's look at at the `Indexable` behavior ([`KModelBehaviorIndexable`](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/libraries/model/behavior/indexable.php)) in some detail. In many cases its desireable to assign a unique identifier to a row in a table. To ensure that row is unique, those tables apply a `unique index` to a column of that table, and so each row must have a different value for that column.
+
+The `Indexable` behavior takes care of finding out what unique indexes you have defined in your schema and adds them to the model's state variable, stipulating that they are unique. Then, before you call either the `fetch` or `count` method, it takes care of injecting these unique state values into the `WHERE` clause of the query.
+
+This means that for every model that is `Indexable` in our application we don't have to worry about making sure that we've defined unique states in the model or even building queries based on those states, because it is automatic.
+
+## The Complete List of Model Behaviors
 
 + [Indexable](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/libraries/model/behavior/indexable.php#L16) Gets the index information from the associated table's schema and populates the state with those columns, and automatically builds the where part of the query based on those states.
 + [Sortable](https://github.com/nooku/nooku-framework/blob/master/code/libraries/koowa/libraries/model/behavior/sortable.php#L16) Adds `sort` and `direction` to the model's state and then builds the `ORDER BY` part of the query object based on those values if they exist.