Complete gem, model and overwritting sections for customization

docs/en/SUMMARY.md

@@ -24,7 +24,9 @@
 * [Images](customization/images.md)
 * [Views & Styles](customization/views_and_styles.md)
 * [Javascript](customization/javascript.md)
-* [Overwritting](customization/overwritting.md)
+* [Modelos](customization/models.md)
+* [Gemas](customization/gems.md)
+* [Overwritting Application](customization/overwritting.md)
 * [Adding new features](customization/new_features.md)
 
 ### Features

docs/en/customization/gems.md

@@ -0,0 +1,9 @@
+# Gemfile
+
+To add new gems (libraries) you can edit the `Gemfile_custom` file. For example to add [rails-footnotes](https://github.com/josevalim/rails-footnotes) gem you would just add:
+
+```ruby
+gem 'rails-footnotes', '~> 4.0'
+```
+
+And then just do the classic Ruby on Rails flow `bundle install` and following any gem specific install steps from it's own documentation.

docs/en/customization/models.md

@@ -0,0 +1,75 @@
+# Models
+
+If you need to create new models or customize existent ones, you can do it so at the `app/models/custom` folder. Keep in mind that for old models you'll need to firstly require the dependency.
+
+For example for Madrid's City Hall fork its required to check the zip code's format (it always starts with 280 followed by 2 digits). That check is at `app/models/custom/verification/residence.rb`:
+
+```ruby
+require_dependency Rails.root.join('app', 'models', 'verification', 'residence').to_s
+
+class Verification::Residence
+
+  validate :postal_code_in_madrid
+  validate :residence_in_madrid
+
+  def postal_code_in_madrid
+    errors.add(:postal_code, I18n.t('verification.residence.new.error_not_allowed_postal_code')) unless valid_postal_code?
+  end
+
+  def residence_in_madrid
+    return if errors.any?
+
+    unless residency_valid?
+      errors.add(:residence_in_madrid, false)
+      store_failed_attempt
+      Lock.increase_tries(user)
+    end
+  end
+
+  private
+
+    def valid_postal_code?
+      postal_code =~ /^280/
+    end
+
+end
+```
+
+Do not forget to cover your changes with a test at the `spec/models/custom` folder. Following the example we could create `spec/models/custom/residence_spec.rb`:
+
+```ruby
+require 'rails_helper'
+
+describe Verification::Residence do
+
+  let(:residence) { build(:verification_residence, document_number: "12345678Z") }
+
+  describe "verification" do
+
+    describe "postal code" do
+      it "should be valid with postal codes starting with 280" do
+        residence.postal_code = "28012"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(0)
+
+        residence.postal_code = "28023"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(0)
+      end
+
+      it "should not be valid with postal codes not starting with 280" do
+        residence.postal_code = "12345"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(1)
+
+        residence.postal_code = "13280"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(1)
+        expect(residence.errors[:postal_code]).to include("In order to be verified, you must be registered in the municipality of Madrid.")
+      end
+    end
+
+  end
+
+end
+```

docs/en/customization/overwritting.md

@@ -1 +1,14 @@
-# Overwritting
+# Overwritting application.rb
+
+If you need to extend or modify the `config/application.rb` just do it at the `config/application_custom.rb` file. For example if you want to change de default language to English, just add:
+
+```ruby
+module Consul
+  class Application < Rails::Application
+    config.i18n.default_locale = :en
+    config.i18n.available_locales = [:en, :es]
+  end
+end
+```
+
+Remeber that in order to see this changes live you'll need to restart the server.

docs/es/SUMMARY.md

@@ -24,6 +24,8 @@
 * [Imágenes](customization/images.md)
 * [Vistas & Estilos](customization/views_and_styles.md)
 * [Javascript](customization/javascript.md)
+* [Modelos](customization/models.md)
+* [Gemas](customization/gems.md)
 * [Adaptar la aplicación](customization/overwritting.md)
 * [Añadir nuevas funcionalidades](customization/new_features.md)
 

docs/es/customization/gems.md

@@ -0,0 +1,9 @@
+# Gemfile
+
+Para agregar librerías (gems) nuevas puedes hacerlo en el fichero `Gemfile_custom`. Por ejemplo si quieres agregar la gema [rails-footnotes](https://github.com/josevalim/rails-footnotes) debes hacerlo agregandole
+
+```ruby
+gem 'rails-footnotes', '~> 4.0'
+```
+
+Y siguiendo el flujo clásico en Ruby on Rails (`bundle install` y seguir con los pasos específicos de la gema en la documentación)

docs/es/customization/models.md

@@ -0,0 +1,75 @@
+# Modelos
+
+Si quieres agregar modelos nuevos, o modificar o agregar métodos a uno ya existente puedes hacerlo en `app/models/custom`. En el caso de los modelos antiguos debes primero hacer un require de la dependencia.
+
+Por ejemplo en el caso del Ayuntamiento de Madrid se requiere comprobar que el código postal durante la verificación sigue un cierto formato (empieza con 280). Esto se realiza creando este fichero en `app/models/custom/verification/residence.rb`:
+
+```ruby
+require_dependency Rails.root.join('app', 'models', 'verification', 'residence').to_s
+
+class Verification::Residence
+
+  validate :postal_code_in_madrid
+  validate :residence_in_madrid
+
+  def postal_code_in_madrid
+    errors.add(:postal_code, I18n.t('verification.residence.new.error_not_allowed_postal_code')) unless valid_postal_code?
+  end
+
+  def residence_in_madrid
+    return if errors.any?
+
+    unless residency_valid?
+      errors.add(:residence_in_madrid, false)
+      store_failed_attempt
+      Lock.increase_tries(user)
+    end
+  end
+
+  private
+
+    def valid_postal_code?
+      postal_code =~ /^280/
+    end
+
+end
+```
+
+No olvides poner los tests relevantes en `spec/models/custom`, siguiendo con el ejemplo pondriamos lo siguiente en `spec/models/custom/residence_spec.rb`:
+
+```ruby
+require 'rails_helper'
+
+describe Verification::Residence do
+
+  let(:residence) { build(:verification_residence, document_number: "12345678Z") }
+
+  describe "verification" do
+
+    describe "postal code" do
+      it "should be valid with postal codes starting with 280" do
+        residence.postal_code = "28012"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(0)
+
+        residence.postal_code = "28023"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(0)
+      end
+
+      it "should not be valid with postal codes not starting with 280" do
+        residence.postal_code = "12345"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(1)
+
+        residence.postal_code = "13280"
+        residence.valid?
+        expect(residence.errors[:postal_code].size).to eq(1)
+        expect(residence.errors[:postal_code]).to include("In order to be verified, you must be registered in the municipality of Madrid.")
+      end
+    end
+
+  end
+
+end
+```

docs/es/customization/overwritting.md

@@ -1 +1,14 @@
-# Adaptar la aplicación
+# Adaptar application.rb
+
+Cuando necesites extender o modificar el `config/application.rb` puedes hacerlo a través del fichero `config/application_custom.rb`. Por ejemplo si quieres modificar el idioma por defecto al inglés pondrías lo siguiente:
+
+```ruby
+module Consul
+  class Application < Rails::Application
+    config.i18n.default_locale = :en
+    config.i18n.available_locales = [:en, :es]
+  end
+end
+```
+
+Recuerda que para ver reflejado estos cambios debes reiniciar el servidor de desarrollo.