SilverStripe CMS JavaScript Refactoring

SILVERSTRIPE CMS
JAVASCRIPT REFACTORING
The jsparty is over!

Friday, 28 August 2009

SCOPE
• JavaScript library upgrade, no more forks

• CMS JavaScript cleanup
Rewrite in jQuery where feasible

• CMS PHP Controller simpliﬁcation

• More solid UI components with jQuery UI and plugins

• CSS Architecture for easier customization

• Not a large-scale CMS redesign

LIBRARIES

• Prototype 1.4rc3 to jQuery 1.3

• Random UI code and ancient libs to jQuery UI 1.7

• Custom behaviour.js to jQuery.concrete

• External libraries managed by Piston (piston.rubyforge.org/)
instead of svn:externals


GOODBYE JSPARTY
• Merged external libraries
to cms/thirdparty and sapphire/thirdparty


THE DARK AGES

function hover_over() {
Element.addClassName(this, 'over');
}
function hover_out() {
Element.removeClassName(this, 'over');
}

hover_behaviour = {
onmouseover : hover_over,
onmouseout : hover_out
}
jsparty/hover.js


THE DARK AGES
class LeftAndMain {
// ...
public function returnItemToUser($p) {
// ...
$response = <<<JS
var tree = $('sitetree');
var newNode = tree.createTreeNode("$id", "$treeTitle", "{$p->class}{$hasChildren}
{$singleInstanceCSSClass}");
node = tree.getTreeNodeByIdx($parentID);
if(!node) {
node = tree.getTreeNodeByIdx(0);
}
node.open();
node.appendTreeNode(newNode);
newNode.selectTreeNode();
JS;
FormResponse::add($response);
FormResponse::add($this->hideSingleInstanceOnlyFromCreateFieldJS($p));

return FormResponse::respond();
}
}

cms/code/LeftAndMain.php (excerpt)


BEST PRACTICES

• Don’t claim global properties

• Assume element collections

• Encapsulate: jQuery.concrete, jQuery plugin,
jQueryUI widget (in this order)


ENCAPSULATE: EXAMPLE
Simple Highlight jQuery Plugin
// create closure
(function($) {
// plugin definition
$.fn.hilight = function(options) {
// build main options before element iteration
var opts = $.extend({}, $.fn.hilight.defaults, options);
// iterate and reformat each matched element
return this.each(function() {
$this = $(this);
// build element specific options
var o = $.meta ? $.extend({}, opts, $this.data()) : opts;
// update element styles
$this.css({backgroundColor: o.background,color: o.foreground});
});
};
// plugin defaults
$.fn.hilight.defaults = {foreground: "red",background: "yellow"};
// end of closure
})(jQuery);


BEST PRACTICES

• Useplain HTML, jQuery.data() and
jQuery.metadata to encode initial state
and (some) conﬁguration

• Better
than building “object cathedrals” in
most cases


STATE: EXAMPLE
Simple Form Changetracking

State in CSS $('form :input').bind('change', function(e) {
$(this.form).addClass('isChanged');
});
properties $('form').bind('submit', function(e) {
if($(this).hasClass('isChanged')) return false;
});

$('form :input').bind('change', function(e) {

State in DOM $(this.form).data('isChanged', true);
});
$('form').bind('submit', function(e) {
(through jQuery.data()) if($(this).data('isChanged')) return false;
});


BEST PRACTICES
• Ajax responses should default to HTML
Makes it easier to write unobtrusive markup and use SilverStripe templating

• Use HTTP metadata to transport state and additional data
Example: 404 HTTP status code to return “Not Found”
Example: Custom “X-Status” header for more detailed UI status

• Return JSON if HTML is not feasible
Example: Update several tree nodes after CMS batch actions
Alternative: Inspect the returned DOM for more structured data like id attributes

• For AJAX and parameter transmission, <form> is your friend


AJAX: EXAMPLE
Simple Serverside Autocomplete for Page Titles
<form action"#">
<div class="autocomplete {url:'MyController/autocomplete'}">
<input type="text" name="title" />
<div class="results" style="display: none;">
</div>
<input type="submit" value="action_autocomplete" />
</form>
MyController.ss

Using jQuery.metadata,
but could be a plain SilverStripe Form as well

<ul>
<% control Results %>
<li id="Result-$ID">$Title</li>
<% end_control %>
</ul>
AutoComplete.ss


AJAX: EXAMPLE

class MyController {
function autocomplete($request) {
$SQL_title = Convert::raw2sql($request->getVar('title'));
$results = DataObject::get("Page", "Title LIKE '%$SQL_title%'");
if(!$results) return new HTTPResponse("Not found", 404);

// Use HTTPResponse to pass custom status messages
$this->response->setStatusCode(200, "Found " . $results->Count() . " elements");

// render all results with a custom template
$vd = new ViewableData();
return $vd->customise(array(
"Results" => $results
))->renderWith('AutoComplete');
}
}
MyController.php


AJAX: EXAMPLE

$('.autocomplete input').live('change', function() {
var resultsEl = $(this).siblings('.results');
resultsEl.load(
// get form action, using the jQuery.metadata plugin
$(this).parent().metadata().url,
// submit all form values
$(this.form).serialize(),
// callback after data is loaded
function(data, status) {
resultsEl.show();
// optional: get all record IDs from the new HTML
var ids = jQuery('.results').find('li').map(function() {
return $(this).attr('id').replace(/Record-/,'');
});
}
);
});
MyController.js


BEST PRACTICES

• Use events and observation for component communication

• Use composition for synchronous, two-way communicatoin

• Use callbacks to allow for customization

• Don’t overuse prototypical inheritance and pseudo-classes

• Only expose public APIs where necessary
(through jQuery.concrete)


RESOURCES

Documentation (unreleased)
http://doc.silverstripe.com/doku.php?id=2.4:javascript

Source (unreleased, pre 2.4 alpha)
http://github.com/chillu/sapphire/tree/jsrewrite

http://github.com/chillu/cms/tree/jsrewrite


SilverStripe CMS JavaScript Refactoring

Recommended

More Related Content

What's hot (20)

Similar to SilverStripe CMS JavaScript Refactoring (20)

Recently uploaded (20)

SilverStripe CMS JavaScript Refactoring