1- # opal-jquery
1+ # opal-jquery: jQuery Wrapper For Opal
22
33[ ![ Build Status] ( http://img.shields.io/travis/opal/opal-jquery/master.svg )] ( http://travis-ci.org/opal/opal-jquery )
44
@@ -53,6 +53,243 @@ opal-jquery also supports zepto. To run specs for zepto use the rake task:
5353
5454 $ bundle exec rake zepto
5555
56+ ## Getting Started
57+
58+ ### Usage
59+
60+ ` opal-jquery ` can now be easily added to your opal application sources using a
61+ standard require:
62+
63+ ``` ruby
64+ # app/application.rb
65+ require ' opal'
66+ require ' jquery'
67+ require ' opal-jquery'
68+
69+ alert " Hello from jquery + opal"
70+ ```
71+
72+ > ** Note** : this file requires two important dependencies, ` jquery ` and ` opal-jquery ` .
73+ > You need to bring your own ` jquery.js ` file as the gem does not include one. If
74+ > you are using the asset pipeline with rails, then this should be available
75+ > already, otherwise download a copy and place it into ` app/ ` or whichever directory
76+ > you are compiling assets from. You can alternatively require a zepto instance.
77+
78+ The ` #alert ` method is provided by ` opal-jquery ` . If the message displays, then
79+ ` jquery ` support should be working.
80+
81+ ### How does opal-jquery work
82+
83+ ` opal-jquery ` provides an ` Element ` class, whose instances are toll-free
84+ bridged instances of jquery objects. Just like ruby arrays are just javascript
85+ arrays, ` Element ` instances are just jquery objects. This makes interaction
86+ with jquery plugins much easier.
87+
88+ Also, ` Element ` will try to bridge with Zepto if it cannot find jQuery loaded,
89+ making it ideal for mobile applications as well.
90+
91+ ## Interacting with the DOM
92+
93+ ### Finding Elements
94+
95+ opal-jquery provides the ` Element ` class, which can be used to find elements in
96+ the current document:
97+
98+ ``` ruby
99+ Element .find(' #header'
100+ ```
101+
102+ ` Element.find ` is aliased to ` Element[] ` :
103+
104+ ``` ruby
105+ Element [' .my-class'
106+ ```
107+
108+ These methods acts just like ` $('selector') ` , and can use any jQuery
109+ compatible selector:
110+
111+ ``` ruby
112+ Element .find(' #navigation li:last'
113+ ```
114+
115+ The result is just a jQuery instance, which is toll-free bridged to
116+ instances of the ` Element ` class in ruby:
117+
118+ ``` ruby
119+ Element .find(' .foo' class
120+ # => Element
121+ ```
122+
123+ Instances of ` Element ` also have the ` #find ` method available for
124+ finding elements within the scope of each DOM node represented by
125+ the instance:
126+
127+ ``` ruby
128+ el = Element .find(' #header'
129+ el.find ' .foo'
130+ # => #<Element .... >
131+ ```
132+
133+ ### Running code on document ready
134+
135+ Just like jQuery, opal-jquery requires the document to be ready to
136+ be able to fully interact with the page. Any top level access should
137+ use the ` ready? ` method:
138+
139+ ``` ruby
140+ Document .ready? do
141+ alert " document is ready to go!"
142+ end
143+ ```
144+
145+ The ` Kernel#alert ` method is shown above too.
146+
147+ ### Event handling
148+
149+ The ` Element#on ` method is used to attach event handlers to elements:
150+
151+ ``` ruby
152+ Element .find(' #header' :click do
153+ puts " The header was clicked!"
154+ end
155+ ```
156+
157+ Selectors can also be passed as a second argument to handle events
158+ on certain children:
159+
160+ ``` ruby
161+ Element .find(' #header' :click , ' .foo' do
162+ puts " An element with a 'foo' class was clicked"
163+ end
164+ ```
165+
166+ An ` Event ` instance is optionally passed to block handlers as well,
167+ which is toll-free bridged to jquery events:
168+
169+ ``` ruby
170+ Element .find(' #my_link' :click ) do |evt |
171+ evt.stop_propagation
172+ puts " stopped the event!"
173+ end
174+ ```
175+
176+ You can access the element which triggered the event by ` #current_target ` .
177+
178+ ``` ruby
179+ Document .on :click do |evt |
180+ puts " clicked on: #{ evt.current_target } "
181+ end
182+ ```
183+
184+ ### CSS styles and classnames
185+
186+ The various jQuery methods are available on ` Element ` instances:
187+
188+ ``` ruby
189+ foo = Element .find(' .foo'
190+
191+ foo.add_class ' blue'
192+ foo.remove_class ' foo'
193+ foo.toggle_class ' selected'
194+ ```
195+
196+ There are also added convenience methods for opal-jquery:
197+
198+ ``` ruby
199+ foo = Element .find(' #header'
200+
201+ foo.class_name
202+ # => 'red lorry'
203+
204+ foo.class_name = ' yellow house'
205+
206+ foo.class_name
207+ # => 'yellow house'
208+ ```
209+
210+ ` Element#css ` also exists for getting/setting css styles:
211+
212+ ``` ruby
213+ el = Element .find(' #container'
214+ el.css ' color' ' blue'
215+ el.css ' color'
216+ # => 'blue'
217+ ```
218+
219+ ## HTTP/AJAX requests
220+
221+ jQuery's Ajax implementation is also wrapped in the top level HTTP
222+ class.
223+
224+ ``` ruby
225+ HTTP .get(" /users/1.json" do |response |
226+ puts response.body
227+ # => "{\"name\": \"Adam Beynon\"}"
228+ end
229+ ```
230+
231+ The block passed to this method is used as the handler when the request
232+ succeeds, as well as when it fails. To determine whether the request
233+ was successful, use the ` ok? ` method:
234+
235+ ``` ruby
236+ HTTP .get(" /users/2.json" do |response |
237+ if response.ok?
238+ alert " successful!"
239+ else
240+ alert " request failed :("
241+ end
242+ end
243+ ```
244+
245+ It is also possible to use a different handler for each case:
246+
247+ ``` ruby
248+ request = HTTP .get(" /users/3.json"
249+
250+ request.callback {
251+ puts " Request worked!"
252+ }
253+
254+ request.errback {
255+ puts " Request didn't work :("
256+ }
257+ ```
258+
259+ The request is actually triggered inside the ` HTTP.get ` method, but due
260+ to the async nature of the request, the callback and errback handlers can
261+ be added anytime before the request returns.
262+
263+ ### Handling responses
264+
265+ Web apps deal with JSON responses quite frequently, so there is a useful
266+ ` #json ` helper method to get the JSON content from a request:
267+
268+ ``` ruby
269+ HTTP .get(" /users.json" do |response |
270+ puts response.body
271+ puts response.json
272+ end
273+
274+ # => "[{\"name\": \"Adam\"},{\"name\": \"Ben\"}]"
275+ # => [{"name" => "Adam"}, {"name" => "Ben"}]
276+ ```
277+
278+ The ` #body ` method will always return the raw response string.
279+
280+ If an error is encountered, then the ` #status_code ` method will hold the
281+ specific error code from the underlying request:
282+
283+ ``` ruby
284+ request = HTTP .get(" /users/3.json"
285+
286+ request.callback { puts " it worked!"
287+
288+ request.errback { |response |
289+ puts " failed with status #{ response.status_code } "
290+ }
291+ ```
292+
56293## License
57294
58295(The MIT License)
@@ -76,3 +313,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
76313LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
77314OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
78315THE SOFTWARE.
316+
0 commit comments