marionettejs/guides

Learn how to build web apps using Marionette

guides's Issues

Set Marionette Version

Since Marionette 3 is now out, we should update the version numbers throughout the guide to force version 2.4.7. This will prevent newcomers from being confused.

The 'Marionette.LayoutView' is not working in marionette v3.0.0

I tried the tutorial with marionette 3.0.0 and the The 'Marionette.LayoutView' is not working anymore.
I changed it to 'Marionette.View' and it's working.

Validation Result Is Ignored

With these changes, we can now refuse to add an item unless it passes validation. We could also display error messages if validation fails by binding the invalid event in modelEvents. You can see how we've set our fields to blank fields on the model and also in the ui hash. If we start having more and more fields, you can see how this would quickly become unmanageable. Surely we can just clear the form when the model is cleared?

Validation Result Is Ignored

You provided the validation function in model, but in driver.js, you still add the model anyway, regardless of the validation outcome. I think you should wrap the last 2 lines inside onAddTodoItem() inside an if statement, such as if (this.model.validationError === null)

Submitted by @charliegdev

Missing module

We'll be using the layout described in the introduction, so let's move the bulk of our view code into views/layout.js and rejig it a little:

bundle.js:17800 Uncaught Error: Cannot find module "../models/todo"

models are not defined in this or prior sections in the tutorial

/cc @scott-w

submitted by @iampeterbanjo

ToDoModel instantiated but not required

Reported by @jjmontgo:

In the code for driver.js, new ToDoModel() is instantiated in the application's onStart(), but it isn't required on the file.

Analysis: Behaviors

Hey,

I just found myself with a bit of free time and agreed to read over some sections for @jdaudier. Here are my thoughts on the Behavior's section:

Sharing common view Behavior / What is a Behavior?

• The code example is slightly inconsistent. The first snippet uses triggers without a behavior. Then the "same code" is represented within a behavior, but now uses events. I think that this detracts from the intention of the example.

Listening to View events

The example itself here is good for conveying what a Behavior is, but I have some concerns about the correctness of the example. Is it really a view's job to be telling its collection to mark models as newlyAdded? What if there was no view -- should things simply stop being marked as newly added? What if the collection was shared between multiple views? etc... This entire example feels like a job for Cocktail not Behaviors.

I think using an example that's a bit more presentation-specific could be beneficial. Perhaps doing a 'mouseover/mouseout' + showTooltip concept. In fact, I see a tooltip example in the list of extended examples. I feel like this would be a better introductory concept, but maybe others feel differently.

Defaults

All of the defaults example stuff seems fine. Personally, I feel like behaviors should use a different term than 'defaults' since they're not accessed in the same way as BB.Model defaults. This has led me to confusion in the past, but that's not super related to the docs.

Misc

One thing I would've liked to see more talk on is an issue I raised in Mn issues a while back: marionettejs/backbone.marionette#2784. Even if the guide doesn't suggest one pattern or the other... I think it would be prudent to make people aware of their different options for view/behavior interactions. Passing methods down into the behavior vs having the behavior emit events which come back up.

Additionally, I didn't see any mention of nesting behaviors -- which is certainly possible :)

Overall, read well and had a solid amount of examples. I don't really expect people to take the examples at face value, but it would be nice to have a higher level of confidence in them just in case people do copy/paste the examples and assume they're best practice.

template value is missing 'require' for the ToDo LayoutView

In the code snippet below, the template value is missing 'require' for the ToDo LayoutView

https://marionette.gitbooks.io/marionette-guides/content/en/getting_started/tutorial/firstview.html

Our list of items is really a collection, so we'll use the Backbone.Collection to model it. We'll also use a view that specializes in rendering lists of data - the CollectionView. Back in our driver.js file, we're going to use a couple of views:

Originally submitted here: https://www.gitbook.com/book/marionette/marionette-guides/discussions/2

/cc @scott-w

Introduction makes no sense

A couple of minor issues with the introduction:

• The first link to the reference docs is broken
• "Where do I start" is duplicated

Name of event after model save

In https://marionette.gitbooks.io/marionette-guides/content/en/views/index.html there is a description of a post-save model event called afterSave that is triggered in the success callback for the save event. But the code displayed appears to have an error.

Should this line in the save success callback model.trigger('save', model, {}); be model.trigger('afterSave', model, {});?

Form Validation (Assignee / Text inputs)

Need to update the final code for chapter # 2 and in the appendix so the form validation will work. Adding an if statement in layout.js will work:

onChildviewAddTodoItem: function(child) {
    this.model.set({
      assignee: child.ui.assignee.val(),
      text: child.ui.text.val()
    }, {validate: true});

    if (this.model.isValid()) {
      var items = this.model.pick('assignee', 'text');
      this.collection.add(items);
    }
  }

Testing Guide

We need to include a recommended testing style for the Guides that gets users off the ground.

Update for Marionette 3.0

We need an updated version of the book for Marionette 3.0.

We could do this by forking the book and publishing a separate version. We would then have to handle linking from the website.

Typos found while adapting the chapter 2 tutorial

https://marionette.gitbooks.io/marionette-guides/content/en/getting_started/tutorial/layouts.html

Near the end in layout.js onChildviewAddTodoItem still refers to this.ui, but the ui has been refactored out into the form view at this point. To get this to work I needed to add a parameter to the onChildviewAddTodoItem method and access ui via that object.

This also appears in the summary code:

https://marionette.gitbooks.io/marionette-guides/content/en/appendix/getting_started/tutorial/todo_app.html

Newly created objects gets duplicated in Getting Started

The sample code provided in Section 2.5 (Getting Started -> Adding new items) suffers from the bug mentioned in the Marionette Repo #640.

Specifically, when using the code provided to add a new item to the list, two items are added. Once in the itemAdded code, and again when rendering.

template typo

https://marionette.gitbooks.io/marionette-guides/content/en/getting_started/tutorial/firstview.html
In templates/todoitem.html we simply have:

This should be: <%- text %> &mdash; <%- assignee %>

Originally submitted here: https://www.gitbook.com/book/marionette/marionette-guides/discussions/1

/cc @scott-w

Don't trigger `show`

The tutorial currently has:

var App = new Marionette.Application({
  onStart: function(options) {
    var todo = new TodoView({
      collection: new Backbone.Collection(options.initialData.items),
      model: new ToDoModel()
    });
    todo.render();
    todo.triggerMethod('show');
  }
});

App.start({initialData: initialData});

In v3 rendering and "showing" your own view would be greatly discouraged, and I don't think you should really do it in v2 either.. some views will not know they are attached if a region is not involved.

I understand why we got to this place because we were moving away from Application.Regions and because there was no clear place to start a LayoutView, but I would still say that this is a better pattern in v2. Then the change in v3 is to change the regions hash to a simple region: '#app-hook'

I don't know if it is worth the effort of the change, but I've seen this question a bit lately in gitter and SO.

var App = new Marionette.Application({
  regions: {
    'appRegion': '#app-hook'
  },
  onStart: function(options) {
    var todo = new TodoView({
      collection: new Backbone.Collection(options.initialData.items),
      model: new ToDoModel()
    });
    this.getRegion('appRegion').show(todo);
  }
});

App.start({initialData: initialData});

itemAdded never gets called

Now, whenever we click on the "Add Item" button, a new job will be added to our todo list and the form will be cleared. We've taken an opportunity to introduce model and collection driven events as well. For a full list of events, see the Backbone documentation.

itemAdded never gets called

submitted by: @pelachile on https://www.gitbook.com/book/marionette/marionette-guides/discussions/3

Error trying code from guide

I was trying the webpack config for 'Bundled jQuery' method in https://marionette.gitbooks.io/marionette-guides/content/en/getting_started/installing_marionette.html. But it's giving me the following weird error on running webpack. I am using the same config suggested in the guide.

$ node_modules/.bin/webpack .                                                                                                         !10297
Hash: 828209a9b8c5230cb7de
Version: webpack 1.13.3
Time: 48ms
    Asset     Size  Chunks             Chunk Names
bundle.js  1.61 kB       0  [emitted]  main
   [0] multi main 40 bytes {0} [built] [1 error]
   [1] ./app/driver.js 0 bytes {0} [built]

ERROR in multi main
Module not found: Error: Cannot resolve 'file' or 'directory' /home/gokul/root/mobme/worklight/fubar in /home/gokul/root/mobme/worklight/fubar
 @ multi main

Code License

While it should be obvious that readers could copy and paste code, we should include an explicit license grant in the text to provide that extra confidence.

With that in mind, the choices would be:

• MIT
• 2 or 3 clause BSD
• Public Domain grant
• CC0 license (current)

Are there any preferences?

Show me the code

I think this guide would be greatly enhanced if it used an actual functioning application to demonstrate the features (could perhaps start with https://github.com/tastejs/todomvc/tree/gh-pages/examples/backbone_marionette). It wouldn't have to be all that fancy - perhaps using something like https://github.com/typicode/json-server for the data - but right now it's just so many words.

Using ES6

A quick question for discussion:

With ES6 starting to gain popularity through Babel, should the Guides use it as the basis for code samples? I'm happy to throw in the additional configs for Webpack to make it work.

A counterpoint is that it's still not natively supported, and it could possibly add another concept for readers to grasp that prevents the Guide from being useful.

I'm open to suggestions and I'd like to open it to the floor before I get too committed to a coding style for the v3 Guide.