RubyGems - opalla - Versions diffs - 0.1.0 → 0.1.1 - Mend

opalla 0.1.0 → 0.1.1

Files changed (29) hide show

checksums.yaml +4 -4
data/README.md +394 -14
data/lib/opalla.rb +11 -4
data/lib/opalla/component_helper.rb +28 -0
data/lib/opalla/controller_add_on.rb +11 -0
data/lib/opalla/engine.rb +27 -0
data/lib/opalla/middleware.rb +20 -0
data/lib/opalla/util.rb +63 -0
data/lib/opalla/version.rb +1 -1
data/lib/rails/generators/opalla/assets_generator.rb +23 -0
data/lib/rails/generators/opalla/collection_generator.rb +19 -0
data/lib/rails/generators/opalla/component_generator.rb +27 -0
data/lib/rails/generators/opalla/install_generator.rb +62 -0
data/lib/rails/generators/opalla/model_generator.rb +19 -0
data/opal/collection.rb +71 -0
data/opal/component.rb +136 -0
data/opal/controller.rb +60 -0
data/opal/diffDOM.js +1371 -0
data/opal/diff_dom.rb +26 -0
data/opal/element.rb +17 -0
data/opal/hex_random.rb +12 -0
data/opal/model.rb +50 -0
data/opal/opalla.rb +21 -0
data/opal/router.rb +66 -0
data/opal/sha1.js +366 -0
data/opal/view_helper.rb +168 -0
data/opalla.gemspec +8 -0
data/opalla.gif +0 -0
metadata +109 -2

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 809e267708644b22d52a983becd190cc66156859
-  data.tar.gz: c37af2cbd9a4c8503e3d31b528b507fdd41abe6f
+  metadata.gz: b420c0145b5c3f9a19e09a13662039babd80df2f
+  data.tar.gz: 9aad2ce70fb5d1b98fc5039c4dbe3c727e2e63e3
 SHA512:
-  metadata.gz: 0ea42241f2f4bcd4c1a71bf58a35cd5e8a70cec469cdc08c8c046fa2e8349cd03eda1aebc0c47774774c3220dc3560e7fc459a60d68a39db9f2b5e44a24899d1
-  data.tar.gz: 58c9f272c6cfa541268dc8317f630b4a5109d07f68f1cd8284c5a76cac041c0dfed3267954b8ccffb5839c307c2007aeb9de4ec55e4b9aa4da35dacc3f11d49a
+  metadata.gz: a1ff2aeb30b377ffcbc3718b73642be5338251088750a588ebebc6d9db4aca5cad6ea9a51c1c8b8108d93df15a7c148010bf06b5120a3a1844ba751a52093fbe
+  data.tar.gz: 5a83dc76cdfaee6cfc9b0359dbcd981c5273c2748835ef1c405e13b50f14adee079a2049229c358ca8b489b34a9840bc7ca7e36de19bafd381d9ccf36ef7a9a8

data/README.md CHANGED

@@ -1,41 +1,421 @@
 # Opalla
+![Opalla](opalla.gif)
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/opalla`. To experiment with that code, run `bin/console` for an interactive prompt.
+Opalla brings Rails way to the front-end. It follows a Rails conventions mixed with a little of Backbone.
-TODO: Delete this and the text above, and describe your gem
+It's built on top of `opal` and `opal-rails`.
 ## Installation
 Add this line to your application's Gemfile:
 ```ruby
+gem 'opal-rails'
 gem 'opalla'
 ```
+Additionally, if you want to use `haml`, add:
+```ruby
+gem 'opal-haml'
+```
+(That's actually ultra-highly recommended)
 And then execute:
-    $ bundle
+```
+$ bundle
+```
+Then run:
+```sh
+rails g opalla:install
+```
+Opalla is a front-end MVC framework. So you will to have this folder structure:
-Or install it yourself as:
+```
+your_app
+  \_app
+    \_assets
+      \_javascripts
+        \_components
+        \_controllers
+        \_lib
+        \_collections
+        \_models
+        \_views
+```
-    $ gem install opalla
+And that’s it! You’re ready to drive Opalla.
 ## Usage
-TODO: Write usage instructions here
+### Router & Controllers
+It all starts with the Opalla router. It will catch the current URL and direct to the controller/action, exactly like Rails does.
-## Development
+So for example, say you have the following route:
+```ruby
+get 'pages#index'
+```
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+You can generate controllers by running the default Rails controller generator:
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```sh
-## Contributing
+rails g controller pages
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/opalla. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+```
+If you just installed Opalla on your existing app and want to generate Opalla controllers for it, just re-run the command above and leave Rails do the rest! (It won't overwrite anything unless you explicitly ask for).
-## License
+`Opalla::Router` will automatically import the routes and instantiate the `PagesController` inside your `javascripts/controller/pages_controller.rb` and trigger the `index` action:
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+```ruby
+class PagesController < ApplicationController
+  def index
+    el.html 'Hello World!'
+  end
+end
+```
+That would replace the `<body>` tag with 'Hello World', as the default `el` for a controller. If you want to change that, you can add `el 'YOU_SELECTOR_HERE'`, in a jQuery selector fashion. So for example:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  def index
+    el.html 'Hello World!'
+  end
+end
+```
+### Templates
+Your Opalla templates will live under `app/assets/javascripts/views`. There you have `./controllers` and `./components`. Note that components templates should start their names with `_`, just like `partials`.
+Opalla will automatically have your templates folder added to your server side (Rails). So that means your templates will be rendered server-side and client-side. Yay!
+The template will be able to get any access variables (`@variable`) and `methods`. Please note that you have to have both set on server and client sides.
+Server-side:
+```ruby
+class PagesController < ApplicationController
+  helper_method :something_awesome
+  def index
+    @dude = 'Pedro'
+  end
+  def something_awesome
+    'Rails'
+  end
+end
+```
+Client-side, note that all methods are available by default, no need to set them as `helper_methods`:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  def index
+    @dude = 'Pedro'
+    render
+  end
+  def something_awesome
+    'Rails'
+  end
+end
+```
+The following `haml` layout would work for both sides:
+```haml
+%main
+  The dude is called #{@dude}.
+  He works with #{something_awesome}
+```
+If you want to share variables with your front-end Opalla MVC, that’s ok. Use the `expose` method automatically available on your server-side controllers:
+```ruby
+  def index
+    expose message: 'Hello World!',
+           my_array: [1,2,3]
+  end
+```
+And then you can use the data normally in your views:
+```haml
+  %p= message
+  %p= my_array.join('/')
+```
+That variables will be automatically available on both sides of your application.
+### Components
+`app/assets/javascripts/components` is where you components live. They will by default render the folder located on `app/assets/javascripts/views/components/_COMPONENT_NAME` (without the '_component' part of the name)
+To create components:
+```sh
+rails g opalla:component my_component
+```
+They are instantiated and rendered from the controller layout, like this:
+```haml
+%main
+  The dude is called #{@dude}.
+  He works with #{something_awesome}
+  component(:contact_box)
+```
+That will look for the component `app/assets/javascripts/components/contact_box_component.rb`:
+```ruby
+class ContactBoxComponent < ApplicationComponent
+end
+```
+#### Model Data
+The components can get their data from a `Opalla::Model`. Here's how it goes:
+First, generate your model:
+```sh
+  bin/rails g opalla:model contact_info
+```
+Let’s add a simple attr_accessor:
+```ruby
+  class Opalla::Model
+    attr_accessor :email
+  end
+```
+In the server-side controller you can expose the data, so that will be rendered from the server as default (no one wants blank pages to maybe hurt the SEO):
+```ruby
+  class PagesController < ApplicationController
+    @contact_info = ContactInfo.new
+    @contact_info.email = 'pedro@pedromaciel.com'
+    expose contact: @contact_info
+  end
+```
+Then, in your server side, you don’t need anything for this case, except for render:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  def index
+     render
+  end
+end
+```
+In the controller template:
+```haml
+%main
+  component(model: @contact_box)
+```
+In the component template:
+```haml
+  .contact-info
+    .email= model.email
+```
+In the model (`app/assets/javascripts/models/contact_info.rb`):
+```ruby
+class ContactInfo
+  def initialize
+  end
+end
+```
+### Collection Data
+Generate collections:
+```sh
+  bin/rails g opalla:collection products
+```
+Opalla will automatically assume that the model is the singular name. So `products` for example is a collection of `product` model. So you have to have the `product` model as well.
+When working with collection components, you’ll often want to work with `data-attributes`. Opalla has a nifty way to help you:
+Consider you have the following component:
+```ruby
+  class ProductComponent < ApplicationComponent
+  end
+```
+With the following collection (notice the binding):
+```ruby
+  class Products < Opalla::Collection
+    bind :price, :category
+  end
+```
+On your collection model, you set data:
+```ruby
+  class Product < Opalla::Model
+    data :price, :category, :model_id
+  end
+```
+On your component template:
+```haml
+  .products
+    collection.each |product|
+      .product{data=product.data}
+    end
+  end
+```
+That will generate data attributes: `data-price`, `data-category`, `data-model-id`, the last enabling you to incorporate events in a very simple fashion
+```ruby
+  class ProductComponent < ApplicationComponent
+    events 'click .product' -> target { buy(collection.find(target)) }
+  end
+```
+That would trigger the buy element providing the `model` as argument. That’s because the `find method` in collections will look for the element or closest ancestor that has a `data-model-id` and return the model itself for you. Really easy!
+Check the next chapter to see more ways on how collections can be very useful.
+### Bindings
+You can bind data from a model or collection to the component. That will trigger a `#render` action on the component:
+```ruby
+class ContactBoxComponent < ApplicationComponent
+  bind :email, :name
+end
+```
+And that's it! Everytime the resource attributes change, being it a `model` or a `collection`, the component will be re-rendered.
+#### 2-way binding
+If you assign a `[data-bind='ATTRIBUTE_NAME']` to an input element on your template, it will change look for the closest ancestor that has `[data-model-id]` and change its attribute whenever you change the input.
+Example:
+```haml
+.product{data: product.data} # it is expected you set the model data
+  input{data-bind: 'name'}
+```
+### Events
+Similarly to Backbone, you can add events in the following way:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  events 'click a' => :do_something
+  def index
+    el.html 'Hello World!'
+  end
+  def do_something
+    alert 'I\'m doing something!'
+  end
+end
+```
+You can also provide a `lambda` instead:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  events 'click a' => { alert "I'm doing something!" }
+  def index
+    el.html 'Hello World!'
+  end
+end
+```
+You can also access the targetted object like this:
+```ruby
+class PagesController < ApplicationController
+  el '.main-content'
+  events 'click a' => target { alert 'I\'m doing something!' }
+  def index
+    el.html 'Hello World!'
+  end
+  def do_something
+  end
+end
+```
+Please note that all events have their default behavior prevented by default.
+## Development
+The project is on beta phase. It's missing:
+* Specs
+* Tests
+* Rubocops
+* ActiveRecord models support
+Fork and make a PR. Or talk to me at `pedro@pedromaciel.com`.
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/opalla.rb CHANGED

@@ -1,5 +1,12 @@
-require "opalla/version"
+require 'ostruct'
+require 'bundler'; Bundler.require
-module Opalla
-  # Your code goes here...
-end
+require 'opal-browser'
+require 'opalla/version'
+require 'opalla/component_helper'
+require 'opalla/controller_add_on'
+require 'opalla/util'
+require 'opalla/middleware'
+require 'opalla/engine'
+require_relative '../opal/model'
+require_relative '../opal/collection'