Update documentation to customize JavaScript

Note that, while it doesn't really affect the way the application
behaves (as long as the JavaScript code doesn't rely on the order it's
loaded) we're requiring `app/assets/javascripts/custom.js` after
requiring any files in the `app/assets/javascripts/custom/` folder. This
is done for consistency, since we load the content of
`app/assets/javascripts/application.js` after requiring everything else.

app/assets/javascripts/application.js

@@ -123,8 +123,8 @@
 //= require_tree ./admin
 //= require_tree ./sdg
 //= require_tree ./sdg_management
-//= require custom
 //= require_tree ./custom
+//= require custom
 
 var initialize_modules = function() {
   "use strict";

app/assets/javascripts/custom.js

@@ -1,7 +1,23 @@
-// Overrides and adds customized javascripts in this file
-// Read more on documentation:
-// * English: https://github.com/consuldemocracy/consuldemocracy/blob/master/CUSTOMIZE_EN.md#javascript
-// * Spanish: https://github.com/consuldemocracy/consuldemocracy/blob/master/CUSTOMIZE_ES.md#javascript
+// Add calls to your custom JavaScript code using this file.
 //
+// We recommend creating your custom JavaScript code under the
+// `app/assets/javascripts/custom/` folder and calling it from here.
 //
+// See the `docs/en/customization/javascript.md` file for more information.
 
+var initialize_modules = function() {
+  "use strict";
+
+  // Add calls to your custom code here; this will be called when
+  // loading a page.
+};
+
+var destroy_non_idempotent_modules = function() {
+  "use strict";
+
+  // Add calls to your custom code here when your JavaScript code added
+  // in `initialize_modules` is not idempotent.
+};
+
+$(document).on("turbolinks:load", initialize_modules);
+$(document).on("turbolinks:before-cache", destroy_non_idempotent_modules);

docs/en/SUMMARY.md

@@ -32,7 +32,7 @@
   * [Translations and Texts](customization/translations.md)
   * [Images](customization/images.md)
   * [Styles with CSS](customization/css.md)
-  * [Javascript](customization/javascript.md)
+  * [JavaScript](customization/javascript.md)
   * [Models](customization/models.md)
   * [Controllers](customization/controllers.md)
   * [Views and HTML](customization/views.md)

docs/en/customization/customization.md

@@ -4,7 +4,7 @@
 * [Translations and Texts](translations.md)
 * [Images](images.md)
 * [Styles with CSS](css.md)
-* [Javascript](javascript.md)
+* [JavaScript](javascript.md)
 * [Models](models.md)
 * [Controllers](controllers.md)
 * [Views and HTML](views.md)

docs/en/customization/javascript.md

@@ -1,15 +1,52 @@
-# Javascript
+# Customizing JavaScript
 
-If you want to add some custom Javascript code, `app/assets/javascripts/custom.js` is the file to do it. For example to create a new alert just add:
+In order to add custom JavaScript code, you can create a file under `app/assets/javascripts/custom/`.
+
+## Adding new functions
+
+To create a new function, we need to define it and then call it when the browser loads a page.
+
+For example, in order to create an alert, we can create the file `app/assets/javascripts/custom/alert.js` with the following content:
 
 ```js
-$(function(){
-  alert('foobar');
-});
+(function() {
+  "use strict";
+  App.Alert = {
+    initialize: function() {
+      alert("foobar");
+    }
+  };
+}).call(this);
 ```
 
-If you work with Coffeescript code you can check it with [coffeelint](http://www.coffeelint.org/) (install with `npm install -g coffeelint`) :
+Then, edit the `initialize_modules` function in `app/assets/javascripts/custom.js`:
 
-```bash
-coffeelint .
+```js
+var initialize_modules = function() {
+  "use strict";
+
+  // Add calls to your custom code here; this will be called when
+  // loading a page
+
+  App.Alert.initialize();
+};
 ```
+
+## Overwriting existing functions
+
+In Consul Democracy, functions are defined as object properties. That means that, in order to overwrite a function, you can simply redefine the property of the object containing it. Where possible, it's recommended that your custom code calls the original code and only modifies the cases where it should behave differently. This way, when upgrading to a new version of Consul Democracy that updates the original functions, your custom functions will automatically include the modifications in the original code as well. Sometimes this won't be possible, though, which means you might need to change your custom function when upgrading.
+
+For example, let's change the `generatePassword` function in `app/assets/javascripts/managers.js`. To do so, create a file `app/assets/javascripts/custom/managers.js` with the following content:
+
+```js
+(function() {
+  "use strict";
+  App.Managers.consulGeneratePassword = App.Managers.generatePassword;
+
+  App.Managers.generatePassword = function() {
+    return App.Managers.consulGeneratePassword() + "custom";
+  };
+}).call(this);
+```
+
+This will return what the original function returns followed by the "custom" string.

docs/es/SUMMARY.md

@@ -32,7 +32,7 @@
   * [Traducciones y Textos](customization/translations.md)
   * [Imágenes](customization/images.md)
   * [Estilos con CSS](customization/css.md)
-  * [Javascript](customization/javascript.md)
+  * [JavaScript](customization/javascript.md)
   * [Modelos](customization/models.md)
   * [Controladores](customization/controllers.md)
   * [Vistas y HTML](customization/views.md)

docs/es/customization/customization.md

@@ -1,10 +1,10 @@
-# Customization
+# Personalización del código
 
 * [Introducción](introduction.md)
 * [Traducciones y Textos](translations.md)
 * [Imágenes](images.md)
 * [Estilos con CSS](css.md)
-* [Javascript](javascript.md)
+* [JavaScript](javascript.md)
 * [Modelos](models.md)
 * [Controladores](controllers.md)
 * [Vistas y HTML](views.md)

docs/es/customization/javascript.md

@@ -1,15 +1,52 @@
-# Javascript
+# Personalización de JavaScript
 
-Si quieres agregar código Javascript puedes hacerlo en el fichero `app/assets/javascripts/custom.js`. Por ejemplo si quieres que salga una alerta puedes poner lo siguiente:
+Para añadir código de JavaScript personalizado, crea un fichero en `app/assets/javascripts/custom/`.
+
+## Añadir nuevas funciones
+
+Para crear una nueva función, necesitas definirla y hacer que se llame cuando el navegador carga una página.
+
+Por ejemplo, para crear una alerta, podemos crear el fichero `app/assets/javascripts/custom/alert.js` con el siguiente contenido:
 
 ```js
-$(function(){
-  alert('foobar');
-});
+(function() {
+  "use strict";
+  App.Alert = {
+    initialize: function() {
+      alert("foobar");
+    }
+  };
+}).call(this);
 ```
 
-Si trabajas con código coffeescript puedes revisarlo con [coffeelint](http://www.coffeelint.org/) (instalalo con `npm install -g coffeelint`) :
+A continuación, edita la función `initialize_modules` del fichero `app/assets/javascripts/custom.js`:
 
-```bash
-coffeelint .
+```js
+var initialize_modules = function() {
+  "use strict";
+
+  // Add calls to your custom code here; this will be called when
+  // loading a page
+
+  App.Alert.initialize();
+};
 ```
+
+## Sobrescribir funciones existentes
+
+En Consul Democracy, las funciones de JavaScript se definen como propiedades de un objeto. Esto quiere decir que, para sobrescribir una función, basta con redefinir la propiedad del objeto que la contiene. Siempre que sea posible, recomendamos que tu código personalizado llame al código original y solamente modifique los casos en que debería comportarse de forma diferente. De este modo, al actualizar a una versión de Consul Democracy que actualice las funciones originales, tus funciones personalizadas incluirán las modificaciones del código original automáticamente. En ocasiones, hacer esto no será posible, con lo que tendrás que cambiar tu función personalizada al actualizar.
+
+Como ejemplo, vamos a cambiar la función `generatePassword` del fichero `app/assets/javascripts/managers.js`. Para ello, crea el fichero `app/assets/javascripts/custom/managers.js` con el siguiente contenido:
+
+```js
+(function() {
+  "use strict";
+  App.Managers.consulGeneratePassword = App.Managers.generatePassword;
+
+  App.Managers.generatePassword = function() {
+    return App.Managers.consulGeneratePassword() + "custom";
+  };
+}).call(this);
+```
+
+Esto devolverá lo que devuelve la función original seguida del texto "custom".