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

opalla 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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'