README.md in cdq-1.0.8 vs README.md in cdq-2.0.0
- old
+ new
@@ -3,14 +3,15 @@
Core Data Query (CDQ) is a library to help you manage your Core Data stack
while using RubyMotion. It uses a data model file, which you can generate in
XCode, or you can use [ruby-xcdm](https://github.com/infinitered/ruby-xcdm).
-[](https://gemnasium.com/infinitered/cdq)
[](https://travis-ci.org/infinitered/cdq)
[](http://badge.fury.io/rb/cdq)
+CDQ is maintained by [Infinite Red](http://infinite.red), a web and mobile development company based in Portland, OR and San Francisco, CA.
+
## Get Started
1. [Introducing CDQ](#introducingCDQ)
2. [Greenfield Quick Start Tutorial](https://github.com/infinitered/cdq/wiki/Greenfield-Quick-Start)
3. [Cheat Sheet](https://github.com/infinitered/cdq/wiki/CDQ-Cheat-Sheet)
4. [API docs](http://rubydoc.info/github/infinitered/cdq)
@@ -94,11 +95,10 @@
```ruby
schema "0001 initial" do
entity "Article" do
-
string :body, optional: false
integer32 :length
boolean :published, default: false
datetime :publishedAt, default: false
string :title, optional: false
@@ -107,11 +107,13 @@
end
entity "Author" do
float :fee
string :name, optional: false
- has_many :articles
+
+ # Deleting an author will delete all associated articles
+ has_many :articles, deletionRule: "Cascade"
end
end
```
@@ -211,10 +213,12 @@
Author.create(name: "Shakespeare", publish_count: 400, first_published: 1550)
Author.create(name: "Blake", publish_count: 100, first_published: 1778)
cdq.save
```
+CDQ will automatically set the object's property `created_at` to `Time.now` if it exists. If you want to use this ActiveRecord-like automatic attribute, make sure to add `datetime :created_at` to your schema's model definition.
+
### Reading
```ruby
author = Author.create(name: "Le Guin", publish_count: 150, first_published: 1970)
author.name # => "Le Guin"
@@ -227,12 +231,38 @@
author = Author.first
author.name = "Ursula K. Le Guin"
cdq.save
```
+You can also update multiple attributes of a single object:
+
+```ruby
+ author = Author.first
+ author.update(name: "Mark Twain", publish_count: 30, first_published: 1865)
+ cdq.save
+```
+
+The update command will raise an `UnknownAttributeError` if you try and set an attribute that doesn't exist on the object so it's good practice to sanitize the data before you call `update`:
+
+```ruby
+ new_author_data = {
+ name: "Mark Twain",
+ publish_count: 30,
+ first_published: 1865,
+ some_attribute_that_doesnt_exist_on_author: "balderdash!"
+ }
+ sanitized = new_author_data.keep_if{|k,_| Author.attribute_names.include?(k) }
+
+ author = Author.first
+ author.update(sanitized)
+ cdq.save
+```
+
**NOTE** Custom class methods will have to `include CDQ` in order to have access to the `cdq` object. If you're calling `cdq` from a class method, you also have to `extend CDQ`.
+CDQ will automatically set the object's property `updated_at` to `Time.now` if it exists. If you want to use this ActiveRecord-like automatic attribute, make sure to add `datetime :updated_at` to your schema's model definition.
+
### Deleting
```ruby
author = Author.first
author.destroy
cdq.save
@@ -380,12 +410,75 @@
```
> NOTE: strings and symbols are NOT interchangeable. `cdq('Entity')` gives you a
query generator for an entity, but `cdq(:attribute)` starts a predicate for an
attribute.
+## Reserved model attributes
+
+CDQ does some smart automatic attribute setting. If you add attributes `:created_at` and/or `:updated_at` to a model in your schema file, whenever a record is created or updated, these properties will be updated accordingly. Therefore, you can not define your own `:created_at` or `:updated_at` model attributes. These attributes must be of type `datetime`. Note that these attributes aren't set until you call `cdq.save`
+
+Example:
+
+```ruby
+schema "0001 initial" do
+ entity "Author" do
+ string :name, optional: false
+
+ datetime :created_at
+ datetime :updated_at
+ end
+end
+```
+
+```ruby
+a = Author.create(name: "Le Guin")
+# Notice that the properties aren't set yet
+#
+# <Author: 0x1175f9540> (entity: Author; id: 0x117504810
+# <x-coredata:///Author/tA4E22210-72CF-4272-BF2C-0C5C63A55B072> ; data: {
+# name: "Le Guin";
+# created_at: nil;
+# updated_at: nil;
+# })
+
+cdq.save
+
+puts a # Original reference to created Author object
+# <Author: 0x1175f9540> (entity: Author; id: 0x117504810
+# <x-coredata:///Author/tA4E22210-72CF-4272-BF2C-0C5C63A55B072> ; data: {
+# name: "Le Guin";
+# created_at: 2015-08-19 20:44:40 +0000;
+# updated_at: 2015-08-19 20:44:40 +0000;
+# })
+
+a.name = "Some Other Guy"
+puts a
+# Note that nothing has changed except the name:
+#
+# <Author: 0x1175f9540> (entity: Author; id: 0x117504810
+# <x-coredata:///Author/tA4E22210-72CF-4272-BF2C-0C5C63A55B072> ; data: {
+# name: "Some Other Guy";
+# created_at: 2015-08-19 20:44:40 +0000;
+# updated_at: 2015-08-19 20:44:40 +0000;
+# })
+
+cdq.save
+puts a
+# <Author: 0x1175f9540> (entity: Author; id: 0x117504810
+# <x-coredata:///Author/tA4E22210-72CF-4272-BF2C-0C5C63A55B072> ; data: {
+# name: "Some Other Guy";
+# created_at: 2015-08-19 20:44:40 +0000;
+# updated_at: 2015-08-19 20:47:40 +0000;
+# })
+```
+
+Also note that you should never use `object_id` as a model attribute as it will conflict with an internally generated property.
+
## iCloud
+**Removed as of version 2.0.0. If you still need this, pin cdq gem to before version 2.0.0**
+
As of version 0.1.10, there is some experimental support for iCloud, written by
@katsuyoshi. Please try it out and let us know how it's working for you. To
enable, initialize like this:
```ruby
@@ -413,5 +506,9 @@
```
$ rake args='-com.apple.CoreData.SQLDebug 3'
```
`com.apple.CoreData.SQLDebug` takes a value between 1 and 3; the higher the value, the more verbose the output.
+
+## Premium Support
+
+[CDQ](https://github.com/infinitered/cdq), as an open source project, is free to use and always will be. [Infinite Red](https://infinite.red/) offers premium CDQ support and general mobile app design/development services. Email us at [hello@infinite.red](mailto:hello@infinite.red) to get in touch with us for more details.