LiveWhale CMS

Welcome, Guest Login

Support Center

Styleguide: Javascript

Last Updated: Nov 04, 2014 03:19PM PST

Basic Coding Style

  • Use two spaces per level of indent. (Do not use tabs or mix the indents.)
  • Always use camelCase, never snake_case, for functions, “methods” and variables. Use CappedCamelCase for “class” names, e.g.var liveWhale = new LiveWhale();.
  • Despite Mislav’s blog post and the ensuing debate it caused, use semicolons for clarity. If you don’t want to use semicolons, then write CoffeeScript. :)
  • Use // for comment blocks (instead of /* */). See documentation below.
  • Don’t ever use $.get or $.post. Instead use $.ajax and provide both a success handler and an error handler.
  • Use events rather than direct calls of alternative module/class/object methods. For jQuery, use $.fn.on instead of $.fn.bind$.fn.delegate and $.fn.live

Selectors

If writing for HTML5, try to use relavant data attributes as a first choice when binding your JavaScript to the DOM. For example, in the Roadmap Github integration, the issues list (among other locations) demonstrates this. By binding to the data attribute rather than the CSS class, the behavior remains independent of both the design and markup, reducing handaches down the road.

<!-- when listing issues -->
<ul class="issues list" data-query-uri="/issues?milestone=none">

<!-- or, an individual issue -->
<li class="issue" data-issues-number="76" data-issues-state="open" data-issues-milestone="none">

If HTML5 is not being used or a data attribute has no relevance, try to prefix all JavaScript class selectors with js- (see slightly obtrusive javascript). The idea is that you should be able to distinguish a presentational class from a functional class.

Core Objects

While adding to the JavaScript core is discouraged, if you do choose to add to a JavaScript core object (Number, String, Boolean, Object, Function, Array, Date, RegExp) please do so carefully. Always check for prior existence as demonstrated in the following examples.

// javascript
if (!String.prototype.toDate) {
  String.prototype.toDate = function() {
    if (this.isISO8601()) {
      return new Date(this.toString());
    }
    return new Date();
  };
}
# coffeescript
unless String::toDate
  String::toDate = () ->
    return new Date(this.toString()) if this.isISO8601()
    new Date()

Namespaces

All top level objects should be namespaced to avoid conflict with other libraries. All LiveWhale core and core module JavaScript uses the livewhale namespace.

White Whale custom client work and Developer-made modules should use their own top-level namespaces.

Libraries

LiveWhale uses jQuery as it’s primary JavaScript library, but you are free to use any library you prefer. LiveWhale’s jQuery uses $.noConflict() to keep everything separate and is loaded into window.livewhale.jQuery should you wish to use it. (If choosing to do that, be aware that we upgrade LiveWhale’s jQuery regularly and you would be subject to our upgrade schedule.)

MVV*

When extensive REST-style functionality is needed, LiveWhale is agnostic of course and White Whale has not yet made a determination as to a preferred library for the CMS’ use. The LiveWhaleScreens widget uses Backbone, supported by Underscore and jQuery, and the developer Roadmap does as well. However, the LiveWhale team is investigating the use of Angular as a tool for the CMS’ use.

Documentation

Rather than bless specific documentation software, we follow these guidelines as best possible regardless of the tool:

  • Comments should be renderable into HTML via Markdown.
  • Prepend your functions/methods with commented documentation. Use // for JavaScript and # for CoffeeScript unless your tool requires otherwise.
  • You may endline comments when the script is not explicit enough on its own, but it is not required.
  • For simple or obvious methods/functions, simply describe the what it does.
  • For complex methods/functions, do the full but: list expected parameters with type and whether they are required or not; show sample usage (signature) and type any returned value(s).

Testing

Write unit/functional tests for your JavaScript when your code is significant, such as when a stand-alone library, part of the LiveWhale core or in a developer-made module available for others. (We prefer JSLint for syntax checking BTW.) We are also working towards doing full testing of the LiveWhale UI with a headless browser like PhantomJS.

Note: LiveWhale version 1.5+ ships with jQuery version 1.10.2 

eb8f96c071020d8b0923da726d6cab65@livewhale.desk-mail.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete?b_id=4256