Namespace: SC.RenderContext

A RenderContext is a builder that can be used to generate HTML for views or to update an existing element. Rather than making changes to an element directly, you use a RenderContext to queue up changes to the element, finally applying those changes or rendering the new element when you are finished.

You will not usually create a render context yourself but you will be passed a render context as the first parameter of your render() method on custom views.

Render contexts are essentially arrays of strings. You can add a string to the context by calling push(). You can retrieve the entire array as a single string using join(). This is basically the way the context is used for views. You are passed a render context and expected to add strings of HTML to the context like a normal array. Later, the context will be joined into a single string and converted into real HTML for display on screen.

In addition to the core push and join methods, the render context also supports some extra methods that make it easy to build tags.

context.begin() <-- begins a new tag context context.end() <-- ends the tag context...

Defined in: render_context.js

Field Summary

Class Methods

Field Detail

SC.RenderContext.length Number

the current number of strings owned by the context, including the opening tag.

SC.RenderContext.needsContent

YES if the context needs its content filled in, not just its outer attributes edited. This will be set to YES anytime you push strings into the context or if you don't create it with an element to start with.

SC.RenderContext.offset Number

this initial offset into the strings array where this context instance has its opening tag.

SC.RenderContext.strings Array
The current working array of strings.
SC.RenderContext.updateMode String

Specify the method that should be used to update content on the element. In almost all cases you want to replace the content. Very carefully managed code (such as in CollectionView) can append or prepend content instead.

You probably do not want to change this property unless you know what you are doing.

Class Method Detail

$(sel)

Returns a CoreQuery instance for the element this context wraps (if it wraps any). If a selector is passed, the CoreQuery instance will be for nodes matching that selector.

Renderers may use this to modify DOM.

Parameters:
sel
addAttr(nameOrAttrs, value)

Adds the specified attribute to the current context.

This is a convenience method that simply calls setAttr(nameOrAttrs, value).

Parameters:
nameOrAttrs String|Object
the name of an attribute or a hash of attribute names with values
value String|Number
attribute value if a single attribute name for nameOrAttrs is passed
Returns:
SC.RenderContext
receiver
addClass(nameOrClasses)

Adds a class or classes to the current context.

This is a convenience method that simply calls setClass(nameOrClasses, YES).

Parameters:
nameOrClasses String|Array
a class name or an array of class names
Returns:
SC.RenderContext
receiver
addStyle(nameOrStyles, value)

Adds the specified style to the current context.

This is a convenience method that simply calls setStyle(nameOrStyles, value).

Parameters:
nameOrStyles String|Object
the name of a style or a hash of style names with values
value String|Number
style value if a single style name for nameOrStyles is passed
Returns:
SC.RenderContext
receiver
attr(nameOrAttrs, value)
Parameters:
nameOrAttrs
value
attrs()

Retrieves the current attributes for the context, less the class and style attributes.

If you retrieve the attributes hash to edit it, you must pass the hash back to setAttr in order for it to be applied to the element on rendering.

Use classes() or styles() to get those specific attributes.

Returns:
Object
attributes hash
begin(tagNameOrElement)

Begins a new render context based on the passed tagName or element. Generate said context using end().

Parameters:
tagNameOrElement
Returns:
SC.RenderContext
new context
classes()
Retrieves the class names for the current context.
Returns:
Array
classNames array
classNames(deprecatedArg)
Parameters:
deprecatedArg
css(nameOrStyles, value)
Parameters:
nameOrStyles
value
element()

If the current context targets an element, this method returns the element. If the context does not target an element, this method will render the context into an offscreen element and return it.

Returns:
DOMElement
the element
end()

Ends the current tag editing context. This will generate the tag string including any attributes you might have set along with a closing tag.

The generated HTML will be added to the render context strings. This will also return the previous context if there is one or the receiver.

If you do not have a current tag, this does nothing.

Returns:
SC.RenderContext
escapeHTML(text)

Helper method escapes the passed string to ensure HTML is displayed as plain text while preserving HTML entities like ' , à, etc. You should make sure you pass all user-entered data through this method to avoid errors. You can also do this with the text() helper method on a render context.

Parameters:
text String|Number
value to escape
Returns:
String
string with all HTML values properly escaped
get(idx)

Returns the string at the designated index. If you do not pass anything returns the string array. This index is an offset from the start of the strings owned by this context.

Parameters:
idx Number
the index
Returns:
String|Array
hasClass(name)

Returns YES if the outer tag current has the passed class name, NO otherwise.

Parameters:
name String
the class name
Returns:
Boolean
html(line)
Parameters:
line
id(idName)
Reads the outer tag id if no param is passed, sets the id otherwise.
Parameters:
idName String
the id or set
Returns:
String|SC.RenderContext
id or receiver
init(tagNameOrElement, prevContext)

When you create a context you should pass either a tag name or an element that should be used as the basis for building the context. If you pass an element, then the element will be inspected for class names, styles and other attributes. You can also call update() or replace() to modify the element with you context contents.

If you do not pass any parameters, then we assume the tag name is 'div'.

A second parameter, parentContext, is used internally for chaining. You should never pass a second argument.

Parameters:
tagNameOrElement String|DOMElement
prevContext
Returns:
SC.RenderContext
receiver
join(joinChar)
Joins the strings together, closes any open tags and returns the final result.
Parameters:
joinChar String
optional string to use in joins. def empty string
Returns:
String
joined string
push(line)

Adds a string to the render context for later joining and insertion. To HTML escape the string, see the similar text() method instead.

Note: You can pass multiple string arguments to this method and each will be pushed.

When used in render() for example,

MyApp.MyView = SC.View.extend({

  innerText: '',

  render: function (context) {
    var innerText = this.get('innerText');

    // This will be pushed into the DOM all at once.
    context.push('<div class="inner-div">', innerText, '<span class="inner-span">**</span></div>');
  }

});
Parameters:
line String
the HTML to add to the context
Returns:
SC.RenderContext
receiver
remove(elementId)
Removes an element with the passed id in the currently managed element.
Parameters:
elementId
removeAttr(styleName)

Removes the specified attribute from the current context.

This is a convenience method that simply calls setAttr(name, undefined).

Parameters:
styleName String
the name of the attribute to remove
Returns:
SC.RenderContext
receiver
removeClass(name)

Removes the specified class name from the current context.

This is a convenience method that simply calls setClass(name, NO).

Parameters:
name String
the class to remove
Returns:
SC.RenderContext
receiver
removeStyle(styleName)

Removes the specified style from the current context.

This is a convenience method that simply calls setStyle(name, undefined).

Parameters:
styleName String
the name of the style to remove
Returns:
SC.RenderContext
receiver
resetClasses()

Removes all class names from the context.

Be aware that setClass() only effects the class names specified. If there are existing class names that are not modified by a call to setClass(), they will remain on the context. For example, if you call addClass('a') and addClass('b') followed by setClass({ b:NO }), the 'b' class will be removed, but the 'a' class will be unaffected.

If you want to call setClass() or addClass() to replace all classes, you should call this method first.

Returns:
SC.RenderContext
receiver
resetClassNames()
resetStyles()

Removes all styles from the context.

Be aware that setStyle() only affects the styles specified. If there are existing styles that are not modified by a call to setStyle(), they will remain on the context. For example, if you call addStyle('margin-left', 10) and addStyle('margin-right', 10) followed by setClass({ 'margin-right': null }), the 'margin-right' style will be removed, but the 'margin-left' style will be unaffected.

If you want to call setStyle() or addStyle() to replace all styles, you should call this method first.

Returns:
SC.RenderContext
receiver
setAttr(nameOrAttrs, value)

Sets or unsets an attribute or attributes on the context. Passing a value will set the value for the given attribute name, passing a null or undefined value will unset any current value for the given attribute name and remove it.

When used in render() for example,

MyApp.MyView = SC.View.extend({

  // By default this syle will not appear since the value is null.
  title: null,

  render: function (context) {
    var title = this.get('title');

    // Set the `title` and `data-test` attributes.
    context.setAttr({
      title: title,
      'data-test': SC.buildMode === 'test'
    });
  }
});
Parameters:
nameOrAttrs String|Object
the name of an attribute or a hash of attribute names with values
value String Optional
attribute value if a single attribute name for nameOrAttrs is passed
Returns:
SC.RenderContext
receiver
setClass(nameOrClasses, shouldAdd)

Sets or unsets class names on the current context.

You can either pass a single class name and a boolean indicating whether the value should be added or removed, or you can pass a hash with all the class names you want to add or remove with a boolean indicating whether they should be there or not.

When used in render() for example,

MyApp.MyView = SC.View.extend({

  isAdministrator: NO,

  render: function (context) {
    var isAdministrator = this.get('isAdministrator');

    // Sets the 'is-admin' class appropriately.
    context.setClass('is-admin', isAdministrator);
  }

});
Parameters:
nameOrClasses String|Hash
either a single class name or a hash of class names with boolean values indicating whether to add or remove the class
shouldAdd Boolean
if a single class name for nameOrClasses is passed, this
Returns:
SC.RenderContext
receiver
setStyle(nameOrStyles, value)

Sets or unsets a style or styles on the context.

Passing a value will set the value for the given style name, passing a null or undefined value will unset any current value for the given style name and remove it.

Be aware that setStyle() only effects the styles specified. If there are existing styles that are not modified by a call to setStyle(), they will remain on the context. For example, if you call addStyle('margin-left', 10) and addStyle('margin-right', 10) followed by setClass({ 'margin-right': null }), the 'margin-right' style will be removed, but the 'margin-left' style will be unaffected.

If you want to call setStyle() or addStyle() to replace all styles, you should call resetStyles() method first.

When used in render() for example,

MyApp.MyView = SC.View.extend({

  textColor: 'blue',

  // By default this syle will not appear since the value is null.
  fontFamily: null,

  render: function (context) {
    var textColor = this.get('textColor'),
      fontFamily = this.get('fontFamily');

    // Set the `color` and `fontFamily` styles.
    context.setStyle({
      color: textColor,
      fontFamily: fontFamily
    });
  }
});
Parameters:
nameOrStyles String|Object
the name of a style or a hash of style names with values
value String|Number Optional
style value if a single style name for nameOrStyles is passed
Returns:
SC.RenderContext
receiver
styles(deprecatedArg)
Retrieves the current styles for the context.
Parameters:
deprecatedArg
Returns:
Object
styles hash
tag(tagName, opts)
Generates a tag with the passed options. Like calling context.begin().end().
Parameters:
tagName String
optional tag name. default 'div'
opts Hash
optional tag options. defaults to empty options.
Returns:
SC.RenderContext
receiver
tagName(tagName)
Reads outer tagName if no param is passed, sets tagName otherwise.
Parameters:
tagName String
pass to set tag name.
Returns:
String|SC.RenderContext
tag name or receiver
text(line)

Pushes the passed string to the render context for later joining and insertion, but first escapes the string to ensure that no user-entered HTML is processed as HTML. To push the string without escaping, see the similar push() method instead.

Note: You can pass multiple string arguments to this method and each will be escaped and pushed.

When used in render() for example,

MyApp.MyView = SC.View.extend({

  userText: '<script src="http://maliciousscripts.com"></script>',

  render: function (context) {
    var userText = this.get('userText');

    // Pushes "<script src="http://maliciousscripts.com"></script>" in the DOM
    context.text(userText);
  }

});
Parameters:
line String
the text to add to the context
Returns:
SC.RenderContext
receiver
update()

If an element was set on this context when it was created, this method will actually apply any changes to the element itself. If you have not written any inner html into the context, then the innerHTML of the element will not be changed, otherwise it will be replaced with the new innerHTML.

Also, any attributes, id, classNames or styles you've set will be updated as well. This also ends the editing context session and cleans up.

Returns:
SC.RenderContext
previous context or null if top
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)