release notes

CHANGELOG.md

@@ -1,16 +1,29 @@
 # 1.0.1
 
-This is our first maintenance release that solves several important
-issues.
-
-* Added support for automated model reloading after save(). 
-* Added documentation sections for Advanced Topics with tips and tricks
-  * how to implement [soft-delete](http://agile-data.readthedocs.io/en/develop/advanced.html#soft-delete), [audit](http://agile-data.readthedocs.io/en/develop/advanced.html#audit-fields)
-  * how to [override default method actions](http://agile-data.readthedocs.io/en/develop/model.html?highlight=hook#how-to-prevent-action), e.g. [delete()](shttp://agile-data.readthedocs.io/en/develop/advanced.html#soft-delete-that-overrides-default-delete)
-  * how to [verify updates](http://agile-data.readthedocs.io/en/develop/model.html?highlight=hook#how-to-verify-updates)
-  * how to create [fields with unique values](http://agile-data.readthedocs.io/en/develop/advanced.html#creating-unique-field)
-
-* Updated to latest version in dependencies
+This is our first maintenance release that solves several important issues.
+
+* Change: `$m->insert()` will return ID and not clone of `$m`. Cloning was causing some problems.
+* Change: calling ref() on object without active record will return you object without active record instead of exception
+* Change: `$m->ref()` into non-existant hasOne() relation then [saving it will update field inside $m](http://agile-data.readthedocs.io/en/develop/relations.html?highlight=contact_id#relations-with-new-records).
+* Added ability to call `save([$data])`, which will combine set() and save()
+* Added support for `$model->title_field`
+* Added [afterUnload and beforeUnload hooks](http://agile-data.readthedocs.io/en/develop/model.html#hooks).
+* Added support for [automated model reloading](http://agile-data.readthedocs.io/en/develop/expressions.html?highlight=reloading#model-reloading-after-save)
+* Added support for advanced patterns described here:
+  * ability to implement [soft-delete](http://agile-data.readthedocs.io/en/develop/advanced.html#soft-delete), [audit](http://agile-data.readthedocs.io/en/develop/advanced.html#audit-fields)
+  * support to [override default method actions](http://agile-data.readthedocs.io/en/develop/model.html?highlight=hook#how-to-prevent-action), e.g. [delete()](shttp://agile-data.readthedocs.io/en/develop/advanced.html#soft-delete-that-overrides-default-delete)
+  * support to [verify updates](http://agile-data.readthedocs.io/en/develop/model.html?highlight=hook#how-to-verify-updates) with afterInsertQuery
+  * ability to create [fields with unique values](http://agile-data.readthedocs.io/en/develop/advanced.html#creating-unique-field)
+* Added support for [Related Aliases](http://agile-data.readthedocs.io/en/develop/relations.html#relation-aliases). Now you can hasOne() hasMany() to itself.
+* Fix: when you update field from join and then immediatelly save()
+* Fix: when you join on existing field
+* Fix: update and delete no longer try to use join or aliases
+* Fix: setting different values twice wouldn't reset dirty status if you return to the original
+* Fix: dirty flags are still available for `afterSave()` method (so that you know which fields were saved)
+* Documented $m->withID();
+* Updated to latest version of DSQL
+
+Included PRs: #75, #74, #73, #72, #71, #70, #65, #63, #61, #58, #55
 
 # 1.0.0
 

composer.json

@@ -14,7 +14,7 @@
     ],
     "require": {
         "php": ">=5.5.0",
-        "atk4/dsql": "~1.0.1",
+        "atk4/dsql": "~1.0.8",
         "atk4/core": "~1.1.0"
     },
     "require-dev": {

docs/conditions.rst

@@ -206,4 +206,16 @@ to the $value::
     $m->addCondition($m->getElement('name'), '!=', $this->getElement('surname'));
 
 
+Using withID
+============
+
+.. php:method:: withID($id)
+
+This method is similar to load($id) but instead of loading the specified record, it
+sets condition for ID to match. Technically that saves you on equery if you do not
+need actual record by are only looking to traverse::
+
+    $u = new Model_User($db);
+    $books = $u->withID(20)->ref('Books');
+
 

docs/model.rst

@@ -137,11 +137,6 @@ use the following syntax when accessing fields of an active record::
 When you modify active record, it keeps the original value in the $dirty
 array:
 
-.. php:attr:: dirty
-
-    Contains list of modified fields since last loading and their original
-    valies.
-
 .. php:method:: set
 
     Set field to a specified value. The original value will be stored in
@@ -159,22 +154,41 @@ array:
 
     This will restore original value of the field.
 
+.. php:method:: get
+
+    Returns one of the following:
+
+     - If value was set() to the field, this value is returned
+     - If field was loaded from database, return original value
+     - if field had default set, returns default
+     - returns null.
+
 .. php:method:: isset
 
-    Return true if field contains unsaved changes::
+    Return true if field contains unsaved changes (dirty)::
 
         isset($m['name']); // returns false
         $m['name'] = 'Other Name';
         isset($m['name']); // returns true 
 
-.. php:method:: get
 
-    Returns one of the following:
+.. php:method:: isDirty
+
+    Return true if one or multiple fields contain unsaved changes (dirty)::
+
+        if ($m->isDirty(['name','surname'])) {
+           $m['full_name'] = $m['name'].' '.$m['surname'];
+        }
+
+    When the code above is placed in beforeSave hook, it will only be executed when
+    certain fields have been changed. If your recalculations are expensive, it's
+    pretty handy to rely on "dirty" fields to avoid some complex logic.
+
+.. php:attr:: dirty
+
+    Contains list of modified fields since last loading and their original
+    valies.
 
-     - If value was set() to the field, this value is returned
-     - If field was loaded from database, return original value
-     - if field had default set, returns default
-     - returns null.
 
 Full example::
 
@@ -213,6 +227,45 @@ Full example::
 
     Verify and convert first argument got get / set;
 
+Title Field and ID Field
+===========
+
+
+ID Field
+--------
+
+.. php:attr:: id_field
+
+    If your data storage uses field different than ``id`` to keep the ID of your records, then you can
+    specify that in $id_field property.
+
+.. tip:: You can change ID field of the current ID field by calling::
+
+        $m['id'] = $new_id;
+        $m->save();
+
+    This will update existing record with new $id. If you want to save your current field over another
+    existing record then::
+
+        $m->id = $new_id;
+        $m->save();
+
+    You must remember that only dirty fields are saved, though. (We might add replace() function though).
+
+Title Field
+-----------
+
+.. php:attr:: title_field
+
+    This field by default is set to 'name' will act as a primary title field of your table. This is
+    especially handy if you use model inside UI framework, which can automatically display value of
+    your title field in the header, or inside drop-down.
+
+    If you don't have field 'name' but you want some other field to be title, you can specify that in
+    the property. If title_field is not needed, set it to false or point towards a non-existant field.
+
+    See: :php:meth::`hasOne::addTitle()`
+
 Hooks
 =====
 
@@ -230,6 +283,9 @@ Hooks
   - afterUpdate [only if existing record]
   - afterInsert [only if new record]
 
+  - beforeUnload
+  - afterUnload
+
 - afterSave
 
 How to verify Updates