Views (HTML)

As usual you should make some tests with the changes that you made and configure a Continuous Integration environment for checking that your overrides does not get removed with new decidim versions.

Overrides

To find what you need to change you will need to make some detective work to find out which partial or view do you need to change. You can do so by:

  • looking at your application log and finding the lines that start with "Rendered"

  • inspecting with the web development tools of your browser, copying a special class and using grep, github search or your IDE search by multiple files to find out on which file this exists.

Filename method

If you want to override a view or partial given by Decidim you can do this just by naming it with the same filename that you already have. On more details, if you want to change the social media icons on the footer, you can do so by looking at which file you need to change, copying that file to your application with the same filename and directory structure, and making your local changes.

As an example, if I want to change the footer, you’d need to search for the file (on this case, it is on decidim-core/app/views/layouts/decidim/footer/_mini.html.erb), and copy that file to your own application on app/views/layouts/decidim/footer/_mini.html.erb).

Deface method

You will need the deface gem installed on your application, and follow their instructions on how to use the different overriding methods that they support.

As an example, if you want to change the footer, you can do so by creating the file app/overrides/layouts/decidim/_main_footer/pre_footer.html.erb.deface with these contents:

<!-- insert_before ".main-footer" -->
hello world

View Models (a.k.a. Cells)

Decidim uses the View Models (a.k.a. Cells) to define parts of the user interface. Cells allow you to reduce complexity within the controllers and helpers, to separate relevant functionality only related to a specific part of a UI into its own encapsulated entity.

Cells consists of two parts:

  1. The cell class which controls the rendering logic and can define helper methods for the views

  2. The view written in ERB as you are used to when writing normal Rails views

If you want to customize any cells within your application, you can use the "filename method" described above to find the relevant cell in charge of rendering the content you want to modify and copying this file to the exact same path within your own app folder as where you found the view.

If you want to customize the cell class logic, you can either copy that file to the same path where you found it and customize it there or implement concerns to keep better track of what you have changed in different parts of Decidim. See the Logic customization guide to learn more about this approach.

If you want to customize cells within your modules, you need to add the following initializer to your module’s engine to make them aware of the potential lookup path:

module Decidim
  module YourModule
    class Engine < ::Rails::Engine
      initializer "decidim_your_module.add_cells_view_paths" do
        Cell::ViewModel.view_paths << File.expand_path("#{Decidim::YourModule::Engine.root}/app/cells")
      end
    end
  end
end

New pages

If you want to add a new HTML page, you can do this by working as a regular Rails application (ie, you can scaffold a new view and work with the HTML as usual).

As an example of how to do this on Decidim Barcelona application, there is the StaticController (main accountability section pages). You should inherit your controller from Decidim::ApplicationController.