decidim 0.23.6 → 0.24.0.rc1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of decidim might be problematic. Click here for more details.

Files changed (114) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +1 -0
  3. data/docs/README.adoc +74 -0
  4. data/docs/antora.yml +7 -0
  5. data/docs/modules/configure/pages/environment_variables.adoc +69 -0
  6. data/docs/modules/configure/pages/index.adoc +16 -0
  7. data/docs/modules/configure/pages/initializer.adoc +376 -0
  8. data/docs/modules/customize/assets/images/header-snippet.png +0 -0
  9. data/docs/modules/customize/assets/images/menu.png +0 -0
  10. data/docs/modules/customize/assets/images/organization-colors.png +0 -0
  11. data/docs/modules/customize/pages/authorizations.adoc +22 -0
  12. data/docs/{customization/code.md → modules/customize/pages/code.adoc} +12 -9
  13. data/docs/{customization/gemfile.md → modules/customize/pages/gemfile.adoc} +5 -4
  14. data/docs/modules/customize/pages/images.adoc +7 -0
  15. data/docs/modules/customize/pages/javascript.adoc +59 -0
  16. data/docs/modules/customize/pages/menu.adoc +25 -0
  17. data/docs/modules/customize/pages/oauth.adoc +33 -0
  18. data/docs/modules/customize/pages/styles.adoc +64 -0
  19. data/docs/modules/customize/pages/texts.adoc +30 -0
  20. data/docs/modules/customize/pages/users_registration_mode.adoc +17 -0
  21. data/docs/{customization/views.md → modules/customize/pages/views.adoc} +13 -13
  22. data/docs/modules/develop/assets/images/barcelona.png +0 -0
  23. data/docs/modules/develop/assets/images/helsinki.png +0 -0
  24. data/docs/modules/develop/assets/images/indices.png +0 -0
  25. data/docs/{advanced/api.md → modules/develop/pages/api.adoc} +2 -2
  26. data/docs/{advanced/authorship.md → modules/develop/pages/authorable.adoc} +5 -5
  27. data/docs/modules/develop/pages/c4_component.adoc +91 -0
  28. data/docs/modules/develop/pages/c4_container.adoc +42 -0
  29. data/docs/modules/develop/pages/c4_context.adoc +35 -0
  30. data/docs/{advanced/components.md → modules/develop/pages/components.adoc} +47 -10
  31. data/docs/{advanced/content_blocks.md → modules/develop/pages/content_blocks.adoc} +16 -13
  32. data/docs/{advanced/content_processors.md → modules/develop/pages/content_processors.adoc} +25 -19
  33. data/docs/modules/develop/pages/data-picker.adoc +85 -0
  34. data/docs/modules/develop/pages/deploy.adoc +15 -0
  35. data/docs/modules/develop/pages/docker.adoc +12 -0
  36. data/docs/{advanced/embeddable.md → modules/develop/pages/embeddable.adoc} +6 -6
  37. data/docs/{advanced/endorsable.md → modules/develop/pages/endorsable.adoc} +31 -25
  38. data/docs/{advanced/fixing_locales.md → modules/develop/pages/fixing_locales.adoc} +36 -23
  39. data/docs/{advanced/followers.md → modules/develop/pages/followable.adoc} +9 -8
  40. data/docs/modules/develop/pages/guide.adoc +16 -0
  41. data/docs/modules/develop/pages/guide_architecture.adoc +17 -0
  42. data/docs/modules/develop/pages/guide_changelog.adoc +8 -0
  43. data/docs/modules/develop/pages/guide_commands.adoc +86 -0
  44. data/docs/modules/develop/pages/guide_development_app.adoc +44 -0
  45. data/docs/modules/develop/pages/guide_development_with_custom_seed_data.adoc +31 -0
  46. data/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc +63 -0
  47. data/docs/modules/develop/pages/guide_example_apps.adoc +59 -0
  48. data/docs/modules/develop/pages/guide_git_conventions.adoc +75 -0
  49. data/docs/modules/develop/pages/guide_github_projects.adoc +42 -0
  50. data/docs/modules/develop/pages/guide_semver.adoc +7 -0
  51. data/docs/{advanced/how_to_fix_metrics.md → modules/develop/pages/how_to_fix_metrics.adoc} +76 -59
  52. data/docs/modules/develop/pages/machine_translations.adoc +42 -0
  53. data/docs/modules/develop/pages/managing_translations_i18n.adoc +24 -0
  54. data/docs/modules/develop/pages/maps.adoc +499 -0
  55. data/docs/modules/develop/pages/metrics.adoc +119 -0
  56. data/docs/{advanced/modules.md → modules/develop/pages/modules.adoc} +16 -6
  57. data/docs/{advanced/newsletter_templates.md → modules/develop/pages/newsletter_templates.adoc} +12 -10
  58. data/docs/{advanced/notifications.md → modules/develop/pages/notifications.adoc} +40 -38
  59. data/docs/{advanced/open-data.md → modules/develop/pages/open-data.adoc} +4 -3
  60. data/docs/modules/develop/pages/permissions.adoc +92 -0
  61. data/docs/{advanced/profiling.md → modules/develop/pages/profiling.adoc} +15 -12
  62. data/docs/modules/develop/pages/releases.adoc +148 -0
  63. data/docs/modules/develop/pages/reportable.adoc +31 -0
  64. data/docs/modules/develop/pages/security.adoc +33 -0
  65. data/docs/{advanced/share_tokens.md → modules/develop/pages/share_tokens.adoc} +18 -14
  66. data/docs/{advanced/templates.md → modules/develop/pages/templates.adoc} +14 -12
  67. data/docs/{advanced/testing.md → modules/develop/pages/testing.adoc} +21 -20
  68. data/docs/{advanced/activity_log.md → modules/develop/pages/traceable.adoc} +31 -26
  69. data/docs/modules/develop/pages/turbolinks.adoc +7 -0
  70. data/docs/{advanced/view_hooks.md → modules/develop/pages/view_hooks.adoc} +29 -23
  71. data/docs/modules/develop/pages/view_models_aka_cells.adoc +105 -0
  72. data/docs/modules/install/pages/checklist.adoc +39 -0
  73. data/docs/modules/install/pages/index.adoc +148 -0
  74. data/docs/{manual-installation.md → modules/install/pages/manual.adoc} +54 -42
  75. data/docs/modules/install/pages/update.adoc +95 -0
  76. data/docs/{services/activejob.md → modules/services/pages/activejob.adoc} +3 -3
  77. data/docs/modules/services/pages/elections_bulletin_board.adoc +52 -0
  78. data/docs/{services/etherpad.md → modules/services/pages/etherpad.adoc} +15 -12
  79. data/docs/modules/services/pages/maps.adoc +311 -0
  80. data/docs/modules/services/pages/smtp.adoc +10 -0
  81. data/docs/modules/services/pages/social_providers.adoc +122 -0
  82. data/lib/decidim/gem_manager.rb +5 -5
  83. data/lib/decidim/version.rb +1 -1
  84. metadata +137 -100
  85. data/README.md +0 -157
  86. data/docs/advanced/add_authorizable_action.md +0 -63
  87. data/docs/advanced/adding_fixtures_aka_dummy_content.md +0 -9
  88. data/docs/advanced/data-picker.md +0 -83
  89. data/docs/advanced/deploy.md +0 -9
  90. data/docs/advanced/how_to_create_a_module.md +0 -9
  91. data/docs/advanced/machine_translation_service.md +0 -12
  92. data/docs/advanced/managing_translations_i18n.md +0 -24
  93. data/docs/advanced/metrics.md +0 -114
  94. data/docs/advanced/permissions.md +0 -23
  95. data/docs/advanced/releases.md +0 -114
  96. data/docs/advanced/tradeoffs.md +0 -14
  97. data/docs/advanced/view_models_aka_cells.md +0 -99
  98. data/docs/checklist.md +0 -55
  99. data/docs/customization/authorizations.md +0 -5
  100. data/docs/customization/images.md +0 -7
  101. data/docs/customization/javascript.md +0 -9
  102. data/docs/customization/machine_translations.md +0 -30
  103. data/docs/customization/maps.md +0 -610
  104. data/docs/customization/oauth.md +0 -50
  105. data/docs/customization/styles.md +0 -11
  106. data/docs/customization/texts.md +0 -27
  107. data/docs/customization/users_registration_mode.md +0 -17
  108. data/docs/development_guide.md +0 -166
  109. data/docs/getting_started.md +0 -191
  110. data/docs/possible_flows_for_proposal.png +0 -0
  111. data/docs/services/analytics.md +0 -23
  112. data/docs/services/elections_bulletin_board.md +0 -38
  113. data/docs/services/maps.md +0 -362
  114. data/docs/services/social_providers.md +0 -98
@@ -1,31 +1,32 @@
1
- # Activity log
1
+ = Activity log
2
2
 
3
3
  In order to make your component compatible with the activity log, you need to follow these steps:
4
4
 
5
- 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.
6
- 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.
5
+ . 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.
6
+ . 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.
7
7
 
8
8
  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!
9
9
 
10
- ## The default renderer
10
+ == The default renderer
11
11
 
12
12
  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.
13
13
 
14
- ## Customizing the logs for your resources
14
+ == Customizing the logs for your resources
15
15
 
16
- 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:
16
+ 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:
17
17
 
18
- - You want to show what type of resource is affected by the action log
19
- - The default renderer cannot find the correct field to render the resource name
20
- - You want to show more info
21
- - You want to change the order of the factors in the log sentence
22
- - You want to change the format of the values in the diff
18
+ * You want to show what type of resource is affected by the action log
19
+ * The default renderer cannot find the correct field to render the resource name
20
+ * You want to show more info
21
+ * You want to change the order of the factors in the log sentence
22
+ * You want to change the format of the values in the diff
23
23
 
24
24
  Let's go ahead and see how to create your own resource presenter.
25
25
 
26
26
  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:
27
27
 
28
- ```ruby
28
+ [source,ruby]
29
+ ----
29
30
  module Decidim
30
31
  module Accountability
31
32
  module AdminLog
@@ -34,15 +35,16 @@ module Decidim
34
35
  end
35
36
  end
36
37
  end
37
- ```
38
+ ----
38
39
 
39
40
  Some examples with basic customization follow, although you can read the source code docs and overwrite any method you need.
40
41
 
41
- ### Changing the action log sentence
42
+ === Changing the action log sentence
42
43
 
43
44
  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:
44
45
 
45
- ```ruby
46
+ [source,ruby]
47
+ ----
46
48
  module Decidim
47
49
  module Accountability
48
50
  module AdminLog
@@ -61,17 +63,18 @@ module Decidim
61
63
  end
62
64
  end
63
65
  end
64
- ```
66
+ ----
65
67
 
66
68
  This is useful to show the resource type in the sentence.
67
69
 
68
- ### Limiting what fields get presented in the diff
70
+ === Limiting what fields get presented in the diff
69
71
 
70
- 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.
72
+ 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.
71
73
 
72
74
  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:
73
75
 
74
- ```ruby
76
+ [source,ruby]
77
+ ----
75
78
  module Decidim
76
79
  module Accountability
77
80
  module AdminLog
@@ -90,13 +93,14 @@ module Decidim
90
93
  end
91
94
  end
92
95
  end
93
- ```
96
+ ----
94
97
 
95
- #### Value types presenters
98
+ ==== Value types presenters
96
99
 
97
100
  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:
98
101
 
99
- ```ruby
102
+ [source,ruby]
103
+ ----
100
104
  module Decidim
101
105
  module Accountability
102
106
  module AdminLog
@@ -112,11 +116,12 @@ module Decidim
112
116
  end
113
117
  end
114
118
  end
115
- ```
119
+ ----
116
120
 
117
121
  Then you can write your own value presenter as:
118
122
 
119
- ```ruby
123
+ [source,ruby]
124
+ ----
120
125
  module Decidim
121
126
  module Accountability
122
127
  module AdminLog
@@ -131,8 +136,8 @@ module Decidim
131
136
  end
132
137
  end
133
138
  end
134
- ```
139
+ ----
135
140
 
136
- ## Multiple logs
141
+ == Multiple logs
137
142
 
138
143
  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.
@@ -0,0 +1,7 @@
1
+ = Turbolinks
2
+
3
+ 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.
4
+
5
+ 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.
6
+
7
+ 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.
@@ -1,51 +1,55 @@
1
- # View hooks
1
+ = View hooks
2
2
 
3
- ## General description
3
+ == General description
4
4
 
5
5
  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.
6
6
 
7
7
  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:
8
8
 
9
- ```ruby
9
+ [source,ruby]
10
+ ----
10
11
  <% if defined? Decidim::Processes %>
11
12
  <% # iterate through the most important ones %>
12
13
  <% end %>
13
14
  <% if defined? Decidim::Assemblies %>
14
15
  <% # iterate through the most important ones %>
15
16
  <% end %>
16
- ```
17
+ ----
17
18
 
18
19
  This raises two important issues:
19
20
 
20
- 1. We are linking `decidim-core` with `decidim-assemblies` and `decidim-participatory_processes`. This is not perfect.
21
- 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.
21
+ . We are linking `decidim-core` with `decidim-assemblies` and `decidim-participatory_processes`. This is not perfect.
22
+ . 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.
22
23
 
23
- ## Rendering view hooks
24
+ == Rendering view hooks
24
25
 
25
26
  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`:
26
27
 
27
- ```ruby
28
+ [source,ruby]
29
+ ----
28
30
  <%= Decidim.view_hooks.render(:highlighted_elements, deep_dup) %>
29
- ```
31
+ ----
30
32
 
31
33
  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.
32
34
 
33
- ## Registering view hooks
35
+ == Registering view hooks
34
36
 
35
37
  Other engines would register blocks of Ruby and Rails code from their initializers. For example, in `decidim-participatory_processes`:
36
38
 
37
- ```ruby
39
+ [source,ruby]
40
+ ----
38
41
  # decidim-participatory_processes/lib/decidim/participatory_processes/engine.rb
39
42
  initializer "decidim_participatory_processes.view_hooks" do
40
43
  Decidim.view_hooks.register(:highlighted_elements) do |view_context|
41
44
  view_context.render(partial: "my/partial")
42
45
  end
43
46
  end
44
- ```
47
+ ----
45
48
 
46
49
  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:
47
50
 
48
- ```ruby
51
+ [source,ruby]
52
+ ----
49
53
  # decidim-participatory_processes/lib/decidim/participatory_processes/engine.rb
50
54
  initializer "decidim_participatory_processes.view_hooks" do
51
55
  Decidim.view_hooks.register(:highlighted_elements) do |view_context|
@@ -55,11 +59,12 @@ initializer "decidim_participatory_processes.view_hooks" do
55
59
  view_context.render(partial: "decidim/participatory_processes/my/partial", locals: { highlighted_processes: highlighted_processes })
56
60
  end
57
61
  end
58
- ```
62
+ ----
59
63
 
60
64
  We're passing a deep copy of the view context to allow us to extend it without polluting the original view context:
61
65
 
62
- ```ruby
66
+ [source,ruby]
67
+ ----
63
68
  # decidim-proposals/lib/decidim/proposals/engine.rb
64
69
  initializer "decidim_participatory_processes.view_hooks" do
65
70
  Decidim.view_hooks.register(:participatory_space_highlighted_elements) do |view_context|
@@ -68,24 +73,25 @@ initializer "decidim_participatory_processes.view_hooks" do
68
73
  view_context.render(partial: "decidim/participatory_spaces/highlighted_proposals", locals: { })
69
74
  end
70
75
  end
71
- ```
76
+ ----
72
77
 
73
78
  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:
74
79
 
75
- ```ruby
80
+ [source,ruby]
81
+ ----
76
82
  Decidim.view_hooks.register(:highlighted_elements, priority: Decidim::ViewHooks::HIGH_PRIORITY) do |view_context|
77
83
  # ...
78
84
  end
79
- ```
85
+ ----
80
86
 
81
- ## Enabling view hooks in your engine
87
+ == Enabling view hooks in your engine
82
88
 
83
89
  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.
84
90
 
85
- ## The engine I want to extend does not support view hooks, what can I do?
91
+ == The engine I want to extend does not support view hooks, what can I do?
86
92
 
87
- 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.
93
+ 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.
88
94
 
89
- ## View hooks drawbacks and alternatives
95
+ == View hooks drawbacks and alternatives
90
96
 
91
- 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.
97
+ 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.
@@ -0,0 +1,105 @@
1
+ = View Models (a.k.a. Cells)
2
+
3
+ == General description
4
+
5
+ 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.
6
+
7
+ Cells are faster than ActionView. While exposing a better performance, you step-wise encapsulate fragments into cell widgets and enforce interfaces.
8
+
9
+ === View Model
10
+
11
+ 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.
12
+
13
+ == Decidim Cards
14
+
15
+ `card_for @instance` will render the corresponding default card for each component instance.
16
+ If a card for the given resource is not registered, a _basic_ (default) card is shown.
17
+
18
+ To render a specified size/variation include the `size` option as a `symbol`: `card_for @instance, size: :m`
19
+
20
+ === Card M
21
+
22
+ To render a label to identify the type of component renderized add to the `context` the `label` option.
23
+
24
+ The `label` option accepts this arguments:
25
+
26
+ * `false` or `"false"` will not render the label from the locales `t(model.class.model_name.i18n_key, scope: "activerecord.models", count: 1)`
27
+ * `true` or `"true"` will render the translation from
28
+ * `"whathever string"` will render it as String
29
+
30
+ == Introducing a Card Cell to a `component`
31
+
32
+ * add *dependency* to "decidim-*.gemspec"
33
+ +
34
+ [source,rb]
35
+ ----
36
+ s.add_dependency "cells-erb", "~> 0.1.0"
37
+ s.add_dependency "cells-rails", "~> 0.0.9"
38
+ ----
39
+
40
+ * *require* cells in `decidim-<module>/lib/decidim/<module>/engine.rb`
41
+ +
42
+ [source,rb]
43
+ ----
44
+ require "cells/rails"
45
+ require "cells-erb"
46
+
47
+ initializer "decidim_<module>.add_cells_view_paths" do
48
+ Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/cells")
49
+ Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/views") # for partials
50
+ end
51
+ ----
52
+
53
+ * The attribute `card` of the resource is defined in `decidim-core/lib/decidim/resource_manifest.rb`:
54
+ +
55
+ [source,rb]
56
+ ----
57
+ # The cell to use to render the card of a resource.
58
+ attribute :card, String
59
+ ----
60
+ +
61
+ 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:
62
+ +
63
+ [source,rb]
64
+ ----
65
+ component.register_resource(:<my_resource>) do |resource|
66
+ resource.class = "Decidim::<Component>/<MyResource>" # eg. "Decidim::Proposals::ProposalDraft
67
+ resource.card = "decidim/<component>/<my_resource>" # eg. "decidim/proposals/proposal_draft"
68
+ resource.component_manifest = component
69
+ end
70
+ ----
71
+ +
72
+ [source,rb]
73
+ ----
74
+ module Decidim
75
+ module <Component>
76
+ class <MyResource> < Decidim::ApplicationRecord
77
+ include Decidim::Resourceable
78
+ # ...
79
+ end
80
+ end
81
+ end
82
+ ----
83
+
84
+ * The *Cell Class*, following the convention, will reside in `decidim-<component>/app/cells/decidim/<component>/<my_resource>_cell.rb`:
85
+ +
86
+ [source,rb]
87
+ ----
88
+ module Decidim
89
+ module <Component>s
90
+ class <MyResource>Cell < Decidim::ViewModel
91
+ def show
92
+ render # renders decidim-<component>/app/cells/decidim/<component>/<my_resource>
93
+ end
94
+ end
95
+ end
96
+ end
97
+ ----
98
+
99
+ * The *Cell Views* will be in the `decidim-<component>/app/cells/decidim/<component>/<my_resource>` and defaults to `show.erb`
100
+
101
+ == More Info
102
+
103
+ * https://github.com/trailblazer/cells/blob/master/README.md[cells/README.md at master · trailblazer/cells]
104
+ * http://trailblazer.to/gems/cells/[Trailblazer: Cells] / http://trailblazer.to/gems/cells/api.html[Trailblazer: Cells API]
105
+ * https://www.sitepoint.com/introduction-to-cells-a-better-view-layer-for-rails/[Introduction to Cells: A Better View Layer for Rails -- SitePoint]
@@ -0,0 +1,39 @@
1
+ = Checklist
2
+
3
+ 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:
4
+
5
+ == Technological
6
+
7
+ . Choose a *domain or subdomain* for your application. Some typical names involve "Participation" or "Decision" conjugations.
8
+ . 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].
9
+ . Customize the xref:customize:styles.adoc[*look and feel*] (colors, pictures, fonts, etc).
10
+ . Configure *SSL*:
11
+ .. We recommend using at least *https://letsencrypt.org/[Let's Encrypt]* for minimum security.
12
+ .. Configure *redirection from HTTP to HTTPS* on your web server.
13
+ .. Configure your *Certificate Authority Authorization* (CAA) DNS records
14
+ .. Install complete *Certificate Chains* if it's needed for your provider
15
+ .. Use current SSL/TLS Protocols (*TLS 1.2 or 1.3*)
16
+ .. If you add new static files, be careful of not introducing *mixed content*
17
+ .. Use the *https://www.ssllabs.com/ssltest/[SSL Server Test]* and follow their recommendations
18
+ . Configure your *SMTP* server.
19
+ . 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].
20
+ . Setup *backup* on your server. The most important things to save are the `public/uploads` and the database.
21
+ . Decide and implement which kind of *xref:customize:authorizations.adoc[Authorization]* you're going to use.
22
+ . Comply with our License (Affero GPL 3) and *publish your code* to http://github.com[GitHub] or wherever you want.
23
+ . Review your *decidim initializer* on your application (config/initializers/decidim.rb).
24
+ . Configure your xref:services:activejob.adoc[*ActiveJob*] background queue.
25
+ . If you want, configure your xref:services:social_providers.adoc[*social providers*] to enable login using external applications.
26
+ . Check that you don't have any *default users, emails and passwords*, neither on the admin or on the system panel.
27
+ . Configure xref:install:index.adoc#scheduled_tasks[scheduled tasks].
28
+ . 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.
29
+ . 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].
30
+
31
+ == Contents
32
+
33
+ . Ideally you'll have a *Team* formed with experts on IT, Communication, Participation, Design and Law.
34
+ . 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`.
35
+ . Comply with your current *legal requirements*, like to registrate your privacy policy with the autorities (eg LOPD on Spain).
36
+ . Fill the *Participatory Processes Configuration Form* to prepare your Participatory Process for Decidim.
37
+ . Read the *https://decidim.org/docs/[Administration manual]*.
38
+ . Participate on *http://meta.decidim.org[MetaDecidim]*.
39
+ . Read the Decidim *https://decidim.org/contract/[Social Contract]*.
@@ -0,0 +1,148 @@
1
+ = Getting started with Decidim
2
+ :source-highlighter: highlightjs
3
+
4
+ == What is and what isn't Decidim?
5
+
6
+ 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.
7
+
8
+ These libraries are published to Rubygems.org, so you can add Decidim to your Ruby on Rails app as external dependencies.
9
+
10
+ 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.
11
+
12
+ == Creating your Decidim app
13
+
14
+ === A. Recommended: manual installation
15
+
16
+ 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 😅.
17
+
18
+ The flow is: install gem, generate a Ruby on Rails app, enjoy.
19
+
20
+ [source,console]
21
+ ----
22
+ gem install decidim
23
+ decidim decidim_application
24
+ ----
25
+
26
+ 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].
27
+
28
+ === B. Installation script [experimental]
29
+
30
+ 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].
31
+
32
+ [source,console]
33
+ ----
34
+ wget -O install-decidim.sh https://raw.githubusercontent.com/Platoniq/decidim-install/master/script/install-decidim.sh
35
+ chmod +x decidim-install.sh
36
+ ./install-decidim.sh decidim_application
37
+ ----
38
+
39
+ == Initializing your app for local development
40
+
41
+ You should now setup your database:
42
+
43
+ [source,console]
44
+ ----
45
+ bin/rails db:create db:migrate db:seed
46
+ ----
47
+
48
+ This will also create some default data so you can start testing the app:
49
+
50
+ .Default seed's users
51
+ |===
52
+ |Type |Email |Password| URL |Description
53
+
54
+ |Decidim::System::Admin
55
+ |system@example.org
56
+ |decidim123456
57
+ |/system
58
+ |Administrator for the multitenant
59
+
60
+ |Decidim::User
61
+ |admin@example.org
62
+ |decidim123456
63
+ |/admin
64
+ |Administrator for the organization
65
+
66
+ |Decidim::User
67
+ |user@example.org
68
+ |decidim123456
69
+ |/user/sign_in
70
+ |User for the organization
71
+
72
+ |===
73
+
74
+ 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.
75
+
76
+ If you want to verify yourself against the default authorization handler use a document number ended with "X".
77
+
78
+ You can now start your server!
79
+
80
+ [source,console]
81
+ ----
82
+ bin/rails s
83
+ ----
84
+
85
+ Visit http://localhost:3000 to see your app running.
86
+
87
+ == Configuration & setup
88
+
89
+ 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.
90
+
91
+ === Scheduled tasks
92
+
93
+ 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.
94
+
95
+ You can configure it with `crontab -e`, for instance if you've created your Decidim application on /home/user/decidim_application:
96
+
97
+ [source,console]
98
+ ----
99
+ # Remove expired data portability files
100
+ 0 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:delete_data_portability_files
101
+
102
+ # Compute metrics
103
+ 1 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:metrics:all
104
+
105
+ # Compute open data
106
+ 2 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:open_data:export
107
+
108
+ # Delete old registrations forms
109
+ 3 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim_meetings:clean_registration_forms
110
+ ----
111
+
112
+ === Further configuration
113
+
114
+ We also have other guides on how to configure some extra components:
115
+
116
+ * xref:services:activejob.adoc[ActiveJob]: For background jobs (like sending emails).
117
+ * xref:services:geocoding.adoc[Geocoding]: How to enable geocoding for proposals and meetings.
118
+ * xref:services:social_providers.adoc[Social providers integration]: Enable sign up from social networks.
119
+
120
+ == Deploy
121
+
122
+ 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:
123
+
124
+ [source,ruby]
125
+ ----
126
+ email = <your email>
127
+ password = <a secure password>
128
+ user = Decidim::System::Admin.new(email: email, password: password, password_confirmation: password)
129
+ user.save!
130
+ ----
131
+
132
+ 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.
133
+
134
+ Then, visit the `/system` dashboard and login with the email and passwords you just entered and create your organization. You're done! :tada:
135
+
136
+ 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.
137
+
138
+ == Checklist
139
+
140
+ There are several things you need to check before making your putting your application on production. See the xref:install:checklist.adoc[checklist].
141
+
142
+ == Contributing
143
+
144
+ 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.
145
+
146
+ 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.
147
+
148
+ Finally, you can also find other ways of helping us on our xref:contribute:index.adoc[contribution guide].