quickbase_record 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f8eee22d616a9abd33c9d3441d75554f606e3c4
-  data.tar.gz: cad3664b593752dbee3c69d5aac2c8b364cd5d76
+  metadata.gz: 66af6aaf85c6d5350a049cc7a4323b54199627d9
+  data.tar.gz: 3c9cba75db0cd942cd63add02c5d7a77a09aaaaa
 SHA512:
-  metadata.gz: 0b51a88a4ba3547b52c0eeb93bea5b5ef50aaa4be66102061c35a5c324dedc143069e81af07a0e86aea751c1858c5560044e3d1e22fe203ba08a3ca57cc43345
-  data.tar.gz: 9375ed2ec16e0fb24da1ec9d1f5533550205c0867d325832352875a6244f2d9d280757a1474cac7d86a5ef5c41f3710504417b7343659456324cc37a49d3845c
+  metadata.gz: c3e8a79ff986d7003f31ee40d38d719f01c1be517d86f08b644f1afe245af2165a70d03bd4b64b1ca9ed875b04516f7bb548fbbaf87f623d98c1b17912d0a8ed
+  data.tar.gz: 92c863cc14b32b7b170d56b2b103f5dc5825f1a004f84919fe063246e41f2fe5237acd73debe07afee6edf1aea147710fadf8096090c2ac01f53776b293dbfed

data/README.md

@@ -1,6 +1,6 @@
 # QuickbaseRecord
 
-QuickbaseRecord is a baller ActiveRecord-style ORM for using the Intuit QuickBase platform as a database for Ruby or Ruby on Rails applications.
+QuickbaseRecord is a baller ActiveRecord-style ORM/API client for QuickBase.
 
 ## Installation
 
@@ -18,29 +18,30 @@ Or install it yourself as:
 
     $ gem install quickbase_record
 
-## Usage
-
-  * [Methods](#available-methods)
+## Setup
 
 ### Initialize the API Client
-QuickbaseRecord is built on top of the [Advantage Quickbase](https://github.com/AdvantageIntegratedSolutions/Quickbase-Gem) gem to make the API calls to QuickBase, so you'll need to configure QuickbaseRecord with your app's realm name and provide a valid username, password, and token (if applicable). This can be done in a single initializer file with a call to `QuickbaseRecords.configure`.
+First you'll need to configure QuickbaseRecord with your app's realm name (realm-name.quickbase.com) and provide a valid username, password, and application token (if applicable). Alternatively, you can supply a user token. This can be done in a single initializer file with a call to `QuickbaseRecord.configure`.
 
 ```
   # config/initializers/quickbase_record.rb
 
   QuickbaseRecord.configure do |config|
     config.realm = "quickbase_app_realm_name"
+    config.token = "quickbase_app_token_if_applicable"
     config.username = "valid_username"
     config.password = "valid_password"
-    config.token = "quickbase_app_token_if_applicable"
+
+    # or, instead of username/password:
+
+    config.usertoken = "quickbase_user_token"
   end
 ```
 
 ### Include it in your Class
-Simply `include QuickbaseRecord::Model` in your class and use the `.define_fields` method to supply the table's DBID and a mapping of desired field names => QuickBase FIDs.
+Now you can simply `include QuickbaseRecord::Model` in a class representing a QuickBase table and call the `.define_fields` method to supply the table's Database ID and a mapping of desired field names => QuickBase Field IDs.
 
-**(NEW IN 0.4.0)**
-.define_fields follows a similar pattern to ActiveRecord migrations. It takes a block where data types and field names are definied with a corresponding QuickBase FID.
+`.define_fields` follows a similar pattern to ActiveRecord migrations. It takes a block where data types and field names are defined with a corresponding QuickBase Field ID.
 
 ```
   # app/models/post.rb
@@ -50,6 +51,7 @@ Simply `include QuickbaseRecord::Model` in your class and use the `.define_field
 
     define_fields do |t|
       t.dbid 'abcde12345'
+      t.date :date_created, 1, :read_only
       t.number :id, 3, :primary_key
       t.string :content, 7
       t.string :author, 8
@@ -62,192 +64,191 @@ Simply `include QuickbaseRecord::Model` in your class and use the `.define_field
 ```
 
 ### .define_fields
-.define_fields(:field_name, fid, *options)
 
-The following data types are currently supported:
+`.define_fields` will create attr_accessors for all fields and parse API responses to match the configured data type. Note that values will **not** be converted to anything when sending API calls.
 
-  * **dbid**
-    - The dbid for the QuickBase table
-    - **Does not take multiple arguments, only a string of the dbid**
+The following configuration options/data types are supported:
 
+  * **dbid** *required
+    - The Database ID for the QuickBase table
+    - **Does not accept multiple arguments, only a string of the Database ID**
   * **string**
     - All values are converted to a String
-
   * **number**
-    - All values are converted to a Numeric (and knows if it needs to be a float)
+    - All values are converted to a Numeric (ints or floats)
   * **date**
-    - All values are converted to a string representation of the date value: "07/30/2015" or nil for empty values
+    - All values are converted to a string representation of the date value: ex: "07/30/2015". Does not currently work for Date/Time conversion, so you'll have to pull in Date/Time fields as strings and parse them yourself. Sorry.
   * **boolean**
     - All values are converted to true or false (QuickBase returns "1" and "0")
   * **file_attachment**
-    - Doesn't really do anything, only makes you feel better :) File attachments are explained below.
+    - Doesn't really do anything, only makes you feel better :) File attachments are explained [below](#file-attachments).
 
 Additional options may be added to field definitions:
 
-  * **:primary_key**
-    - This is a required option for one field.
+  * **:primary_key** *required
+    - Pretty obvious.
   * **:read_only**
-    - Fields marked as :read_only will not respond to #save or #update_attributes calls.
+    - Fields marked as :read_only will not be sent along 'write' API requests -- #save, #update_attributes, #create, and .save_collection.
     - Useful for formula/lookup/other fields in your QuickBase table that you can't write to.
 
 
-**IMPORTANT: You must supply a "dbid" data type and mark a single field as :primary_key**
+**IMPORTANT: You must supply a "dbid" data type and mark a single field as :primary_key. Weird shit can happen if you don't. Eventually I'll throw some errors if they're missing, but for now it's the wild west.**
+
+## Methods
+
+### Query for Records
+
+* **.find(id)**
+  ```ruby
+    Post.find(params[:id])
+    Post.find(3123)
+  ```
+  - Query for a specific QuickBase record by it's primary key.
+  - Returns a single object
+
+* **.where(query_hash OR string in QuickBase query format)**
+  ```ruby
+    Post.where(author: 'Cullen Jett')
+  ```
+  - Query QuickBase by any field name defined in your class' field mapping
+  - Returns an array of objects
+
+  - Multiple field_name/value pairs are joined with 'AND'
+  ```ruby
+    Post.where(id: 1, author: 'Cullen Jett')
+    # ^ is parsed to the QuickBase format: {'3'.EX.'1'}AND{'8'.EX.'Cullen Jett'}
+  ```
+
+  - Values in an array are joined with 'OR'
+  ```ruby
+    Post.where(author: ['Cullen Jett', 'Socrates'])
+    # {'8'.EX.'Cullen Jett'}OR{'8'.EX.'Socrates'}
+  ```
+
+  - To use a comparator other than 'EX', pass the value as another hash with the key as the comparator
+  ```ruby
+    Post.where(author: {XEX: 'Cullen Jett'})
+    # {'8'.XEX.'Cullen Jett'}
+
+    Post.where(date_created: {OBF: 'today'})
+    # {'1'.OBF.'today'}
+  ```
+
+  - Also accepts a string in the standard QuickBase query format. This way works with both field names or Field IDs.
+  ```ruby
+    Post.where("{'3'.EX.'1'}")
+    Post.where("{author.XEX.'Cullen Jett'}")
+  ```
+
+* **.batch_where(attributes_hash, count=1000)**
+  - Same as `.where`, but queries in batches of {count} since QuickBase has a limit on how much data you can get back in one go. This bad boy will call multiple queries and then concatenate all of the responses in a single array.
+  ```ruby
+    Post.batch_where({date_created: ['today', 'yesterday']}, 5000)
+  ```
+
+* **.qid(id)**
+  - Accepts a QID (QuickBase report ID)
+  - Returns an array of objects
+  ```ruby
+    Post.qid(1)
+  ```
+
+#### Query Options (clist, slist, options)
+  To query using the QuickBase query options such as 'clist', 'slist', or 'options', include :query_options as a key and a hash of `option_property: value` as values. An example is in order:
+  ```ruby
+    Post.where(author: ['Cullen Jett', 'Socrates'], query_options: {clist: 'id.author', slist: 'author', options: 'num-1'})
+  ```
+
+#### Broken Query?
+If you want to see the QuickBase query string output of a `.where()` query hash you can pass your query hash to the `.build_query()` method and it will return the QuickBase query.
 
-### Queries
-To query for records you can use the .find, .where, or .qid methods on the class. See below for examples.
-
-If you want to see the QuickBase query string output of a .where() argument you can pass your query hash to the .build_query() method and it will return the QuickBase query.
-
-```
-Post.build_query(author: 'Cullen', title: 'Some Title')
-=> "{'8'.EX.'Cullen'}AND{'9'.EX.'Some Title'}"
+```ruby
+  Post.build_query(author: 'Cullen', title: 'Some Title')
+  => "{'8'.EX.'Cullen'}AND{'9'.EX.'Some Title'}"
 ```
 
-You can also access the underlying instance of the AdvantageQuickbase client with .qb_client. This property lives on both the class and on any instance of that class. To access the dbid for the table, call .dbid on the class.
+#### AdvantageQuickbase
+QuickBaseRecord is built on top of the [AdvantageQuickbase gem](https://github.com/AdvantageIntegratedSolutions/Quickbase-Gem). You can access the underlying instance of the AdvantageQuickbase client with `.qb_client`. This property lives on both the class and on any instance of that class. To access the dbid for the table, call .dbid on the class.
 
-```
+```ruby
   Post.qb_client.do_query(...)
   @post = Post.new(...)
   @post.qb_client.edit_record(self.class.dbid, self.id, {5 => 'Something', 6 => 'Something else'})
 ```
 
-## Available Methods
+## Create and Update Records
   * **.create(attributes_hash)**
-    - Intantiate *and* save a new object with the given attributes
-    - Assigns the returned object it's new ID
-    ```
+    ```ruby
       Post.create(content: 'Amazing post content', author: 'Cullen Jett')
     ```
+    - Instantiate *and* save a new object with the given attributes
+    - Assigns the returned object it's new Record ID
 
   * **.save_collection(array_of_objects)**
-    - Save an array of objects (of the same class)
-    - Uses API_ImportFromCSV under the hood, so it will edit a record if it has a record ID or create one if not.
-    - Returns array of record IDs
-    ```
+    ```ruby
       @post1 = Post.new(content: 'Amazing post content', author: 'Cullen Jett')
       @post2 = Post.find(123)
 
       Post.save_collection([@post1, @post2])
     ```
-
-  * **.find(id)**
-    - Query for a specific QuickBase record by it's ID
-    - Returns a single object
-    ```
-      Post.find(params[:id])
-    ```
-
-  * **.where(attributes_hash OR string)**
-    - Query QuickBase by any field name defined in your class' field mapping
-    - Returns an array of objects
-    ```
-      Post.where(author: 'Cullen Jett').first
-    ```
-
-    - Multiple field_name/value pairs are joined with 'AND'
-    ```
-      Post.where(id: 1, author: 'Cullen Jett')
-      # {'3'.EX.'1'}AND{'8'.EX.'Cullen Jett'}
-    ```
-
-    - Values in an array are joined with 'OR'
-    ```
-      Post.where(author: ['Cullen Jett', 'Socrates'])
-      # {'8'.EX.'Cullen Jett'}OR{'8'.EX.'Socrates'}
-
-      Post.where({ [author: 'Cullen Jett', id: 123] })
-      # {'8'.EX.'Cullen Jett'}OR{'3'.EX.'123'}
-    ```
-
-    - To use a comparator other than 'EX' pass the value as another hash with the key as the comparator
-    ```
-      Post.where(author: {XEX: 'Cullen Jett'})
-      # {'8'.XEX.'Cullen Jett'}
-    ```
-
-    - Combine arrays and hashes to build more complex queries
-    ```
-      Post.where(id: [{XEX: 123}, {OBF: 'today'}])
-      # "{'3'.XEX.'123'}OR{'3'.OBF.'today'}"
-
-      Post.where(id: {XEX: 123, OAF: 'today'})
-      # "{'3'.XEX.'123'}AND{'3'.OAF.'today'}"
-    ```
-
-    - Also accepts a string in the standard QuickBase query format
-      * Works with field names or FIDs
-    ```
-      Post.where("{'3'.EX.'1'}")
-      Post.where("{author.XEX.'Cullen Jett'}")
-    ```
-
-    * **Query Options (clist, slist, options)** To query using the QuickBase query options such as 'clist', 'slist', or 'options', include :query_options as a hash of option_property: value
-    ```
-      Post.where(author: ['Cullen Jett', 'Socrates'], query_options: {clist: 'id.author', slist: 'author', options: 'num-1'})
-    ```
-
-  * **.batch_where(attributes_hash, count=1000)**
-    - Same as .where, but queries in batches of {count}
-    ```
-      Post.where({date_created: ['today', 'yesterday']}, 500) # note the necessary "{}" around the attributes_hash
-    ```
-
-  * **.qid(id)**
-    - Accepts a QID (QuickBase report ID)
-    - Returns an array of objects
-    ```
-      Post.qid(1)
-    ```
+    - Save an array of objects (of the same class)
+    - Uses API_ImportFromCSV under the hood, so it will edit a record if it has a record ID or create one if not.
+    - Returns an array of Record IDs
+    - **IMPORTANT: make sure all of the objects have the same QuickBase properties (even if they have empty values). The AdvantageQuickbase gem will use the first object in the array to generate the clist.**
 
   * **#save**
-    - Creates a new record in QuickBase for objects that don't have an ID *or* edits the corresponding QuickBase record if the object already has an ID
-    - Returns the object (if #save created a record in QuickBase the the returned object will now have an ID)
-    ```
+    ```ruby
       @post = Post.new(content: 'Amazing post content', author: 'Cullen Jett')
       @post.save # => <Post: @id: 1, @content: 'Amazing post content', @author: 'Cullen Jett'
 
       @post.author = 'Socrates'
       @post.save # => <Post: @id: 1, @content: 'Amazing post content', @author: 'Socrates'
     ```
+    - Creates a new record in QuickBase for objects that don't have an ID *or* edits the corresponding QuickBase record if the object already has an ID
+    - Returns the object (if #save created a record in QuickBase the the returned object will now have an ID)
 
-  * **#delete**
-    - Delete the corresponding record in QuickBase
-    - It returns the object if successful or `false` if unsuccessful
+  * **#update_attributes(attributes_hash)**
+    ```ruby
+      @post = Post.where(author: 'Cullen Jett').first
+      @post.update_attributes(author: 'Socrates', content: 'Something enlightening...') # => <Post: @id: 1, @author: 'Socrates', @content: 'Something enlightening...'
     ```
+    - **IMPORTANT: Updates *and* saves the object with the new attributes**
+    - Only sends the passed in attributes as arguments to API_AddRecord or API_EditRecord (depending on whether the object has an ID or not)
+    - Returns the object
+
+## Delete Records
+  * **#delete**
+    ```ruby
       @post = Post.find(1)
       @post.delete
     ```
+    - Delete the corresponding record in QuickBase
+    - It returns the object if successful or `false` if unsuccessful
 
   * **.purge_records(attributes_hash OR QID)**
-    - Delete ALL records that match the attributes hash or are in the record corresponding to the QID argument
-    - Returns an array of deleted rids
-    - **CAUTION** If you do not supply a query parameter, this call will delete ALL of the records in the table.
-    ```
+    ```ruby
       Post.purge_records(name: 'Cullen Jett') # attributes hash
       or
       Post.purge_records(9) # QID
 
       => [1,2,3,4,5...]
     ```
+    - Delete ALL records that match the attributes hash or are in the record corresponding to the QID argument
+    - Returns an array of deleted rids
+    - **CAUTION** If you do not supply a query parameter, this call will delete ALL of the records in the table.
+
 
-  * **#update_attributes(attributes_hash)**
-    - **IMPORTANT: Updates *and* saves the object with the new attributes**
-    - Only sends the passed in attributes as arguments to API_AddRecord or API_EditRecord (depending on whether the object has an ID or not)
-    - Returns the object
-    ```
-      @post = Post.where(author: 'Cullen Jett').first
-      @post.update_attributes(author: 'Socrates', content: 'Something enlightening...') # => <Post: @id: 1, @author: 'Socrates', @content: 'Something enlightening...'
-    ```
 
+## Misc Methods
   * **#assign_attributes(attributes_hash)**
-    - Only changes the objects attributes in memory (i.e. does not save to QuickBase)
-    - Useful for assigning multiple attributes at once, otherwise you could use the field name's attr_accessor to change a single attribute.
-    - Returns the object
-    ```
+    ```ruby
       @post = Post.where(author: 'Cullen Jett').first
       @post.assign_attributes(author: 'Socrates', content: 'Something enlightening...')
       @post.save
     ```
+    - Only changes the objects attributes in memory (i.e. does not save to QuickBase)
+    - Useful for assigning multiple attributes at once, otherwise you could use the field name's attr_accessor to change a single attribute.
+    - Returns the object
 
   * **.qb_client and #qb_client**
     - Access the quickbase API client (advantage_quickbase gem) directly
@@ -255,7 +256,7 @@ You can also access the underlying instance of the AdvantageQuickbase client wit
 ## File Attachments
 When ***creating*** an object with a field of type 'file attachment', you must assign it as hash with :name and :file as keys.
 After the object is ***saved*** that field will then become a new hash with :filename and :url as keys.
-```
+```ruby
   @post = Post.new(attachment: {name: 'Test File Name', file: 'path/to/your/file OR file contents'})
   @post.save
   @post.attachment => {filename: 'Test File Name', url: 'https://realm.quickbase.com/up/abcdefg/Test%20File%20Name'}

data/lib/quickbase_record/version.rb

@@ -1,3 +1,3 @@
 module QuickbaseRecord
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/quickbase_record.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = QuickbaseRecord::VERSION
   spec.authors       = ["Cullen Jett"]
   spec.email         = ["cullenjett@gmail.com"]
-  spec.summary       = "An ActiveRecord-style ORM for using Intuit QuickBase tables as models."
-  spec.description   = "QuickbaseRecord is a baller ActiveRecord-style ORM for using the Intuit QuickBase platform as a database for Ruby or Ruby on Rails applications."
+  spec.summary       = "An ORM-style API client for QuickBase."
+  spec.description   = "QuickbaseRecord is a baller ActiveRecord-style ORM/API client for QuickBase."
   spec.homepage      = "https://github.com/cullenjett/quickbase_record"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quickbase_record
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Cullen Jett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-17 00:00:00.000000000 Z
+date: 2016-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,8 +94,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
-description: QuickbaseRecord is a baller ActiveRecord-style ORM for using the Intuit
-  QuickBase platform as a database for Ruby or Ruby on Rails applications.
+description: QuickbaseRecord is a baller ActiveRecord-style ORM/API client for QuickBase.
 email:
 - cullenjett@gmail.com
 executables: []
@@ -153,7 +152,7 @@ rubyforge_project:
 rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
-summary: An ActiveRecord-style ORM for using Intuit QuickBase tables as models.
+summary: An ORM-style API client for QuickBase.
 test_files:
 - spec/fakes/classroom_fake.rb
 - spec/fakes/student_fake.rb