decidim 0.23.6 → 0.24.0.rc1

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

@@ -0,0 +1,42 @@
+[plantuml]
+....
+@startuml
+!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/v2.0.1/C4_Container.puml
+
+' uncomment the following line to make proposals
+'LAYOUT_AS_SKETCH()
+
+title System Container diagram for Decidim Applications (https://decidim.org)
+
+
+Person_Ext(visitor_user, "Visitor User", "Anonymous, non registered user.")
+Person(participant_user, "Participant User", "A registered user. Could also be verified.")
+Person(administration_user, "Administration User", "A registered user with special permissions.")
+
+System_Boundary(decidim_system, "decidim"){
+    Container(web_app, "Web Application", "Ruby on Rails 5.2", "Allows participants to make decisions collaboratively through participatory processes, assemblies, consultations, initiatives, etc.")
+    ContainerDb(rel_db, "Relational Database", "PostgreSQL 9.5.x", "Stores users, participatory processes, assemblies, consultations, initiatives, proposals, meetings, etc.")
+    Container(filesystem, "File System", "Local or remote", "Stores uploads (images, documents, etc.)")
+    Container(worker, "Worker", "Ruby on Rails 5.2", "ActiveJob queues for non syncronuos jobs. Works for open data requests, sending emails, etc.")
+}
+
+System_Ext(decidim_bulletin_board_system, "Decidim Bulletin Board", "Allows participants to cast end-to-end verifiable secret votes.")
+System_Ext(mail_system, "SMTP system (e-mail)", "Sends mails to users, like confirmations, reminders, notifications, etc.")
+System_Ext(etherpad_system, "Etherpad-Lite system", "Optional. Allows real-time text edition in Meetings.")
+System_Ext(geocoding_system, "Geocoding system", "Optional. An Open Street Maps provider, allows geographical localization of Proposals and Meetings..")
+System_Ext(oauth_system, "OAUTH2 System", "Optional. Third party sign on systems. Could be Twitter, Facebook, Google or any other OAUTH2 providers.")
+
+Rel(visitor_user, web_app, "Uses")
+Rel(participant_user, web_app, "Uses")
+Rel(administration_user, web_app, "Uses")
+Rel_Back(participant_user, mail_system, "Sends e-mails to")
+Rel_Back(administration_user, mail_system, "Sends e-mails to")
+Rel_Back_Neighbor(decidim_bulletin_board_system, web_app, "Uses")
+Rel_Neighbor(worker, mail_system, "Sends e-mails", "SMTP")
+Rel(web_app, rel_db, "Uses")
+Rel(web_app, filesystem, "Uses")
+Rel(web_app, oauth_system, "Uses")
+Rel(web_app, geocoding_system, "Uses")
+Rel(web_app, etherpad_system, "Embeds", "Through an Iframe")
+@enduml
+....

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

@@ -0,0 +1,35 @@
+[plantuml]
+....
+@startuml
+!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/v2.0.1/C4_Context.puml
+
+' uncomment the following line to make proposals
+'LAYOUT_AS_SKETCH()
+
+title System Context diagram for Decidim Applications (https://decidim.org)
+
+
+Person_Ext(visitor_user, "Visitor User", "Anonymous, non registered user.")
+Person(participant_user, "Participant User", "A registered user. Could also be verified.")
+Person(administration_user, "Administration User", "A registered user with special permissions.")
+
+System(decidim_system, "Decidim", "Allows participants to make decisions collaboratively through participatory processes, assemblies, consultations, initiatives, etc.")
+
+System_Ext(decidim_bulletin_board_system, "Decidim Bulletin Board", "Allows participants to cast end-to-end verifiable secret votes.")
+System_Ext(mail_system, "SMTP system (e-mail)", "Sends mails to users, like confirmations, reminders, notifications, etc.")
+System_Ext(etherpad_system, "Etherpad-Lite system", "Optional. Allows real-time text edition in Meetings.")
+System_Ext(geocoding_system, "Geocoding system", "Optional. An Open Street Maps provider, allows geographical localization of Proposals and Meetings..")
+System_Ext(oauth_system, "OAUTH2 System", "Optional. Third party sign on systems. Could be Twitter, Facebook, Google or any other OAUTH2 providers.")
+
+Rel(visitor_user, decidim_system, "Uses")
+Rel(participant_user, decidim_system, "Uses")
+Rel(administration_user, decidim_system, "Uses")
+Rel_Back(participant_user, mail_system, "Sends e-mails to")
+Rel_Back(administration_user, mail_system, "Sends e-mails to")
+Rel_Back_Neighbor(decidim_bulletin_board_system, decidim_system, "Uses")
+Rel_Neighbor(decidim_system, mail_system, "Sends e-mails", "SMTP")
+Rel(decidim_system, oauth_system, "Uses")
+Rel(decidim_system, geocoding_system, "Uses")
+Rel(decidim_system, etherpad_system, "Embeds", "Through an Iframe")
+@enduml
+....

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

@@ -1,20 +1,32 @@
-# Components
+= Components
 
-Components are the core contract between external modules and the core. They're used to define pieces of functionality that are pluggable to participatory spaces and can be enabled or disabled by the administrator.
+Components are the core contract between external xref:develop:modules.adoc[modules] and the core. They're used to define pieces of functionality that are pluggable to participatory spaces and can be enabled or disabled by the administrator.
 
-## How do I create a new component?
+== Creating a new component
 
-Components are just gems with one or more Rails engines included in it. You can use as an example [decidim-pages](https://github.com/decidim/decidim/tree/master/decidim-pages).
+If you want to create a new component, you can use https://github.com/decidim/decidim/tree/develop/decidim-generators[decidim-generators] to
+automatically generate a decidim component skeleton, or copy the basic structure
+of an existing mantained plugin.
+
+[source,console]
+----
+decidim --component engine_name
+----
+
+Components are just gems with one or more Rails engines included in it. You can use as an example https://github.com/decidim/decidim/tree/develop/decidim-pages[decidim-pages].
 
 Check out the `lib/decidim/pages` folder: It includes several files, the most important of which is `component.rb`.
 
-## Defining a component manifest
+Upload the component to GitHub with the naming *decidim-module-engine_name*, so it's easier to find on the https://github.com/decidim/decidim/network/dependents[dependency graph].
+
+== Defining a component manifest
 
 Components are defined in a manifest, along with its engine and admin engine counterpart.
 
 There's a DSL available to describe all this:
 
-```ruby
+[source,ruby]
+----
 # :my_component is the unique name of the component that will be globally registered.
 Decidim.register_component(:my_component) do |component|
   # The user will be redirected to the component's engine when accessing it through
@@ -54,12 +66,21 @@ Decidim.register_component(:my_component) do |component|
 
     exports.serializer MyComponent::ResourceSerializer
   end
+
+  # Import definitions allow data to be imported into a component.
+  #
+  # For now supported formats for imports are CSV, JSON and Excel (.xls).
+  # Every resource type needs it's own creator, which creates resource
+  # from parsed data.
+  component.imports :component_resources do |imports|
+    imports.creator MyComponent::ResourceCreator
+  end
 end
-```
+----
 
 Every model in a component doesn't have to (and should not) know about its parent participatory space, but instead should be scoped to the components.
 
-## Settings
+== Settings
 
 Components can define settings that modify its behavior. This settings can be defined to be set for the whole life of the component (global settings), or to be set for each different step of the participatory space (step settings).
 
@@ -73,7 +94,8 @@ Each attribute defined can be described through properties:
 * `enum` attributes should have a `choices` attributes that list all the possible values. This could be a lambda function.
 * they can be `readonly` in some cases, throught a lambda function that received the current component within the `context`.
 
-```ruby
+[source,ruby]
+----
 # :my_component is the unique name of the component that will be globally registered.
 Decidim.register_component(:my_component) do |component|
   ...
@@ -91,10 +113,25 @@ Decidim.register_component(:my_component) do |component|
 
   ...
 end
-```
+----
 
 Each setting should have one or more translation texts related for the admin zone:
 
 * `decidim.components.[component_name].settings.[global|step].[attribute_name]`: Admin label for the setting.
 * `decidim.components.[component_name].settings.[global|step].[attribute_name]_help`: Additional text with help for the setting use.
 * `decidim.components.[component_name].settings.[global|step].[attribute_name]_readonly`: Additional text for the setting when it is readonly.
+
+== Fixtures
+
+This sections explains how to add dummy content to a development application.
+
+=== Proposals example
+
+. In decidim-proposals open `lib/decidim/proposals/component.rb`.
+. Find the `+component.seeds do...+` block.
+. Create your dummy content as if you were in a `db/seed.rb` script.
+
+=== Tips and Tricks
+
+* Take advantage of the Faker gem, already in decidim.
+* If you need content for i18n fields, you can use https://github.com/decidim/decidim/blob/develop/decidim-core/lib/decidim/faker/localized.rb[Localizaed], which uses `Faker` internally.

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

@@ -1,11 +1,11 @@
-# Content blocks
+= Content blocks
 
 Content blocks come from the need of making sortable and configurable layout chunks. The abstraction is similar to view hooks, but content blocks allow the user to manually configure and sort each block. The order and configuration is backed in the database.
 
 As of today, content blocks can be:
 
-- Sorted
-- Published
+* Sorted
+* Published
 
 Configuration will come in the near future.
 
@@ -13,22 +13,24 @@ Content blocks are defined per scope, and must be unique in that scope. Examples
 
 Content blocks are used in the organization homepage.
 
-## Registering a content block
+== Registering a content block
 
 Content blocks use the same manifests-registry pattern used in other places around Decidim. Here's how to register them:
 
-```ruby
+[source,ruby]
+----
 Decidim.content_blocks.register(:homepage, :stats) do |content_block|
   content_block.cell "decidim/content_blocks/stats_block"
   content_block.public_name_key "decidim.content_blocks.stats_block.name"
 end
-```
+----
 
 Let's analyze the example. In the first line, we register a content block named `:stats` for the `:homepage` scope. Then we define the name of the `cell` that will be used to render the content block, and we define the i18n key that holds the name for the content block. These are the only required fields to register a content block.
 
 Note that content blocks need to be registered from an initializer. If you are adding a content block from a module, use this in the `engine.rb` file of your module:
 
-```ruby
+[source,ruby]
+----
 module Decidim::MyModule::Engine < ::Rails::Engine
   # ...
 
@@ -40,23 +42,24 @@ module Decidim::MyModule::Engine < ::Rails::Engine
 
   # ...
 end
-```
+----
 
-## Managing content blocks
+== Managing content blocks
 
-Content blocks registered under the `:homepage` scope can be seen in the admin area, under Settings -> Homepage. You need to be an organization admin in order to enter this section.
+Content blocks registered under the `:homepage` scope can be seen in the admin area, under Settings \-> Homepage. You need to be an organization admin in order to enter this section.
 
 You'll see all the registered content blocks for the `:homepage` scope, those active and those inactive. You can reorder blocks and (un)publish them.
 
 Another use for content blocks, for example, can be seen at the newsletter templates system.
 
-## Rendering content blocks
+== Rendering content blocks
 
 You can check the code we use in the homepage to render them, or use something like this:
 
-```ruby
+[source,ruby]
+----
 <% Decidim::ContentBlock.published.for_scope(:homepage, organization: current_organization).each do |content_block| %>
   <% next unless content_block.manifest %>
   <%= cell content_block.manifest.cell %>
 <% end %>
-```
+----

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

@@ -1,25 +1,27 @@
-# Content processors
+= Content processors
 
 A content processor is a concept to refer to a set of two classes: a content parser class and a content renderer class.
 
 The content parser class is used to process the text before it is saved to the database, and the associated renderer class is used to render the saved content.
 
-## How do I add a content processor?
+== How do I add a content processor?
 
 Register the content processor in an `initializer`:
 
-```ruby
+[source,ruby]
+----
 Decidim.content_processors += [:special_words]
-```
+----
 
 This symbol will be used to instantiate parsers and processors using the following convention:
 
-- "Decidim::ContentParsers::#{type.to_s.camelize}Parser"
-- "Decidim::ContentRenderers::#{type.to_s.camelize}Renderer"
+* "Decidim::ContentParsers::#{type.to_s.camelize}Parser"
+* "Decidim::ContentRenderers::#{type.to_s.camelize}Renderer"
 
 Autoload parser and renderer if in the lib/ dir. For example if in proposals module edit `lib/decidim/proposals.rb`:
 
-```rb
+[source,rb]
+----
 module Decidim
   ...
   module ContentParsers
@@ -30,11 +32,12 @@ module Decidim
   end
   ...
 end
-```
+----
 
 Declare the parser class:
 
-```rb
+[source,rb]
+----
 class Decidim::ContentParsers::SpecialWordsParser < BaseParser
   Metadata = Struct.new(:count)
 
@@ -46,33 +49,36 @@ class Decidim::ContentParsers::SpecialWordsParser < BaseParser
     Metadata.new(content.scan('foo').size)
   end
 end
-```
+----
 
 And the renderer class:
 
-```rb
+[source,rb]
+----
 class Decidim::ContentRenderers::SpecialWordsRenderer < BaseRenderer
   def render
     content.gsub(/\~\~(.*?)\~\~/, '<del>\1</del>')
   end
 end
-```
+----
 
-## How to use the content parser class
+== How to use the content parser class
 
-```rb
+[source,rb]
+----
 parser = Decidim::ContentParsers::SpecialWordsParser.new(content, {})
 parser.rewrite # returns the content rewritten
 parser.metadata # returns a Metadata object
-```
+----
 
-## How to use the content renderer class
+== How to use the content renderer class
 
-```rb
+[source,rb]
+----
 renderer = Decidim::ContentRenderers::SpecialWordsRenderer.new(content)
 parser.render # returns the content formatted
-```
+----
 
-## Additional documentation
+== Additional documentation
 
 You can check the docs in the base classes and the user processor.

data/docs/modules/develop/pages/data-picker.adoc

@@ -0,0 +1,85 @@
+= 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 https://medium.com/@mibosc/responsive-design-why-and-how-we-ditched-the-good-old-select-element-bc190d62eff5[this] 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 then return to 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:
+
+[source,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.
+
+. 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.
+. 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 and will close the picker
+* href: the url to be used for choosing
+* picker-choose: when not present the picker will navigate as a regular anchor. 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.
+
+This is an example of a link used to choose an element:
+
+[source,html]
+----
+  <a class="button" href="[picker path browsing this element]" data-picker-text="[text]" data-picker-value="[value]" data-picker-choose>[text]</a>
+----
+
+*Checkboxes* also can be used in the selector, to allow to select several values at once. In this case, the `href` attribute is replaced with `data-picker-url` and the `data-picker-value` attribute is replaced with the `value` built-in attribute.
+
+This is an example of a checkbox that allow to choose an element without closing the picker:
+
+[source,html]
+----
+  <label><input type="checkbox" data-picker-url="[picker path browsing this element]" data-picker-text="[text]" value="[value]" data-picker-choose>[text]</label>
+----
+
+== Examples of use of the DataPicker
+
+* Scopes picker: Allows to browse the tree of scopes and select one or several scopes.
+ ** link:../../decidim-core/lib/decidim/form_builder.rb[FormBuilder scopes picker field]: Basic method to render a scope picker for a form.
+ ** link:../../decidim-core/lib/decidim/filter_form_builder.rb[FilterFormBuilder scopes picker field]: Basic method to render a scope picker for a filter form.
+ ** link:../../decidim-core/app/helpers/decidim/scopes_helper.rb[Scopes pickers helpers]: Helpers to simplify the call to basic methods.
+ ** link:../../decidim-core/app/controllers/decidim/scopes_controller.rb[Global scopes picker controller]: Controller used to browse the scopes on a picker in any part of the application.
+ ** link:../../decidim-proposals/app/views/decidim/proposals/proposals/_edit_form_fields.html.erb[Proposals' frontend form using a scopes picker]: Use of a scope picker helper on a frontend page.
+ ** link:../../decidim-proposals/app/views/decidim/proposals/admin/proposals/_form.html.erb[Proposals' admin form using a scopes picker]: Use of a scope picker helper on an admin page.
+ ** link:../../decidim-meetings/app/views/decidim/meetings/meetings/_filters.html.erb[Meetings' multiple scopes picker for filtering]: Use of a multiple scopes picker on a filter form.
+* Proposals picker: Allows to search and select multiple proposals to be referenced from other components.
+ ** link:../../decidim-proposals/app/helpers/decidim/proposals/admin/proposals_picker_helper.rb[Proposals pickers helper]: Helper to render a DataPicker for proposals selection.
+ ** link:../../decidim-proposals/app/controllers/concerns/decidim/proposals/admin/picker.rb[Proposals picker concern for admin pages]: You will need to add this concern to your controller, add a route for `proposals_picker` endpoint and create a view for it to show the proposals picker in your component context.
+ ** link:../../decidim-proposals/app/cells/decidim/proposals/proposals_picker_cell.rb[Proposals picker cell]: You can use this cell to reuse the logic in your picker view.
+ ** link:../../decidim-accountability/app/controllers/decidim/accountability/admin/results_controller.rb[Accountability's admin controller with a proposals picker]: It only needs to add the concern (and the endpoint to the routes).
+ ** link:../../decidim-accountability/app/views/decidim/accountability/admin/results/proposals_picker.html.erb[Accountability's admin view with a proposals picker]: It only needs to render the cell.

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

@@ -0,0 +1,15 @@
+= Deploy
+
+== Self-hosted
+
+You can install Decidim like a regular Ruby on Rails application, with nginx, Passenger, rbenv and PostgreSQL. You should also configure a valid SMTP account to send emails and add the delayed_job gem and execute it so you can receive emails (ie on user registration).
+
+== Heroku
+
+You can follow an opinionated Rails generator to configure your decidim app so that it can be https://github.com/codegram/decidim-deploy-heroku[deployed to Heroku].
+
+== Docker
+
+You can also deploy a Decidim app using Docker on hosting services that support it like Dokku, Heroku and all the cloud providers.
+
+See the xref:develop:docker.adoc[Decidim on Docker doc] for more details.