Alternative implementation for #333.

After playing with it I find that I really prefer this method much better. It mirrors the traditional backbone events hash as the 'selector' is re-purposed to mean event target. It also works with declarative binding to not_a_model_or_a_collection.

An example would be ...

listen:
  '!router:changeURL': 'aHandler'
  'change model': 'bHandler'

.. instead of:

mediatorEvents:
  '!router:changeURL': 'aHandler'

modelEvents:
  'change': 'bHandler'

Discuss.

Handle all kinds of routing through Router#route, deprecate separate methods and events for routing by name.

This functionality can now be achieved by passing a hash instead of a path to Router#route or the methods and events delegating to it, which can declare the intended target via either

controller and action keys or name key, and params hash.

The hash will be used to determine the path via reverse routing.

This settles #533.

As chaplin promotes inheritance, I don't believe we should expose afterRender or afterInitialize and instead instruct users to just override initialize and/or render and call super.

afterRender (before the super call) or render (after the super call) were good hooks to fire $el manipulation code before the $el was inserted into the DOM. This hook is now achieved by listening to the rendered event that is fired by the view after it replaces the contents of its $el and before it attaches it to the DOM (and this is made very easy by the listen hash).

afterInitialize was moved into the constructor to be just nicely called after the initialize stack is called. This had the side effect of having nothing of mention in the base view initialize method so now super is no longer necessary in the base view class.

Thoughts on the changes?

This is the implementation of the example shown on gh-232. It still needs unit tests and some code review. Opinions welcome.

So from that came composing. Additions are two-fold. The first of which is named regions -- in essence, providing canonical names to selectors. All views can register regions through their regions method. This is not directly related to composing however it complements it greatly as we'll see. The second and last is the ability for views to not only be instantiated and rendered by a controller, but to alternatively be composed. A composed view is instantiated and rendered only if it has not been composed before. Once a view is composed in an action; as long as all subsequent actions likewise compose it, it will not be disposed.

An example shall tell a thousand words: http://concordusapps.github.com/composer-example/ And the source to the example: https://github.com/concordusapps/composer-example

The modifications to chaplin are located at https://github.com/concordusapps/chaplin/tree/topics/composition. Layout is responsible for region management. A new module, Composer is responsible for the composition process and tracking lifetime of composed views.

Current:

class Controller
  beforeAction:
    '.*': (params, route) -> 
      @compose 'site', SiteView

    'show': (params, route) ->
      @compose 'navigation',
        compose: ->
          @model = new Navigation
          @view = new NavigationView {@model}
        check: ->
          console.log arguments
          yes

Proposed:

class Controller
  beforeEach: (params, route) ->
    @compose 'site', SiteView

    if route.action is 'show'
      @compose 'navigation',
        compose: ->
          @model = new Navigation
          @view = new NavigationView {@model}
        check: ->
          console.log arguments
          yes

Basically current form is no longer needed since we pass route information. Switching to classical method will:

• Decrease complexity and ambiguity
• Increase performance (walking the whole protochain is costly)

This is a proposal on how to give the documentation for Chaplin some more glory, while still keeping them close to the source for convenient maintenance. It also builds on @paulmillr's work to have bi-lingual (CoffeeScript/JavaScript) docs.

It would be nice to have some more freedom in the presentation of the docs, make browsing them more convenient, and offer an option to switch between the two languages to reduce visual noise.

At the same time, as @molily told me, an earlier attempt at keeping the docs in a separate repo has been abandoned due to trouble with keeping source and documentation in sync.

My basic idea for remedying both is to leave documentation source files where they are now, but use GitHub Pages to make them available to the public. Using Jekyll, the existing files can be transformed into a more easy-to-use, more browsable collection of docs, without having to change too much.

You can see my first steps into this direction here: http://knuton.github.io/chaplin/chaplin.collection_view.html

I have slightly adapted the styles from chaplinjs.org and added the option to choose one's preferred language at the top of the page (persisted in localStorage).

The individual doc files would not have to change much in order to accomodate this change: https://github.com/chaplinjs/chaplin/commit/06ea47f50310fb5a11c8a29670ec2537c863b969#L4R0

Another addition I would like to make is to add a sidebar or some other option to jump between modules quickly.

The main benefits I expect from this are

• the option to choose a preferred language,
• ease of navigation, more discoverability,
• stability of docs for current release (if docs are deployed to docs.chaplin.org on every release).

I'd like to hear your feedback. Paul has already expressed his concerns in an inline note. Paul, can you explain how this suggestion would be harder to maintain compared with the current setup?

Ideas on supporting reversal of routes declared via regular expressions?

This is supported in django by normalizing a regular expression and then building a list of format strings of the possibilities and when reverse is called it iterates through each one applies parameters and tests the result. This totals around ~600 lines of python code. It would probably be about ~400 lines of coffee as javascript regex is much less complex.

Do we even need to support reversing regex routes? It feels half-done without it, but it also may be the better option.

Something simple like...

match /post\/(\d+)\-.*\/edit/

... would not feasibly be able to be reversed.

I'm almost for removing the ability to have regex routes entirely.

The following ...

match /products\/(\d+)[\w\-$]*/, 'null#null',
  names: ['id']

... could be rewritten as ...

match "products/:slug", 'null#null',
  constraints:
    slug: /(\d+)[\w\-$]*/

... with a few modifications to how constraints is implemented.

Hi there,

I just updated to the latest version of Twitter Bootstrap and jQuery. Also I made sure, that Chaplin is up-to-date. Since I updated, I get the following error, when opening my application:

Uncaught RangeError: Maximum call stack size exceeded

I used the chaplin-boilerplate-plain project to get started with Chaplin and everything worked quite well and out-of-the-box. Since the update however it seems to fail, when this.initLayout() is called.

I will try to dig a bit deeper.

Edit the structure as discussed here in #25.

1. application_controller is renamed dispatcher because it wasn't a controller but a dispatcher. It is also removed from the controllers/ folder
2. rename application to core so it allows the user to create an application named Application. Another option could be chaplin but requiring chaplin/chaplin isn't meaningful imo
3. application_view is now named layout. It isn't loaded anymore from the core because it is too application specific. Actually, there is a application_layout that inherits from layout and that the user need to initialize from his application. If you approve this change, we'll need to refactor layout to remove some code that is imo too "application specific" and should be left to the user to decide wether or not to use it (for instance map all links internally)
4. application_controller is now outside of chaplin and serve as a middle layer between controller and the controllers in your application. As a result any controller now inherit from application_controller rather than controller.

1. Switch to simple one-handler request-response stuff instead of !events.

2. API is mediator.getHandler, setHandler and removeHandlers. Matches marionette API.

3. Add helpers.redirectTo instead of global !router:route.

4. Return a promise from compose() if Composition::compose returned promise.Return a promise from compose() if Composition::compose returned promise. Allows to do:

   beforeAction: ->
     @compose 'stuff', ->
       @model = new User
       @model.fetch()
   

I made some changes on the core architecture as well as smaller changes and bundled them in this branch to discuss about them.

The most important thing is probably the split of the controller startup/disposal logic between ApplicationController and ApplicationView. I always felt that ApplicationView isn’t the right place since it’s not a view question, but a app-wide mechanism. ApplicationController as parent of other controllers makes more sense.

Second thing is the split between Router and routes. The routes used to lie in the Router class which is definitely not the right place. Now they are sourced out into a routes.coffee which looks much like the Rails counterpart routes.rb.

Third thing is the mediator revamp. mediator.user is now readonly in ES5-conformant browsers and the new mediator.setUser method should be used when setting the user. The idea is to prevent accidental overwriting. At least you will get a strict mode exception in ES5-capable browsers.

What do you think?

The https://github.com/chaplinjs/chaplin/blob/master/docs/chaplin.composer.md#long-form says:

The check method should return true when it wishes the composition to be disposed and the compose method to be called.

But in reality https://github.com/chaplinjs/chaplin/blob/master/src/chaplin/composer.coffee#L126, it does the opposite:

    # Apply the check method
    if current and current.check composition.options
      # Mark the current composition as not stale
      current.stale false
    else
      # Remove the current composition and apply this one
      current.dispose() if current

Hey,

I'm getting error in Internet Explorer (version 11.0.9699) with message "Invalid pointer" on 788 line in chaplin.js, where is this part of code: this.history[historyMethod]({}, document.title, url);

I don't know what exactly this code does. I'm using chaplin indirectly in third-party software.

What could be the cause?

Thanks.

I do not see any reason for limitating the listen hash to model, collection, mediator. With the optionNames property i can add 'native' additional models or collections to a view. So i think it would be consistent to also support them in listen hash.

code: /src/chaplin/views/view.coffee:311 https://github.com/chaplinjs/chaplin/blob/master/src/chaplin/views/view.coffee

Hi!

My project depends on Chaplin through following line (within package.json):

"chaplin": "^1.0.1"

Which I think tells npm to install the newest Chaplin version that is compatible with version 1.0.1.

But npm install installs version 1.2.0, which results in following errors when I try to build the project:

$ gulp javascripts
[22:48:47] Using gulpfile ~/trustvox.js/Gulpfile.js
[22:48:49] Compile error: TypeError: Path must be a string. Received 1
[22:48:49] Finished 'javascripts' after 2.52 s
[22:48:49] Compile error: Error: Cannot find module './chaplin/application' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/composer' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/dispatcher' from '/root/trustvox.js/node_modules/chaplin'                                                                                                               [6/1826]
[22:48:49] Compile error: Error: Cannot find module './chaplin/controllers/controller' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/composition' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/history' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/route' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/router' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/support' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/sync_machine' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/models/collection' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/models/model' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/views/collection_view' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/views/layout' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './chaplin/views/view' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './composer' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './dispatcher' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/router' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './views/layout' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/composition' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../controllers/controller' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './history' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './route' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './model' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './view' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module './view' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/event_broker' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../lib/utils' from '/root/trustvox.js/node_modules/chaplin'
[22:48:49] Compile error: Error: Cannot find module '../mediator' from '/root/trustvox.js/node_modules/chaplin'

The build completes successfully when I force Chaplin version 1.1.1.

My questions is: are these versions really compatible?

Thanks!

It seems there is a little bug in CollectionView. If I add to Collection array of models, like:

  models = [{a:'1'}, {a:'2'}, {a:'3'}, {a:'4'}]
  collection.add models, at: 5

The new item views will be created in CollectionView but the order of added items will be reversed. This is because of this line in CollectionView:

  # When an item is added, create a new view and insert it.
  itemAdded: (item, collection, options) =>
    @insertView item, @renderItem(item), options.at

options.at has the original value 5, so all items will insert in this position, where it should insert into position of options.index which has the proper position of newly added model in the whole Collection.