Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 142 lines (108 sloc) 3.662 kb
b6ee191 Clay Allsopp testing the read me markdown
authored
1 # RemoteModel
2
3
4 JSON API <-> NSObject in one line. Powered by RubyMotion and [BubbleWrap](https://github.com/mattetti/BubbleWrap/).
5
6 ## Example
7
f331547 Clay Allsopp more concise readme
authored
8 Let's say we have some User and Question objects retrievable via our API. We can do fun stuff like:
9
10 ```ruby
bf341bf Clay Allsopp lol more docs
authored
11 # GET http://ourapi.com/users/1.json -> {:user => {id: 1}}
f331547 Clay Allsopp more concise readme
authored
12 user = User.find(1) do |user|
13 # async
bf341bf Clay Allsopp lol more docs
authored
14 # GET http://ourapi.com/users/1/questions.json -> {:questions => [...]}
f331547 Clay Allsopp more concise readme
authored
15 Question.find_all(user_id: user.id) do |questions|
16 # async
17 puts questions
18 end
19 end
20
21 # Later...
6d41a3d Clay Allsopp updated readme
authored
22 => [#<Question @user=#<User>,
23 #<Question @user=#<User>]
f331547 Clay Allsopp more concise readme
authored
24 ```
25
26 Here's what our files look like:
b6ee191 Clay Allsopp testing the read me markdown
authored
27
28 #### ./app/models/user
29 ```ruby
30 class User < RemoteModule::RemoteModel
c673fbc Clay Allsopp clean up the readme
authored
31 attr_accessor :id
b6ee191 Clay Allsopp testing the read me markdown
authored
32
33 has_many :questions
34
35 collection_url "users"
36 member_url "users/:id"
37 end
38 ```
39
40 #### ./app/models/question.rb
41 ```ruby
42 class Question < RemoteModule::RemoteModel
43 attr_accessor :id, :question, :is_active
44
45 belongs_to :user
46
47 collection_url "users/:user_id/questions"
48 member_url "users/:user_id/questions/:id"
49
50 custom_urls :active_url => member_url + "/make_active"
51
bf341bf Clay Allsopp lol more docs
authored
52 # The urls substitute params based on a passed hash and/or object's methods,
53 # so we define user_id to use for the collection/member urls
b6ee191 Clay Allsopp testing the read me markdown
authored
54 def user_id
55 user && user.id
56 end
57
bf341bf Clay Allsopp lol more docs
authored
58 # An example of how we can use custom URLs to make custom nice(r) methods
f2baadd Clay Allsopp add an example
authored
59 # EX
60 # a_question.make_active(false) do |question|
61 # p question.is_active
62 # end
c673fbc Clay Allsopp clean up the readme
authored
63 def make_active(active)
b6ee191 Clay Allsopp testing the read me markdown
authored
64 post(self.active_url, payload: {active: active}) do |response, json|
65 self.is_active = json[:question][:is_active]
c673fbc Clay Allsopp clean up the readme
authored
66 if block_given?
67 yield self
b6ee191 Clay Allsopp testing the read me markdown
authored
68 end
69 end
70 end
71 end
6d41a3d Clay Allsopp updated readme
authored
72 ```
73
52767b0 Clay Allsopp more changes
authored
74 ## Installation
75
1a7aacb Clay Allsopp Add gem creation files
authored
76 ```ruby
77 gem install remote_model
52767b0 Clay Allsopp more changes
authored
78 ```
79
1a7aacb Clay Allsopp Add gem creation files
authored
80 And now in your Rakefile, require `remote_model`:
52767b0 Clay Allsopp more changes
authored
81
82 ```ruby
1a7aacb Clay Allsopp Add gem creation files
authored
83 $:.unshift("/Library/RubyMotion/lib")
84 require 'motion/project'
85 require 'remote_model'
86
52767b0 Clay Allsopp more changes
authored
87 Motion::Project::App.setup do |app|
88 ...
89 end
90 ```
91
1a7aacb Clay Allsopp Add gem creation files
authored
92 ## Setup
93
52767b0 Clay Allsopp more changes
authored
94 Add an initialization file somewhere, like ./app/initializers/remote_model.rb. This is where we put the API specifications:
95
96 ```ruby
97 module RemoteModule
98 class RemoteModel
99 # The default URL for our requests.
100 # Overrideable per model subclass
101 self.root_url = "http://localhost:5000/"
102
103 # Options attached to every request
104 # Appendable per model subclass
29da0bf Clay Allsopp Update README.md
authored
105 # See BubbleWrap docs on what can be passed in BubbleWrap::HTTP.<method>(url, options)
52767b0 Clay Allsopp more changes
authored
106 self.default_url_options = {
107 :headers => {
108 "x-api-token" => "some_token",
109 "Accept" => "application/json"
110 }
111 }
112 end
113 end
114 ```
115
6d41a3d Clay Allsopp updated readme
authored
116 ## How?
117
6242b5e Clay Allsopp lets use a real example
authored
118 RemoteModel is designed for JSON APIs which return structures with "nice" properties.
6d41a3d Clay Allsopp updated readme
authored
119
120 When you make a request with a RemoteModel (self.get/put/post/delete), the result is always parsed as JSON. The ActiveRecord-esque methods take this JSON and create objects out of it. It's clever and creates the proper associations (belongs_to/has_one/has_many) within the objects, as defined in the models.
121
122 #### FormatableString
123
6242b5e Clay Allsopp lets use a real example
authored
124 The AR methods also use the member/collection defined URLs to make requests. These URLs are a string which you can use :symbols to input dynamic values. These strings can be formatted using a hash and/or using an object (it will look to see if the object responds to these symbols and call the method if applicable):
6d41a3d Clay Allsopp updated readme
authored
125
126 ```ruby
127 >> s = RemoteModule::FormatableString.new("url/:param")
128 => "url/:param"
129 >> s.format({param: 6})
130 => "url/6"
6242b5e Clay Allsopp lets use a real example
authored
131 >> obj = Struct.new("Paramer", :param).new(param: 100)
52767b0 Clay Allsopp more changes
authored
132 => ...
133 >> s.format({}, obj)
134 => "url/100"
6d41a3d Clay Allsopp updated readme
authored
135 ```
136
137 RemoteModels can define custom urls and call those as methods (see question.rb above).
138
139 ## Todo
140
141 - More tests
142 - CoreData integration
Something went wrong with that request. Please try again.