Skip to content

Commit b57b408

Browse files
hmdnehmdne
committed
Update README, add examples
1 parent 16c0da9 commit b57b408

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+941
-56
lines changed

‎LICENSE

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
Copyright (C) 2014 by meh
1+
Copyright (C) 2013-2018 by meh
2+
Copyright (C) 2019-2021 hmdne and the Opal-Browser contributors
23

34
Permission is hereby granted, free of charge, to any person obtaining a copy
45
of this software and associated documentation files (the "Software"), to deal

‎README.md

+106-54
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,31 @@
1-
Browser support for Opal
2-
========================
1+
Opal-Browser - Client side web development in pure Ruby, using Opal
2+
===================================================================
33

4-
[![Build Status](https://secure.travis-ci.org/opal/opal-browser.svg?branch=master)](http://travis-ci.org/opal/opal-browser)
54
[![Gem Version](https://badge.fury.io/rb/opal-browser.svg)](http://badge.fury.io/rb/opal-browser)
65
[![Code Climate](http://img.shields.io/codeclimate/github/opal/opal-browser.svg)](https://codeclimate.com/github/opal/opal-browser)
76

87

9-
This library aims to be a full-blown wrapper for all the browser API including
8+
This library aims to be a full-blown wrapper for all the browser API as defined by
109
HTML5.
1110

11+
It provides a very JQuery-like interface to DOM, but itself it doesn't use nor
12+
require JQuery nor opal-jquery (which is an alternative library for interfacing
13+
the web browser). The main difference though is that Opal-Browser goes far beyond
14+
what JQuery does.
15+
1216
Usage
1317
=====
1418

15-
_Server side (config.ru, Rakefile, Rails, Sinatra, etc.)_
19+
_Gemfile_
20+
21+
```ruby
22+
source 'https://rubygems.org/'
23+
24+
gem 'paggio', github: 'hmdne/paggio'
25+
gem 'opal-browser'
26+
```
27+
28+
_Server side (config.ru, Rakefile, Rails, Sinatra, Roda, etc. - not needed for static compilation)_
1629

1730
```ruby
1831
require 'opal-browser'
@@ -23,18 +36,47 @@ _Browser side_
2336

2437
```ruby
2538
require 'opal'
26-
require 'browser'
39+
require 'native'
40+
require 'promise'
41+
require 'browser/setup/full'
42+
2743
# Your Opal code here
44+
$document.body << "Hello world!"
2845
```
2946

30-
_Static Compile JS_
47+
_Static Compile Opal + Opal-Browser library_
48+
3149
```bash
32-
opal -I ./opal --gem paggio --compile opal/browser.rb > browser.js
50+
bundle exec opal -c -q opal-browser -p native -p promise -p browser/setup/full -e '#' -E > opal-browser.js
3351
```
3452

53+
_Static Compile your application_
54+
55+
```bash
56+
bundle exec opal -Oc -s opal -s native -s promise -s browser/setup/full app/application.rb > application.js
57+
```
58+
59+
_And load it in HTML!_
60+
61+
```html
62+
<!DOCTYPE html>
63+
<html>
64+
<head>
65+
<title>My Application</title>
66+
</head>
67+
<body>
68+
<script src='opal-browser.js' onload='Opal.require("native"); Opal.require("promise"); Opal.require("browser/setup/full");'></script>
69+
<script src='application.js'></script>
70+
</body>
71+
</html>
72+
```
73+
74+
See the examples/integrations/ directory for various ideas on how to quickly start
75+
development using opal-browser.
76+
3577
Features
3678
========
37-
This is a list of the currently wrapped features and some details on them.
79+
This is a list of many currently wrapped features and some details on them.
3880

3981
DOM
4082
---
@@ -47,8 +89,8 @@ $document.ready do
4789
end
4890
```
4991

50-
It also supports a markaby inspired builder DSL which generates DOM nodes
51-
directly instead of creating a string.
92+
It also supports a markaby inspired builder DSL (using Paggio) which generates
93+
DOM nodes directly instead of creating a string.
5294

5395
```ruby
5496
$document.ready do
@@ -60,12 +102,37 @@ $document.ready do
60102
end
61103
```
62104

105+
Events
106+
------
107+
108+
Add an event to a given element:
109+
110+
```ruby
111+
$document.at_css("button").on(:click) do |e|
112+
e.prevent # Prevent the default action (eg. form submission)
113+
alert "Button clicked!"
114+
end
115+
```
116+
117+
Or add it to a parent element and use a delegator, so that an event gets fired
118+
when any button children of `$document` is clicked:
119+
120+
```ruby
121+
$document.on(:click, "button") do |e|
122+
e.prevent
123+
# e.on is a button that has been clicked
124+
e.on.inner_text = "Clicked!"
125+
end
126+
```
127+
128+
Run an event once with `#one` instead of `#on`, or disable an event with `#off`.
129+
63130
CSSOM
64131
-----
65-
CSSOM support is still incomplete but the useful parts are implemented, this
66-
includes a DSL for generating a CSS style and the same DSL is also used to
67-
change style declarations (which can either belong to a `DOM::Element` or a
68-
`CSS::Rule::Style`).
132+
CSSOM support (using Paggio) is still incomplete but the useful parts are
133+
implemented, this includes a DSL for generating a CSS style and the same DSL
134+
is also used to change style declarations (which can either belong to a
135+
`DOM::Element` or a `CSS::Rule::Style`).
69136

70137
```ruby
71138
$document.body.style.apply {
@@ -140,9 +207,16 @@ Storage
140207
The HTML5 Storage API has been wrapped and it exports a single Storage class
141208
that uses the most appropriate and available API to store data locally.
142209

210+
```ruby
211+
require 'browser/storage'
212+
213+
$storage = $window.storage
214+
$storage[:hello] = "world"
215+
```
216+
143217
Database SQL
144218
------------
145-
WebSQL has been fully wrapped.
219+
WebSQL has been fully wrapped (Chromium-only)
146220

147221
```ruby
148222
require 'browser/database/sql'
@@ -166,55 +240,33 @@ db.transaction {|t|
166240
Browser support
167241
===============
168242

169-
* Internet Explorer 6+
170-
* Firefox (Current - 1) or Current
171-
* Chrome (Current - 1) or Current
172-
* Safari 5.1+
173-
* Opera 12.1x or (Current - 1) or Current
243+
* Edge (Current - 3) to Current
244+
* Firefox (Current - 3) to Current
245+
* Chrome (Current - 3) to Current
246+
* Safari (Current - 3) to Current
247+
* Opera (Current - 3) to Current
174248

175249
Any problem above browsers should be considered and reported as a bug.
176250

177-
(Current - 1) or Current denotes that we support the current stable version of
178-
the browser and the version that preceded it. For example, if the current
179-
version of a browser is 24.x, we support the 24.x and 23.x versions.
180-
181-
12.1x or (Current - 1) or Current denotes that we support Opera 12.1x as well
182-
as last 2 versions of Opera. For example, if the current Opera version is 20.x,
183-
we support Opera 12.1x, 19.x and 20.x but not Opera 15.x through 18.x.
184-
185-
Cross-browser testing sponsored by [BrowserStack](http://browserstack.com).
186-
187-
CSS selectors
188-
-------------
189-
Older browsers do not support CSS selector in queries, this means you'll need
190-
external polyfills for this.
191-
192-
The suggested polyfill is [Sizzle](http://sizzlejs.com/), require it **before**
193-
opal-browser.
194-
195-
JSON parsing
196-
------------
197-
Older browsers don't support JSON parsing natively, this means you'll need
198-
external polyfills for this.
199-
200-
The suggested polyfill is [json2](https://github.com/douglascrockford/JSON-js),
201-
require it **before** opal-browser.
251+
(Current - 3) to Current denotes that we support the current major stable version
252+
of the browser and 3 versions preceding it. For example, if the current version
253+
of a browser is 24.x, we support all versions between 21.x to 24.x.
202254

203-
XPath support
204-
-------------
205-
Not all browsers support XPath queries, I'm looking at you Internet Explorer,
206-
this means you'll need external polyfills for this.
255+
We will accept compatibility patches for even earlier browser versions. Opal-Browser
256+
is written in such a way, that it integrates a robust compatibility check system,
257+
similar to Modernizr, and the history of this library goes even as far as supporting
258+
Internet Explorer 6.
207259

208-
The suggested polyfill is
209-
[wgxpath](https://code.google.com/p/wicked-good-xpath/), require it **before**
210-
opal-browser.
260+
See the [polyfills documentation](docs/polyfills.md) if you wish to polyfill some
261+
behaviors not supported by the ancient web browsers (like `querySelectorAll`).
211262

212263
License
213264
=======
214265

215266
(The MIT License)
216267

217-
Copyright (C) 2014 by meh
268+
Copyright (C) 2013-2018 by meh<br>
269+
Copyright (C) 2019-2021 hmdne and the Opal-Browser contributors
218270

219271
Permission is hereby granted, free of charge, to any person obtaining a copy
220272
of this software and associated documentation files (the "Software"), to deal

‎docs/polyfills.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
CSS selectors
2+
-------------
3+
Older browsers do not support CSS selector in queries, this means you'll need
4+
external polyfills for this.
5+
6+
The suggested polyfill is [Sizzle](http://sizzlejs.com/), require it **before**
7+
opal-browser.
8+
9+
JSON parsing
10+
------------
11+
Older browsers don't support JSON parsing natively, this means you'll need
12+
external polyfills for this.
13+
14+
The suggested polyfill is [json2](https://github.com/douglascrockford/JSON-js),
15+
require it **before** opal-browser.
16+
17+
XPath support
18+
-------------
19+
Not all browsers support XPath queries, I'm looking at you Internet Explorer,
20+
this means you'll need external polyfills for this.
21+
22+
The suggested polyfill is
23+
[wgxpath](https://code.google.com/p/wicked-good-xpath/), require it **before**
24+
opal-browser.

‎examples/2048/Gemfile

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
source "https://rubygems.org"
2+
3+
gem "opal-sprockets"
4+
gem "puma"
5+
gem "rack"
6+
gem "paggio", github: "hmdne/paggio"
7+
gem "opal-browser", path: "../.."

‎examples/2048/README.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2048 clone with Opal-Browser
2+
============================
3+
4+
A 167 line implementation of 2048, but in Ruby inside a browser!
5+
6+
To install, run:
7+
8+
$ bundle install
9+
10+
Start server
11+
------------
12+
13+
$ bundle exec rackup

0 commit comments

Comments
 (0)