Decidim::ExtraUserFields

This module allows administrators to define a set of extra fields for users. The fields are configurable in the admin panel of the organization. When enabled, they are shown in the user profile and in the registration form.

Supported extra fields for users:

• Country
• Date of birth
• Gender
• Location
• Phone number
• Postal code

This module also enables an Export action in the participants admin panel, which allows to download a list of participants in CSV, JSON or Excel.

Installation

Add this line to your application's Gemfile:

gem 'decidim-extra_user_fields', github: 'openpoke/decidim-module-extra_user_fields'

or for the original one:

gem 'decidim-extra_user_fields', github: 'PopulateTools/decidim-module-extra_user_fields'

And then execute:

bundle
bin/rails decidim:upgrade
bin/rails db:migrate

EXPERTS ONLY

Under the hood, when running bundle exec rails decidim:upgrade the decidim-extra_user_fields gem will run the following (that can also be run manually if you consider):

bin/rails decidim_extra_user_fields:install:migrations

You can also the version of the gem that matches your Decidim version:

gem "decidim-extra_user_fields", github: "PopulateTools/decidim-module-extra_user_fields", branch: "release/0.28-stable"
gem "decidim-extra_user_fields", github: "PopulateTools/decidim-module-extra_user_fields", branch: "release/0.27-stable"
gem "decidim-extra_user_fields", github: "PopulateTools/decidim-module-extra_user_fields", branch: "release/0.26-stable"
gem "decidim-extra_user_fields", github: "PopulateTools/decidim-module-extra_user_fields", branch: "release/0.25-stable"
gem "decidim-extra_user_fields", github: "PopulateTools/decidim-module-extra_user_fields", branch: "release/0.24-stable"

Usage

Admin setup

After installing the gem and migrating the database, you can enable the extra fields in the admin panel of the organization. Go to Settings > Manage extra user fields. There you can enable the fields you want to use. By default all fields are required and don't include any format validation.

Most of the fields are plain text inputs, but other have a special format:

• Date of birth displays a date picker
• Country displays a country list dropdown

User signup and profile

Once the fields are enabled, they will be shown in the user signup form and in the user profile.

Admin users export

An extra feature of this plugin is to enable an Export action in the participants admin panel. This action allows to download a list of participants in CSV, JSON or Excel. The fields included in the export are the Decidim User attributes plus the extra fields enabled in the admin panel.

Configuration

By default, the module is configured to read the configuration from ENV variables.

Currently, the following ENV variables are supported:

ENV variable	Description	Default value
EXTRA_USER_FIELDS_UNDERAGE_LIMIT	The minimum age limit to consider a user as underage. This is used to determine if the user falls into the underage category.	18
EXTRA_USER_FIELDS_UNDERAGE_OPTIONS	Options for selecting the age for when someone is considered "underage".	15 16 17 18 19 20 21
EXTRA_USER_FIELDS_GENDERS	Options for the gender field (you need to add the corresponding I18n keys, ie: decidim.extra_user_fields.genders.prefer_not_to_say )	female male other prefer_not_to_say
EXTRA_USER_FIELDS_AGE_RANGES	Options for the age range field (you need to add the corresponding I18n keys, e.g., decidim.extra_user_fields.age_ranges.up_to_16)	up_to_16 17_to_30 31_to_60 61_or_more prefer_not_to_say

Configuration through an initializer

It is also possible to configure the module using the an initializer:

Create an initializer (for instance config/initializers/extra_user_fields.rb) and configure the following:

# config/initializers/extra_user_fields.rb

Decidim::ExtraUserFields.configure do |config|
  config.genders = [:female, :male, :other, :prefer_not_to_say]
  config.age_ranges = ["30_or_younger", "31_or_older", "prefer_not_to_say"]
  
  ...
end

Contributing

This module follows the regular git workflow:

• Fork the project from master branch
• Create a feature branch
• Commit your changes
• Open a pull request
• Wait for a review and check that the CI is green

We'll merge the PR ASAP and release a new version of the gem.

Adding a new field to the module

You can find the development guidelines for adding a new field in this module in the docs/create_new_field.md file.

Contribute to Decidim

See Decidim.

Roadmap

Some of the features we would like to add to this module:

• custom validations for the fields
• enable/disable the mandatory flag for each field
• find a way to add the fields to the user export without having to modify this module

License

This engine is distributed under the GNU AFFERO GENERAL PUBLIC LICENSE.