decidim 0.24.0 → 0.25.0.rc1

data/docs/modules/customize/pages/code.adoc

@@ -12,7 +12,10 @@ Most of the time, you should work with the generated application. That applicati
 decidim DecidimBarcelona
 ----
 
-If you want to override/change anything (for instance the homepage), you can just do it with the same name of the file, through Monkey Patching.
+If you want to override/change anything, you can just do it with the same name of the file, through Monkey Patching. Some real world examples of this method:
+
+* https://github.com/gencat/participa/blob/master/app/decorators/decidim/admin/selective_newsletter_form_decorator.rb[Decidim::Admin::SelectiveNewsletterForm]. As it's a decorator you also need to make it available in the https://github.com/gencat/participa/blob/3416992ae095f6ab1e826fee961253514c4ff0ef/config/application.rb#L48[application config]
+* https://github.com/barcelonaregional/decidim-premet25/blob/master/config/initializers/etiquette_validator.rb[EtiquetteValidator.class_eval]
 
 If you want to extend Decidim, the prefered way should be by having a Module. This is a Ruby on Rails Engine which provides ruby code (models, views, controllers, assets, etc). You can use it through multiple ways:
 

data/docs/modules/customize/pages/images.adoc

@@ -2,6 +2,6 @@
 
 You can change most of the images (for instance the logo, main banner on homepage, contents of participatory processes, etc) through the Administration panel.
 
-If you want to override the standard images given by Decidim (for instance the initial image for user's avatars) you can do it by naming it the same way as the original image, in this case it should be `app/assets/images/decidim/default-avatar.svg`
+As Decidim uses Webpacker, there's no way to override existing images including in Decidim.
 
-If you want to add a new image you can do it as any Rails application, leaving it on your image's asset folder and using image_tag helper. You can see more documentation on http://guides.rubyonrails.org/asset_pipeline.html[Rails guide].
+If you want to add a new image you can do it as any Rails application, leaving it on your image's asset folder (`app/packs/images`) and using image_pack_tag helper (or asset_pack_path). You can see more documentation on http://guides.rubyonrails.org/webpacker.html[Rails guide].

data/docs/modules/customize/pages/javascript.adoc

@@ -2,9 +2,11 @@
 
 You can add Javascript code by multiple ways in Decidim:
 
-== Asset pipeline
+== Webpacker
 
-Just add it to `app/assets/javascripts/application.js`. For example to create a new alert just add:
+Decidim uses Webpack (via Webpacker) to compile assets, including javascript.
+
+During the generation of a decidim app, the file `app/packs/src/decidim/decidim_application.js` is created and hooked to Decidim packs, so any javascript written there is compiled within Decidim assets. For example to create a new alert just add:
 
 [source,javascript]
 ----
@@ -13,7 +15,10 @@ $(function(){
 });
 ----
 
-More information in https://guides.rubyonrails.org/asset_pipeline.html[Rails Asset Pipeline documentation].
+More information in https://guides.rubyonrails.org/webpacker.html[Rails Webpacker documentation].
+
+If you want to replace a whole file existin in Decidim you can do it by creating a file in your application with the same name and the same path. I.e: to replace `decidim-core/app/packs/src/decidim/editor.js` you should create in your Rails app a file in
+  `app/packs/src/decidim/editor.js` and it will have more priority over the Decidim file.
 
 == Head extra file
 

data/docs/modules/customize/pages/menu.adoc

@@ -19,6 +19,62 @@ Depending in the kind of space and module, then you can see or not some of the s
 - For conferences, you need to enable the module and it appears when there's some published content by an administrator.
 - For initiatives, you need to enable the module. Every participant can see it, as anyone can create one. That's because is a bottom-up kind of mechanism.
 
+Starting with 0.25.dev, Decidim Menu Api has been modified, in order to improve developer and administrators experience.
+The changes on the menu has deprecated the previous `menu.item` call, in favour of `menu.add_item` that has the following structure:
+[source,ruby]
+....
+menu.add_item :identifier, # String or symbol to uniquely define the menu
+              link_caption,
+              link_path or url
+              options: {
+                position: # Optional,
+                if: # Optional,
+                active: # Optional,
+                icon_name: # Optional ,
+                submenu: # Optional,
+              }
+....
+
+
+Additionally, the new menu api will allow to interact with the menu in several ways:
+[source,ruby]
+....
+Decidim.menu :user_menu do |menu|
+  menu.remove_item :identifier
+  menu.move :identifier, after: :anchor_identifier
+  menu.move :identifier, before: :anchor_identifier
+end
+....
+
+
+== Example usage:
+Starting from a default menu like:
+
+image::original_user_menu.png[Decidim Menu]
+
+After applying the below initializer, the menu rendering will be modified to:
+[source,ruby]
+....
+# config/initializers/decidim.user_menu.rb
+
+Decidim.menu :user_menu do |menu|
+  menu.remove_item :user_interests
+  menu.move :own_user_groups, after: :account
+  menu.move :authorizations, before: :notifications_settings
+end
+....
+
+image::modified_user_menu.png[Decidim Menu]
+
+== The menu Structure
+Decidim uses internally a number of menus that are being used in various admin sections.
+Those menus are being defined inside the engine or admin_engine file of a decidim module.
+The menus are being defined as `Decidim.menu :identifier`. In order to render those menus, there are a number of methods that can be used:
+
+- main_menu in admin section
+- sidebar_menu will render the secondary admin section
+- simple_menu will render any submenus
+
 There's also a https://github.com/OpenSourcePolitics/decidim-module-navbar_links[NavBar links module] made by the community that you can use to add your custom links.
 
 Finally if you want to dive in the code that handles this, a good starting point is the https://rubydoc.info/github/decidim/decidim/develop/Decidim/Menu[Menu API].

data/docs/modules/customize/pages/styles.adoc

@@ -50,11 +50,14 @@ image::header-snippet.png[Header snippet]
 
 Notice that you can resize this textarea.
 
-== Asset pipeline
+== Webpacker
 
-You can go to app/assets/stylesheets/application.css.sass on your generated applications. There you can override any class using CSS with SASS.
+Decidim uses Webpacker to compile assets. There are two ways to customize CSS:
 
-In https://github.com/decidim/decidim/blob/develop/decidim-core/app/assets/stylesheets/decidim/_variables.scss[decidim-core/app/assets/stylesheets/decidim/_variables.scss] you can find the `variables` that can be overriden in your `sass`.
+1. if you want to redefine just CSS vars or Foundation settings, use _decidim-settings.scss
+2. if you want to redefine a specific snippet of CSS (let's say a few classes but not a whole file) you can use decidim_application.scss
+3. and of course you can overwrite whole files by copying them into the application i.e: to replace `decidim-core/app/packs/stylesheets/modules/_cookie-bar.scss` you should create in your Rails app a file in
+  `app/packs/stylesheets/modules/_cookie-bar.scss` and it will have more priority over the Decidim file.
 
 We use http://sass-lang.com/guide[SASS, with SCSS syntax] as CSS preprocessor.
 

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

@@ -135,3 +135,33 @@ This sections explains how to add dummy content to a development application.
 
 * 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.
+
+== Assets
+
+In order to attach the new component assets to Webpacker configuration, you need to follow a few steps. We are considering two scenarios:
+
+- while the component is being developed, where changes in Webpacker configuration should be done in the development for simplicity
+- once the component has been completed, change the Webpacker templates for the app generators
+
+In both cases, changes are the same:
+
+1. Add the new component `app/packs` folder to webpacker.yml
+2. Add the new entrypoints of the component to `config/webpack/custom.js`
+
+=== Updating the development application
+
+While the component is being developed, it'll be simpler and faster to update Webpacker configuration inside the development app. The new component `app/packs` folder needs to be added to the list of paths that Webpack will use to look for assets.
+
+Also, components might have one or many entrypoints (for CSSs and javascripts) and images. These entrypoints need to be manually added to `config/webpack/custom.js`. **Any change in both files** requires to restart `webpack-dev-server` process.
+
+Take into account that generating a new development application **overwrites** Webpacker configuration so these changes might be overwriten. That's why it's necessary, once the changes are stable enough, to update the generators files.
+
+=== Updating Webpacker configuration for the generators
+
+Decidim webpacker configuration lives in `decidim-core/lib/decidim/webpacker`. Any change performed in the development app should be replicated in these files.
+
+Also, any npm package added to package.json should be replicated in Decidim package.json file.
+
+=== Updating the design app
+
+These changes should also be translated to the design app `config/webpacker.yml` and `config/webpack/custom.js` files. And if there are changes in the npm packages, these should be moved to.

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

@@ -0,0 +1,175 @@
+= Migrate to Webpacker an instance app
+
+In order to migrate an existing Decidim app to Webpacker, there are a few changes your need to run in your code.
+
+Disclaimer: this recipe might not work for all the cases, it tries to cover the generic scenarios. If you find yourself with a complex scenario and want to improve this guide feel free to open a PR to complete the guide.
+
+== About Webpacker
+
+It's recommended to understand how Webpacker works. More information:
+
+* https://github.com/rails/webpacker#usage
+* https://edgeguides.rubyonrails.org/webpacker.html
+
+== Requirements
+
+Before starting the migration, please check you have the following dependencies installed:
+
+- Node.js version 15.14.0 (this version is mandatory)
+- Npm version 7.7.0 (it works with other versions, but this is the recommended)
+
+== Add Webpacker to the application
+
+Follow the steps described https://github.com/rails/webpacker#installation[here]
+
+- Install it
+
+[source,console]
+----
+bundle exec rails webpacker:install
+----
+
+* Install Decidim webpacker custom code
+
+[source,console]
+----
+bundle exec rails decidim:webpacker:install
+----
+
+This task do a few steps to allow the Rails instance to have a webpacker instance sharing the code between itself and Decidim gem.
+
+This task is automatically performed every time decidim is updated, to get the latest Webpack configuration. This happens when you run the `decidim:upgrade` task.
+
+== Copy Decidim custom CSS and Javascript
+
+`webpacker:install` task should have created to you the following dirs structure:
+
+[source,console]
+----
+app/packs:
+  ├── entrypoints
+  └── src
+  └── stylesheets
+  └── images
+----
+
+If it's not the case you must create it. Then, copy Decidim customizable assets
+
+* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.js[decidim_application.js] to `app/packs/src/decidim/decidim_application.js`
+* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.scss[decidim_application.scss] to `app/packs/stylesheets/decidim/decidim_application.scss`
+* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/_decidim-settings.scss[_decidim-settings.scss] to `app/packs/stylesheets/decidim/_decidim-settings.scss`
+
+These files are hooked into Decidim packs (specifically into decidim-core pack) and will be automatically included inside that pack when compiled.
+
+== Migrate images
+
+Copy the existing images from `app/assets/images` to `app/packs/images`. Images will be available at `/media/images/image.png`
+
+== Migrate stylesheets
+
+Existing stylesheets should be moved from `app/assets/stylesheets` to `app/packs/stylesheets` and imported with `@import` into `decidim_application.scss`. Take into account that you might need to adjust a bit the paths of the `@import` to adjust them to the new locations.
+
+If that CSS file is replacing a Decidim file, there's no need to add it to `decidim_application.scss`.
+
+If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
+
+== Migrate javascripts
+
+Existing javascripts should be moved from `app/assets/javascsripts` to `app/packs/src` and imported with `import` into `decidim_application.js`. Take into account that you might need to adjust a bit the paths of the `import` to adjust them to the new locations.
+
+If that JS file is replacing a Decidim file, there's no need to add it to `decidim_application.js`
+
+== Update Rails helpers
+
+`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`.
+
+For images, if they are in `app/packs/images` you could use `image_pack_tag`.
+
+== Migrate vendorized files and gems
+
+Sometimes assets are included in `vendor/assets/` folder or imported from gems. For each specific one you should check:
+
+1. if the asset is a javascript that is available as npm package the recommendation is to add it to package.json with `npm install`. If it's not available you might want to copy it to `app/packs/src` and import it.
+2. if the asset is a stylesheet it should be copied to `app/packs/stylesheets` and imported with `@import...` from `_decidim-settings.scss`. Alternatively you can use the optional asset includes as described below to include these in the Decidim main SCSS files.
+
+== Optional asset includes
+
+Decidim Webpacker provides a new configuration convention that allows you to add extra configurations for webpacker using a configuration file named `config/assets.rb`. Within this file, you have the following API methods available:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+# Define the base path of your module. Please note that `Rails.root` may not be
+# used because we are not inside the Rails environment when this file is loaded.
+base_path = File.expand_path("..", __dir__)
+
+# If you want to import some extra SCSS files in the Decidim main SCSS file
+# without adding any extra stylesheet inclusion tags, you can use the following
+# method to register the stylesheet import for the main application. This would
+# include an SCSS file at `app/packs/stylesheets/your_app_extensions.scss` into
+# the Decidim's main SCSS file.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_extensions")
+
+# If you want to do the same but include the SCSS file for the admin panel's
+# main SCSS file, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_admin_extensions", group: :admin)
+----
+
+== Remove Sprockets references
+
+The completely remove Sprockets references from your application:
+
+* Review your Gemfile and remove any reference to `sprockets` and `sassc-rails`
+* Remove `config/initializers/assets.rb`
+* Remove `app/assets` folder
+* In `config/application.rb` replace:
+
+[source,ruby]
+----
+require 'rails/all'
+----
+
+with:
+
+[source,ruby]
+----
+require "decidim/rails"
+# Add the frameworks used by your app that are not loaded by Decidim.
+# require "action_cable/engine"
+# require "action_mailbox/engine"
+# require "action_text/engine"
+----
+
+* In `config/environments/*.rb` remove any line containing `config.assets.*` (i.e `config.assets.debug = true`)
+
+== Deployment
+
+The deployment needs to be updated to manually run `npm install` before assets are precompiled.
+
+In the case of Capistrano this can be done with a before hook:
+
+[source,ruby]
+----
+namespace :deploy do
+  desc "Decidim webpacker configuration"
+  task :decidim_webpacker_install do
+    on roles(:all) do
+      within release_path do
+        with rails_env: fetch(:rails_env) do
+          execute "npm ci"
+        end
+      end
+    end
+  end
+
+  before "deploy:assets:precompile", "deploy:decidim_webpacker_install"
+end
+----
+
+Also, in the case of Capistrano it's interesting to add to the shared_paths the following folders:
+
+* `tmp/webpacker-cache`
+* `node_modules`
+* `public/decidim-packs`

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

@@ -0,0 +1,121 @@
+= Migrate to Webpacker a Decidim module
+
+Decidim modules are included to Decidim apps as gems. Since the introduction of Webpacker to manage and compile assets in Decidim, there are some changes required to make modules compatible with Decidim
+
+== About Webpacker
+
+It's recommended to understand how Webpacker works. More information:
+
+* https://github.com/rails/webpacker#usage
+* https://edgeguides.rubyonrails.org/webpacker.html
+
+== Overview
+
+The recommended way to import assets from a gem in a Rails app using Webpacker is to publish a package in npmjs.org and include it in the package.json via `npm install`. Then the assets are available to Webpack via node_modules/ folder
+
+Once created, you should update the instructions to install the module and add the step to add the assets with npm.
+
+== Folder migration
+
+It's recommend to migrate to the new folders structure:
+
+```
+app/packs:
+  ├── entrypoints
+  └── src
+  └── stylesheets
+  └── images
+```
+
+== Update Rails helpers
+
+`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`
+
+For images, if they are in `app/packs/images` you could use `image_pack_tag`.
+
+== Asset compilation
+
+As all assets are now compiled using Webpacker without ever loading the Rails or Decidim environment, there are some new conventions how to tell Webpacker about the Decidim module's assets.
+
+To begin with, create a new file named `config/assets.rb` inside your Decidim module.
+
+After this, add the following contents in that file, depending what kind of assets your module provides:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+# Define the base path of your module. Please note that `Rails.root` may not be
+# used because we are not inside the Rails environment when this file is loaded.
+base_path = File.expand_path("..", __dir__)
+
+# Register an additional load path for webpack. All the assets within these
+# directories will be available for inclusion within the Decidim assets. For
+# example, if you have `app/packs/src/decidim/foo.js`, you can include that file
+# in your JavaScript entrypoints (or other JavaScript files within Decidim)
+# using `import "src/decidim/foo"` after you have registered the additional path
+# as follows.
+Decidim::Webpacker.register_path("#{base_path}/app/packs")
+
+# Register the entrypoints for your module. These entrypoints can be included
+# within your application using `javascript_pack_tag` and if you include any
+# SCSS files within the entrypoints, they become available for inclusion using
+# `stylesheet_pack_tag`.
+Decidim::Webpacker.register_entrypoints(
+  decidim_foo: "#{base_path}/app/packs/entrypoints/decidim_foo.js",
+  decidim_foo_admin: "#{base_path}/app/packs/entrypoints/decidim_foo_admin.js"
+)
+
+# If you want to import some extra SCSS files in the Decidim main SCSS file
+# without adding any extra stylesheet inclusion tags, you can use the following
+# method to register the stylesheet import for the main application.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/app")
+
+# If you want to do the same but include the SCSS file for the admin panel's
+# main SCSS file, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/admin", group: :admin)
+
+# If you want to override some SCSS variables/settings for Foundation from the
+# module, you can add the following registered import.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/settings", type: :settings)
+
+# If you want to do the same but override the SCSS variables of the admin
+# panel's styles, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/admin_settings", type: :settings, group: :admin)
+----
+
+== Component stylesheet migration
+
+In older Decidim versions your components could define their own stylesheet as follows:
+
+[source,ruby]
+----
+Decidim.register_component(:your_component) do |component|
+  component.engine = Decidim::YourComponent::Engine
+  component.stylesheet = "decidim/your_component/your_component"
+  component.admin_stylesheet = "decidim/your_component/your_component_admin"
+end
+----
+
+These were automatically included in the main application's stylesheet file and also in the admin panel's stylesheet file. These no longer work with Webpacker as the Decidim environment is not loaded when Webpacker compiles the assets.
+
+What you should do instead is to follow the asset compilation migration guide above and migrate these definitions into your module's `config/assets.rb` file as follows:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+base_path = File.expand_path("..", __dir__)
+
+# Register the additonal path for Webpacker in order to make the module's
+# stylesheets available for inclusion.
+Decidim::Webpacker.register_path("#{base_path}/app/packs")
+
+# Register the main application's stylesheet include statement:
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component")
+
+# Register the admin panel's stylesheet include statement:
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component_admin", group: :admin)
+----