js-guidelines.md

Javacript guidelines

This document is a frontend/theme javacript guideline for working with loop.

We use jQuery and native javascript along with Drupal's JavaScript coding standards and the exceptions and deviations that are mentioned below.

Content

1. File structure
2. Comments
3. Functions, loops etc.
4. Manipulating the frontend

1. File structure

---

Place files in a folder named scripts. Place shared functions etc. in a file named theme-name-common.js. Create a javascript file for each functionality needed eg. search.js, my-function.js.

Filestructure example

-- scripts
  -- my-theme-common.js
  -- search.js
  -- my-function.js

2. Comments

Inline documentation for source files should follow the Doxygen formatting conventions.

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works. Comments can be removed by JS compression utilities later, so they don't negatively impact on the file download size.

Non-documentation comments should use capitalized sentences with punctuation. All caps are used in comments only when referencing constants, e.g., TRUE. Comments should be on a separate line immediately before the code line or block they reference

//Unselect all other checkboxes.

3. Functions, loops etc.

---

See Drupal's JavaScript coding standards.

4. Manipulating the frontend

• Prefix elements with .js-
• Don't use .js- for styling
• Use state classes like .is-, .has- as mentioned in the CSS guidelines.
• For sending data from the frontend to javascript use the HTML5 data attribute

Examples

  <a href="http://example.com" class="button js-make-active">This is a button</a>

  $(".js-make-active").click(function() {
    $(this).addClass('.is-active');
  });

.button {
  background-color: $gray;

  &.is-active {
    background-color: $green;
  }
}

  <a href="http://example.com" class="button is-active js-do-something">This is a button</a>