{"id":13503694,"url":"https://github.com/opal/opal-jquery","last_synced_at":"2025-04-12T15:34:58.246Z","repository":{"id":1461066,"uuid":"1697060","full_name":"opal/opal-jquery","owner":"opal","description":"jQuery for Opal","archived":false,"fork":false,"pushed_at":"2024-01-08T16:07:41.000Z","size":870,"stargazers_count":189,"open_issues_count":5,"forks_count":63,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-04-24T15:19:24.268Z","etag":null,"topics":["jquery","opal-jquery","ruby","zepto"],"latest_commit_sha":null,"homepage":"https://github.com/opal/opal-jquery#readme","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2011-05-03T16:28:46.000Z","updated_at":"2024-03-20T13:28:32.000Z","dependencies_parsed_at":"2024-01-08T17:11:12.988Z","dependency_job_id":null,"html_url":"https://github.com/opal/opal-jquery","commit_stats":{"total_commits":407,"total_committers":32,"mean_commits":12.71875,"dds":0.5724815724815725,"last_synced_commit":"a811015b2e0bf93cf651ccabed38c6ae4a601cbb"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opal%2Fopal-jquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opal%2Fopal-jquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opal%2Fopal-jquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opal%2Fopal-jquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opal","download_url":"https://codeload.github.com/opal/opal-jquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590066,"owners_count":21129742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jquery","opal-jquery","ruby","zepto"],"created_at":"2024-07-31T23:00:43.526Z","updated_at":"2025-04-12T15:34:58.222Z","avatar_url":"https://github.com/opal.png","language":"Ruby","readme":"# Opal jQuery\n\n*jQuery wrapper for Opal*\n\n[![Build Status](http://img.shields.io/travis/opal/opal-jquery/master.svg)](http://travis-ci.org/opal/opal-jquery)\n\n**opal-jquery** provides DOM access to opal by wrapping jQuery (or zepto)\nand providing a nice ruby syntax for dealing with jQuery instances.\n\n\u003c!-- See the Opal website for [documentation](http://opalrb.org/docs/jquery). --\u003e\n\n\n\n\n## Installation\n\nInstall opal-jquery from RubyGems:\n\n```\n$ gem install opal-jquery\n```\n\nOr include it in your Gemfile for Bundler:\n\n```ruby\ngem 'opal-jquery'\n```\n\n\n\n\n## Running Specs\n\nGet the dependencies:\n\n    $ bundle install\n\n\n### Browser\n\nYou can run the specs in any web browser, by running the `config.ru` rack file:\n\n    $ bundle exec rackup\n\nAnd then visiting `http://localhost:9292` in any web browser.\n\n\n### Phantomjs\n\nYou will need phantomjs to run the specs outside the browser.  It can\nbe downloaded at [http://phantomjs.org/download.html](http://phantomjs.org/download.html)\n\nOn osx you can install through homebrew\n\n    $ brew update; brew install phantomjs\n\nRun the tests inside a phantom.js runner:\n\n    $ bundle exec rake\n\n\n### Zepto\n\nopal-jquery also supports zepto. To run specs for zepto use the rake task:\n\n    $ bundle exec rake zepto\n\n\n\n\n## Getting Started\n\n\n### Usage\n\n`opal-jquery` can now be easily added to your opal application sources using a\nstandard require:\n\n```ruby\n# app/application.rb\nrequire 'opal'\nrequire 'jquery'\nrequire 'opal-jquery'\n\nalert \"Hello from jquery + opal\"\n```\n\n\u003e **Note**: this file requires two important dependencies, `jquery` and `opal-jquery`.\n\u003e You need to bring your own `jquery.js` file as the gem does not include one. If\n\u003e you are using the asset pipeline with rails, then this should be available\n\u003e already, otherwise download a copy and place it into `app/` or whichever directory\n\u003e you are compiling assets from. You can alternatively require a zepto instance.\n\nThe `#alert` method is provided by `opal-jquery`. If the message displays, then\n`jquery` support should be working.\n\n\n### How does opal-jquery work\n\n`opal-jquery` provides an `Element` class, whose instances are toll-free\nbridged instances of jquery objects. Just like ruby arrays are just javascript\narrays, `Element` instances are just jquery objects. This makes interaction\nwith jquery plugins much easier.\n\nAlso, `Element` will try to bridge with Zepto if it cannot find jQuery loaded,\nmaking it ideal for mobile applications as well.\n\n\n\n\n## Interacting with the DOM\n\n\n### Finding Elements\n\nopal-jquery provides the `Element` class, which can be used to find elements in\nthe current document:\n\n```ruby\nElement.find('#header')\n```\n\n`Element.find` is aliased to `Element[]`:\n\n```ruby\nElement['.my-class']\n```\n\nThese methods acts just like `$('selector')`, and can use any jQuery\ncompatible selector:\n\n```ruby\nElement.find('#navigation li:last')\n```\n\nThe result is just a jQuery instance, which is toll-free bridged to\ninstances of the `Element` class in ruby:\n\n```ruby\nElement.find('.foo').class\n# =\u003e Element\n```\n\nInstances of `Element` also have the `#find` method available for\nfinding elements within the scope of each DOM node represented by\nthe instance:\n\n```ruby\nel = Element.find('#header')\nel.find '.foo'\n# =\u003e #\u003cElement .... \u003e\n```\n\n\n### Running code on document ready\n\nJust like jQuery, opal-jquery requires the document to be ready to\nbe able to fully interact with the page. Any top level access should\nuse the `ready?` method:\n\n```ruby\nDocument.ready? do\n  alert \"document is ready to go!\"\nend\n```\n\nor the equivilent `Document.ready` promise which is useful when combined with other promises:\n\n```ruby\nDocument.ready.then do |ready|\n  alert \"Page is ready to use!\"\nend\n```\n\nNotice the use of the `Kernel#alert` method.\n\n\n### Event handling\n\nThe `Element#on` method is used to attach event handlers to elements:\n\n```ruby\nElement.find('#header').on :click do\n  puts \"The header was clicked!\"\nend\n```\n\nSelectors can also be passed as a second argument to handle events\non certain children:\n\n```ruby\nElement.find('#header').on(:click, '.foo') do\n  puts \"An element with a 'foo' class was clicked\"\nend\n```\n\nAn `Event` instance is optionally passed to block handlers as well,\nwhich is toll-free bridged to jquery events:\n\n```ruby\nElement.find('#my_link').on(:click) do |evt|\n  evt.stop_propagation\n  puts \"stopped the event!\"\nend\n```\n\nYou can access the element which triggered the event by `#current_target`.\n\n```ruby\nDocument.on :click do |evt|\n  puts \"clicked on: #{evt.current_target}\"\nend\n```\n\n\n### CSS styles and classnames\n\nThe various jQuery methods are available on `Element` instances:\n\n```ruby\nfoo = Element.find('.foo')\n\nfoo.add_class 'blue'\nfoo.remove_class 'foo'\nfoo.toggle_class 'selected'\n```\n\nThere are also added convenience methods for opal-jquery:\n\n```ruby\nfoo = Element.find('#header')\n\nfoo.class_name\n# =\u003e 'red lorry'\n\nfoo.class_name = 'yellow house'\n\nfoo.class_name\n# =\u003e 'yellow house'\n```\n\n`Element#css` also exists for getting/setting css styles:\n\n```ruby\nel = Element.find('#container')\nel.css 'color', 'blue'\nel.css 'color'\n# =\u003e 'blue'\n```\n\n\n\n\n## HTTP/AJAX requests\n\njQuery's Ajax implementation is also wrapped in the top level HTTP\nclass.\n\n```ruby\nHTTP.get(\"/users/1.json\") do |response|\n  puts response.body\n  # =\u003e \"{\\\"name\\\": \\\"Adam Beynon\\\"}\"\nend\n```\n\nThe block passed to this method is used as the handler when the request\nsucceeds, as well as when it fails. To determine whether the request\nwas successful, use the `ok?` method:\n\n```ruby\nHTTP.get(\"/users/2.json\") do |response|\n  if response.ok?\n    alert \"successful!\"\n  else\n    alert \"request failed :(\"\n  end\nend\n```\n\nIt is also possible to use a different handler for each case:\n\n```ruby\nrequest = HTTP.get(\"/users/3.json\")\n\nrequest.callback {\n  puts \"Request worked!\"\n}\n\nrequest.errback {\n  puts \"Request didn't work :(\"\n}\n```\n\nThe request is actually triggered inside the `HTTP.get` method, but due\nto the async nature of the request, the callback and errback handlers can\nbe added anytime before the request returns.\n\n\n### Handling responses\n\nWeb apps deal with JSON responses quite frequently, so there is a useful\n`#json` helper method to get the JSON content from a request:\n\n```ruby\nHTTP.get(\"/users.json\") do |response|\n  puts response.body\n  puts response.json\nend\n\n# =\u003e \"[{\\\"name\\\": \\\"Adam\\\"},{\\\"name\\\": \\\"Ben\\\"}]\"\n# =\u003e [{\"name\" =\u003e \"Adam\"}, {\"name\" =\u003e \"Ben\"}]\n```\n\nThe `#body` method will always return the raw response string.\n\nIf an error is encountered, then the `#status_code` method will hold the\nspecific error code from the underlying request:\n\n```ruby\nrequest = HTTP.get(\"/users/3.json\")\n\nrequest.callback { puts \"it worked!\" }\n\nrequest.errback { |response|\n  puts \"failed with status #{response.status_code}\"\n}\n```\n\n\n### Supplying an XHR method\n\nTo supply an XHR callback include a lambda with the `xhr` option:\n\n```ruby\nupdate_progress = lambda do\n  xhr = `new window.XMLHttpRequest()`\n  update_progress = lambda do |evt|\n    # update your progress here\n  end\n  `xhr.upload.addEventListener(\"progress\", update_progress, false)`\n  xhr\nend\n\ncloud_xfer = HTTP.put \"http://my.cloud.storage/location\", xhr: update_progress, ... etc ...\n```\n\n\n\n\n## Usage of JQuery plugins\nExtra plugins used for JQuery aren't available to ruby code by default, you will have to `expose` these functions to opal-jquery.\n\n```ruby\nElement.expose :cool_plugin\n```\n\nArguments 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.\n\n```ruby\nElement.expose :cool_plugin\n\nel = Element['.html_element']\nel.cool_plugin({argument: 'value', argument1: 1000}.to_n)\n```\n\n\n##  License\n\n(The MIT License)\n\nCopyright (C) 2013 by Adam Beynon\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\n","funding_links":[],"categories":["Uncategorized","Ruby"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopal%2Fopal-jquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopal%2Fopal-jquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopal%2Fopal-jquery/lists"}