Update documentation to customize views

docs/en/SUMMARY.md

@@ -31,10 +31,11 @@
   * [Introduction](customization/introduction.md)
   * [Translations and Texts](customization/translations.md)
   * [Images](customization/images.md)
-  * [Views and Styles](customization/views_and_styles.md)
+  * [Styles with CSS](customization/css.md)
   * [Javascript](customization/javascript.md)
   * [Models](customization/models.md)
   * [Controllers](customization/controllers.md)
+  * [Views and HTML](customization/views.md)
   * [Components](customization/components.md)
   * [Gems](customization/gems.md)
   * [Application configuration](customization/application.md)

docs/en/customization/css.md

@@ -1,10 +1,4 @@
-# Views and Styles
-
-## Views (HTML)
-
-If you want to change any page HTML  you can just find the correct file under the `app/views` folder and put a copy at `app/views/custom` keeping as well any sub-folder structure, and then apply your customizations. For example if you want to customize `app/views/pages/conditions.html` you'll have to make a copy at `app/views/custom/pages/conditions.html.erb` (note the `pages` subdirectory).
-
-## CSS Styles with SASS
+# Styles with CSS
 
 In order to make changes to any CSS selector (custom style sheets), you can add them directly at `app/assets/stylesheets/custom.scss`. For example to change the header color (`.top-links`) you can just add:
 

docs/en/customization/customization.md

@@ -3,10 +3,11 @@
 * [Introduction](introduction.md)
 * [Translations and Texts](translations.md)
 * [Images](images.md)
-* [Views and Styles](views_and_styles.md)
+* [Styles with CSS](css.md)
 * [Javascript](javascript.md)
 * [Models](models.md)
 * [Controllers](controllers.md)
+* [Views and HTML](views.md)
 * [Components](components.md)
 * [Gems](gems.md)
 * [Application configuration](application.md)

docs/en/customization/views.md

@@ -0,0 +1,11 @@
+# Customizing views and HTML
+
+Just like most Ruby on Rails application, Consul Democracy uses ERB templates to render HTML. These templates are traditionally placed in the `app/views/` folder.
+
+Unlike [Ruby code](models.md), [CSS code](css.md) or [JavaScript code](javascript.md), it isn't possible to overwrite only certain parts of an ERB template. So, in order to customize a view, find the correct file under the `app/views/` folder and copy it to `app/views/custom/`, keeping as well any sub-folder structure, and then apply your customizations. For example, to customize `app/views/welcome/index.html.erb`, copy it to `app/views/custom/welcome/index.html.erb`.
+
+In order to keep track of your custom changes, when using git, we recommend copying the original file to the custom folder in one commit (without any modifications) and then modifying the custom file in a different commit. When upgrading to a new version of Consul Democracy, this will make it easier to check the differences between the view in the old version of Consul Democracy, the view in the new version of Consul Democracy, and your custom changes.
+
+As mentioned earlier, the custom file will completely overwrite the original one. This means that, when upgrading to a new version of Consul Democracy, the changes in the original file will be ignored. You'll have to check the changes in the original file and apply them to your custom file if appropriate.
+
+**Note**: Consul Democracy only uses the `app/views/` folder for code written before 2021. Code written since then is placed under the `app/components/` folder. The main reason is that components allow extracting some of the logic to a Ruby file, and maintaining custom Ruby code is easier than maintaining custom ERB code.

docs/es/SUMMARY.md

@@ -31,10 +31,11 @@
   * [Introducción](customization/introduction.md)
   * [Traducciones y Textos](customization/translations.md)
   * [Imágenes](customization/images.md)
-  * [Vistas y Estilos](customization/views_and_styles.md)
+  * [Estilos con CSS](customization/css.md)
   * [Javascript](customization/javascript.md)
   * [Modelos](customization/models.md)
   * [Controladores](customization/controllers.md)
+  * [Vistas y HTML](customization/views.md)
   * [Componentes](customization/components.md)
   * [Gemas](customization/gems.md)
   * [Configuración de la aplicación](customization/application.md)

docs/es/customization/css.md

@@ -1,10 +1,4 @@
-# Vistas y Estilos
-
-## Vistas (HTML)
-
-Si quieres modificar el HTML de alguna página puedes hacerlo copiando el HTML de `app/views` y poniendolo en `app/views/custom` respetando los subdirectorios que encuentres ahí. Por ejemplo si quieres modificar `app/views/pages/conditions.html` debes copiarlo y modificarla en `app/views/custom/pages/conditions.html.erb`
-
-## Estilos CSS con SASS
+# Estilos con CSS
 
 Si quieres cambiar algun selector CSS (de las hojas de estilo) puedes hacerlo en el fichero `app/assets/stylesheets/custom.scss`. Por ejemplo si quieres cambiar el color del header (`.top-links`) puedes hacerlo agregando:
 

docs/es/customization/customization.md

@@ -3,10 +3,11 @@
 * [Introducción](introduction.md)
 * [Traducciones y Textos](translations.md)
 * [Imágenes](images.md)
-* [Vistas y Estilos](views_and_styles.md)
+* [Estilos con CSS](css.md)
 * [Javascript](javascript.md)
 * [Modelos](models.md)
 * [Controladores](controllers.md)
+* [Vistas y HTML](views.md)
 * [Componentes](components.md)
 * [Gemas](gems.md)
 * [Configuración de la aplicación](application.md)

docs/es/customization/views.md

@@ -0,0 +1,11 @@
+# Personalización de vistas y HTML
+
+Al igual que la mayoría de aplicaciones hechas con Ruby on Rails, Consul Democracy utiliza ficheros ERB para generar HTML. Estos ficheros tradicionalmente se encuentran en el directorio `app/views/`.
+
+A diferencia del [código de Ruby](models.md), [código de CSS](css.md) o [código de JavaScript](javascript.md), no es posible sobrescribir solamente partes de un fichero ERB. Así que, para personalizar una vista, tendrás que encontrar el archivo que quieras cambiar en el directorio `app/views/` y copiarlo en `app/views/custom/`, manteniendo la estructura de subdirectorios, y posteriormente aplicar las personalizaciones. Por ejemplo, si quieres personalizar `app/views/welcome/index.html.erb`, tendrás que copiarlo en `app/views/custom/welcome/index.html.erb`.
+
+Para que sea más fácil llevar la cuenta de tus cambios personalizados, al utilizar el sistema de control de versiones git, recomendamos copiar el archivo original al directorio personalizado en un "commit" (sin modificar este fichero) y modificar el archivo personalizado en otro "commit" distinto. Esto hará que, al actualizar a una nueva versión de Consul Democracy, sea más fácil comprobar las diferencias entre la vista de la versión anterior de Consul Democracy, la vista de la nueva versión de Consul Democracy, y tus cambios personalizados.
+
+Como se ha mencionado anteriormente, el archivo personalizado sobrescribirá el original completamente. Esto quiere decir que, al actualizar a una nueva versión de Consul Democracy, los cambios en el archivo original serán ignorados. Tendrás que comprobar los cambios en el archivo original y aplicarlos a tu fichero personalizado cuando corresponda.
+
+**Nota**: Consul Democracy solamente utiliza el directorio `app/views/` para código escrito antes del año 2021. El código escrito desde entonces se encuentra en el directorio `app/components/`. La razón principal es que los componentes permiten extraer parte de la lógica en un archivo de Ruby, y mantener código Ruby personalizado es más sencillo que mantener código ERB personalizado.