NOTE: This page is currently under construction. Most of this page contains rough notes intended to help people get started while I work on more polished text. You may find gaps here that make the notes a bit harder to follow than fully drafted prose. If you would like to help turn these notes into something more accessible, please claim the section you want to work on in the comments and thanks! -Charles

A good way to learn exactly what the view helpers take (as options) is to read the source code .

About View Helpers

View helpers are JavaScript classes that manage part of your web page for you. They create dom elements, handle events, perform animation and lots of other useful things. In fact, in SproutCore you often will not work with HTML or the DOM directly unless you are writing a view. Instead, you should let the SproutCore view classes handle it for you.

Although views are JavaScript, they have an HTML component to them also, of course. Rather than make you write some HTML and JavaScript to build your views, SproutCore comes with a useful set of view helpers that can automatically generate both the HTML and JavaScript for you. This can make your life much easier when it comes to designing the visual part of your application.

View helpers are special functions written in a domain specific dialect of ruby that can take the pain out of generating nice UI controls for your application. You use a view helper in your .rhtml template files by including the name of the view helper plus any options like so:

<%= button_view :my_button, :title => "OK", :action => "Contacts.editController.commitChanges" %>

When this view helper is processed while building your HTML, it will generate both the HTML and JavaScript required to generate a button. It can also optionally generate CSS styles for your page, though currently no view helpers actually use this facility.

Using View Helpers In Your Own Code

All view helpers follow some specific patterns:

1. You wrap a view helper in <%= and > braces. i.e. <= button_view … %> This is also known as embedded ruby.

2. If you would like to specify the HTML/views that should appear INSIDE of the view, then do not use the “=” sign at the beginning and place a “do” at the end of the phrase, then use <% end %> to conclude the view.

EXAMPLE WITHOUT INNER-HTML:

<%= view :my_view %>

EXAMPLE WITH INNER-HTML:

<% view :my_view do %>
-- this will be included as HTML inside of the view --
<% end %>

For very short phrases of text, you can also specify the inner html as an option:

<%= view :my_view, :inner_html => "this will appear inside of the view" %>

Basic Options

Every view helper accepts the following basic options. All options are optional except you must specify either a view_identifier, an outlet or both:

<%= view_name :view_identifier, 
   :outlet => :outlet_name, 
   :bind => {}, 
   :attributes => {}, 
   :tag => 'TAG'
   :properties => {}, 
   :view => 'SC.View'
   %>

• view_name: This is the type of view you want to create. The most basic type is a generic ‘view’, but there are specific subtypes available for most controls. See the View Helper Reference for more information.
• view_identifier This is the name by which you will access the view in code. You must use a view_identifier for all top-level views (i.e. those that are not included inside of any other view). The identifier must be unique. Typically you specify a view identifier using a colon and all lower case and underscores (which is the syntax for a Ruby symbol). This will be converted into camelCase for use in JavaScript.
• outlet The value of this option is the name you want the view to have on its parent view. Most of the time you won’t need to access views directly so you won’t care what name it has. In that case, you can just use :outlet => true and SproutCore will generate a unique name for you.
• bind This hash identifies any properties you want bound to other properties in the system. You will use this quite often to setup bindings for your views. The format is :bind => { :property => ‘path.toOther.property’ }. “property” should be the name of a property on the view you are creating such as “value” or “content”, while “path.toOther.property” is a JavaScript path to some other property you want to bind to.
• attributes This optional hash specifies any attributes to set on the root HTML element for the view. Usually you won’t need to use this directly since the view helper will fill in attributes for you but this is available in case you need to provide some non-standard options.
• tag This is the tag name for the root HTML element. Usually the view helper will fill this in for you but you can use this option to override it.
• properties This hash identifies any properties you want defined on the JavaScript generated for the view. Normally the view helpers will create all the properties you need, but you can use this to provide any non-standard options that you require.
• view Specifies the class of the created view. Normally the view helper will generate this for you so you don’t need to do it yourself but if you create your own subclass, you can override the default view class with this property.

— More forthcoming.

Related Links

• View Helper Reference – Reference documentation for view helper tags

Comments

If you make edits to this page, please leave a comment here indicating what you changed. Thanks. -Charles

Minor cleanup. -bruml2

I have a question about the view_identifier. Since Ruby allows symbols to be camel case, and Javascript allows identifiers to be lowercase with underscores, I don’t really understand why both are used. Browsers do switch between hyphen separated words (in CSS) and camel case (in Javascript) because hyphens are not allowed in Javascript identifiers, but using two ways to spell identifiers depending where you are in the code, for no technical reason I am aware of, seems like it is making the developer do more work converting in their head, and making the framework more confusing to use. Is there another reason besides the one given above (which doesn’t appear to hold water for the reasons I’ve given)? —Dethe

if you get the following JS error in SC.Page.get():

ret is null
if (SC.window && !ret.parentNode) {

make sure to nest your view helpers in other views. i just wasted a day doubting everything i have written, just to find out i had to nest view helpers properly. i.e. helpers like list_view don’t work if they are direct children of content_for().

i don’t know if this is obvious for people doing Cocoa, for HTML output people it certainly isn’t! Also, I didn’t find this documented anywhere; is this a bug, or a requirement of Sproutcore?

Example:

<% content_for('body') do %>

  <% view do %>
    <%= list_view :outlet => true,
      :content_value_key => :name,
      :bind => { :content => 'StylesBrowser.stylesController.arrangedObjects' }  
    %>

    <%= button_view :load_styles_button, 
      :title => 'Load Styles', 
      :action => 'StylesBrowser.stylesController.loadStyles' 
    %>
  <% end %>
  
<% end %>

the <%= view %>’s surely can be other types of view helpers.

— phillipoertel

• added 2 new paragraphs as the 1st 2 paragraphs under ‘about view helpers’ section – that explains what view are in a nutshell and what view helps help you do. Thought it was relevant here as if you don’t know what a view is then you might not know why you would need to use view helpers. — gskluzacek