Basics of Childviews

ChildViews can be designed in two main places: In the instance of the view (.lproj directory), and the definition of the custom view (view directory). Depending on what you want to do, you would define the child views in the right layer. For one-off view layout constuction, as in building your user-focused application and laying out the views, you will define the child views in the .lproj directories. If you want to build a composite view that you will be using repeatedly then you would build the definition of the childviews in the view directory.

Childviews in the Instance Layer

We have already seen this in our current application in the main_page.js in english.lproj. We are going to add another child view to show what we can do:

  MyApp.mainPage = SC.Page.design({
 
    // The main pane is made visible on screen as soon as your app is loaded.
    // Add childViews to this pane for views to display immediately on page 
    // load.
    mainPane: SC.MainPane.design({
      childViews: 'titleView blogBodyView'.w(), // <== The List of Child View names that you want to render...
 
      titleView: MyApp.TitleView.design({
        layout: { centerX: 0, top: 10, width: 400, height: 50 },
        classNames: ['another-custom-class'],
        name: 'Basic View API',
        icon: 'tutorial'
      }),
 
      blogBodyView: SC.LabelView.design({
        escapeHTML: NO, // This means that if there is HTML in the value string do not escape it, render the HTML
        layout: { centerX: 0, top: 70, width: 400, height: 500 },
        classNames: ['blog-body'],
        value: "This is the intro to an awesome blog post. <h2>New Header for cool stuff</h2> Keep posting some cool stuff"
      })
    })
  });

OK, we have added two childviews to the main page: titleView, which is the custom view that we have built, and blogBodyView, which is using an basic SC.View. The important thing to note is that we create these as named views in the SC.MainPane design definition. This gives us the ability to reference the child views through named paths:

  MyApp.getPath('mainPane.titleView'); // will return the instance of the MyApp.TitleView in the page
  MyApp.getPath('mainPane.blogBodyView'); // will return the instance of the SC.LabelView in the page

Then, if you want to create them in the page and make them visible to add them to the childViews parameter. This is the most common way that you are going to be creating childviews.

Childviews in the View Definition Layer

Sometimes you will want to create composite views made up of view that you want to use over an over. For this example, we will make a rating bar at the bottom of the blog post. So let’s run:

  sc-gen view MyApp.RatingBarView

Which will create rating_bar.js in the view directory. We are going to add a function called createChildViews() to the file and this is where we are going to put three different views in there: An SC.LabelView; a SC.ButtonView for ‘Helpful Post’; and one SC.ButtonView for ‘Unhelpful Post’. So we will make the file look like this:

  MyApp.RatingBarView = SC.View.extend(
  /** @scope MyApp.RatingBarView.prototype */ {
 
    createChildViews: function(){
      var view, childViews = [];
 
      // The first view.  Using the Class and Full Parameter Method
      view = this.createChildView( SC.LabelView, {
        layout: {left: 10, top: 5, width: 200, height: 25},
        value: "Was this Post Helpful?"
      });
      childViews.push(view);
 
      // The Second View...using the Design Pattern method...only need to fill out the first parameter of the createChildView()
      view = this.createChildView( 
        SC.ButtonView.design({
          layout: {right: 90, top: 5, width: 80, height: 22},
          title: "Yes"
        })
      );
      childViews.push(view);
 
      // The Third View...
      view = this.createChildView( 
        SC.ButtonView.design({
          layout: {right: 5, top: 5, width: 80, height: 22},
          title: "No"
        })
      );
      childViews.push(view);
 
      this.set('childViews', childViews);
    }
 
  });

And then we make a simple change to the main_page.js in the english.lproj directory:

  MyApp.mainPage = SC.Page.design({
 
    // The main pane is made visible on screen as soon as your app is loaded.
    // Add childViews to this pane for views to display immediately on page 
    // load.
    mainPane: SC.MainPane.design({
      childViews: 'titleView blogBodyView ratingBar'.w(),
 
      titleView: MyApp.TitleView.design({
        layout: { centerX: 0, top: 10, width: 400, height: 50 },
        classNames: ['another-custom-class'],
        name: 'Basic View API',
        icon: 'tutorial'
      }),
 
      blogBodyView: SC.LabelView.design({
        escapeHTML: NO, // This means that if there is HTML in the value string do not escape it, render the HTML
        layout: { centerX: 0, top: 70, width: 400, height: 500 },
        classNames: ['blog-body'],
        value: "This is the intro to an awesome blog post. <h2>New Header for cool stuff</h2> Keep posting some cool stuff"
      }),
 
      ratingBar: MyApp.RatingBarView.design({
        layout: { centerX: 0, top: 580, width: 400, height: 32 },
        classNames: ['rating-bar']
      })
    })
  });

And now if we add a little more css, we get the app to look like this:

using the createChildView()

The createChildView() is a very important function to use. You should only use this function when you are creating child views that will live in your parent view. This function will set up the ownership chain and all the little things that you need the view to do to function correctly in Sproutcore. There are two methods for using the createChildView() that you can choose to do: Class and Full Parameter method and the Design Pattern method. Let’s take a look at the first method, this is lifted from the view.js code in Sproutcore:

  /**
    Instantiates a view to be added to the childViews array during view 
    initialization. You generally will not call this method directly unless 
    you are overriding createChildViews(). Note that this method will 
    automatically configure the correct settings on the new view instance to 
    act as a child of the parent.
 
    @param {Class} viewClass
    @param {Hash} attrs optional attributes to add
    @returns {SC.View} new instance
    @test in createChildViews
  */
  createChildView: function(view, attrs) {
    // Code to do the stuff...
  }

The first parameter is the view class and the second parameters is all the attributes that you want to send to the function when it is created. The second method (Design Pattern) takes advantage of the fact that .design() acts just like a extension of the view class object. It is really up to you which you prefer to do, they work exactly the same.

Micellaneous

There are a couple of functions that are important to note when you are making basic views. You might not need to do all or any of these but they have some little quirks that need to be known:

init()

You might find the need to overwrite the init() function to do some special initialization. This is common practice but you must follow this pattern:

  init: function(){
    sc_super()
 
    // <== YOUR CODE HERE
  }

The reason for this is that the init() in the view is what sets up the bindings and that should be done first and then your stuff second.

didCreateLayer()

This function is called only once at the end of the cycle of creating the view layer. This is where you would set up some extra bindings or some special event handling that needs all the parts created and instantiated first. You do not need to call sc_super() if you extend() SC.View because there is no implementation of didCreateLayer() in SC.View. If you extend one of your own classes or one that does implement didCreateLayer() remember to call sc_super().

willDestroyLayer()

willDestroyLayer() is the paired function to didCreateLayer() and you would need to remove any work that would cause memory leaks that you did in the didCreateLayer()). The same sc_super() principles apply.

Conclusions

This is the basics for building custom views and composite views and 90% of the views that you will create will just need to use what is in this post and part 1. In a later post, I want to show you some more advanced stuff that you can do with the child views.

Invoking Methods

Invoking Methods are used when you are implementing a new generic view class, or designing a specific instance of a view for later use, or creating an instance of a view. There are three functions that do this:

• extend(): implements a generic view class
• design(): designs a specific instance of a view for later use
• create(): creates a specific instance of the view

Using extend()

For basic use, extend() is the function that you use to create a generic view class from another view class and usually this is the SC.View class. For this post, we will be building up a basic view and using all the basic methods that you will come across. So let’s begin…

So the first thing we have to do is make a simple view to show the title of the blog post. We will call this the TitleView. So we will run the following command:

  sc-gen view MyApp.TitleView

This will create the view from our root directory (/apps/my_app/views) and it will create a new file called title.js…

  // ==========================================================================
  // Project:   MyApp.TitleView
  // Copyright: ©2009 My Company, Inc.
  // ==========================================================================
  /*globals MyApp */
 
  sc_require('core');
 
  /** @class
 
    This is the Title View that we are going to use all the different
    View API Calls
 
    @extends SC.View
  */
  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    // TODO: Add your own code here.
 
  });

So this is just the shell of the object that we are going to fill with the stuff that we want use from the View API. When we use extend() we are extending the base class of SC.View and then we are going to add our own stuff as well as override some specific API elements of SC.View to get what we want. The use of extend() doesn’t create an instance of the view and here is the first…

So this isn’t very exciting yet, because we can’t see anything. So we have to actually create an instance of this TitleView and now we will learn the correct way of…

Using design()

This is a part of the Design View API. This is a very special API that is used to create instances of a view without actually creating the view yet. They are sort of stored for later use when the application needs to create them. So how we would use this would be to add the view to the main pane. In the main_page.js, we change it to look like this:

  // ==========================================================================
  // Project:   MyApp - mainPage
  // Copyright: ©2009 My Company, Inc.
  // ==========================================================================
  /*globals MyApp */
 
  sc_require('core');
  sc_require('views/title');
 
  // This page describes the main user interface for your application.  
  MyApp.mainPage = SC.Page.design({
 
    // The main pane is made visible on screen as soon as your app is loaded.
    // Add childViews to this pane for views to display immediately on page 
    // load.
    mainPane: SC.MainPane.design({
      childViews: 'titleView'.w(),
 
      titleView: MyApp.TitleView.design({
        layout: { centerX: 0, top: 10, width: 400, height: 50 }
      })
    })
 
  });

The most important thing to see here is that view cannot live outside an SC.Page. SC.Page is a holder for views to access them. It manages it keeps them accessible when they are hidden from the application and give you a means to get to them from other parts of tha application.

Using create()

The final Invoking Method is create(). This method is actually used the least and only when you need to create a view right at the moment. This is usually done in another view where you need to keep an internal view around for display purposes. We will create one later on when we add an action to the title bar to show a popup for the author.

Properties

Now, we will tackle the properties that are the most common for you to use when using the Sproutcore 1.0 View API. The first one that we will discuss is…

classNames

Out of the box, any view that extends() and SC.View has a class named sc-view, but you can add your own classes by adding a property to your view called classNames. This is an array of strings that will be added to the root element in the DOM object. So let’s make the TitleView look like this:

  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    classNames: ['title-view', 'another-custom-class']
 
  });

After we create a file called style.css in the english.lproj and add some simple css, our view should look like this:

and the HTML looks like this:

  <div style="left: 0px; right: 0px; top: 0px; bottom: 0px;" class="sc-view sc-pane sc-main" id="sc255">
    <div style="left: 50%; width: 400px; margin-left: -200px; top: 10px; height: 50px;" class="sc-view title-view another-custom-class" id="sc256"/>
  </div>

You can see that we have the class names that were add to the view. Now, you can add these class names in the MyApp.TitleView file or you can add the same property to the instance of the view when you use design() the only difference is that if you do it in the MyApp.TitleView it will be added to every instance of the MyApp.TitleView and if you use it in the design() the class will only exist for that instance. So the next thing that we want to do is change the tag of our view from a div to a H1 tag, we accomplish this by using the tagName and layout properties…

tagName and layout

We will make a simple change to the MyApp.TitleView to make it look like this:

  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    tagName: 'h1',
    classNames: ['title-view']
 
  });

Now, if we re-run the application the html will look like this:

  <div style="left: 0px; right: 0px; top: 0px; bottom: 0px;" class="sc-view sc-pane sc-main" id="sc255">
    <h1 style="left: 50%; width: 400px; margin-left: -200px; top: 10px; height: 50px;" class="sc-view title-view another-custom-class" id="sc256"/>
  </div>

Now, we have full control over what the base tag of our view. By the way, I moved one of the clasNames out to the instance of the view in the main pane to show that properties can live on the extend() or the design()

For the layout property, we have already used this in the MainPane and frozencanuck has a pretty good explanation of how to use layout to position objects on the page. The list of layout parameters that you can use are:

• top: Anchors to the top of the frame that you are in
• right: Anchors to the right of the frame that you are in
• bottom: Anchors to the bottom of the frame that you are in
• left: Anchors to the left of the frame that you are in
• centerX: Anchors to the middle horizontal position of the frame that you are in
• centerY: Anchors to the middle vertical postion of the frame that you are in
• height: The fixed height of the view
• minHeight: The minimum height of the view
• maxHeight: The max height of the view
• width: The fixed width of the view
• minWidth: The minimum width of the view
• maxWidth: The max width of the view

Layout is usually added to the actual instance of the view in the .lproj layer of the code. So the next two properties that we will talk about is…

status properties

These two properties (isEnabled and isVisible), when used, will add the following classes respectively: disabled and hidden. These can be very important classes you use with bindings. So if you had a controller that was going to hide one of the views you would create a binding like this:

  MyApp.mainPage = SC.Page.design({
 
    // The main pane is made visible on screen as soon as your app is loaded.
    // Add childViews to this pane for views to display immediately on page 
    // load.
    mainPane: SC.MainPane.design({
      childViews: 'titleView'.w(),
 
      titleView: MyApp.TitleView.design({
        layout: { centerX: 0, top: 10, width: 400, height: 50 },
        classNames: ['another-custom-class'],
        isVisibleBinding: 'MyApp.blogController.showTitle'
      })
    })
 
  });

This will change that value on the view to make it visible or not depending on the bound value. Now, there is one more property that we need to talk about and that is…

displayProperties

The property displayProperties is a very special property that will trigger the view to re-render itself when new data is set on the view. So let’s add a new property that we will use on the view called name and icon that will be used to print out the name of the blog post that this title view is representing and add an icon to the title. So we will change the MyApp.TitleView to look like this:

  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    /**
    @public: Property to change the view too..
    */
    name: '',
    icon: '',
 
    tagName: 'h1',
    classNames: ['title-view'],
    displayProperties: ['name', 'icon']
 
  });

Now, when ever something calls a set() on these any one of these properties, the view will trigger a refresh on the view and re-render the html with the changes to reflect the new values. We have add this it is all well and good but it doesn’t really help us at all. We need to add some functions to the view to create our our custom feel to the view…So we will transition to talking about…

Functions

The very first function that we will talk about is the most important one gives us the ability to create a custom feel to our view and that function is…

render()

The render() function has two parameters: context and firstTime. The first (context) is the SC.RenderContext that is used to build up the HTML to render in the page. Part of the power of Sproutcore is that it makes use of the innerHTML() speed in the browser to re-render pages very quickly without the need for DOM manipulation. This is very important for performance on the not so stellar browsers (like IE). The second parameter is firstTime and this indicates when the object is rendered for a second time or more. This can be triggered by a change in the one of the displayProperties. So, we are going to add a render() to to the MyApp.TitleView:

  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    /**
    @public: Property to change the view too..
    */
    name: '',
    icon: '',
 
    tagName: 'h1',
    classNames: ['title-view'],
    displayProperties: ['name', 'icon'],
 
    render: function(context, firstTime){
      var name = this.get('name');
      var icon = this.get('icon');
 
      if(firstTime){
        context = context.begin('div').addClass('image %@-icon'.fmt(icon)).end();
        context = context.begin('span').addClass('name').text(name).end();
      }
    }
 
  });

and the MainPane is changed to look like the following…

  MyApp.mainPage = SC.Page.design({
 
    // The main pane is made visible on screen as soon as your app is loaded.
    // Add childViews to this pane for views to display immediately on page 
    // load.
    mainPane: SC.MainPane.design({
      childViews: 'titleView'.w(),
 
      titleView: MyApp.TitleView.design({
        layout: { centerX: 0, top: 10, width: 400, height: 50 },
        classNames: ['another-custom-class'],
        name: 'Basic View API',
        icon: 'tutorial'
      })
    })
 
  });

Added some css to make it look different in style.css:

  h1.title-view {
    background-color: red;
  }
 
  div.image {
    position: absolute;
    left: 10px;
    top: 9px;
    height: 32px;
    width: 32px;
    background-color: green;
  }
 
  span.name {
    float: right;
    margin-top: 9px;
    margin-right: 10px;
    width: 338px;
    height: 32px;
    background-color: blue;
    color: white;
    text-align: center;
    font-size: 20px;
  }

and now it looks like this:

with the HTML looking like this:

  <h1 style="left: 50%; width: 400px; margin-left: -200px; top: 10px; height: 50px;" class="sc-view title-view another-custom-class" id="sc256">
    <div class="image tutorial-icon"/>
    <span class="name">Basic View API</span>
  </h1>

which brings us to another…

We also touched on some of the functions in the SC.RenderContext:

• begin(): This begins a tag and it takes one parameter of tagname
• addClass(): This adds a class to the current context tag
• text(): This adds the inner text of the current context tag
• end(): This ends the current context tag

I will do a later post on the SC.RenderContext API. So now lets do something a little tricky, we are going to modify the view at runtime and have the render function called again to make the view change. So we change the TitleView again:

  MyApp.TitleView = SC.View.extend(
  /** @scope MyApp.TitleView.prototype */ {
 
    /**
    @public: Property to change the view too..
    */
    name: '',
    icon: '',
 
    tagName: 'h1',
    classNames: ['title-view'],
    displayProperties: ['name', 'icon'],
 
    render: function(context, firstTime){
      console.log('Rendering TitleView');
      var name = this.get('name');
      var icon = this.get('icon');
      var isFav = this.get('isFavorite');
 
      if(firstTime){
        context = context.setClass('favorite', isFav);
        context = context.begin('div').addClass('image %@-icon'.fmt(icon)).end();
        context = context.begin('span').addClass('name').text(name).end();
      } 
      else {
        this.$('div.image').replaceWith('<div class="image %@-icon" />'.fmt(icon));
        this.$('span.name').text(name);
      }
    }
 
  });

We are actually doing DOM manipulation with the subsequent calls and we are touching on the first part of the SC.CoreQuery which is a subset of the JQuery DOM manipulation. You can add JQuery to your project and it will override the SC.CoreQuery, but there are some really helpful function that are very similar to the SC.RenderContext API. The way that you access the elements is very JQuery-selectoresque with the $() notation. If you want to access the base object of the view, you can use: this.$() which you can add class or change the css. And this brings up another:

To see some changes, you can run the following:

  var titleView = MyApp.mainPage.getPath('mainPane.titleView')
  SC.run(function() { titleView.set('name', 'RenderContext API'); titleView.set('icon', 'commentary'); })

Conclusions

For part 1, we have done all that we need to do create custom views and manipulate them with changes to the view when properties get updated. In part 2, we will add some more functionality like add childViews and pair them with the current SC.RenderContext to make composite views with custom HTML.

The Basics

In more detail, the Root Controller Paradigm is based off the notion that you need a controller that is the source or root of where all the other controllers get their content. This makes maintenance much easier because all the work is usually done in one place for the records and the other controllers have maybe 2-3 lines of code to set up the bindings correctly to populate the content. Then, if you need to do some specialized work (like searching) you do it in the appropriate layer. Your controller chain is segmented in the proper object-oriented manner saving you time in development, documentation, and debugging.

I usually follow these steps to make it easier:

1. Draw a Picture of the Root Controller, Controller Chain and Bindings
2. Create the Root Controller
3. Create the Controller Chain with the Bindings
4. Add any specialty code that is needed in the Controller Chain

Step #1: Draw a Picture

I find it extremely useful to draw a picture of the Controller Chain and the Bindings. This is the best way to review your work and make sure you haven’t forgotten anything. It is also helpful to diagram out what functionality you need at what layer. It is also a wonderful documentation tool for future reference. For this iTunes-like functionality, the Controller Chain looks like the following:

You can see that the Root Controller is the sourceCategoriesController. This is where most of the work will be done and where we will spend most of our time and where most of the complex stuff will be done. Then you can see how the Controller Chain will cascade the data through the structure. You can see we are going to use an interaction of a TreeController, ArrayControllers, and ObjectControllers to accomplish what we want to do.

Step #2: Create the Root Controller

When we develop the sourceCategoriesController (Root Controller), we are going create a TreeController that will cascade the data through the structure. This particular controller will drive the view on the left side of our iTunes-like app. The structure is lifted from iTunes to give a point of reference. Here is a sample of what the code would look like:

  // ==========================================================================
  // SproutTunes.sourceCategoriesController
  // ==========================================================================
 
  sc_require('core');
 
  /** @static
 
    This is the Root Controller...
    @extends SC.TreeController
    @author Evin Grano [EG]
  */
  SproutTunes.sourceCategoriesController = SC.TreeController.create(
  /** @scope SproutTunes.sourceCategoriesController.prototype */ {
 
    treeItemIsGrouped: YES,
    content: null,
 
    /**
      @public function for contructing the source list on the left side
    */
    refreshSources: function(){
 
      var librarySources = SC.Object.create({
        treeItemIsExpanded: YES,
        hasContentIcon: NO,
        displayName: 'Libraries',
        treeItemChildren: [
          SC.Object.create({
            contentValueKey: 'displayName',
            displayName: "Music"
            items: function(){
              var collection = [];
              var q = SC.Query.create({recordType: SproutTunes.Music});
              collection = store.findAll(q);
 
              return collection;
            }.property().cacheable()
          }),
          SC.Object.create({
            contentValueKey: 'displayName',
            displayName: "Movies",
            assets: function(){
              var collection = [];
              var q = SC.Query.create({recordType: SproutTunes.Movie});
              collection = store.findAll(q);
 
              return collection;
            }.property().cacheable()
          }),
 
          // ADD MORE LIBRARY SOURCES: TV SHOWS, PODCASTS, ETC...
        ]
      });
 
      var playlists = SC.Object.create({
        treeItemIsExpanded: YES,
        hasContentIcon: NO,
        displayName: "Playlists",
        treeItemChildren: [
          SC.Object.create({
            displayName: "SproutTunes DJ".loc(),
            items: function(){
              var collection = [];
              // CODE FOR CREATING DJ MUSIC PLAYLIST
              return collection;
            }.property().cacheable()
          }),
 
          // Enter a List of SC.Objects for Playlists
        ]
      });
 
      var allSources = SC.Object.create({
        treeItemIsExpanded: YES,
        treeItemChildren:[librarySources, playlists]
      });
 
      this.set('content', allSources);
      this.set('selection', SC.SelectionSet.create());
    }
  });

So you can see that SC.Object that is selected will drive the content of the sourceController.

Step #3: Create the Controller Chain with the Bindings

This is the first controller that gets the benefits of the Root Controller Paradigm. The code would look something like this:

  // ==========================================================================
  // SproutTunes.sourceController
  // ==========================================================================
 
  sc_require('core');
  /** @static
 
    @extends SC.ObjectController
    @author Evin Grano
  */
  SproutTunes.sourceController = SC.ObjectController.create(
  /** @scope SproutTunes.sourceController.prototype */ {
    contentBinding: 'SproutTunes.sourceCategoriesController.selection',
    contentBindingDefault: SC.Binding.single()
  });

Now, we start the chain so the next controller in our chain is the itemsController. This is driven by the ‘items’ property that we set up in the Root Controller objects. The code for this would look like this:

  // ==========================================================================
  // SproutTunes.itemsController
  // ==========================================================================
 
  sc_require('core');
  /** @static
 
    @extends SC.ArrayController
    @author Evin Grano
  */
  SproutTunes.itemsController = SC.ArrayController.create(
  /** @scope SproutTunes.itemsController.prototype */ {
    contentBinding: 'SproutTunes.sourceController.items',
 
    // search stuff
    search: null,
    searchContent: null,
 
    _searchHasChanged: function(){
      var c = this.get('content');
      this.set('searchContent', c);
    }.observes('search'),
 
    _contentHasChanged: function(){
      var c = this.get('content');
      this.set('searchContent', c);
    }.observes('[]')
  });

Next, we have the next part of the chain which is the itemsSearchController that is what the ‘song’ list will show. The code will look like this:

  // ==========================================================================
  // SproutTunes.itemsSearchController
  // ==========================================================================
 
  sc_require('core');
 
  /** @static
 
    @extends SC.ArrayController
    @author Evin Grano
  */
  SproutTunes.itemsSearchController = SC.ArrayController.create(
  /** @scope SproutTunes.itemsSearchController.prototype */ {
    contentBinding: 'SproutTunes.itemsController.searchContent'
 
  });

and now the final controller in the chain, itemController and this is what the code would look like:

  // ==========================================================================
  // SproutTunes.itemController
  // ==========================================================================
 
  sc_require('core');
  /** @static
 
    @extends SC.ObjectController
    @author Evin Grano
  */
  SproutTunes.itemController = SC.ObjectController.create(
  /** @scope SproutTunes.itemController.prototype */ {
    contentBinding: 'SproutTunes.itemsSearchController.selection',
    contentBindingDefault: SC.Binding.single()
  });

Step #4: Add Specialty code

Now that we have our completed Controller Chain, we could hook up a ListView to the sourceCategoriesController to get a list on the left side and we could hook up another ListView to the itemsSearchController to show the list of items once the source is chosen. But, we want to add searching to the itemsController. The code would look like this:

  // ==========================================================================
  // SproutTunes.itemsController
  // ==========================================================================
 
  sc_require('core');
  /** @static
 
    @extends SC.ArrayController
    @author Evin Grano
  */
  SproutTunes.itemsController = SC.ArrayController.create(
  /** @scope SproutTunes.itemsController.prototype */ {
    contentBinding: 'SproutTunes.sourceController.items',
 
    // search stuff
    search: null,
    searchContent: null,
 
    _updateSearchContent: function(){
      var c = this.get('content');
      var search = this.get('search');
 
      if (!search || !c){
        this.set('searchContent', c);
      }
      else {
        search = search.toLowerCase();
        var currItem, currSearchFields;
        var searchArray = [];
        for(var i = 0, len = c.get('length'); i < len; i++){
          currItem = c.objectAt(i);
          currSearchFields = currItem.get('searchFields');
          if (currSearchFields.match(search)) searchArray.push(currItem);
        }
 
        this.set('searchContent', searchArray);
      }
    },
 
    _searchHasChanged: function(){
      this._updateSearchContent();
    }.observes('search'),
 
    _contentHasChanged: function(){
      this._updateSearchContent();
    }.observes('[]')
  });

Conclusion

Now, you have the very clear separation of the all the functionality in controller layer and you can trust that the bindings are going to be set correctly. So most of your work is done in the Root Controller and then you just add functionality only at the levels that make sense. This will keeps all the information in the correct layer of the MVC structure as well as increase your ability to maintain the code and you get the benefits of the bindings in the controller layer.

What is a Composite View?

As stated before, a composite view is a custom view that you build that is mainly made up of other views that operates in a special way. You would often use this when you are developing a structure of views in your ‘.lproj’ layer and you find yourself repeating a paradigm or wanting a group of views or view structure to operate in a specific manner. Examples of these can be a composite view made up of a textfield, labels, buttons that change the look and appearance of view. View that have special mouse functionality like a popup window or similar structure that makes passing some simple information for bindings or content to a internal child view.

Example

I will use a very simplistic example of a composite view for a master list view with a search bar. I call this composite view the MasterView and it will consist of a SC.TextFieldView and a SC.ListView. You usually don’t want to do such a simplistic view as this, but it will work for the purposes of illustration. The code might look like this:

myApp.MasterView = SC.View.extend(
/** @scope myApp.MasterView.prototype */ {
 
  classNames: ['master-view'],
 
  /**
    Necessary config elements to set up binding in the composite view
  */
  contentPath: '',      // Binding Path for the content of the ListView
  selectionPath: '',    // Binding Path for the selection on the ListView
  searchPath: '',       // Binding Path for the text searching
  contentValueKey: '',  // ContentValueKey to be passed to the ListView
 
  /**
    Overwritten createChildView where you set up all 
    the internal child view and where we are
    going to use the Binding Paths
  */
  createChildViews: function() {
    var childViews = [], view;
 
    //Add the search text field
    view = this.createChildView(
      SC.TextFieldView.design({
        layout: {/* layout here */},
        valueBinding: this.get('searchPath')
      }),
      { rootElementPath: [0] }
    );
    childViews.push(view);
 
    view = this.createChildView(
      SC.ListView.design({
        layout: { /* layout here */ }, 
        contentValueKey: this.get('contentValueKey'),
        contentBinding: this.get('contentPath'),
        selectionBinding: this.get('selectionPath'),
      }),
      { rootElementPath: [1] }
    );
    childViews.push(view);
 
    this.set('childViews', childViews); 
  },
 
  /* Do Special Stuff as Needed */
});

Then, as you need to create instances of your composite view in the ‘.lproj’ layer it would look something like this:

  aRealMasterView: myApp.MasterView.design({
    layout: { /* layout here */ },
    contentPath: 'myApp.myRecordsController.arrangedObjects',
    selectionPath: 'myApp.myRecordsController.selection',
    searchPath: 'myApp.myRecordsController.search',
    contentValueKey: 'name'
  })

Conclusion

Its as simple as this. Now you are able to pass your bindings around without creating superfluous bindings that have to be updated, but have no real using in your composite view layer. The ‘-Binding’ convention is a great convenience, but unless you specifically want to create a binding in that view layer it is easily misuse and can cause performance hits.

the basics

Bindings are just configuration that one sets up so that when a value changes it changes all the elements that are connected to it. They are found most often in the view layer, but are used heavily in the controller and the model as well. We will focus on the view layer. Here is a simple picture of what bindings do for you:

The general concept is that all the views connect to one value ‘name’ in the controller so that if it changes at any time it is reflected automatically in the views. This is the power of bindings.

the basic rules for bindings

There are a few simples rules to follow when using bindings in sproutcore. If you follow these, you will have a much better understanding of what is occurring and will make code debugging much easier. Often times if your model and controller layers are set up correctly, most of your bugs will ben in your bindings.

Rule #1: Use the ‘-Binding’ naming convention ONLY for a bindings

When you set up a binding you uses the following convention:

  // DO THIS 
  nameBinding: 'myApp.modelController.name',
  // NOT THESE
  skiBinding: 'Rossignol'
  glueBinding: 'Very Firm'

Often you might want to pass bindings through a view to another view. DO NOT use the ‘-Binding’ convention! Think of anything with the postfix of ‘-Binding’ as a reserved word. This will set up a real binding that will update whenever something changes it will update. This will slow your app down as things are being updated without the need.

Rule #2: Use the ‘-Path’ naming convention to pass a binding to another view

If you do need to pass a binding to a child view or pass it around for some reason, use the ‘-Path’ naming convention:

  namePath: 'myApp.modelController.name'

A further discussion of using this convention can be found in the discussion about composite views.

Rule #3: View Bindings must only be set up in the ‘.lproj’ layer

Fight the urge to set up bindings for the view layer anywhere but in the ‘.lproj’ layer. You should never be directly setting bindings in a view class even if you know what something is supposed to be. This is a maintenance nightmare and will cause lots of problems if you ever have to change something. It also violates some of the basic OO design structure. If you need a bind set up further down, use the ‘-Path’ naming convention.

Rule #4: Use One Way Bindings whenever possible

Always use a One Way Binding when you can. This will speedup performance because the SC RunLoop won’t have to do extra work to update values and observe values on both ends. Example:

  nameBinding: SC.Binding.from('myApp.modelController.name').oneWay()

This is particularly useful when you are creating views that are for display purposes only. There is no need to have any changes to the view be observed for change.

Using Bindings in Sproutcore

When you set up bindings you are actually setting up a binding pattern that is created at run time in the init() method. This is why it is very important to add the sc_super() to the top of your init() if you ever overwrite it.

The ‘*’ Trek Convention

Often times you will see a ‘*’ being used in some bindings in sproutcore. This little feature is one of the massive improvements that sproutcore has made to Binding from Cocoa. The ‘*’ creates a chained observation structure that is very powerful and causes less code to have to be created.

The ‘*’ creates the observation point in the binding observation chain. Everything to the left of the ‘*’ is the object that is to be observed and everything to the right of the ‘*’ is the property chain that is being observed for changes. Example:

  nameBinding: 'myApp.modelController*otherProperty.name'

An english reading of this would be: “Observe ‘myApp.modelController’ for changes to the property ‘otherProperty.name’”. This means that any change to ‘otherProperty’ or ‘otherProperty.name’ will trigger a binding update. This is particularly useful when you want to observe an array for changes to the whole thing or to the size of the array.

You never want to add a ‘*’ to the last property it is already implied:

  nameBinding: 'myApp.modelController.name'
  // Same as...
  nameBinding: 'myApp.modelController*name'

Absolute and Relative Paths

Most of the time you will be using an absolute path for setting up your bindings. This is the most common form that you will use. Often you might want to make a relative path for a binding. This will be used when you want to bind a child view to a parent view in a view class. You can still use the ‘*’ naming convention. Here is an example of a relative path:

  nameBinding: '.parentView.name'
  descriptionBinding: '.parentView*otherObject.name'

Setting up bindings implicitly

There are a few times where you might want to set up binding explicitly. The best to use the .bind() method on SC.Object:

  this.bind('name', SC.Binding.from('myApp.modelController.name').oneWay());

You will want to use this rarely and only when you want to do some dynamic binding that can change or morph. For the general uses, you want to avoid using this at all costs, but it is good to know for future references.

conclusion

Bindings are incredibly powerful and are the base of what makes Sproutcore so cool. In a later post we will talk about how to use bindings to your advantage in the controller layer with the Root Controller methodology.

So you might be reading the last post and got excited want to try it in one of your own applications. Then, the Reality Fairy drops by to seed doubt and you say, ‘Great, but what does it look like in real life’. So we have created an example application to show how it is done. First, we will start with the statecharts. This is a very simple application of a contact address book.

Using Statecharts for GUI Interactions…

The first statechart is of the general application structure and workflow:

You can see from the chart that there are two states that have substates. This one of the powers of statecharts in limiting the complexity of the application and diagram. The next statechart is for the File Upload Wizard:

Next, we will show the last state chart for the failure state:

Using Statecharts for Server Calls…

We created a new collection object that handles the calls to the server. The reason that this is helpful is that now you can use the objects currently loaded in the collection and then refresh the list in the background seamlessly. This is the state chart:

Example application

We created a really simple application called Contact Tool. It’s a port of the contacts sproutcore sample app to the new bitburger view with states for server calls. We’ve left all the state transitions explicit so you can see it go through all the states. You can also download the source from github here.

Introduction

In this post, we will discuss creating a sproutcore application using a modeling method called ‘Statecharts’. This was invented by a man named David Harel, who invented it in order to have a state diagram that could model things like: superstates; concurrent states; and activities as part of a state. These are starting to gain more use in the software development world because of the distinct advantages that it provides to developers. These advantages include, but are not limited to:

• Usability Testing
• Interaction Testing
• Scope Definition
• Bug Discovery (they’re in the statechart)
• Real Bugs are easier to Find/Fix

Statecharts also provide the ability to model cross-state events and interactions on multiple levels. This reduces the complexity of the diagrams and pre-segments the application into functional areas for development. You often find that once you get an ‘area’ correct is just stays ‘correct’ and make modification to the code a lot easier. There is another great paper on use of statecharts here.

Using Statecharts in Sproutcore

One of the distinct advantages of Statecharts is that you can actually use them in your code. That way you can match your statecharts directly to the code. This is accomplished in sproutcore with a plugin that Erich Ocean wrote. You can install it with the Sproutcore Build tools:

  sc-install onitunes-statechart

The best structure for using statecharts in Sproutcore is to make two new files: core_states.js and core_actions.js.
core_states.js should look like this:

  require('core');
  require('core_actions');
  MyApp.mixin( /** @scope MyApp */{
    goStateA1: function(){
      // TODO: Settings for State A1
    },
    goStateA2: function(){
      // TODO: Settings for State A2
    },
    goStateB1: function(){
      // TODO: Settings for State B1
    },
    goStateB2: function(){
      // TODO: Settings for State B2
    },
  });

core_actions.js should look like this:

  require('core');
  MyApp.mixin( /** @scope MyApp */{
    submitLogin: function() {
      var handled = NO;
      switch(this.state.a){
          case 1:
            // TODO: More actions
            this.goState('a', 2);
            handled = YES;
            break;
      }
      if(!handled) console.log('submitLogin Action not handled in state %@[%@]'.fmt('a',this.state.a));
    },
    reauthenticate: function() {
      var handled = NO;
 
      switch(this.state.a){
          case 1:
          case 2:
            // TODO: More Actions
            alert('You need to Reauthenticate...');
            this.goState('a', 1);
            window.location = "/login.aspx";
            handled = YES;
            break;
      }
      if(!handled) console.log('reauthorize Action not handled in state %@[%@]'.fmt('a',this.state.a));
    }
  });

What do statecharts look like?

Statecharts look a lot like state diagrams and are comprised of boxes and lines with some standard styling to indicate what they are. Major areas of statecharts are divided into two different types: States and Events.

States

States are further divided into the following type of states: Start, End, Switch, External, Transient, States, State w/ substates, and History

Rules for States

There are several rules for the different state types. Start, End, External, and History States are more functional indications than real states. They tell you how the application is supposed to function and basically modify the states they are linked to. States and State w/ substates are the most common and the most used. These state are only supposed to be setting values. There should be no ‘if’ or ‘switch’ statements in these states. This is where the power of statecharts is revealed when you are in a state, it looks only one way. The last two states: Switch and Transient are special. Switch states are allowed to have ‘if’ and ‘switch’ statements but only those statements. Transient states are ‘holding’ states with only Auto exit events.

This is what they look like in the code:

  goStateA1: function(){
    MyApp.set('pageView', 'MyApp.loginPage.mainView');
    MyApp.set('globalNavigationMenu', 'MyApp.navigationPage.globalMenuView');
  },
  goStateA2: function(){
    MyApp.set('pageView', 'MyApp.bodyPage.mainView');
    MyApp.set('globalNavigationMenu', 'MyApp.navigationPage.globalMenuView');
  },

Events (transitions)

Events are further divided into the following types: Regular and Auto. They can linked to states and sub-states; and they can have parameters and/or conditions. They are represented by arrowed lines.

  submitLogin: function() {
    var handled = NO;
    switch(this.state.a){
        case 1:
          // TODO: More actions
          this.goState('a', 2);
          handled = YES;
          break;
    }
    if(!handled) console.log('submitLogin Action not handled in state %@[%@]'.fmt('a',this.state.a));
  },

Miscellaneous State Objects:

In addition to the major components of States and Events, there are several other elements that are useful. They include:

• Grouping: This is where you box a few state that have the same exit\entry events so that you can clean up the diagram
• Parallel States: These are concurrent states that are mutually exclusive. This happens rarely.
• Indexing: Once you create the state chart you index the states numerically and group them by alphabetical area

Where To Use Statecharts

GUI Interactions

The primary use of statecharts in development is to describe the function of the application. This is a interaction map of the application.

Object Life Cycle

For complex models, you can use statecharts to handle the life cycle of the object. This allows different interactions to occur and can gate the object.

Server Communications

Statecharts are perfect for handling complex calls to the server and lazy loading of information. You can use them for interactive speed gains such as a quick load of object followed by a larger load of objects in the background.

Conclusion

Statecharts are a great tool to use in developing interactive applications. They provide a great way to segment and develop the application with fewer bugs. Sproutcore comes with great plugin to help you create solid applications. We will have a follow up post to show you what is really looks like.

Configuration

My configuration file looks like the following:

  [core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
    ignorecase = true
  [remote "origin"]
    url = evin@my.ip.address.to.git:/var/git/application.git
    fetch = +refs/heads/*:refs/remotes/origin/*
  [remote "mike"]
    url = evin@ip.address.to.git:/var/git/application.git
    fetch = +refs/remotes/mike/*:refs/remotes/mike/*
  [remote "chris"]
    url = evin@ip.address.to.git:/var/git/application.git
    fetch = +refs/remotes/chris/*:refs/remotes/chris/*
  [remote "mo"]
    url = evin@ip.address.to.git:/var/git/application.git
    fetch = +refs/remotes/chris/*:refs/remotes/mo/*
  [branch "master"]
    remote = origin
    merge = refs/heads/master

As you can see, I have 3 developers that send me branches for review. Each of them have their own root branch that all their topic branches are attached.

Integrator Process

First, you do the following:

  git checkout master
  git pull origin master

This is to make sure you are on the most current master branch (this should always be the case). Now, look at each of the emails for the topic branch for each of the developers:

  git branch topic_branch
  git merge <username>/topic_branch
  git diff
or
  gitk

The reason for the local topic branch is that it makes a staging area for the merge to make sure the changes are good and wont break anything. This is where you would run the unit test and any integration tests that you have made or just do so manual testing. Always do the code review at this point. For new members of my team or developers that aren’t used to the technology or code base, I try to do this in person if possible. It really helps you understand peoples coding styles and creates an easy way to give good feedback.
If merge is okay and code acceptable, then do the following:

  git checkout master
  git merge topic_branch
  get branch -d topic_branch

NOTE: You use a the lowercase -d, this checks to make sure your merge has fully been incorporated in the HEAD. This is a good simple check that everything went as planned when you delete. If, on the other hand, the code is not acceptable and you want to reject the merge, you would do the following:

  git checkout master
  git branch -D topic_branch

NOTE: You use an uppercase -D in this case because that forces a delete of the branch regardless of the merge state. And don’t forget to follow up with an email or conversation on why the change was rejected in a detailed manner. After you have integrated all the topic branches from the various developers, you need to do one last thing:

  git push origin master

This allows all the other users to get the latest and greatest when they pull from the master repository in the morning or when you make your integrations. The very last thing that I do is because our project has a slave READ-ONLY Subversion repository that is a part of a wider integration build process. I wrote a simple Ruby script called Git2svn that slaves the svn repository to the current master branch in git. I have open sourced the script on Github. You can check it out here.

Git Configuration

In order to do the single integrator process, you need to set up all the developers to have the same git config file. It should look something like this:

[core]
  repositoryformatversion = 0
  filemode = true
  bare = false
  logallrefupdates = true
  ignorecase = true
[remote "origin"]
  url = evin@my.ip.address.to.git:/var/git/application.git
  fetch = +refs/heads/*:refs/remotes/origin/*
  push = +refs/heads/*:refs/remotes/evin/*
[branch "master"]
  remote = origin
  merge = refs/heads/master

Obviously, replace “evin” with the user name of each of the developers. This configuration is accomplishing two things. One, it set it so that when the developer does a:

  git pull origin master
or
  git fetch origin master

That is pulls\fetches from the master branch. Two, when the developer is using his master branch or topic_branch, they will only push to a remote branch root with their username and doesn’t contaminate the master branch.

Daily Developer Process

Now, each of the individual developers then run the follow commands at the beginning of the day:

  git checkout master
  git pull origin master

Then, the developer starts to work on each of their “topic_branches”:

  git checkout topic_branch
  git rebase master

What this does is rewrite the history a little on the “topic_branch” to make the alignment correct for other changes that other developers made the day before. Once, this is done you might need to fix any merge errors to bring topic_branch current. Now, do the coding for the day on the “topic_branch”. Once the “topic_branch” has reached the point of integration with the master branch, do the following:

  git push

Then, Email Integrator with: “Integrator, please merge evin/topic_branch”. Thats it for each of the developers…

Key Value Coding (KVC)

Key Value Coding is where to ‘get’ or ‘set’ properties on an object in the following format:

  myModel.get('myProperty'); 
  myModel.set('myProperty', 'myValue');

Access to all properties **NEEDS** to be done in this way to invoke the KVC and KVO structure in Sproutcore. Only violate this in very narrow ways and only because you know what you are doing.

Key Value Observing (KVO)

Key Value Observing (KVO) is usually harnessed through the view rhtml object by binding the values of the views to some things:

  titleBinding: 'App.modelController.name'

It can also be done in the code when you set the binding structures in the controllers.

Using KVC and KVO

I will start with a picture:

This is a representation of what you should use. When in a View and you change something you drive changes using KVC ‘set’ functions through the View to the Controller and then through to the Model. Then the changes *bounce* back up using the KVO that you have set up. This provides a great way to systemically make changes in an orderly manner. There is a great discussion on KVC and KVO
on the Sproutcore Wiki by Erich Ocean (onitunes)