阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 opal jquery 中文API文档

      插件 opal jquery 中文API文档 https://github.com/opal/opal-jquery

      Opal jQuery

      jQuery wrapper for Opal

      Build Status

      opal-jquery provides DOM access to opal by wrapping jQuery (or zepto) and providing a nice ruby syntax for dealing with jQuery instances.

      Installation

      Install opal-jquery from RubyGems:

      $ gem install opal-jquery
      

      Or include it in your Gemfile for Bundler:

      gem 'opal-jquery'
      

      Running Specs

      Get the dependencies:

      $ bundle install
      

      Browser

      You can run the specs in any web browser, by running the config.ru rack file:

      $ bundle exec rackup
      

      And then visiting http://localhost:9292 in any web browser.

      Phantomjs

      You will need phantomjs to run the specs outside the browser. It can be downloaded at http://phantomjs.org/download.html

      On osx you can install through homebrew

      $ brew update; brew install phantomjs
      

      Run the tests inside a phantom.js runner:

      $ bundle exec rake
      

      Zepto

      opal-jquery also supports zepto. To run specs for zepto use the rake task:

      $ bundle exec rake zepto
      

      Getting Started

      Usage

      opal-jquery can now be easily added to your opal application sources using a standard require:

      # app/application.rb
      require 'opal'
      require 'jquery'
      require 'opal-jquery'
      
      alert "Hello from jquery + opal"
      

      Note: this file requires two important dependencies, jquery and opal-jquery. You need to bring your own jquery.js file as the gem does not include one. If you are using the asset pipeline with rails, then this should be available already, otherwise download a copy and place it into app/ or whichever directory you are compiling assets from. You can alternatively require a zepto instance.

      The #alert method is provided by opal-jquery. If the message displays, then jquery support should be working.

      How does opal-jquery work

      opal-jquery provides an Element class, whose instances are toll-free bridged instances of jquery objects. Just like ruby arrays are just javascript arrays, Element instances are just jquery objects. This makes interaction with jquery plugins much easier.

      Also, Element will try to bridge with Zepto if it cannot find jQuery loaded, making it ideal for mobile applications as well.

      Interacting with the DOM

      Finding Elements

      opal-jquery provides the Element class, which can be used to find elements in the current document:

      Element.find('#header')
      

      Element.find is aliased to Element[]:

      Element['.my-class']
      

      These methods acts just like $('selector'), and can use any jQuery compatible selector:

      Element.find('#navigation li:last')
      

      The result is just a jQuery instance, which is toll-free bridged to instances of the Element class in ruby:

      Element.find('.foo').class
      # => Element
      

      Instances of Element also have the #find method available for finding elements within the scope of each DOM node represented by the instance:

      el = Element.find('#header')
      el.find '.foo'
      # => #<Element .... >
      

      Running code on document ready

      Just like jQuery, opal-jquery requires the document to be ready to be able to fully interact with the page. Any top level access should use the ready? method:

      Document.ready? do
        alert "document is ready to go!"
      end
      

      or the equivilent Document.ready promise which is useful when combined with other promises:

      Document.ready.then do |ready|
        alert "Page is ready to use!"
      end
      

      Notice the use of the Kernel#alert method.

      Event handling

      The Element#on method is used to attach event handlers to elements:

      Element.find('#header').on :click do
        puts "The header was clicked!"
      end
      

      Selectors can also be passed as a second argument to handle events on certain children:

      Element.find('#header').on(:click, '.foo') do
        puts "An element with a 'foo' class was clicked"
      end
      

      An Event instance is optionally passed to block handlers as well, which is toll-free bridged to jquery events:

      Element.find('#my_link').on(:click) do |evt|
        evt.stop_propagation
        puts "stopped the event!"
      end
      

      You can access the element which triggered the event by #current_target.

      Document.on :click do |evt|
        puts "clicked on: #{evt.current_target}"
      end
      

      CSS styles and classnames

      The various jQuery methods are available on Element instances:

      foo = Element.find('.foo')
      
      foo.add_class 'blue'
      foo.remove_class 'foo'
      foo.toggle_class 'selected'
      

      There are also added convenience methods for opal-jquery:

      foo = Element.find('#header')
      
      foo.class_name
      # => 'red lorry'
      
      foo.class_name = 'yellow house'
      
      foo.class_name
      # => 'yellow house'
      

      Element#css also exists for getting/setting css styles:

      el = Element.find('#container')
      el.css 'color', 'blue'
      el.css 'color'
      # => 'blue'
      

      HTTP/AJAX requests

      jQuery’s Ajax implementation is also wrapped in the top level HTTP class.

      HTTP.get("/users/1.json") do |response|
        puts response.body
        # => "{\"name\": \"Adam Beynon\"}"
      end
      

      The block passed to this method is used as the handler when the request succeeds, as well as when it fails. To determine whether the request was successful, use the ok? method:

      HTTP.get("/users/2.json") do |response|
        if response.ok?
          alert "successful!"
        else
          alert "request failed :("
        end
      end
      

      It is also possible to use a different handler for each case:

      request = HTTP.get("/users/3.json")
      
      request.callback {
        puts "Request worked!"
      }
      
      request.errback {
        puts "Request didn't work :("
      }
      

      The request is actually triggered inside the HTTP.get method, but due to the async nature of the request, the callback and errback handlers can be added anytime before the request returns.

      Handling responses

      Web apps deal with JSON responses quite frequently, so there is a useful #json helper method to get the JSON content from a request:

      HTTP.get("/users.json") do |response|
        puts response.body
        puts response.json
      end
      
      # => "[{\"name\": \"Adam\"},{\"name\": \"Ben\"}]"
      # => [{"name" => "Adam"}, {"name" => "Ben"}]
      

      The #body method will always return the raw response string.

      If an error is encountered, then the #status_code method will hold the specific error code from the underlying request:

      request = HTTP.get("/users/3.json")
      
      request.callback { puts "it worked!" }
      
      request.errback { |response|
        puts "failed with status #{response.status_code}"
      }
      

      Supplying an XHR method

      To supply an XHR callback include a lambda with the xhr option:

      update_progress = lambda do
        xhr = `new window.XMLHttpRequest()`
        update_progress = lambda do |evt|
          # update your progress here
        end
        `xhr.upload.addEventListener("progress", update_progress, false)`
        xhr
      end
      
      cloud_xfer = HTTP.put "http://my.cloud.storage/location", xhr: update_progress, ... etc ...
      

      Usage of JQuery plugins

      Extra plugins used for JQuery aren’t available to ruby code by default, you will have to expose these functions to opal-jquery.

      Element.expose :cool_plugin
      

      Arguments to a exposed function will be passed as they are, so these arguments will have to be passed as native JS instead of ruby code. A conversion to native JS can be done with the .to_n method.

      Element.expose :cool_plugin
      
      el = Element['.html_element']
      el.cool_plugin({argument: 'value', argument1: 1000}.to_n)
      

      License

      (The MIT License)

      Copyright (C) 2013 by Adam Beynon

      Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

      The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

      THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

      目录
      目录