consul/nairobi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

GitBook: [master] 86 pages and 110 assets modified

Browse Source
This commit is contained in:
consuldocs
2020-07-14 22:51:03 +00:00
committed by gitbook-bot
parent 06fe16d6b4
commit 5ed5960428
196 changed files with 5304 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/english-documentation/customization/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Customization
* [Introduction](introduction.md)
* [Texts & Translations](translations.md)
* [Images](images.md)
* [Views & Styles](views_and_styles.md)
* [Javascript](javascript.md)
* [Models](models.md)
* [Gems](gems.md)
* [Overwritting Application](overwritting.md)

10
docs/english-documentation/customization/gems.md Normal file
View File

@@ -0,0 +1,10 @@
# Gems
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.

18
docs/english-documentation/customization/images.md Normal file
View File

@@ -0,0 +1,18 @@
# Images
If you want to overwrite any image, firstly you need to findout the filename, and by defaul it will be located under `app/assets/images`. For example if you want to change the header logo \(`app/assets/images/logo_header.png`\) you must create another file with the exact same file name under `app/assets/images/custom` folder. The images and icons that you will most likely want to change are:
* apple-touch-icon-200.png
* icon\_home.png
* logo\_email.png
* logo\_header.png
* map.jpg
* social\_media\_icon.png
* social\_media\_icon\_twitter.png
## City Map
You'll find the city map at [`/app/assets/images/map.jpg`](https://github.com/consul/consul/blob/master/app/assets/images/map.jpg), just replace it with an image of your cities districts \([example](https://github.com/ayuntamientomadrid/consul/blob/master/app/assets/images/map.jpg)\).
Afterwards we recommend you to use an online tool like [http://imagemap-generator.dariodomi.de/](http://imagemap-generator.dariodomi.de/) or [https://www.image-map.net/](https://www.image-map.net/) to generate the html coordinates to be able to generate a [image-map](https://www.w3schools.com/tags/tag_map.asp) for each of the districts. Those coordinates should be introduced on the respective Geozones at the admin geozones panel \(`/admin/geozones`\)

110
docs/english-documentation/customization/introduction.md Normal file
View File

@@ -0,0 +1,110 @@
# Introduction
You can modify your own CONSUL to have your custom visual style, but first you'll have to [create your own fork from](../getting_started/create.md).
We've created an specific structure where you can overwrite and customize the application in a way that will let you keep updating it from CONSUL's main repository, without having conflicts on code merging or risking loosing your customization changes. We try to make CONSUL as vanilla as possible to help other developers onboard the codebase.
## Special Folders and Files
In order to customize your CONSUL fork, you'll make use of some `custom` folders on the following paths:
* `config/locales/custom/`
* `app/assets/images/custom/`
* `app/views/custom/`
* `app/controllers/custom/`
* `app/models/custom/`
Also these are the files where you can apply some customization:
* `app/assets/stylesheets/custom.css`
* `app/assets/stylesheets/_custom_settings.css`
* `app/assets/javascripts/custom.js`
* `Gemfile_custom`
* `config/application.custom.rb`
## Remote translations on demand by the user
The aim of this service is to be able to offer all the dynamic contents of the application \(proposals, debates, budget investments and comments\) in different languages without the need for a user or administrator to have created each one of their translations.
When an user visit a page with a language where there is untranslated content, he will has a button to request the translation of all the content. This content will be sent to an automatic translator \(in this case [Microsoft TranslatorText](https://azure.microsoft.com/en-us/services/cognitive-services/translator-text-api/)\) and as soon as the response is obtained, all these translations will be available to any user.
### Getting started
In order to use this functionality, the following steps are necessary: 1. Have an api key to connect to the translation service. For this we need an [Azure account](https://azure.microsoft.com/en-us/) 1. Once you are logged into the Azure portal, subscribe to the Translator Text API in Microsoft Cognitive Service. 1. Once you have subscribed to the Translator Text service, you will have access to 2 api keys in the section **RESOURCE MANAGEMENT > Keys** that will be necessary for the configuration of the translation service in your application.
### Configuration
To activate the translation service in your application you must complete the following steps:
#### Add api key in the application
In the previous section we have commented that once subscribed to the translation service we have 2 api keys. To configure the service correctly in our application we must add one of the two api keys in the file `secrets.yml` in section `apis:` with the key `microsoft_api_key` as we can see in the following image:
![Add api key to secrets](../../.gitbook/assets/add-api-key-to-secrets.png)
#### Activate module
Once we have the new key in the `secrets.yml` we can now proceed to activate the module. To activate the functionality you must follow 2 steps: 1. Execute the following command `bin/rake settings:create_remote_translations_setting RAILS_ENV=production` 1. Accessing through the administration panel of your application to the section **Configuración > Funcionalidades** and activate module **Traducciones Remotas** as shown below: ![Active remote translations](../../.gitbook/assets/active-remote-translations-en.png)
### Use Cases
Once we have the api key in our `secrets.yml` and the activated module, users will already be able to use the functionality. We attach some screenshots of how the application interacts with our users:
* When a user visits a page in a language without translated content, an informative text will appear at the top of the page and a button to request the translation. \(**Note:** _If user visit page with a language not supported by the translation service, no text or translation button will be displayed. See section: Available languages for remote translation_\) ![Display text and button](../../.gitbook/assets/display-text-and-button-en.png)
* Once the user click the `Translate page` button, the translations are enqueued and the page is reloaded with a notice \(_Informing that the translations have been requested correctly_\) and an informative text in the header \(_explaining when you will be able to see these translations_\). ![Display notice and text after enqueued translations](../../.gitbook/assets/display-notice-and-text-after-enqueued-en.png)
* If an user visit a page that does not have translations but have already been requested by another user. The application will not show you the translate button, but an informative text in the header \(_explaining when you will be able to see these translations_\). ![Display text explaining that translations are pending](../../.gitbook/assets/display-text-translations-pending-en.png)
* The translation request, response processing and data saving are delegated to `Delayed Jobs` and as soon as they are processed, the user will be able to read them after page refresh. ![Display translated content](../../.gitbook/assets/display-translated-content-en.png)
### Available languages for remote translation
Currently these are all the [available languages](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/quickstart-ruby-languages) in the translation service:
```text
["af", "ar", "bg", "bn", "bs", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "fa", "fi", "fil", "fj", "fr", "he", "hi", "hr", "ht", "hu", "id", "is", "it", "ja", "ko", "lt", "lv", "mg", "ms", "mt", "mww", "nb", "nl", "otq", "pl", "pt", "ro", "ru", "sk", "sl", "sm", "sr-Cyrl", "sr-Latn", "sv", "sw", "ta", "te", "th", "tlh", "to", "tr", "ty", "uk", "ur", "vi", "yua", "yue", "zh-Hans", "zh-Hant"]
```
Of all the languages that Consul currently has defined\(`available_locales`\) in `config/application.rb` are not included in the above list and no translation service is offered for the following languages:
```text
["val", "gl", "sq"]
```
### Pricing
The translation service used has the [pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator-text-api/) the most competitive. The price for each 1 Million characters translated is 8.43 € and there is no fixed cost per month. Google and DeepL have an approximate price of between 16.00 € and 20.00 € for each 1 million characters and a fixed monthly cost.
Although technical measures have been taken to prevent misuse of this service, we recommend the creation of Alerts offered by Azure so that an Administrator can be notified in the event of detecting unusual use of the service.
To create an Alert in Azure we must follow the following steps: 1. Sign in to the **Azure Portal**. 1. Register the resource providers needed to create Alerts 1. On the Azure portal menu, select **All services**. 1. In the **All services** box, enter **subscription**, and then select **Subscriptions**. 1. Select the subscription from the subscription list in order to view it. 1. Select **Resource providers** and check the list of available resource providers. 1. Among the resource providers we must select **microsoft.insights** and click on the button **Register** 1. Create new alert rule: 1. On the Azure portal menu, select **All services**. 1. In the **All services** box, enter **subscription**, and then select **Subscriptions**. 1. Select the subscription from the subscription list in order to view it. 1. Select **Resources** and access the resource created from translations of the type **Cognitive Services** 1. In the **Monitoring** section select **Alerts** and we access **New alert rule** 1. Select the **Resource** that we want to alert on \(if we have followed the previous steps it should already be selected\) 1. Add a **Condition**. In this case the one we are interested is called `Characters Translated`. Once selected we must define the logic of the Alert to suit our needs. Ex: Fill "Operator" field with "Greater than" option, fill "Aggregation type" field with "Total" option and fill "Threshold value" field with the number of characters we consider should be translated before being notified. In this section you can also set the time period and frequency of evaluation. 1. In order to be notified we have to create an **Action Group** and associate it with this Alert we're creating. To do this, access the button **Create** and fill out the form. As you can see there are different types of actions, we must select **Email/SMS/Push/Voice** and configure the option that we consider convenient according to our needs. 1. Once this group of actions has been created, it is directly associated with the rule we are creating. 1. Finally, all you have to do is add a name and click on the **Create new alert rule**
### Add a new translation service
If you want to integrate more translation services for any reason \(new translation service appears, you want to change to include languages that are currently not supported, etc.\) the code is ready to be added. This is made possible by the `RemoteTranslations::Caller` class which is an intermediate layer between untranslated content management and the currently used Microsoft Translation Client. A good solution for adding another translation service would be to replace the call to the `MicrosoftTranslateClient` in the `translations` method of `RemoteTranslations::Caller` with the new service implemented. If you want to coexist with both should only be managed in which case we want to use one or the other, either through specific conditions in the code or through a management in the Settings of the application.
```ruby
class RemoteTranslationsCaller
...
def translations
@translations ||= RemoteTranslations::Microsoft::Client.new.call(fields_values, locale)
# Add new RemoteTranslations Client
# @translations = RemoteTranslations::NewTranslateClient::Client.new.call(fields_values, locale_to)
end
...
end
```
## Translation interface
The aim of this feature is to allow users the introduction of dynamic contents in many languages at the same time. From the administration panel you can activate or deactivate it. If you deactivate this feature \(default configuration\) users will be able to enter one single translation.
### Enable module
To activate this feature you must follow 2 steps: 1. Execute the following command `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` \(This is only required for already existing intallations, for new consul installations this step is not needed\). 2. Accessing as administrator user to the administration panel of your Consul application to the section **Configuration > Features** and activating the feature called **Translation Interface** as you can see next: ![Active interface translations](../../.gitbook/assets/active-interface-translations-en.png)
### Use Cases
* When the translation interface is active: As you can see in the image below translation interface has two selectors, the firt one "Select language" is to switch between enabled languages and the second one "Add language" is to add new languages to the form. Translatable fields appears with a blue background to facilitate users to distinguish between translatable and not translatable fields. Additionally interface provides a link `Remove language` to delete the current language shown at "Select language". If a user accidentally removes a translation he can recover it re-adding it to the form. This feature is visible during creation and edition of translatable resources. ![Translations inteface enabled](../../.gitbook/assets/translations-interface-enabled-en.png)
* When the translation interface is disabled: When this feature is deactivated users will see standard forms without translation interface and without translation highlight. ![Translations inteface enabled](../../.gitbook/assets/translations-interface-disabled-en.png)

16
docs/english-documentation/customization/javascript.md Normal file
View File

@@ -0,0 +1,16 @@
# 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:
```javascript
$(function(){
alert('foobar');
});
```
If you work with Coffeescript code you can check it with [coffeelint](http://www.coffeelint.org/) \(install with `npm install -g coffeelint`\) :
```bash
coffeelint .
```

76
docs/english-documentation/customization/models.md Normal file
View File

@@ -0,0 +1,76 @@
# 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
```

15
docs/english-documentation/customization/overwritting.md Normal file
View File

@@ -0,0 +1,15 @@
# Overwritting Application
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.

39
docs/english-documentation/customization/translations.md Normal file
View File

@@ -0,0 +1,39 @@
# Texts & Translations
## Translations
Currently, CONSUL is totally or partially translated to multiple languages. You can find the translations at the [Crowdin project](https://crowdin.com/project/consul).
Please [join the translators](https://crwd.in/consul) to help us complete existing ones, or contact us through [CONSUL's gitter](https://gitter.im/consul/consul) to become a proofreader and validate translators' contributions.
If your language isn't already present in the Crowdin project, please [open an issue](https://github.com/consul/consul/issues/new?title=New%20language&body=Hello%20I%20would%20like%20to%20have%20my%20language%20INSERT%20YOUR%20LANGUAGE%20NAME%20added%20to%20CONSUL) and we'll set it up in a breeze.
If you want to check existing translations of the user-facing texts you can find them organized in YML files under `config/locales/` folder. Take a look at the official Ruby on Rails [internationalization guide](http://guides.rubyonrails.org/i18n.html) to better understand the translations system.
## Custom Texts
Since CONSUL is always evolving with new features, and in order to make your fork easier to be updated, we strongly recommend translation files not to be modified, but instead "overwritten" with custom translation files in case a text needs to be customized for you.
So if you just want to change some of the existing texts, you can just drop your changes at the `config/locales/custom/` folder. We strongly recommend to include only those texts that you want to change instead of a whole copy of the original file. For example if you want to customize the text "Ayuntamiento de Madrid, 2016" that appears on every page's footer, firstly you want to locate where it's used \(`app/views/layouts/_footer.html.erb`\) and look at the locale identifier inside the code:
```ruby
<%= t("layouts.footer.copyright", year: Time.current.year) %>
```
Then find the file where this identifier will be located \(in that case `config/locales/es/general.yml`\) following this structure \(we're only displaying the relevant parts in the following snippet\):
```text
es:
layouts:
footer:
copyright: Ayuntamiento de Madrid, %{year}
```
In order to customize it, you should create a new file `config/locales/custom/es/general.yml` with just that content, and change "Ayuntamiento de Madrid" with our organization name. We strongly recommend to make copies from `config/locales/` and modify or delete the lines as needed to keep the indentation structure and avoid issues.
## Maintaining your Custom Texts & Languages
CONSUL has the [i18n-tasks](https://github.com/glebm/i18n-tasks) gem, it's an awesome helping tool to manage i18n translations. Just check `i18n-tasks health` for a nice report.
If you have a custom language different than English, you should add it to the [i18n-tasks.yml config file both `base_locale` and `locales`](https://github.com/consul/consul/blob/master/config/i18n-tasks.yml#L4-L7) variables so your language files will be checked as well.

34
docs/english-documentation/customization/views_and_styles.md Normal file
View File

@@ -0,0 +1,34 @@
# Views & 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
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:
```css
.top-links {
background: red;
}
```
If you want to change any [foundation](http://foundation.zurb.com/) variable, you can do it at the `app/assets/stylesheets/_custom_settings.scss` file. For example to change the main application color just add:
```css
$brand: #446336;
```
We use [SASS, with SCSS syntax](http://sass-lang.com/guide) as CSS preprocessor.
Also you can check your scss files syntax with
```bash
scss-lint
```
### Accesibility
To maintain accesibility level, if you add new colors use a [Color contrast checker](http://webaim.org/resources/contrastchecker/) \(WCAG AA is mandatory, WCAG AAA is recommended\)