ParseResource

ParseResource makes it easy to interact with Parse.com's REST API. It adheres to the ActiveRecord pattern. ParseResource is fully ActiveModel compliant, meaning you can use validations and Rails forms.

Ruby/Rails developers should feel right at home.

If you're used to Post.create(:title => "Hello, world", :author => "Octocat"), then this is for you.

Features

• ActiveRecord-like API, almost no learning curve
• Validations
• Rails forms and scaffolds just work

Use cases

• Build a custom admin dashboard for your Parse.com data
• Use the same database for your web and native apps
• Pre-collect data for use in iOS and Android apps

Installation

Include in your Gemfile:

gem"kaminari"# optional for pagination supportgem"parse_resource","~> 1.8.0"

Or just gem install:

geminstallkaminari# optional for pagination supportgeminstallparse_resource

Create an account at Parse.com. Then create an application and copy the app_id and master_key into a file called parse_resource.yml. If you're using a Rails app, place this file in the config folder.

development:
app_id: 1234567890master_key: abcdefghtest:
app_id: 1234567890master_key: abcdefghproduction:
app_id: 1234567890master_key: abcdefgh

You can create separate Parse databases if you want. If not, include the same info for each environment.

In a non-Rails app, include this somewhere (preferable in an initializer):

ParseResource::Base.load!("your_app_id","your_master_key")

Usage

Create a model:

classPost < ParseResource::Basefields:title,:author,:bodyvalidates_presence_of:titleend

If you are using version 1.5.11 or earlier, subclass to just ParseResource--or just update to the most recent version.

Creating, updating, and deleting:

p=Post.new# validationsp.valid?#=> false p.errors#=> #<ActiveModel::Errors:0xab71998 ... @messages={:title=>["can't be blank"]}> p.title="Introducing ParseResource"#=> "Introducing ParseResource" p.valid?#=> true # setting more attributes, then savingp.author="Alan deLevie"p.body="Ipso Lorem"p.date=Time.nowp.save#=> true# checking the id generated by Parse's serversp.id#=> "QARfXUILgY" p.updated_at#=> nil p.created_at#=> "2011-09-19T01:32:04.973Z" # does anybody want this to be a DateTime object? Let me know.# updatingp.title="[Update] Introducing ParseResource"p.save#=> truep.updated_at#=> "2011-09-19T01:32:37.930Z" # more magic from Parse's servers# destroying an objectp.destroy#=> true p.title#=> nil

Finding:

posts=Post.where(:author=>"Arrington")# the query is lazy loaded# nothing gets sent to the Parse server until you run #all, #count, or any Array method on the query # (e.g. #first, #each, or #map)posts.eachdo |post|
"#{post.title}, by #{post.author}"endposts.map{|p| p.title}#=> ["Unpaid blogger", "Uncrunched"]id="DjiH4Qffke"p=Post.find(id)#simple find by id# ActiveRecord style find commandsPost.find_by_title("Uncrunched")#=> A Post objectPost.find_all_by_author("Arrington")#=> An Array of Posts# batch save an array of objectsPost.save_all(array_of_objects)# destroy all objects, updated to use Parse batch destroyPost.destroy_all(array_of_objects)# you can chain method calls, just like in ActiveRecordPost.where(:param1=>"foo").where(:param2=>"bar").all# limit the queryposts=Post.limit(5).where(:foo=>"bar")posts.length#=> 5# get a countPost.where(:bar=>"foo").count#=> 1337

Pagination with kaminari:

# get second page of results (default is 25 per page)Post.page(2).where(:foo=>"bar")# get second page with 100 results per pagePost.page(2).per(100).where(:foo=>"bar")

Users

Note: Because users are special in the Parse API, you must name your class User if you want to subclass ParseUser.

# app/models/user.rbclassUser < ParseUser# no validations included, but feel free to add your ownvalidates_presence_of:username# you can add fields, like any other kind of Object...fields:name,:bio# but note that email is a special field in the Parse API.fields:emailend# create a useruser=User.new(:username=>"adelevie")user.password="asecretpassword"user.save#=> true# after saving, the password is automatically hashed by Parse's server# user.password will return the unhashed password when the original object is in memory# from a new session, User.where(:username => "adelevie").first.password will return nil# check if a user is logged inUser.authenticate("adelevie","foooo")#=> falseUser.authenticate("adelevie","asecretpassword")#=> #<User...># A simple controller to authenticate usersclassSessionsController < ApplicationControllerdefnewenddefcreateuser=User.authenticate(params[:username],params[:password])ifusersession[:user_id]=user.idredirect_toroot_url,:notice=>"logged in !"elseflash.now.alert="Invalid username or password"render"new"endenddefdestroysession[:user_id]=nilredirect_toroot_url,:notice=>"Logged out!"endend

If you want to use parse_resource to back a simple authentication system for a Rails app, follow this tutorial, and make some simple modifications.

Installations

Note: Because Installations, are special in the Parse API, you must name your class Installation if you want to manipulate installation objects.

classInstallation < ParseResource::Basefields:appName,:appVersion,:badge,:channels,:deviceToken,:deviceType,:installationId,:parseVersion,:timeZoneend

GeoPoints

classPlace < ParseResource::Basefields:locationendplace=Place.newplace.location=ParseGeoPoint.new:latitude=>34.09300844216167,:longitude=> -118.3780094460731place.saveplace.location.inspect#=> #<ParseGeoPoint:0x007fb4f39c7de0 @latitude=34.09300844216167, @longitude=-118.3780094460731>place=Place.newplace.location=ParseGeoPoint.newplace.location.latitude=34.09300844216167place.location.longitude= -118.3780094460731place.saveplace.location.inspect#=> #<ParseGeoPoint:0x007fb4f39c7de0 @latitude=34.09300844216167, @longitude=-118.3780094460731>server_place=Place.find(place.objectId)server_place.location.inspect#=> #<ParseGeoPoint:0x007fb4f39c7de0 @latitude=34.09300844216167, @longitude=-118.3780094460731>server_place.location.latitude#=> 34.09300844216167server_place.location.longitude#=> -118.3780094460731

Querying by GeoPoints

Place.near(:location,[34.09300844216167, -118.3780094460731],:maxDistanceInMiles=>10).allPlace.near(:location,[34.09300844216167, -118.3780094460731],:maxDistanceInKilometers=>10).allPlace.near(:location,[34.09300844216167, -118.3780094460731],:maxDistanceInRadians=>10/3959).allPlace.within_box(:location,[33.81637559726026, -118.3783150233789],[34.09300844216167, -118.3780094460731]).all

DEPRECATED Associations

classPost < ParseResource::Base# As with ActiveRecord, associations names can differ from class names...belongs_to:author,:class_name=>'User'fields:title,:bodyendclassUser < ParseUser# ... but on the other end, use :inverse_of to complete the link.has_many:posts,:inverse_of=>:authorfield:nameendauthor=Author.create(:name=>"RL Stine")post1=Post.create(:title=>"Goosebumps 1")post2=Post.create(:title=>"Goosebumps 2")# assign from parent classauthor.posts << post1author.posts << post2# or assign from child classpost3=Post.create(:title=>"Goosebumps 3")post3.author=authorpost3.save#=> true# relational queriesposts=Post.include_object(:author).allposts.eachdo |post|
putspost.author.name# because you used Post#include_object, calling post.title won't execute a new query# this is similar to ActiveRecord's eager loadingend# fetch users through a relation on posts named commenterspost=Post.firstusers=User.related_to(post,:commenters)

File Upload

@post=Post.first()result=Post.upload(uploaded_file.tempfile,uploaded_file.original_filename,content_type: uploaded_file.content_type)@post.thumbnail={"name"=>result["name"],"__type"=>"File"}

Custom Getters and Setters

defnameval=get_attribute("name")# custom getter actions herevalenddefname=(val)# custom setter actions to val hereset_attribute("name",val)end

Documentation

Here

To-do

• User authentication
• Better documentation
• Associations
• Callbacks
• Push notifications
• Better type-casting
• HTTP request error handling

User authentication is my top priority feature. Several people have specifically requested it, and Parse just began exposing User objects in the REST API.

Let me know of any other features you want.

Contributing to ParseResource

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Create parse_resource.yml in the root of the gem folder. Using the same format as parse_resource.yml in the instructions (except only creating a test environment, add your own API keys.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2013 Alan deLevie. See LICENSE.txt for further details.