README.md in initjs-1.0.1 vs README.md in initjs-2.0.0.beta1
- old
+ new
@@ -1,67 +1,67 @@
# Initjs [](https://travis-ci.org/josemarluedke/initjs) [](https://codeclimate.com/github/josemarluedke/initjs) [](https://gemnasium.com/josemarluedke/initjs) [](http://badge.fury.io/rb/initjs)
Initjs is a RubyGem that helps your organize your javascript files using Rails' asset pipeline. Providing a simple and automatic way to execute your javascript for a specific page.
-Works fine with Turbolinks from Rails.
+Works fine with Turbolinks and pjax.
## Javascript structure example
-The structure you need follow is the same of your controller and actions on a Rails app.
-You can use a namespace too.
+The structure you need follow is the same of your controller and actions on your Rails application.
-### Simple javascript functions
+### Simple objects
```coffee
-# app/assets/javascripts/app_name/posts/new.js.coffee
AppName.Posts ?= {}
-AppName.Posts.New = ->
- # Javascript for the page "posts/new"
+AppName.Posts.New =
+ init: ->
+ # Javascript for the page "posts/new"
+ modules: -> []
```
```coffee
-# app/assets/javascripts/app_name/posts/show.js.coffee
AppName.Posts ?= {}
-AppName.Posts.Show = ->
- # Javascript for the page "posts/1"
+AppName.Posts.Show =
+ init: ->
+ # Javascript for the page "posts/1"
+ modules: -> []
```
+
+We support namespaces too:
+
```coffee
-# app/assets/javascripts/app_name/blog/posts/show.js.coffee
AppName.Blog ?= {}
AppName.Blog.Posts ?= {}
-AppName.Blog.Posts.Show = ->
- # Javascript for the page "blog/posts/1"
+AppName.Blog.Posts.Show =
+ init: ->
+ # Javascript for the page "blog/posts/1"
+ modules: -> []
```
-### Using Backbone.js
+Also you can use just a function, if you'll not use modules.
```coffee
-# app/assets/javascripts/app_name/posts/new.js.coffee
AppName.Posts ?= {}
-AppName.Posts.New = Backbone.View.extend
+AppName.Posts.New = ->
# Javascript for the page "posts/new"
```
+
+### Using Backbone.js
+
```coffee
-# app/assets/javascripts/app_name/posts/show.js.coffee
AppName.Posts ?= {}
-AppName.Posts.Show = Backbone.View.extend
- # Javascript for the page "posts/1"
+AppName.Posts.New =
+ init: Backbone.View.extend
+ # Javascript for the page "posts/new"
+ modules: -> []
```
-```coffee
-# app/assets/javascripts/app_name/blog/posts/show.js.coffee
-AppName.Blog ?= {}
-AppName.Blog.Posts ?= {}
-AppName.Blog.Posts.Show = Backbone.View.extend
- # Javascript for the page "blog/posts/1"
-```
-
## Requirements
- Rails 3.1 or higher
- jQuery (`jquery-rails`)
- CoffeeScript (`coffee-rails`)
@@ -77,45 +77,147 @@
Run the generator:
rails generate initjs:install
-Make sure initjs generator has injected `//= require app_name/app_name.js` and `//= require init.js` to your Javascript manifest file (usually found at `app/assets/javascripts/application.js`).
+Make sure initjs generator has injected `//= require app_name/app_name.js` and `//= require init.js` to your Javascript manifest file (usually in `app/assets/javascripts/application.js`).
## Usage
-Include the Initjs tag in your application layout (usually found at `app/view/layouts/application.html.erb`) right after the opening of the body tag.
+Include the Initjs tag in your application layout (usually in `app/view/layouts/application.html.erb`) right after the opening of the body tag.
```erb
- <body>
- <%= initjs_tag app_name: "AppName" %>
- …
- </body>
+<body>
+ <%= initjs_tag 'AppName' %>
+ …
+</body>
```
-### The app file
+Why this tag? This tag will add the informations about the controller and action that is been executed.
-If you have a commom javascript that you need execute every page, you can put in `app/assets/javascripts/app_name/app_name.js.coffee`
-#### Structure example
+### The app file
+The app file is the main file for your application, you can set some configurations and put some common code that you need to run on each page. This app file is usually in `app/assets/javascripts/app_name/app_name.js.coffee`. See the default file below:
+
+
```coffee
#= require_self
#= require_tree .
window.AppName =
- Common:
- initPage: ->
- # If you are using the Turbolinks and you need run a code only one time, put something here.
- # if you're not using the turbolinks, there's no difference between init and initPage.
- init: ->
- # Something here. This is called in every page, with or without Turbolinks.
- finish: ->
- # Something here. This is called in every page, with or without Turbolinks.
+ configs:
+ turbolinks: true # True to use initjs with Turbolinks by default.
+ pjax: false # True to use initjs with pjax by default.
+ respond_with: # To not use respond_with, just set false.
+ 'Create': 'New' # Respond the Create action with the New.
+ 'Update': 'Edit' # Respond the Update action with the Edit.
+
+ initPage: ->
+ # If you are using the Turbolinks and you need run a code only one time, put something here.
+ # if you're not using the turbolinks, there's no difference between init and initPage.
+ init: ->
+ # Something here. This is called in every page, with or without Turbolinks.
```
+### Modules
+
+How about code that we need over and over again? Initjs was a solution for that: Modules!
+
+Modules is the solution to not repeat the same code in more than one place. We just create a function with the code that we need in more than one place and then in the view we need use it, we just say it.
+
+#### Examples
+
+```coffee
+AppName.Tabs = ->
+ $('.tabs a').click ->
+ # do something when the link is clicked
+```
+
+```coffee
+AppName.Posts.Show =
+ init:
+
+ modules: -> [AppName.Tabs]
+```
+
+This `AppName.Tabs` will be automatically called when you access `/posts/1` for example.
+
+
+You also can declare modules for controller, namespaces and for the app, and even modules:
+
+```coffee
+AppName.Posts.modules = -> [AppName.Tabs]
+```
+
+This is saying to use the `AppName.Tabs` module on all pages that is on `posts` controller.
+
+```coffee
+AppName.Tabs =
+ init: ->
+ $('.tabs a').click ->
+ # do something when the link is clicked
+ modules: -> [AppName.SomeOtherModule]
+```
+
+
+To declare modules for entire the app, you can do it on the app file:
+
+```coffee
+window.AppName =
+ initPage: ->
+ # ...
+
+ # ...
+
+ modules: -> [AppName.Tabs]
+```
+
+### Partials
+
+Sometimes we need execute a javascript for html that will be rendered from a request using ajax/pjax and then execute the javascript. Initjs give you support for that.
+
+You will need add on your 'partial' the `initjs_tag` and say that is a partial:
+
+```erb
+<%= initjs_tag app_name: 'AppName', partial: true %>
+```
+
+Then you'll need call the Initjs initialize for the partial. Let's say we are using pjax to request the 'partial'.
+
+```coffee
+$('.pjax-content').on 'pjax:complete', ->
+ Initjs.initializePartial()
+```
+
+Then Initjs will execute the javascript for that 'partial'.
+
+**Important:** Modules in controller, namespace and in the application will not be initialized on partials, only modules in the specific view. The `init` function on the app file will be called on partials.
+
+
+### Respond with
+
+Let's say we have a `form` for edit a post with validations on the back-end side. My action is `edit` and the javascript is write for that action. When I submit this form and get an error, the action that is executing is `update` and not `edit` anymore. So Initjs should call the `Posts.Update` right? Right! But I need the same code that `Posts.Edit` uses to be executed on `Posts.Update` and I should be able to do it without repeating the code. Since Initjs 2.0.0 we have this feature by default.
+
+On the app file we have a configuration saying the default action that will be executed.
+
+```coffee
+window.AppName =
+ configs:
+ # ...
+ respond_with:
+ 'Create': 'New' # Respond the Create action with the New.
+ 'Update': 'Edit' # Respond the Update action with the Edit.
+```
+
+You can change these actions or add more if you need.
+
+Also you can disable this feature if ypu don't need it, just set `false` to `respond_with` variable.
+
+**Important:** Initjs will take a look to see if is there a function for the view first of executing the respond_with, if so, it will initialize the view and not the respond_with configured action.
+
## Recomended directory structure
Here is the app folder `app/assets/javascripts/app_name/`.
* app_name
@@ -192,59 +294,97 @@
* /app_name
* /blog
* /posts
* new.js.coffee
+## Changelog
-## Development environment
+### 2.0.0
-You'll need [RVM](https://rvm.io/) to isolate your development environment.
+- Add support for objects instead of only fuctions
+- Add support for modules
+- Add support for configurations
+- Add support for pjax
+- Add support to initialize inside a partial (pjax friendly)
+- Add support for respond_with
+- Remove the default namespace Common on app file
+- Remove the finish filter
+- Lots of refactoring and improvements
-Make sure you install `Ruby 1.9.3` on your [RVM](https://rvm.io/).
+### 1.0.1
+- Remove the the necessity of pass app_name on initjs_tag
+- Change from `=->` to `= ->` on generators
+- Use `?= {}` instead of `if` statement
+- Change `if` statement for Trubolinks
+- Others minor fixes
+
+### 1.0.0
+
+- Add support for application name
+- Add 'install' generator
+- Add 'add' generator
+- Improve the specs
+
+### 0.1.3
+
+- Add Rails 4 compatibility
+
+### 0.1.2
+
+- Solve bug on IE in addEventListener
+
+### 0.1.1
+
+- Add initPage support to work better with Turbolinks
+
+### 0.1.0
+
+- First release
+
+
+
+## Development environment
+
+Make sure you install `Ruby 2.0.0`.
+
Then just checkout the code, configure dependencies and run the tests:
1. Clone the repository:
`git clone git://github.com/josemarluedke/initjs.git`
-2. Enter the repo directory and accept the [RVM](https://rvm.io/):
+2. Enter the repo directory.
`cd initjs`
- `yes` if solicited
+3. Install [Bundler](http://gembundler.com/).
-3. Install [Bundler](http://gembundler.com/) into our [RVM](https://rvm.io/):
-
`gem install bundler`
4. Install all dependencies from [Gemspec](http://docs.rubygems.org/read/chapter/20):
`bundler install`
### Running tests
-1. Go to dummy app folder
+1. Run the rspec
- `cd spec/dummy/`
+ `rake spec`
-2. Run the rspec
-
- `rspec spec/`
-
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Thanks
-I have thanks to @diogob, that is my inspiration for this gem and thanks for core of code ([gist:2321526](https://gist.github.com/2321526))
+I have thanks to @diogob, that is my inspiration for this gem and thanks for core of code ([gist:2321526](https://gist.github.com/diogob/2321526/326c848e29406743c67fd040d4237ffe7ebcc6cd))
# License
Copyright (c) 2012-2013 Josemar Davi Luedke
-Licensed under the MIT license (see LICENSE.txt file)
+Licensed under the [MIT license](LICENSE).
\ No newline at end of file