opal 0.8.0 → 0.8.1.rc1

data/docs/libraries.md

@@ -0,0 +1,36 @@
+# Using external libraries in your Opal app
+
+As described in the getting started docs, opal uses a load path which works
+with sprockets to create a set of locations which opal can require files
+from. If you want to add a directory to this load path, you can add it to
+either the global environment, or a sprockets instance.
+
+### Global Environment
+
+In the `Opal` module, a property `paths` is used to hold the load paths which
+`Opal` uses to require files from. You can add a directory to this:
+
+```ruby
+Opal.append_path '../my_lib'
+```
+
+Now, any ruby files in this directory can be discovered.
+
+### Sprockets instances
+
+`Opal::Environment` is a subclass of the sprockets environment class which
+can have instance specific paths added to it. This class will inherit all
+global paths, but you can also add your instance paths as:
+
+```ruby
+env = Opal::Environment.new
+env.append_path '../my_lib'
+```
+
+## with Opal::Builder
+
+_WIP_
+
+## With opal-sprockets
+
+_WIP_

data/docs/promises.md

@@ -0,0 +1,64 @@
+# Promise
+
+`Promise` is a class available in the Opal stdlib for helping structure asynchronous code.
+
+It can be required inside any Opal applicaton:
+
+```ruby
+require 'promise'
+```
+
+## Usage
+
+This example shows how to use a `HTTP` request from `opal-jquery` from a callback style, into a promise style handler.
+
+```ruby
+def get_json(url)
+  promise = Promise.new
+
+  HTTP.get(url) do |response|
+    if response.ok?
+      promise.resolve response.json
+    else
+      promise.reject response
+    end
+  end
+
+  promise
+end
+
+get_json('/users/1.json').then do |json|
+  puts "Got data: #{json}"
+end.fail do |res|
+  alert "It didn't work :( #{res}"
+end
+```
+
+A promise can only be resolved or rejected once.
+
+### Chaining Promises
+
+Promises become useful when chained together. The prevous example could be extended to get another object from the result of the first request.
+
+```ruby
+get_json('/users/1.json').then do |json|
+  get_json("/posts/#{json[:post_id]}.json")
+end.then do |post|
+  puts "got post: #{post}"
+end
+```
+
+### Composing Promises
+
+`Promise.when` can be used to wait for more than 1 promise to resolve (or reject). Lets assume we wanted to get 2 different users:
+
+```ruby
+first = get_json '/users/1.json'
+second = get_json '/users/2.json'
+
+Promise.when(first, second).then do |user1, user2|
+  puts "got users: #{user1}, #{user2}"
+end.fail do
+  alert "Something bad happened"
+end
+```

data/docs/rails.md

@@ -0,0 +1,116 @@
+# Opal in a Rails application
+
+Add Opal to your Gemfile:
+
+``` ruby
+gem 'opal-rails'
+```
+
+Or to start off with Opal when you build your new Rails app:
+
+```bash
+rails new <app-name> --javascript=opal
+```
+
+## Basic usage through the asset pipeline
+
+```js
+// app/assets/application.js.rb
+
+//= require opal
+//= require opal_ujs
+//= require turbolinks
+//= require_tree .
+```
+
+Opal requires are forwarded to the Asset Pipeline at compile time (similarly to what happens for RubyMotion). You can use either the `.rb` or `.opal` extension:
+
+```ruby
+# app/assets/javascripts/greeter.js.rb
+
+puts "G'day world!" # check the console!
+
+# Dom manipulation
+require 'opal-jquery'
+
+Document.ready? do
+  Element.find('body > header').html = '<h1>Hi there!</h1>'
+end
+```
+
+
+
+
+### As a template
+
+You can use it for your views too, it even inherits instance and local variables from actions:
+
+```ruby
+# app/controllers/posts_controller.rb
+
+def create
+  @post = Post.create!(params[:post])
+  render type: :js, locals: {comments_html: render_to_string(@post.comments)}
+end
+```
+
+Each assign is filtered through JSON so it's reduced to basic types:
+
+```ruby
+# app/views/posts/create.js.opal
+
+post = Element.find('.post')
+post.find('.title').html    = @post[:title]
+post.find('.body').html     = @post[:body]
+post.find('.comments').html = comments_html
+```
+
+
+### As a Haml filter (optional)
+
+Of course you need to require `haml-rails` separately since its presence is not assumed
+
+```haml
+-# app/views/posts/show.html.haml
+
+%article.post
+  %h1.title= post.title
+  .body= post.body
+
+%a#show-comments Display Comments!
+
+.comments(style="display:none;")
+  - post.comments.each do |comment|
+    .comment= comment.body
+
+:opal
+  Document.ready? do
+    Element.find('#show-comments').on :click do |click|
+      click.prevent_default
+      click.current_target.hide
+      Element.find('.comments').effect(:fade_in)
+    end
+  end
+```
+
+
+### Spec!
+
+Add specs into `app/assets/javascripts/spec`:
+
+and then a spec folder with you specs!
+
+```ruby
+# app/assets/javascripts/spec/example_spec.js.rb
+
+describe 'a spec' do
+  it 'has successful examples' do
+    'I run'.should =~ /run/
+  end
+end
+```
+
+Then visit `/opal_spec` from your app and **reload at will**.
+
+![1 examples, 0 failures](http://f.cl.ly/items/001n0V0g0u0v14160W2G/Schermata%2007-2456110%20alle%201.06.29%20am.png)
+

data/docs/rspec.md

@@ -0,0 +1,98 @@
+# RSpec
+
+`opal-rspec` allows opal to use rspec for running specs in javascript
+environments. It comes with built-in support for running rspec with custom
+`phantomjs` and standard web browser formatters. Also, async spec examples
+are supported to reflect browser usage of ruby applications.
+
+```ruby
+describe User do
+  it "can be created with a name" do
+    expect(User.new).to_not be_persisted
+  end
+end
+```
+
+### Installation
+
+Add the `opal-rspec` gem to your Gemfile:
+
+```ruby
+# Gemfile
+gem 'opal'
+gem 'opal-rspec'
+```
+
+## Running specs
+
+### phantomjs
+
+To run specs, a rake task can be added which will load all spec files
+from `spec/`:
+
+```ruby
+# Rakefile
+require 'opal/rspec/rake_task'
+Opal::RSpec::RakeTask.new(:default)
+```
+
+Then, to run your specs inside phantomjs, just run the rake task:
+
+```sh
+$ bundle exec rake
+```
+
+### In a Browser
+
+`opal-rspec` can use sprockets to build and serve specs over a simple rack server. Add the following to a `config.ru` file:
+
+```ruby
+# config.ru
+require 'bundler'
+Bundler.require
+
+run Opal::Server.new { |s|
+  s.main = 'opal/rspec/sprockets_runner'
+  s.append_path 'spec'
+  s.debug = false
+}
+```
+
+Then run the rack server bundle exec rackup and visit `http://localhost:9292` in any web browser.
+
+## Async examples
+
+`opal-rspec` adds support for async specs to rspec. These specs are defined using
+`#async` instead of `#it`:
+
+```ruby
+describe MyClass do
+  # normal example
+  it 'does something' do
+    expect(:foo).to eq(:foo)
+  end
+
+  # async example
+  async 'does something else, too' do
+    # ...
+  end
+end
+```
+
+This just marks the example as running async. To actually handle the async result,
+you also need to use a `run_async` call inside some future handler:
+
+```ruby
+async 'HTTP requests should work' do
+  HTTP.get('/users/1.json') do |res|
+    run_async {
+      expect(res).to be_ok
+    }
+  end
+end
+```
+
+The block passed to `run_async` informs the runner that this spec is finished
+so it can move on. Any failures/expectations run inside this block will be run
+in the context of the example.
+

data/docs/sinatra.md

@@ -0,0 +1,79 @@
+# Using Opal with Sinatra
+
+Add Opal to your Gemfile (or install using `gem`):
+
+```ruby
+# Gemfile
+gem 'sinatra'
+gem 'opal', '~> 0.6.2'
+```
+
+Opal uses `sprockets` as its default build system, so the asset-pipeline
+from rails can be mimicked here to map all ruby assets in the `/assets`
+path to be compiled using opal.
+
+## Basic Application
+
+```ruby
+# config.ru
+require 'opal'
+require 'sinatra'
+
+opal = Opal::Server.new {|s|
+  s.append_path 'app'
+  s.main = 'application'
+}
+
+map opal.source_maps.prefix do
+  run opal.source_maps
+end
+
+map '/assets' do
+  run opal.sprockets
+end
+
+get '/' do
+  <<-HTML
+    <!doctype html>
+    <html>
+      <head>
+        <script src="/assets/application.js"></script>
+      </head>
+    </html>
+  HTML
+end
+
+run Sinatra::Application
+```
+
+This creates a simple sprockets instance under the `/assets` path. Opal
+uses a set of load paths to compile assets using sprockets. The
+`Opal::Environment` instance is a simple subclass of `Sprockets::Environment`
+with all the custom opal paths added automatically.
+
+This `env` object includes all the opal corelib and stdlib paths. To add
+any custom application directories, you must add them to the load path using
+`env.append_path`. You can now add an `app/application.rb` file into this
+added path with some basic content:
+
+```ruby
+# app/application.rb
+require 'opal'
+
+puts "wow, running ruby!"
+```
+
+It is necessary to require the opal corelib (seen in the `require` call) above.
+This just makes the Opal runtime and corelib available. Then it is possible to
+use all the corelib methods and classes, e.g. `Kernel#puts` as seen above.
+
+### Running Application
+
+As this is just a simple sinatra application, you can run it:
+
+```sh
+$ bundle exec rackup
+```
+
+And point your browser towards `http://localhost:9292/` and view the browser
+debug console. You should see this message printed.

data/docs/source_maps.md

@@ -0,0 +1,49 @@
+# Source maps
+
+Source maps are available (on current stable release, v0.6.x) even without explicit support from Sprockets in a sort of hackish way.
+
+_As such even if they generally work fine there are some limitations and edge case issues._
+
+NOTE: Currently on `master` branch sourcemaps are work-in-progress and probably will integrate with the upcoming Sprockets 4 that has integrated support for them.
+
+#### Processor `source_map_enabled` flag
+To enable sourcemaps in the Sprockets processor you need to turn on the relative flag:
+
+```ruby
+Opal::Processor.source_map_enabled = true # default
+```
+
+
+#### Sprockets debug mode
+
+The  sourcemaps only work with Sprockets in debug mode because they are generated just for single files.
+
+
+## Enable source maps
+
+### Rails
+
+Rails has debug mode already enabled in development environment with the following line from `config/environments/development.rb`:
+
+```ruby
+# Debug mode disables concatenation and preprocessing of assets.
+# This option may cause significant delays in view rendering with a large
+# number of complex assets.
+config.assets.debug = true
+```
+
+`opal-rails` also enables sourcemaps in development so with the standard setup you ready to go.
+
+
+### Sinatra
+
+You can add `Opal::Server` as in the official example: [sinatra/config.ru](https://github.com/opal/opal/blob/0-6-stable/examples/sinatra/config.ru).
+
+### Opal::Server
+
+`Opal::Server` implements sourcemaps and can be used alone or with `Rack::Cascade` in conjunction with other apps.
+
+### Opal::Environment
+
+`Opal::Environment` is a bit lower level and doesn't support source maps by itself.
+