From 7b86d843d2b74b864479256c74ef291b3544d006 Mon Sep 17 00:00:00 2001 From: Bertocq Date: Wed, 13 Sep 2017 14:39:44 +0200 Subject: [PATCH] Complete gem, model and overwritting sections for customization --- docs/en/SUMMARY.md | 4 +- docs/en/customization/gems.md | 9 ++++ docs/en/customization/models.md | 75 +++++++++++++++++++++++++++ docs/en/customization/overwritting.md | 15 +++++- docs/es/SUMMARY.md | 2 + docs/es/customization/gems.md | 9 ++++ docs/es/customization/models.md | 75 +++++++++++++++++++++++++++ docs/es/customization/overwritting.md | 15 +++++- 8 files changed, 201 insertions(+), 3 deletions(-) create mode 100644 docs/en/customization/gems.md create mode 100644 docs/en/customization/models.md create mode 100644 docs/es/customization/gems.md create mode 100644 docs/es/customization/models.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index bf09a80fa..788285385 100644 --- a/docs/en/SUMMARY.md +++ b/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 diff --git a/docs/en/customization/gems.md b/docs/en/customization/gems.md new file mode 100644 index 000000000..46600bbf6 --- /dev/null +++ b/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. diff --git a/docs/en/customization/models.md b/docs/en/customization/models.md new file mode 100644 index 000000000..f8d8075fc --- /dev/null +++ b/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 +``` diff --git a/docs/en/customization/overwritting.md b/docs/en/customization/overwritting.md index 898986935..586fc30c3 100644 --- a/docs/en/customization/overwritting.md +++ b/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. diff --git a/docs/es/SUMMARY.md b/docs/es/SUMMARY.md index b68deaaaa..5dfecb560 100644 --- a/docs/es/SUMMARY.md +++ b/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) diff --git a/docs/es/customization/gems.md b/docs/es/customization/gems.md new file mode 100644 index 000000000..98aa91f0c --- /dev/null +++ b/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) diff --git a/docs/es/customization/models.md b/docs/es/customization/models.md new file mode 100644 index 000000000..bbc78a5e3 --- /dev/null +++ b/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 +``` diff --git a/docs/es/customization/overwritting.md b/docs/es/customization/overwritting.md index 32cead74b..c1932bc21 100644 --- a/docs/es/customization/overwritting.md +++ b/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.