An opinionated structure for building Marionette apps highly based on the excellent Backbone Rails Series.
This library is all about the UI so it doesn't alter your models and collections.
- Configuration
- Project Structure
- Behaviors
- Components
- Config
- Controllers
- Entities
- Routers
- Utilities
- Views
You need to run the configure method to tell this library about your app. Here is an example of the configuration options.
marionette_lib = require 'marionette_lib'
marionette_lib.configure {
app: myApp
handlebars: require('handlebars')
}
This is the usual project structure for apps that use this library.
- /apps
|- /section_name
|- /edit
|- Edit.coffee
|- EditController.coffee
|- /list
|- List.coffee -- if needed
|- item.hbs -- if needed
|- list.hbs -- if needed
|- ListController.coffee
|- /show
|- view.hbs -- template if needed
|- View.coffee
|- ShowController.coffee
|- app.coffee
|- index.styl
- /behaviors
- /components
- /config
- /entities
- app.coffee
- main.coffee
- main_config.coffee
This is a simple behavior baked in to all views and layouts which allows you work with BEM style modifiers. It will also trigger events on the view when modifiers are turned on and off.
class MyView extends marionette_lib.views.ItemView
name: 'my'
initialize: ->
@on 'modified:shown', (state) ->
console.log('are we in the shown state?', state.on)
showSomething: ->
@triggerMethod 'modified', 'shown'
toggleSomething: ->
@triggerMethod 'modified', 'shown', { toggle: true }
removeSomething: ->
@triggerMethod 'modified', 'shown', { remove: true }
I the example above you will get the my--shown
class added,
toggled and then removed from the view's element.
You will also get the modified:[modifier]
event triggered on the view.
Which you can subscribe to like:
@on 'modified:shown`, (state) ->
console.log(state.on) # true/false
You can also use the Marionette method form:
onModifiedShown: (state) ->
console.log(state.on) # true/false
The base controller makes sure that all controllers register themselves in the app registry so we can keep track of what has or hasn't been cleaned up properly.
The app controller is used for managing portions of the app like a listing or showing an item.
Here is a simple example of how you might write a ListController.coffee
.
List = require './List'
class PeopleListController extends marionette_lib.controllers.App
initialize: ->
@people = new Person.Collection()
@list = new List(collection: @people)
@people.fetch()
@show @list,
loading: true
If you needed a layout with regions then the controller would manage what goes in to the regions.
Layout = require './Layout'
List = require './List'
Stats = require('components').Stats
class PeopleListController extends marionette_lib.controllers.App
initialize: ->
@people = new Person.Collection()
@layout = new Layout()
@list = new List(collection: @people)
# an example component controller
@peopleStats = new Stats(collection: @people)
# once the layout is shown we want to show the sub views
@layout.on 'show', =>
@show @list,
region: @layout.listRegion
loading: true
@show @peopleStats,
region: @layout.statsRegion
loading: true
# fetch the data
@people.fetch()
# show the layout
@show @layout
The router controller allows you to manage the routes along with controlling the access to them. Here is an example of how this might be used.
loggedInPolicy = new marionette_lib.controllers.Router.ActionPolicy({
isAuthorized: (actionName, actionConfig) ->
return userIsLoggedIn
})
router = new marionette_lib.controllers.Router
defaultPolicy: loggedInPolicy
actionUnauthorized: (actionName, actionConfig) ->
doSomethingWhenUnauthorized()
# these actions whill be available on the object
# ie router.onlywhenLoggedIn()
actions: {
onlyWhenLoggedIn: (name, options) ->
# this will only be called if loggedInPolicy
# is authorized
customPolicy: {
fn: ->
doSomething()
policy: new marionette_lib.controllers.Router.ActionPolicy({
isAuthorized: (actionName, actionConfig) ->
return checkCustomState()
})
unauthorized: (actionName, actionConfig) ->
# this will override the main actionUnauthorized method
doSomethingWhenUnauthorized()
}
}
The Static Controller is useful to be able to render static html from a backbone view template.
Say we wanted to render a button like so:
<button type="button" class="btn">button</button>
Here is a very simple template which you would use in a static page.
And here is the controller. It will always set the name of the controller as a class on the rendered tag.
class BtnStaticController extends marionette_lib.controllers.Static
name: 'btn'
tagName: 'button'
attributes:
type: 'button'
You can specify attributes
and contextProperties
to pass information
through to the rendered html.
Defaults can be set for attributes and properties.
class BtnStaticController extends marionette_lib.controllers.Static
name: 'btn'
tagName: 'button'
attributes:
type: 'button'
contextProperties:
name: 'Unknown'
Then in your page you can use them:
And the underlying template would look like:
To render
<button type="submit" class="btn">Hello Bob</button>
This encapsulates navigation helpers on the marionette_lib.navigation
namespace.
-
.getCurrentRoute()
return the current url fragment -
.startHistory(options)
start backbone history and set a flag to say it has started -
.to(route, options)
set the url fragment without triggering navigation unless specified in the options
Keep a registry of all controllers instantiated within the app so you can see if any are not being cleaned up.
class MyThing
constructor: ->
@_instance_id = _.uniqueId('thing')
marionette_lib.registry.register(@, @_instance_id)
super
destroy: ->
marionette_lib.registry.unregister(@, @_instance_id)
To make a release run grunt release