decidim 0.23.5 → 0.24.2

data/docs/{advanced/activity_log.md → modules/develop/pages/traceable.adoc}

@@ -1,31 +1,32 @@
-# Activity log
+= Activity log
 
 In order to make your component compatible with the activity log, you need to follow these steps:
 
-1. Make your model include the `Decidim::Traceable` module. This will let Decidim create versions every time your model records are changed. It uses [`paper_trail`](https://github.com/airblade/paper_trail) to generate the versions.
-1. Make your commands use `Decidim.traceability` to create and update records. Documentation can be found in `Decidim::Traceability`. This should set the author of the change in your record properly.
+. Make your model include the `Decidim::Traceable` module. This will let Decidim create versions every time your model records are changed. It uses https://github.com/airblade/paper_trail[`paper_trail`] to generate the versions.
+. Make your commands use `Decidim.traceability` to create and update records. Documentation can be found in `Decidim::Traceability`. This should set the author of the change in your record properly.
 
 That's all you need to do to get it working, really. We have a default way to present logs that Just Works™. Keep reading if you want to customize how the logs for your resources look!
 
-## The default renderer
+== The default renderer
 
 The default renderer doesn't know many things. It knows the author, what action was done, the resource affected and the space where the resource resides. When the resource is updated it shows the diff of all the fields that have been changed, with the old and new values for each field. values are not formatted in any specific way, so you might see some weirdly formatted values on the log diff: that's how it's rendered from the database.
 
-## Customizing the logs for your resources
+== Customizing the logs for your resources
 
- The default presenter doesn't fulfill your needs? You might want to create your own presenter if you find yourself in one of these cases:
+The default presenter doesn't fulfill your needs? You might want to create your own presenter if you find yourself in one of these cases:
 
-- You want to show what type of resource is affected by the action log
-- The default renderer cannot find the correct field to render the resource name
-- You want to show more info
-- You want to change the order of the factors in the log sentence
-- You want to change the format of the values in the diff
+* You want to show what type of resource is affected by the action log
+* The default renderer cannot find the correct field to render the resource name
+* You want to show more info
+* You want to change the order of the factors in the log sentence
+* You want to change the format of the values in the diff
 
 Let's go ahead and see how to create your own resource presenter.
 
 Custom presenters should be named as `Decidim::<your module name>::<log name>::<your model name>Presenter`. There's currently only one log, `AdminLog`. This means that if your model is `Decidim::Accountability::Result`, then your admin log presenter is must be `Decidim::Accountability::AdminLog::ResultPresenter`. You can inherit from `Decidim::Log::BasePresenter` for simplicity:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Accountability
     module AdminLog
@@ -34,15 +35,16 @@ module Decidim
     end
   end
 end
-```
+----
 
 Some examples with basic customization follow, although you can read the source code docs and overwrite any method you need.
 
-### Changing the action log sentence
+=== Changing the action log sentence
 
 In order to change the default sentence to something that fits better to your resource, you can overwrite the `action_string` method in your presenter:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Accountability
     module AdminLog
@@ -61,17 +63,18 @@ module Decidim
     end
   end
 end
-```
+----
 
 This is useful to show the resource type in the sentence.
 
-### Limiting what fields get presented in the diff
+=== Limiting what fields get presented in the diff
 
-By default, all changed fields are presented in the diff. In order to limit them, overwrite the `diff_fields_mapping` method in your custom presenter. It has to return a `Hash`, where keys are the name of the attributes and values are the presenters that render the attributes. **Limitations**: we can only show diffs for column fields, not dynamic methods, so the `diff_fields_mapping` only accepts column names.
+By default, all changed fields are presented in the diff. In order to limit them, overwrite the `diff_fields_mapping` method in your custom presenter. It has to return a `Hash`, where keys are the name of the attributes and values are the presenters that render the attributes. *Limitations*: we can only show diffs for column fields, not dynamic methods, so the `diff_fields_mapping` only accepts column names.
 
 In this example, we're telling our presenter to only present the `start_date` as a date, the `title` as an i18n field, the `decidim_scope_id` with no particular presenter, and `progress` as a percentage:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Accountability
     module AdminLog
@@ -90,13 +93,14 @@ module Decidim
     end
   end
 end
-```
+----
 
-#### Value types presenters
+==== Value types presenters
 
 Decidim comes with some default value types presenters to be used in the diffs. They all live in `Decidim::Log::ValueTypes`, check the source code for the full list. These presenters are used with a symbol, but you can use your own value type presenter if you use a string:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Accountability
     module AdminLog
@@ -112,11 +116,12 @@ module Decidim
     end
   end
 end
-```
+----
 
 Then you can write your own value presenter as:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Accountability
     module AdminLog
@@ -131,8 +136,8 @@ module Decidim
     end
   end
 end
-```
+----
 
-## Multiple logs
+== Multiple logs
 
 Although Decidim currently only has a log for the admin section, in the future we might need an activity log for the public part. It's easy to assume we might need to render the same data in different formats, so we need to differentiate the presenters for each log. The current system handles the case for multiple logs, although we only have one.

data/docs/modules/develop/pages/turbolinks.adoc

@@ -0,0 +1,7 @@
+= Turbolinks
+
+Decidim doesn't support `turbolinks` so it isn't included on our generated apps and it's removed for existing Rails applications which install the Decidim engine.
+
+The main reason is we are injecting some scripts into the body for some individual pages and Turbolinks loads the scripts in parallel. For some libraries like http://leafletjs.com/[leaflet] it's very inconvenient because its plugins extend an existing global object.
+
+The support of Turbolinks was dropped in https://github.com/decidim/decidim/commit/d8c7d9f63e4d75307e8f7a0360bef977fab209b6[d8c7d9f]. If you're interested in bringing turbolinks back, further discussion is welcome.

data/docs/{advanced/view_hooks.md → modules/develop/pages/view_hooks.adoc}

@@ -1,51 +1,55 @@
-# View hooks
+= View hooks
 
-## General description
+== General description
 
 All engines can define their own view hooks, and register to other engines' ones. This allows engines to add content to views rendered by other engines. This will be clearer with an example.
 
 Take the homepage, for example. It is rendered by the `decidim-core`. We want to show there a list of highlighted participatory spaces (processes and assemblies). We cannot be sure the final app has these engines, so we need to check they exist:
 
-```ruby
+[source,ruby]
+----
 <% if defined? Decidim::Processes %>
   <% # iterate through the most important ones %>
 <% end %>
 <% if defined? Decidim::Assemblies %>
   <% # iterate through the most important ones %>
 <% end %>
-```
+----
 
 This raises two important issues:
 
-1. We are linking `decidim-core` with `decidim-assemblies` and `decidim-participatory_processes`. This is not perfect.
-1. The final app cannot extend this view to add more content in a simple way. The developers could overwrite the view, but this raises maintainability problems, as upgrades will be harder.
+. We are linking `decidim-core` with `decidim-assemblies` and `decidim-participatory_processes`. This is not perfect.
+. The final app cannot extend this view to add more content in a simple way. The developers could overwrite the view, but this raises maintainability problems, as upgrades will be harder.
 
-## Rendering view hooks
+== Rendering view hooks
 
 Instead of the previous example, we created the concept of "view hooks". Think of them as a registry of views which can be defined by a given engine and extended by others. To follow the previous example, we would register a view hook in `decidim-core`:
 
-```ruby
+[source,ruby]
+----
 <%= Decidim.view_hooks.render(:highlighted_elements, deep_dup) %>
-```
+----
 
 We're rendering the view hooks registered as `:highlighted_elements`. The `deep_dup` parameter is a deep copy of the view context, we will analyze it later.
 
-## Registering view hooks
+== Registering view hooks
 
 Other engines would register blocks of Ruby and Rails code from their initializers. For example, in `decidim-participatory_processes`:
 
-```ruby
+[source,ruby]
+----
 # decidim-participatory_processes/lib/decidim/participatory_processes/engine.rb
 initializer "decidim_participatory_processes.view_hooks" do
   Decidim.view_hooks.register(:highlighted_elements) do |view_context|
     view_context.render(partial: "my/partial")
   end
 end
-```
+----
 
 In order to register a view hook we need the hook name and a block of Ruby code. We're registering a view hook as `:highlighted-elements`, following our example. We're passing a deep copy of the view context to the block so that we can use our views helper methods there, and we're rendering a partial. We could write `ActiveRecord` queries and pass the results to the partial as `locals` if we wanted a more complex view:
 
-```ruby
+[source,ruby]
+----
 # decidim-participatory_processes/lib/decidim/participatory_processes/engine.rb
 initializer "decidim_participatory_processes.view_hooks" do
   Decidim.view_hooks.register(:highlighted_elements) do |view_context|
@@ -55,11 +59,12 @@ initializer "decidim_participatory_processes.view_hooks" do
     view_context.render(partial: "decidim/participatory_processes/my/partial", locals: { highlighted_processes: highlighted_processes })
   end
 end
-```
+----
 
 We're passing a deep copy of the view context to allow us to extend it without polluting the original view context:
 
-```ruby
+[source,ruby]
+----
 # decidim-proposals/lib/decidim/proposals/engine.rb
 initializer "decidim_participatory_processes.view_hooks" do
   Decidim.view_hooks.register(:participatory_space_highlighted_elements) do |view_context|
@@ -68,24 +73,25 @@ initializer "decidim_participatory_processes.view_hooks" do
     view_context.render(partial: "decidim/participatory_spaces/highlighted_proposals", locals: { })
   end
 end
-```
+----
 
 When registering a view hook, we can set a priority for each one. By default, all view hooks are registered with low priority, but we can change it:
 
-```ruby
+[source,ruby]
+----
 Decidim.view_hooks.register(:highlighted_elements, priority: Decidim::ViewHooks::HIGH_PRIORITY) do |view_context|
   # ...
 end
-```
+----
 
-## Enabling view hooks in your engine
+== Enabling view hooks in your engine
 
 Ideally, each engine should hold their own instance of `Decidim::ViewHooks`. This means that if `decidim-participatory_processes` wants to allow part of its views to be extended by other engines, it should define `Decidim::ParticipatoryProcesses.view_hooks`, and other engines should register to this instance.
 
-## The engine I want to extend does not support view hooks, what can I do?
+== The engine I want to extend does not support view hooks, what can I do?
 
-First of all, send a PR to the engine to add the view hook you need. Expose your needs, so the developers can assess a view hook is the best solution. Sometimes a view hook can be replaced with another abstraction, or another UI. Meanwhile, you can use [`deface`](https://github.com/spree/deface) to extend a view file without replacing it. Be careful, since `deface` is *very* powerful and can be a double-edged sword. We considered adding `deface` to `decidim`, but found that it opened to a code that would be much harder to maintain.
+First of all, send a PR to the engine to add the view hook you need. Expose your needs, so the developers can assess a view hook is the best solution. Sometimes a view hook can be replaced with another abstraction, or another UI. Meanwhile, you can use https://github.com/spree/deface[`deface`] to extend a view file without replacing it. Be careful, since `deface` is _very_ powerful and can be a double-edged sword. We considered adding `deface` to `decidim`, but found that it opened to a code that would be much harder to maintain.
 
-## View hooks drawbacks and alternatives
+== View hooks drawbacks and alternatives
 
-View hooks allow components to extend the views of other components without coupling, but they cannot be sorted by the user, and cannot hold options. Consider checking the content blocks abstraction for a more configurable setup.
+View hooks allow components to extend the views of other components without coupling, but they cannot be sorted by the user, and cannot hold options. Consider checking the content blocks abstraction for a more configurable setup.

data/docs/modules/develop/pages/view_models_aka_cells.adoc

@@ -0,0 +1,105 @@
+= View Models (a.k.a. Cells)
+
+== General description
+
+A cell is an object that represent a fragment of your UI. The scope of that fragment can embrace an entire page, a single comment container in a thread or just an avatar image link.
+
+Cells are faster than ActionView. While exposing a better performance, you step-wise encapsulate fragments into cell widgets and enforce interfaces.
+
+=== View Model
+
+Think of cells, or view models, as small Rails controllers, but without any HTTP coupling. Cells embrace all presentation and rendering logic to present a fragment of the UI.
+
+== Decidim Cards
+
+`card_for @instance` will render the corresponding default card for each component instance.
+If a card for the given resource is not registered, a _basic_ (default) card is shown.
+
+To render a specified size/variation include the `size` option as a `symbol`: `card_for @instance, size: :m`
+
+=== Card M
+
+To render a label to identify the type of component renderized add to the `context` the `label` option.
+
+The `label` option accepts this arguments:
+
+* `false` or `"false"` will not render the label from the locales `t(model.class.model_name.i18n_key, scope: "activerecord.models", count: 1)`
+* `true` or `"true"` will render the translation from
+* `"whathever string"` will render it as String
+
+== Introducing a Card Cell to a `component`
+
+* add *dependency* to "decidim-*.gemspec"
++
+[source,rb]
+----
+s.add_dependency "cells-erb", "~> 0.1.0"
+s.add_dependency "cells-rails", "~> 0.0.9"
+----
+
+* *require* cells in `decidim-<module>/lib/decidim/<module>/engine.rb`
++
+[source,rb]
+----
+require "cells/rails"
+require "cells-erb"
+
+initializer "decidim_<module>.add_cells_view_paths" do
+  Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/cells")
+  Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/views") # for partials
+end
+----
+
+* The attribute `card` of the resource is defined in `decidim-core/lib/decidim/resource_manifest.rb`:
++
+[source,rb]
+----
+# The cell to use to render the card of a resource.
+attribute :card, String
+----
++
+In your `decidim-<component>/lib/decidim/<component>/component.rb` register the resource and set the card value. Note that the model class for your resource must include the `Decidim::Resourceable` concern for this to work:
++
+[source,rb]
+----
+component.register_resource(:<my_resource>) do |resource|
+  resource.class = "Decidim::<Component>/<MyResource>" # eg. "Decidim::Proposals::ProposalDraft
+  resource.card = "decidim/<component>/<my_resource>" # eg. "decidim/proposals/proposal_draft"
+  resource.component_manifest = component
+end
+----
++
+[source,rb]
+----
+module Decidim
+  module <Component>
+    class <MyResource> < Decidim::ApplicationRecord
+      include Decidim::Resourceable
+      # ...
+    end
+  end
+end
+----
+
+* The *Cell Class*, following the convention, will reside in `decidim-<component>/app/cells/decidim/<component>/<my_resource>_cell.rb`:
++
+[source,rb]
+----
+module Decidim
+  module <Component>s
+    class <MyResource>Cell < Decidim::ViewModel
+      def show
+        render # renders decidim-<component>/app/cells/decidim/<component>/<my_resource>
+      end
+    end
+  end
+end
+----
+
+* The *Cell Views* will be in the `decidim-<component>/app/cells/decidim/<component>/<my_resource>` and defaults to `show.erb`
+
+== More Info
+
+* https://github.com/trailblazer/cells/blob/master/README.md[cells/README.md at master · trailblazer/cells]
+* http://trailblazer.to/gems/cells/[Trailblazer: Cells] / http://trailblazer.to/gems/cells/api.html[Trailblazer: Cells API]
+* https://www.sitepoint.com/introduction-to-cells-a-better-view-layer-for-rails/[Introduction to Cells: A Better View Layer for Rails -- SitePoint]

data/docs/modules/install/pages/checklist.adoc

@@ -0,0 +1,39 @@
+= Checklist
+
+As a technopolitical project, Decidim needs several things to work. This is a non comprehensive list that serves as a general recommendation of what things you need to have it working with the best practices:
+
+== Technological
+
+. Choose a *domain or subdomain* for your application. Some typical names involve "Participation" or "Decision" conjugations.
+. Choose which *languages* do you want for your application. In case that your language isn't supported you should translate it on https://crowdin.com/project/decidim[Crowdin].
+. Customize the xref:customize:styles.adoc[*look and feel*] (colors, pictures, fonts, etc).
+. Configure *SSL*:
+.. We recommend using at least *https://letsencrypt.org/[Let's Encrypt]* for minimum security.
+.. Configure *redirection from HTTP to HTTPS* on your web server.
+.. Configure your *Certificate Authority Authorization* (CAA) DNS records
+.. Install complete *Certificate Chains* if it's needed for your provider
+.. Use current SSL/TLS Protocols (*TLS 1.2 or 1.3*)
+.. If you add new static files, be careful of not introducing *mixed content*
+.. Use the *https://www.ssllabs.com/ssltest/[SSL Server Test]* and follow their recommendations
+. Configure your *SMTP* server.
+. Setup the *geolocation* service. We recommend using https://developer.here.com/[Here Maps], but you can use other kind of tiling server compatible with https://www.openstreetmap.org/[Open Street Maps].
+. Setup *backup* on your server. The most important things to save are the `public/uploads` and the database.
+. Decide and implement which kind of *xref:customize:authorizations.adoc[Authorization]* you're going to use.
+. Comply with our License (Affero GPL 3) and *publish your code* to http://github.com[GitHub] or wherever you want.
+. Review your *decidim initializer* on your application (config/initializers/decidim.rb).
+. Configure your xref:services:activejob.adoc[*ActiveJob*] background queue.
+. If you want, configure your xref:services:social_providers.adoc[*social providers*] to enable login using external applications.
+. Check that you don't have any *default users, emails and passwords*, neither on the admin or on the system panel.
+. Configure xref:install:index.adoc#scheduled_tasks[scheduled tasks].
+. You should have a *staging* / preproduction environment where to test changes before deploying to production. If this environment has a copy of production database, you should disable the SMTP server and for privacy issues you should change the usernames / names / emails.
+. You should have a *exception tracking* service or gem, like https://errbit.com/[Errbit], https://github.com/smartinez87/exception_notification[Exception Notification], https://airbrake.io/[Airbrake] or https://sentry.io[Sentry].
+
+== Contents
+
+. Ideally you'll have a *Team* formed with experts on IT, Communication, Participation, Design and Law.
+. Texts for at least, *terms of use, privacy policy and frequently asked questions*. To show the "Terms and conditions" body text in the "Sign Up Form", it is a requirement that the slug of this page to be equal `terms-and-conditions`.
+. Comply with your current *legal requirements*, like to registrate your privacy policy with the autorities (eg LOPD on Spain).
+. Fill the *Participatory Processes Configuration Form* to prepare your Participatory Process for Decidim.
+. Read the *https://decidim.org/docs/[Administration manual]*.
+. Participate on *http://meta.decidim.org[MetaDecidim]*.
+. Read the Decidim *https://decidim.org/contract/[Social Contract]*.

data/docs/modules/install/pages/index.adoc

@@ -0,0 +1,148 @@
+= Getting started with Decidim
+:source-highlighter: highlightjs
+
+== What is and what isn't Decidim?
+
+Decidim is a set of Ruby on Rails engines to create a participatory democracy framework on top of a Ruby on Rails app. This system allows having Decidim code separated from custom code for each installation and still enabling easy updates.
+
+These libraries are published to Rubygems.org, so you can add Decidim to your Ruby on Rails app as external dependencies.
+
+If you want to start your own installation of Decidim, you don't need to clone this repo. Keep reading to find out how to install Decidim.
+
+== Creating your Decidim app
+
+=== A. Recommended: manual installation
+
+If you know Ruby and have already worked with Ruby on Rails, you need to know that decidim is a gem and a command line that generates an application that consumes this gem 😅.
+
+The flow is: install gem, generate a Ruby on Rails app, enjoy.
+
+[source,console]
+----
+gem install decidim
+decidim decidim_application
+----
+
+You can see the xref:install:manual.adoc[official manual installation tutorial], and also you have https://platoniq.github.io/decidim-install/[another manual installation tutorial] made by the nice people of http://www.platoniq.net/[Platoniq].
+
+=== B. Installation script [experimental]
+
+There's also a installation script made by http://www.platoniq.net/[Platoniq] that allows you to install Decidim automatically. You can even check it on a Vagrant virtual machine if you want to. https://platoniq.github.io/decidim-install/script/[More information].
+
+[source,console]
+----
+wget -O install-decidim.sh https://raw.githubusercontent.com/Platoniq/decidim-install/master/script/install-decidim.sh
+chmod +x decidim-install.sh
+./install-decidim.sh decidim_application
+----
+
+== Initializing your app for local development
+
+You should now setup your database:
+
+[source,console]
+----
+bin/rails db:create db:migrate db:seed
+----
+
+This will also create some default data so you can start testing the app:
+
+.Default seed's users
+|===
+|Type |Email |Password| URL |Description
+
+|Decidim::System::Admin
+|system@example.org
+|decidim123456
+|/system
+|Administrator for the multitenant
+
+|Decidim::User
+|admin@example.org
+|decidim123456
+|/admin
+|Administrator for the organization
+
+|Decidim::User
+|user@example.org
+|decidim123456
+|/user/sign_in
+|User for the organization
+
+|===
+
+This data won't be created in production environments, if you still want to do it, run: `$ SEED=true rails db:setup`. We recomend that you first login as system user and edit the host for the organization. Set it to you production host, without the protocol and the port (so if your host is `+https://example.org:3001+`, you need to write `example.org`). After it'd be good to execute the `seed` command, as that would be created with the first Organization created.
+
+If you want to verify yourself against the default authorization handler use a document number ended with "X".
+
+You can now start your server!
+
+[source,console]
+----
+bin/rails s
+----
+
+Visit http://localhost:3000 to see your app running.
+
+== Configuration & setup
+
+Decidim comes pre-configured with some safe defaults, but can be changed through the `config/initializers/decidim.rb` file in your app. Check the comments there or read the comments in https://github.com/decidim/decidim/blob/develop/decidim-core/lib/decidim/core.rb[the source file] (the part with the `config_accessor` calls) for more up-to-date info.
+
+=== Scheduled tasks
+
+For Decidim to function as expected, there are some background tasks that should be scheduled to be executed regularly. Alternatively you could use `whenever` gem or the scheduled jobs of your hosting provider.
+
+You can configure it with `crontab -e`, for instance if you've created your Decidim application on /home/user/decidim_application:
+
+[source,console]
+----
+# Remove expired data portability files
+0 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:delete_data_portability_files
+
+# Compute metrics
+1 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:metrics:all
+
+# Compute open data
+2 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:open_data:export
+
+# Delete old registrations forms
+3 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim_meetings:clean_registration_forms
+----
+
+=== Further configuration
+
+We also have other guides on how to configure some extra components:
+
+* xref:services:activejob.adoc[ActiveJob]: For background jobs (like sending emails).
+* xref:services:geocoding.adoc[Geocoding]: How to enable geocoding for proposals and meetings.
+* xref:services:social_providers.adoc[Social providers integration]: Enable sign up from social networks.
+
+== Deploy
+
+Once you've successfully deployed your app to your favorite platform, you'll need to create your `System` user. First you'll need to create your `Decidim::System` user in your production Ruby on Rails console:
+
+[source,ruby]
+----
+email = <your email>
+password = <a secure password>
+user = Decidim::System::Admin.new(email: email, password: password, password_confirmation: password)
+user.save!
+----
+
+This will create a system user with the email and password you set. We recommend using a random password generator and saving it to a password manager, so you have a more secure login.
+
+Then, visit the `/system` dashboard and login with the email and passwords you just entered and create your organization. You're done! :tada:
+
+You can check the https://github.com/decidim/decidim/tree/develop/decidim-system/README.md[`decidim-system` README file] for more info on how organizations work.
+
+== Checklist
+
+There are several things you need to check before making your putting your application on production. See the xref:install:checklist.adoc[checklist].
+
+== Contributing
+
+We always welcome new contributors of all levels to the project. If you are not confident enough with Ruby or web development you can look for https://github.com/decidim/decidim/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22[issues labeled `good first issue`] to start contibuting and learning the internals of the project by doing easy jobs.
+
+We also have a xref:develop:guide.adoc[developer's reference] that will help you getting started with your environment and our daily commands, routines, etc.
+
+Finally, you can also find other ways of helping us on our xref:contribute:index.adoc[contribution guide].