Creating Decidim v0.24 modules from scratch

Decidim is a very powerful and flexible platform for participatory purposes that can be adapted to many contexts simply configuring its participatory spaces and components.

Even so, and more often than not, organizations need extra features to tailor the software to their needs. When this happens, there are mainly two options for the developers.

1. If the feature is something that Decidim lacks and may be wanted by the whole community, a proposal at meta.decidim.org must done, and on acceptance a PR to the base code will be eventually merged and available in the next release.
2. If the feaure is something specific to the organization, or it is no widely accepted by the community, Decidim still offers the possibility to plug modules in.

This post will tackle this second case, when the developers need to implement a new module.

Using Decidim generators

The decidim-generators module has the Rails generators and corresponding templates to generate a new Decidim application, or a new Decidim component. If what is needed is a new component, the --component option is doing what exactly is required, creating an empty component. But sometimes the need is to extend or override existing features (in components or in participatory spaces or in other places). In this case the same generator can be used to create an empty module.

To invoke the generator:

decidim --component module-name --external

The --external flag tells the generator that the new module will be created outside the decidim/decidim codebase, this way the generator uses the correct paths inside the new module.

Now the module is created.

The module-name.gemspec is the first thing to review. You will review the author if it was not correctly taken from the environment, the title and description, and the module's dependencies. Usually the dependencies needed, in addition of the default decidim-core gem, are the following development dependencies: decidim and decidim-dev. If your module is hacking some specific Decidim module, add also this module as a dependency. In the following example we add, at the bottom of the gemspec file, the dependencies for a module that hacks decidim-proposals and decidim-budgets:

DECIDIM_VER = '>= 0.23'
s.add_dependency 'decidim-core', DECIDIM_VER
s.add_dependency 'decidim-proposals', DECIDIM_VER
s.add_dependency 'decidim-budgets', DECIDIM_VER
s.add_development_dependency 'decidim', DECIDIM_VER
s.add_development_dependency 'decidim-dev', DECIDIM_VER

As we don't want a new component, then the files in "lib/decidim/module-name/*.rb", except version.rb and engine.rb can removed as needed. Don't do this if you are building a component.

Now, bundle install will confirm that all the dependecies are correct.

Pushing the new Decidim module to Github

To be able to work with other team mates, to have a nice history of changes, to share it with he community and for many other reasons the module should be published to a source control management system, normally git, and usually the repository will be hosted at Github. So the examples below take this assumption.

In the Github account that will host the repository click the "New" button in the Repositories tab.

• Fill the "reposiory name" for the module, for example "decidim-verify_wo_registration" (the convention is to start all the modules with the prefix "decidim-").
• Copy the summary in the gemspec file to the description field.
• Make sure you check the repository as Public
• No need to check the "Initialize this repository with a README" because the generator has already created this file for us.
• No need to use "Add .gitignore" as the module should already have it
• Choose the license of your choice if the default GPL3 don't suite your needs (MIT for example is also compatible with Decidim) (you will have to change the steps to add the remote to your module)
• Finally click "Create the repository"

After this you will have an emtpy, or nearly empty, repository in Gihub. To add this remote to your module's codebase that is in your computer, go to the corresponding directory and:

# Initialize a git repository structure
git init
# Add the remote to Github's repository (copy the url in Github's "Clone or download" dropdown)
git remote add origin ssh://git@github.com:CodiTramuntana/decidim-verify_wo_registration.git
git pull origin master
# Add Gemfile.lock to .gitignore
vim .gitignore
# Perform the initial commit
rm Gemfile.lock (libraries should not add restrictions on the exact version of their dependencies to their hosting application)
git add -A
git commit -a -m "Initial commit"
# Push the state of the reposiory in Github
git push

Before start coding, a decidim test_app must be created to be able to execute the created rspec tests. Luckily there's also a generator 

bin/rails decidim:generate_external_test_app --trace