decidim 0.9.3 → 0.10.0

data/docs/{migrate_to_0.8.0.md → advanced/migrate_to_0.8.0.md}

@@ -1,17 +1,16 @@
 # Migration from 0.7.0 to 0.8.0
 
-## Note about this guide.
+## Note about this guide
 
 This is a work-in-progress guide for all those people that needs to adapt his existing source code from Decidim
 0.7.0 to Decidim 0.8.0. If you find a mistake or missing parts in this  document do not hesitate to make a pull request
 and add your discoveries.
 
-
-## Upgrading the gem.
+## Upgrading the gem
 
 You need to alter the following files:
 
-### Gemspec file.
+### Gemspec file
 
 You must set the decidim version to 0.8.0 or higher in your gemspec.
 
@@ -22,6 +21,7 @@ s.add-dependency "decidim-core", "~> 0.8.0"
 ```
 
 ### Gemfile
+
 You must adjust the decidim version in your gem file as well. You also need to add the new engine 'decidim-verifications':
 
 ```ruby
@@ -30,16 +30,17 @@ gem "decidim", "~> 0.8.0"
 gem "decidim-verifications"
 ...
 ```
-### bundle update
+
 Finally run *bundle update* to get the required gems updated.
 
 ```bash
-$ bundle update --full-index
+bundle update --full-index
 ```
 
-## Updating your sources.
+## Updating your sources
 
 ### Factories
+
 Decidim 0.8.0 has migratied from FactoryGirl gem to FactoryBot. Cause this you need to update your factories. Usually the *factories.rb* file looks like this:
 
 ```ruby
@@ -68,7 +69,7 @@ end
 
 ```
 
-### Spec tests examples.
+### Spec tests examples
 
 Some examples have changed its name to be more descriptive. In order to have your tests up and running again you must perform the following substitions in the specs folder:
 
@@ -91,34 +92,36 @@ where the dialog was supposed to be accepted:
 accept_confirm { click_button "Submit" }
 ```
 
-## Steps to do after migrating your source code.
+## Steps to do after migrating your source code
 
-### Adapting code for an existing engine:
+### Adapting code for an existing engine
 
 You must remove the external test app and regenerate it:
 
 ```bash
-$ rm -Rf spec/decidim_dummy_app
-$ bundle exec rails decidim:generate_external_test_app
+rm -Rf spec/decidim_dummy_app
+bundle exec rails decidim:generate_external_test_app
 ```
 
 After regenerating the test app you should recreate the test database as well:
 
 ```bash
-$ cd spec/decidim_dummy_app
-$ bundle exec rails db:drop
-$ bundle exec rails db:create
-$ bundle exec rails db:migrate
-$ bundle exec rails db:migrate RAILS_ENV=test
-$ bundle exec rails db:seed
+cd spec/decidim_dummy_app
+bundle exec rails db:drop
+bundle exec rails db:create
+bundle exec rails db:migrate
+bundle exec rails db:migrate RAILS_ENV=test
+bundle exec rails db:seed
+
 ```
-### Adapting code for an existing Decidim implementation.
+
+### Adapting code for an existing Decidim implementation
 
 After updating the decidim gems you should import the new migrations and execute them:
 
 ```bash
-$ rails decidim:upgraded
-$ rails db:migrate
+rails decidim:upgraded
+rails db:migrate
 ```
 
 Additionally you should change the way uglifier is used in your app:
@@ -132,6 +135,7 @@ Edit the file *config/environments/production.rb* and make the following changes
 # Enable ES6 support
 config.assets.js_compressor = Uglifier.new(harmony: true)
 ```
-# To sum it up.
+
+### To sum it up
 
 Take a cold beer and enjoy democracy.

data/docs/advanced/testing.md

@@ -0,0 +1,29 @@
+# How to test Decidim engines
+
+## Requirements
+
+You need to create a dummy application to run your tests. Run the following command in the decidim root's folder:
+
+```bash
+bundle exec rake test_app
+```
+
+## Running tests for a specific component
+
+A Decidim engine can be tested running the rake task named after it. For
+example, to test the proposals engine, you can run:
+
+```bash
+bundle exec rake test_proposals
+```
+
+## Running the whole test suite
+
+You can also run the full thing including test application generation and tests
+for all components by running
+
+```bash
+bundle exec rake test_all
+```
+
+But beware, it takes a long time... :)

data/docs/advanced/tradeoffs.md

@@ -0,0 +1,14 @@
+# Technical tradeoffs
+
+## Architecture
+
+This is not your typical Ruby on Rails Vanilla App. We've tried using [Consul](http://decide.es) but we found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on "[Propuesta de Cambios de Arquitectura de Consul](https://www.gitbook.com/book/alabs/propuesta-de-cambios-en-la-arquitectura-de-consul/details)".
+
+## 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 [leaflet](http://leafletjs.com/) it's very inconvenient because its plugins extend an existing global object.
+
+The support of Turbolinks was dropped in [d8c7d9f](https://github.com/decidim/decidim/commit/d8c7d9f63e4d75307e8f7a0360bef977fab209b6). If you're interested in bringing turbolinks back, further discussion is welcome.
+

data/docs/{view_hooks.md → advanced/view_hooks.md}

@@ -6,7 +6,7 @@ All engines can define their own view hooks, and register to other engines' ones
 
 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
 <% if defined? Decidim::Processes %>
   <% # iterate through the most important ones %>
 <% end %>
@@ -24,11 +24,11 @@ This raises two important issues:
 
 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`:
 
-```
-<%= Decidim.view_hooks.render(:highlighted_elements, self) %>
+```ruby
+<%= Decidim.view_hooks.render(:highlighted_elements, deep_dup) %>
 ```
 
-We're rendering the view hooks registered as `:highlighted_elements`. The `self` parameter is the view context, we will analyze it later.
+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
 
@@ -43,7 +43,7 @@ initializer "decidim_participatory_processes.view_hooks" do
 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 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:
+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
 # decidim-participatory_processes/lib/decidim/participatory_processes/engine.rb
@@ -57,6 +57,19 @@ initializer "decidim_participatory_processes.view_hooks" do
 end
 ```
 
+We're passing a deep copy of the view context to allow us to extend it without polluting the original view context:
+
+```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|
+    # ...
+    view_context.extend Decidim::Proposals::ApplicationHelper
+    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

data/docs/customization/authorizations.md

@@ -14,4 +14,16 @@ One particular thing about this kind of applications is the need to Authorize a
 
 * By having a list of valid users emails
 
-Right now Decidim supports only a few of these cases, but we have an internal API where you can program your own kind of verifications. You can go see some example code, read more about how to work with Decidim modules, or even see how it’s done for Decidim Barcelona, the Barcelona City Council.
+Right now Decidim supports only a few of these cases, but we have an internal API where you can program your own kind of authorizations. To create your own `AuthorizationHandler` for an external API (ie a Municipal Census) you should add a `app/services/` file, then activate it on `config/initializers/decidim.rb` and finally enabling it on `/system` for the tenant.
+
+You can go see some example code on:
+
+* [Erabaki Pamplona](https://github.com/ErabakiPamplona/erabaki/blob/master/app/services/census_authorization_handler.rb)
+
+* [Decidim Barcelona](https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/master/app/services/census_authorization_handler.rb)
+
+* [Decidim Terrassa](https://github.com/AjuntamentDeTerrassa/decidim-terrassa/blob/master/app/services/census_authorization_handler.rb)
+
+* [Decidim Sant Cugat](https://github.com/AjuntamentdeSantCugat/decidim-sant_cugat/blob/master/app/services/census_authorization_handler.rb)
+
+These are just a few examples but mostly all the Municipal installations have somekind of Authorization.

data/docs/data-picker.md

@@ -0,0 +1,48 @@
+# Data Picker
+
+Simple HTML `select`s are not usable enough for the big collections of data Decidim has. We tried using `select2`, but we found problems with its usage and responsiveness, so we moved to a custom data picker. Also, there are many kinds of data that can be selected and many better usable ways to select this data than the simple select provided by html.
+
+Current Decidim's selector is inspired on [this](https://medium.com/@mibosc/responsive-design-why-and-how-we-ditched-the-good-old-select-element-bc190d62eff5) article.
+
+Data Picker is a selector thought to be reusable in many contexts and kinds of data. The idea behind it is a reusable widget that opens a popup where the user will perform a given selection and, on finish, this selection is returned to the source widget in the main page. The popup is accompained by a semitransparent layer behind it to blur the background and keep the user concentrated in the current action, the selection.
+
+## Artifacts
+Data Picker is composed by 2 visual artifacts, plus the javascript and one controller action for each selection type:
+- **widget**: the first visual artifact is the widget that encapsulates the main Data Picker functionality. This widget manages the rendering of __the button__ that opens the selector and __the popup__. This button is managed via ujs (Unobtrusive JavaScript). The popup is empty and must be filled with a selection partial.
+- **selection functionality** partial: There are many ways to select things (and many kinds of things to select). Thus, the selection functionality can be customized via a selection partial which will be rendered inside the widget's popup. This partial is supplied to the widget via ajax.
+- **controller ajax action**: An ajax action will send the content of the popup in an html partial.
+
+## How to
+### Placing the Data Picker widget:
+The Data Picker widget structure is as follows:
+```html
+<div id="some-unique-id" class="data-picker <%= picker_options[:class]%>" data-picker-name="<%=picker_options[:name]%>">
+  <div class="picker-values"><% @form.proposals.each do |proposal, params| %>
+    <div><a href="<%= prompt_params[:url] %>" data-picker-value="<%=proposal%>"><%=proposal%></a></div>
+  <% end %></div>
+  <div class="picker-prompt"><a href="<%= prompt_params[:url] %>"><%= prompt_params[:text] %></a></div>
+</div>
+```
+
+Placing the widget in a form requires two steps:
+
+It is a good way to implement the widget to think that it is a component that takes parameters.
+1. Prepare Data Picker parameters
+Data Picker takes two arguments the `picker_params` hash (to fill the main div) and the `prompt_params` hash (for the `picker-prompt` div).
+  - `picker_params.id`: the html unique id of the widget instance, required by the JavaScript.
+  - `picker_params.name`: the html name of the widget which will be sent by the form.
+  - `picker_params.class`: one of `picker-multiple`, when user can select multiple data, or `picker-single`, when only one data is to be selected.
+
+2. Html for the Data Picker widget
+
+### Selector popup content
+
+Anchors in the selector can have the following attributes:
+data-close: this anchor will be ignored
+href: the url to be used for choosing
+picker-choose: when 'undefined' will load the given href url. Otherwise a choose action in the component is invoked with params: `url: href, value: picker-value, text: picker-text`.
+picker-value: the selected value
+picker-text (optional): The text to be shown in the picker button.
+
+### Returning the selection to the widget
+To return the selection to the widget in the main page use javascript to set the data-picker-value in the #proposal-picker-choose button.

data/docs/getting_started.md

@@ -10,7 +10,20 @@ If you want to start your own installation of Decidim, you don't need to clone t
 
 ## Creating your Decidim app
 
-### Using Docker [experimental]
+### A. Using installation script [experimental]
+
+> *Please note that this is **experimental***
+
+We've made an script for Ubuntu 16.04 LTS and macos sierra 10.2. It's a BETA and as such you should be aware that this could break your environment (if you have any). It'll install rbenv, postgresql, nodejs and install decidim on this directory. It should take 15 minutes depending on your network connection.
+
+```
+wget http://get.decidim.org -O install_decidim.bash
+bash install_decidim.bash
+```
+
+Read more about the [installation script](https://github.com/alabs/decidim-install).
+
+### B. Using Docker [experimental]
 
 > *Please note that this is **experimental***
 
@@ -22,23 +35,25 @@ docker run --rm -v $(pwd):/tmp codegram/decidim bash -c "bundle exec decidim /tm
 
 This will create a `decidim_application` Ruby on Rails app using Decidim in the current folder. It will install the latest released version of the gem.
 
-### Step by step
+
+### C. Step by step
 
 First of all, you need to install the `decidim` gem:
 
 ```
-$ gem install decidim
+gem install decidim
 ```
 
-Afterwards, you can create an application with the nice `decidim` executable:
+afterwards, you can create an application with the nice `decidim` executable:
 
 ```
-$ decidim decidim_application
-$ cd decidim_application
-$ bundle install
+decidim decidim_application
+cd decidim_application
+bundle install
+rails server
 ```
 
-### Initializing your app for local development
+## Initializing your app for local development
 
 You should now setup your database:
 
@@ -52,12 +67,7 @@ This will also create some default data so you can start testing the app:
 * A `Decidim::Organization` named `Decidim Staging`. You probably want to change its name and hostname to match your needs.
 * A `Decidim::User` acting as an admin for the organization, with email `admin@example.org` and password `decidim123456`.
 * A `Decidim::User` that also belongs to the organization but it's a regular user, with email `user@example.org` and password `decidim123456`.
-
-This data won't be created in production environments, if you still want to do it, run:
-
-```
-$ SEED=true rails db:setup
-```
+This data won't be created in production environments, if you still want to do it, run: ``` $ SEED=true rails db:setup ```
 
 You can now start your server!
 
@@ -73,9 +83,10 @@ Decidim comes pre-configured with some safe defaults, but can be changed through
 
 We also have other guides on how to configure some extra features:
 
-- [Social providers integration](https://github.com/decidim/decidim/blob/master/docs/social_providers.md): Enable sign up from social networks.
-- [Analytics](https://github.com/decidim/decidim/blob/master/docs/analytics.md): How to enable analytics
-- [Geocoding](https://github.com/decidim/decidim/blob/master/docs/geocoding.md): How to enable geocoding for proposals and meetings
+- [ActiveJob](https://github.com/decidim/decidim/blob/master/docs/services/activejob.md)
+- [Analytics](https://github.com/decidim/decidim/blob/master/docs/services/analytics.md): How to enable analytics
+- [Geocoding](https://github.com/decidim/decidim/blob/master/docs/services/geocoding.md): How to enable geocoding for proposals and meetings
+- [Social providers integration](https://github.com/decidim/decidim/blob/master/docs/services/social_providers.md): Enable sign up from social networks.
 
 ## Deploy
 

data/docs/services/activejob.md

@@ -0,0 +1,7 @@
+# ActiveJob
+
+For some kind of actions to work on production (for instance, sending emails on user registration) you need to configure an [ActiveJob](http://edgeguides.rubyonrails.org/active_job_basics.html) backend on your application.
+
+If you don't want to introduce any other external dependencies for `decidim` (such as `redis`), you can use the `delayed_job` backend. That setup only depends on an underlying database which is already a requirement for `decidim` to work. Add the [delayed_job](https://github.com/collectiveidea/delayed_job/) gem to your `Gemfile` and follow the instructions in its readme to set it up.
+
+However, Decidim is agnostic on which kind of backend do you use, so feel free to set up the backend (ie `sidekiq`, `resque`, etc) you like the most.

data/lib/decidim/component_manager.rb

@@ -21,17 +21,25 @@ module Decidim
     end
 
     def run(command, out: STDOUT)
-      command = command.gsub("%version", version).gsub("%name", name)
-      status = system(command, out: out)
-      abort unless status || ENV["FAIL_FAST"] == "false"
+      Dir.chdir(@dir) do
+        command = command.gsub("%version", version).gsub("%name", name)
+        status = system(command, out: out)
+        abort unless status || ENV["FAIL_FAST"] == "false"
+      end
     end
 
     def replace_version
-      self.class.replace_file(
-        "lib/#{name.tr("-", "/")}/version.rb",
-        /def self\.version(\s*)"[^"]*"/,
-        "def self.version\\1\"#{version}\""
-      )
+      Dir.chdir(@dir) do
+        self.class.replace_file(
+          "lib/#{name.tr("-", "/")}/version.rb",
+          /def self\.version(\s*)"[^"]*"/,
+          "def self.version\\1\"#{version}\""
+        )
+      end
+    end
+
+    def short_name
+      name.gsub(/decidim-/, "")
     end
 
     class << self
@@ -42,13 +50,13 @@ module Decidim
           "  \"version\": \"#{version.gsub(/\.pre/, "-pre")}\""
         )
 
-        in_all_dirs do |dir|
+        all_dirs do |dir|
           new(dir).replace_version
         end
       end
 
       def run_all(command, out: STDOUT, include_root: true)
-        in_all_dirs(include_root: include_root) do |dir|
+        all_dirs(include_root: include_root) do |dir|
           new(dir).run(command, out: out)
         end
       end
@@ -67,28 +75,21 @@ module Decidim
         File.open(name, "w") { |f| f.write(new_content) }
       end
 
-      private
-
       def all_dirs(include_root: true)
         Dir.glob(include_root ? "{decidim-*,.}" : "decidim-*")
            .select { |f| File.directory?(f) }
-      end
-
-      def in_all_dirs(include_root: true)
-        all_dirs(include_root: include_root).each do |dir|
-          Dir.chdir(dir) { yield(dir) }
-        end
+           .each { |dir| yield(dir) }
       end
     end
 
     private
 
-    def name
+    def folder_name
       File.basename(@dir)
     end
 
-    def short_name
-      name.gsub(/decidim-/, "")
+    def name
+      folder_name.match?("decidim") ? folder_name : "decidim"
     end
 
     def version