example.html

<header>
  <img src="/assets/img/backbone.png">
  <hr>
  
  <div>
    <h2 class="congrats">Congratulations!</h2>
    <h2>Seeing this means you have installed Backbone Boilerplate correctly.</h2>

    <p>Now that you have the easiest and most-powerful Backbone boilerplate available,
    you're probably wondering how to use it to start building applications...</p>
  </div>
</header>

<section id="toc">
  <h1>Contents</h1>

  <ul>
    <li><a data-bypass href="#overview">Overview</a>
    <li><a data-bypass href="#getting-help">Getting help</a>
    <li><a data-bypass href="#writing-app">Writing your application</a>
      <ul class="nested">
        <li><a data-bypass href="#cleaning">Cleaning out default files and code</a>
        <ul class="nested">
          <li><a data-bypass href="#git-history">Removing the Git history</a>
          <li><a data-bypass href="#test-dir">Removing the test directory</a>
          <li><a data-bypass href="#build-process">Removing the build process</a>
          <li><a data-bypass href="#favicon">Changing the Favicon</a>
          <li><a data-bypass href="#app-code">Removing default application code</a>
          <li><a data-bypass href="#default-routes">Removing the default routes</a>
          <li><a data-bypass href="#default-assets">Removing default assets</a>
        </ul>
        <li><a data-bypass href="#namespace">Setting your namespace</a>
        <li><a data-bypass href="#modules">Creating a module</a>
        <li><a data-bypass href="#templates">Working with templates</a>
        <li><a data-bypass href="#plugins">Working with libraries and plugins</a>
      </ul>
    <li><a data-bypass href="#custom-build">Using the build tool</a>
      <ul class="nested">
        <li><a data-bypass href="#running">Running with the defaults</a>
        <li><a data-bypass href="#customizing">Customizing the build configuration</a>
        <li><a data-bypass href="#server">Using the development server</a>
        <li><a data-bypass href="#adding-tasks">Adding new tasks</a>
      </ul>
    <li><a data-bypass href="#useful-resources">Useful Resources</a>
  </ul>
</section>

<section>
  <h2 id="overview">Overview</h2>

  <p>Backbone Boilerplate is the product of much research and frustration. While
  existing boilerplates for Backbone exist, they will often modify the Backbone
  core, don't have an integrated build system, or impose too much on your
  application's structure. This boilerplate attempts to improve that.

  Organize your application in a logical filesystem, and develop Models,
  Collections, Views, and Routers inside modules. Build your application knowing
  you have efficient, compact code. Backbone Boilerplate extends on the
  versatile Backbone core, and helps developers manage their application.</p>

  <h3 id="core-features">Core Features</h3>
  <ul>
    <li><a target="_blank" href="https://github.com/h5bp/html5-boilerplate">HTML5 Boilerplate</a> included.
    <li>Managed filesystem structure for application code, assets, tests, and distribution.
    <li>Snippets to make common tasks easier: modules, HTML5 History API/Hash navigation, template loading and application events.
    <li>Flexible and extendable build system.
      <ul class="nested">
        <li>Concatenate and minify all your libraries, application code, templates and CSS down to reduce transmission time.
        <li>Compile underscore templates to prevent pre-processing on the client.
      </ul>
  </ul>
</section>

<section>
  <h2 id="getting-help">Getting help</h2>

  <p>If you're encountering issues, need assistance, or have a question that hasn't been answered in this
  tutorial or <a target="blank" href="https://github.com/tbranyen/backbone-boilerplate">the GitHub project page</a>
  you may find help in one of these places:</p>

  <ul>
    <li>IRC - #documentcloud on irc.freenode.net
    <li><a target="blank" href="http://github.com/tbranyen/backbone-boilerplate/issues">GitHub Issues</a> - Please report if you've found an issue,
    bug, or controversial request.
  </ul>

  <p>I want this project to be the best it possibly can and represent the interests of the community, <b>please</b>
  submit issues with features you find useful and anything that you question.</p>
</section>

<section>
  <h2 id="writing-app">Writing your application</h2>
  <p>Your application may be made up of third-party libraries, plugins, application code, templates, and lots of logic.  All of this will need
  to be well structured to keep it maintainable and it also needs to be compiled if deployed into production.  Before you can get started you
  will need to clean out all the existing defaults that are in the boilerplate are necessary to display this tutorial.
  </p>

  <p class="clues"><b>Strongly recommend you read through this tutorial before cleaning out any files that may hold clues on how to use the Boilerplate.</b></p>

  <h3 id="cleaning">Cleaning out default files and code</h3>
  <p>There are several places where customization may be required.</p>

  <ul>
    <li><h4 id="git-history">Removing the Git history</h4>
      <p>If you cloned the Backbone Boilerplate with Git, you should delete the git directory and then initialize your own Git history:

      <pre><code>
    $ rm -rf .git
    $ git init
      </code></pre>
      </p>

    <li><h4 id="test-dir">Removing the test directory</h4>
      <p>If you are not planning on testing your application with QUnit you should delete this directory.</p>

    <li><h4 id="build-process">Removing the build process</h4>
      <p>If you are not planning on using the provided build tool, delete the <code>build</code> folder.  It contains a lot of unnecessary code and
      Node.js modules that you will not need.  You should also clear out the commented out script tags inside of <code>index.html</code>:
      
      <pre><code>
    &lt;!--
         If using the build tool you can uncomment the following lines and use
         these instead.  They will toggle based on if you are using debug or
         release.
    --&gt;

    &lt;!--
    &lt;script src=&quot;/assets/js/libs.js&quot;&gt;&lt;/script&gt;
    &lt;script src=&quot;/assets/js/templates.js&quot;&gt;&lt;/script&gt;
    &lt;script src=&quot;/assets/js/app.js&quot;&gt;&lt;/script&gt;
    --&gt;
      </code></pre>
      </p>

    <li><h4 id="favicon">Changing the Favicon</h4>
      <p>At the root level of the project simply change the <code>favicon.ico</code> file to point to your own branded icon.</p>

    <li><h4 id="app-code">Removing default application code</h4>
      <p>This tutorial is rendered in the <code>app/modules/example.js</code> file and written in <code>app/templates/example.html</code>.
      Both of these files are safe to remove.</p>

    <li><h4 id="default-routes">Removing the default routes</h4>
      <p>Routes are defined in the <code>app/index.js</code> file.  Familiarize yourself with it's contents.  You'll notice the default router has two existing routes and callback defined, reset it to:

      <pre><code>
    // Defining the application router, you can attach sub routers here.
    var Router = Backbone.Router.extend({
      routes: {
        "": "index",
      },

      index: function() {
        // Put your homepage route logic here
      }
    });
      </code></pre>
      </p>


      <p>Above the Router definition you'll see a reference to the example module,
      this is safe to delete as well.

      <pre><code>
    // Include the example module
    var Example = namespace.module("example");
      </code></pre>
      </p>
  
    <li><h4 id="default-assets">Removing default assets</h4>
      <p>The default styles for this tutorial are stored in <code>assets/css/style.css</code>.  You will probably want to remove these since they only make sense for this specific page.  They start on <code>Line 209</code>.  With the following H5BP header:

      <pre><code>
    /* ==|== primary styles =====================================================
       Author: Backbone Boilerplate <Change to your Name>
       ========================================================================== */
     </code></pre>
     </p>

     <p>You may also want to change the name to yours, if you're planning on putting your custom CSS here as well.</p>

     <p>You should delete the <code>assets/img/backbone.png</code> file if you are not planning on using it in your app.</p>
  </ul>

  <h3 id="namespace">Setting your namespace</h3>
  <p>This is a very important starting step to creating your application.  This brands the application to your name and makes
  it something identifiable to new developers.  To set your own namespace, simply open the <code>app/namespace.js</code> file and
  make the following modifications:

    First change the name of the namespace, this is defined on <code>Line 4</code>
    <pre><code>
  this.myapp = {
    // Assist with code organization, by breaking up logical components of code
    // into modules.
    module: function() {
    </code></pre>
    </p>

    <p>Once you've set the name, you'll want to change the reference in <code>index.js</code> on <code>Line 7</code> to:
    
    <pre><code>
  // Shorthand the application namespace
  var app = this.myapp;
    </code></pre>
    </p>
  </p>

  <h3 id="modules">Creating a module</h3>
  <p>Following the Bocoup post on <a data-bypass target="_blank" href="http://weblog.bocoup.com/organizing-your-backbone-js-application-with-modules">Organizing Your Backbone.js Application With Modules</a> this boilerplate provides the same module definition structure.

  Modules are placed in the <code>app/modules/</code> directory.  There is an example module
  there named: <code>example.js</code>.  The actual module definition function is located
  inside the <code>app/index.js</code> file.  You create and reference modules with the same
  function call:  <code>namespace.module(&quot;&lt;module_name&gt;&quot;)</code>.

  Typically a module contains a single Model/Collection/Router and many Views.
  Therefore the returned module object is empty except for a Views object
  property that can be used to attach many Views to, like:

  <pre><code>
  MyModule.Views.Detailed = Backbone.View.extend({ /* ... */ });

  MyModule.Views.Main = Backbone.View.extend({ /* ... */ });
  </code></pre>
  </p>

  <p>
  Attaching Models/Collections/Routers happen on the same level of the module,
  like so:

  <pre><code>
  MyModule.Model = Backbone.Model.extend({ /* ... */ });

  MyModule.Router = Backbone.Router.extend({ /* ... */ });
  </code></pre>
  </p>

  <h3 id="templates">Working with templates</h3>
  <p>Templates are a super useful way to separate concerns in your application.  Instead of generating markup from inside your JavaScript
  application, you instead create it in a separate file and load it into your application.  There are numerous ways of loading in a
  template, but this boilerplate has chosen the most performant way to build all your templates into a single file.</p>

  <p>This tutorial itself is a template that exists in <code>app/templates/example.html</code>.  You can edit this file and hit refresh
  in here to see the changes.  The boilerplate comes with a built in function to handle the loading of templates.  It's called:
  
  <pre><code>
  namespace.fetchTemplate("app/templates/name.html", function(template) {
    // Template here is a function, that accepts an object.  Identical to _.template.
    console.log(template({ ... }));
  });
  </code></pre>
  </p>

  <p>By defining a custom function this will ensure that if you use the build tool or AJAX, that your templates will load consistently.
  You can see it in action inside the <code>app/modules/example.js</code> module.</p>

  <p>If you use the build process to compile your templates, it will automatically find all the HTML files inside the templates
  directory and compile them into a templates.js file.  These are actual JavaScript template functions being compiled on the server, which
  is different from Jammit and most other server-side builders that just invoke functions on page load.</p>

  <p>You can access a compiled template like so:

  <pre><code>
  var template = window.JST["app/modules/example.html"];
  template({ ... });
  </code></pre>
  </p>

  <h3 id="plugins">Working with libraries and plugins</h3>
  <p>Libraries and plugins are easily added to the application, by placing them inside the <code>assets/js/libs/</code> directory.
  If you have many plugins in your application, it may make sense to create a separate folder such as <code>assets/js/plugins/</code> 
  for them.</p>
</section>

<section>
  <h2 id="custom-build">Using the build tool</h2>
  <p>The Backbone Boilerplate build process is a state-of-the-art task driven
  Node.js application that utilizes @cowboy's grunt project.

  To run the defaults, execute the following command from the project root,
  and *not from inside the build folder*.</p>

  <h3 id="running">Running with the defaults</h3>
  <p>To run the defaults, execute the following command from the project root,
  and *not from inside the build folder*.

  <pre><code>
  node build
  </code></pre>
  </p>

  <p>
  This will do a number of things for you.  First it will concatenate all your
  libs, app code, and templates into separate files inside the `dist/debug`
  folder.  It will then minify those files and your CSS into production ready
  files inside the <code>dist/release</code> folder.</p>

  <h3 id="customizing">Customizing the build configuration</h3>
  <p>To customize and configure the build tool, open `build/config.js` and tweak
the settings.</p>

  <h3 id="server">Using the development server</h3>
  <p>
  While writing an application that leverages <code>pushState</code> you can run the
  following command to run a server that will always resolve to the <code>index.html</code>

  <pre><code>
  node build/server
  </code></pre>
  </p>

  <p>
  This will spawn up an HTTP server on port <code>8000</code>.  This server is intended
  for development and not production.  You should use url rewriting or forwarding
  all requests in your production server to achieve this same effect.</p>

  <h4>Serving the built assets</h4>

  <p>If you are using the build tool in conjunction with this development server
  you can optionally update the <code>index.html</code> file to remove the existing script
  tags and uncomment out the scripts tag at the bottom to load the <code>dist/debug</code>
  or <code>dist/release</code> assets.  You can achieve this by specifying either <b>debug</b>
  or <b>release</b> after the server command, like so:

  <pre><code>
  node build/server release
  </code></pre>
  </p>

  <h3 id="adding-tasks">Adding new tasks</h3>
  <p>To add a new task into the build system, you simply copy and paste the task JavaScript folder/file into the <code>build/tasks</code> folder
  or extract the task archive into the same directory.  At the very least in order to run this task, you'll need to add it to the <code>build/config.js</code>
  file.  The last line should look something like:

  <pre><code>
  task.registerTask("default", "clean lint:files concat jst min mincss new_module_here");
  </code></pre>
  </p>

  It's possible the custom task will have additional setup instructions, so make
  sure you read the README for any task.</p>
</section>

<section id="useful-resources">
  <h2>Useful resources</h2>

  <ul>
    <li><a href="http://backbonejs.org/">Backbone documentation</a> - Framework on which Backbone Boilerplate is built.
    <li><a href="http://documentcloud.github.com/underscore/docs/underscore.html">Underscore documentation</a> - Required dependency for Backbone.
  </ul>
</section>