Chapter 4: Modules
Once you've successfully installed Backdrop, you'll be shown a screen with a dummy first post. If you’re using Backdrop for a project where you could otherwise use WordPress, you can go ahead and start creating content. If you’re using Backdrop to create structured data models that are tailored to your research materials, you’ll need to create custom content types, which may require installing additional modules. If you want to create a website that initially provides information about your project, you can immediately set about creating pages and/or posts (as you would with WordPress), and work on creating a more robust data model to present your actual project content over time.
Unlike its predecessor, Drupal, Backdrop is much less reliant on modules to provide basic functionality like an administrative toolbar, URL aliases, and a WYSIWYG (what-you-see-is-what-you-get) editor, which provides a Microsoft Word-like interface for adding texts. Nonetheless, the more niche your needs are within the landscape of nonprofits, small businesses, and community organizations, the more likely it is that you’ll install modules to get the functionality you need when creating your content types, the highly-customizable templates for storing your data, as discussed in chapters 5-7.
Sections 4.1 and 4.2 cover how to look for modules that fit your project’s needs, and how to evaluate whether the modules you find are sufficiently reliable to incorporate into your project. These are important considerations as you develop your own site. Subsequent chapters, which discuss in depth how to build the example site, recommend specific modules; the Backdrop for Humanists site also includes a list of recommended modules for different purposes. Keep in mind, however, that there are many modules beyond those listed in this book that can be helpful for your project.
Backdrop includes an interface for searching for modules, at /admin/modules/install. You can enter keywords and see a list of results. Clicking on one of the results will pull up a shortened version of the module’s profile page, along with a link to the full profile on backdropcms.org.
A visit to the backdropcms.org Modules page will show that there are over 350 modules that you could download and install. This book will cover many modules relevant to digital humanities projects, but if you encounter a situation not addressed in this book, it might be easiest to use a general-purpose search engine to find modules. Because the user community for Drupal, Backdrop’s predecessor, is bigger and has a longer history, you can run a Google search along the lines of Drupal module tag cloud. Once you have found a couple Drupal modules that do what you’re looking for, you can search on the Backdrop modules page for a module of the same name. While some modules are written for Backdrop from scratch, more commonly they’re adapted from existing Drupal modules, and keep the same name.
Adding a module to your site can be a serious commitment. If you use a module that provides a type of field, the sustainability of the data that you store in the corresponding field is going to depend on the module maintainers. Bugs in the module, or in future updates to the module, may lead to data loss. Also, if a module for a field doesn’t provide integration with Views (for displaying the data) and/or Feeds (for importing data in bulk), but the developers promise that integration will be available soon, your project development may have to be put on hold until that integration is ready -- and it may never materialize.
Modules which provide additional display options for Views (for data entry, export or visualizations like maps and slideshows) or data-entry widgets for fields may seem less important than modules that provide field types. If you have to uninstall such a module, you wouldn’t lose any data. What you might lose, however, is a good deal of time spent training project assistants in how to do data entry. You would have to figure out an alternative approach to accomplishing the tasks that those modules were supporting, which may not be easily done. You would also have to rewrite your site documentation.
These worst-case scenarios should not deter you from installing modules; most Backdrop sites have some modules, and specialized sites like digital humanities projects usually have many modules. These scenarios do, however, highlight the importance of conducting some assessment of modules, as described below, before you install them, and certainly before you come to depend on them.
Even as a non-programmer, you shouldn’t see Backdrop as software that gets written somewhere else, where you have to live with the consequences of whatever changes are, or aren’t, made. Backdrop is an open source project, and most module developers are people who volunteer to work on the platform in their spare time. If progress isn’t being made on an issue as fast as you would like, you can often get in touch with the developer to inquire about it. Maybe the developer would be interested in working with someone at your university as a co-maintainer, or perhaps you can write the developer into your next grant proposal to fund some of the work you need done. See section 20.10 for more on getting involved with the Backdrop community.
As a general rule, you should only install modules that you have downloaded from backdropcms.org. The Backdrop community is relatively small, and very welcoming of newcomers, including those with less-technical backgrounds. While there are Backdrop coding standards, they are recommendations rather than requirements: even some popular modules do not meet the coding standards. Modules available by backdropcms.org must be free of identified security holes (which could put your site in jeopardy of being hacked); if a module is found to contain a security hole, the Backdrop Security Team will work with a module maintainer to help fix the issue, if they’re unable to resolve it themselves.
With open source software like Backdrop, the number of users of a module is an important metric. If many sites have a module installed, that indicates that the module basically does what it claims to do. If a module has a relatively large user base, more people are keeping an eye on the module and odds are better that bugs will be reported in a timely manner. Some of those users may themselves be Backdrop developers, and might volunteer to fix bugs as they arise, if the original module developer can’t keep up with the bug reports. If a Backdrop core update has implications for a module, those with a lot of users are more likely to be updated in a timely manner.
The number of sites that report using a module is listed in the right sidebar of the module page. The number of downloads includes downloads made for Backdrop sites that are running on people’s own computers; the number of active installs refers to Backdrop sites that are live online.
How many users counts as “many” varies by module. As of January 2019, the modules that are most frequently used -- because they address a widespread need -- are installed on nearly 200 sites (e.g. Backup and Migrate). Other modules, such as Views Calc (which enables you to write calculations using data stored in your site) address a very specific need, and may be fully usable and well-supported despite only having a small handful of users. Since many Backdrop modules are adapted from Drupal modules with the same name, so it may be helpful to search Google for Drupal module [name of the Backdrop module you’re interested in] to see what the user base was for the prior version.
By being a smaller project, Backdrop feels more like a community. There are developers who are interested in fixing problems as they arise. As long as you keep in mind that these are volunteers who are donating their time, don’t treat the community like your personal developer team, and give back where you can (e.g. by writing documentation), there is minimal risk for a plea for help with a module going unanswered.
In the top right corner of the module’s page on backdropcms.org, you can see the recommended version and its release date, along with a link to all versions. Most Backdrop modules developed from a full-featured and well-tested versions in Drupal. As a result, it’s not necessarily a concern if a module doesn’t release new versions frequently. If you go to the page with all versions of a module, you can click the “Release notes” link to see what changed. Clicking this link will take you to Github, a platform that is commonly used as a repository for digital humanities code and data. Backdrop uses Github for storing code and tracking issues. Almost all release notes will include a link to the issue(s) that the release fixes
You can get a view of open issues for the module by clicking the “Issue queue” link on the module’s page on backdropcms.org, or if you’re already on Github, open issues are one of the options in the horizontal menu bar.
Issues link in the horizontal menu bar of a module’s Github project, also showing the text of a release note for version 1.x-1.0.14 for the Backup and Migrate module.
4.4 Essential module: Backup and Migrate
Backdrop has incorporated almost all of the ubiquitous modules into its core, to reduce the number of modules that site builders have to install and update separately. The only module that isn’t included in Backdrop core that should be installed on every site is Backup and Migrate, which allows you to download or save to your server a compressed copy of your database, code, and/or uploaded files. You can also configure Backup and Migrate to upload your backups to Nodesquirrel, a cloud storage provider that provides 5GB of free backup storage per account.
Once you’ve identified a module you’d like to add to your site, you need to install it (by adding the code for the module to your Backdrop installation) and enable it.
Using the black administration menu at the top of the screen, go to Functionality > Install new modules. Enter the name (or part of the name) of the module you want to install, and hit the “Search” button. When you find the module you’re looking for, click the “Add to Installation queue” link.
This will move the module into the “Installation queue” column, and you can click the “Install” button that appears in that column. The “Install” button takes you to an installation screen that encourages you to backup your site before installation. While there’s little to lose on a brand new site if something goes wrong with a module install, it’s worth doing a quick backup before installing a module on a site where you’ve done a lot of work. See chapter 20 for more on backups.
After you hit the blue “Install” button, if the module doesn’t have any dependencies that need to be installed, you’ll see a screen that allows you to enable the newly-installed modules. Check the checkboxes next to the modules you want to enable, and click the “Enable modules” button.
If the module does rely on other modules that you haven’t yet installed, the installation process will stop at the second step, Install dependencies. It will list the modules that need to be installed, as if you’d selected them and added them to your installation queue. For instance, the Feeds module requires the Job Scheduler module, and if you don’t have it installed, you’ll see the following screen:
You can proceed with installing the dependencies, as if you’d originally added them to your installation queue. Select both the module you originally intended, and its dependencies, when you reach the module enabling screen:
If some of the modules you've installed have sub-modules, you will need to go to the Modules configuration page to enable those sub-modules, since they do not show up on the "Enable modules" screen as part of the installation process.
4.5.4 Configuring modules
Many modules need to be configured after they are installed, in order to accomplish what you need. The location of a given module’s settings within the black administration menu is often not intuitive; the fastest way to get to a module’s settings the first time is to find the module on the List Modules page (Functionality > List modules), and click the “Configure” link next to its name. Not all modules have a “Configure” link; modules that are dependencies for other modules (e.g. Job Scheduler) may just provide code-level functionality.
When you click on the “Configure” link for a module, look at the breadcrumb at the top of the configuration page. This will show you where you can find that page again using the administration menu.
As the breadcrumb above shows, you can find the settings page for Backup and Migrate under Configuration > System > Backup and Migrate.
Backdrop comes with almost all the modules you need for a site where you can define your own simple data model, and display that data in various ways. In addition to installing Backup and Migrate, you’ll almost certainly need to install modules that support additional kinds of data (e.g. historical dates, or pointers to other pieces of data). To simplify site maintenance, Backdrop includes a feature that will automatically update the modules that you’ve installed. (As of Backdrop 1.12, this feature can also update Backdrop core.) While you shouldn’t be reluctant to install modules, you should also resist the temptation to install and enable any module you come across that you can imagine possibly needing, for the convenience of having that functionality available if a situation arises where it would be useful.
Every time you enable a module, you are responsible for updating it -- if not with every release (some releases provide new features rather than important bug or security fixes), generally around 1-4 times per year. The more modules you have enabled, the more updates you will need to perform on a regular basis. See section 20.3 for more on updating modules.
By default, Backdrop checks for module updates periodically, and will notify you (with a yellow or red bar, depending on the importance of the updates) at the top of the module administration page when updates are available. Backdrop checks for updates daily, but you can configure this by going to Reports > Available updates > Settings using the administration menu. (Note: This notation is used throughout the book to describe navigation using the dropdown menu provided by the black horizontal administration menu at the top of the screen. The “>” character is used to indicate that the following word is a sub-menu item, nested beneath the one before it. In some cases, a path (e.g. /admin/reports/updates/settings) is included in parentheses next to the italicized text. This is the actual URL of the page where the admin menu instructions will take you. You can go to it by typing the base URL of your site (e.g. http://www.mysite.org) into the URL bar, and following it with the entire path (for instance, http://www.mysite.org/admin/reports/updates/settings).) On that same page, you can also enter an email to receive a notification when there’s any update, or only when there’s a security update. Updating modules isn't hard, but it can be a hassle if you have many modules enabled. The trade-off is worth it if the modules are providing useful functionality for your site, but not if they're enabled "just in case".
Modules can sometimes interact with one another in unexpected and problematic ways. If you're trying to figure out why your site isn’t working correctly, the fewer modules you have enabled, the easier it can be to troubleshoot. Problems are not always obvious immediately: sometimes a routine module update will cause a conflict with another module, where there hadn't been one before. Having many modules installed may also slow down your site's performance. The precise impact of any given module varies, but each module may add to the amount of processing your Backdrop site will have to perform every time a page is loaded. There are ways to mitigate this impact, through performance optimization techniques, but the best policy is to run as lean a site as possible to begin with.
Don't hesitate to add modules to your site when they might fill a need (especially if you've backed up your database before doing so; occasionally enabling a module can cause catastrophic problems. See section 20.4 for more on backups). However, it’s important to be clear about why you've enabled every module on your site. At least twice a year, look through the list of enabled modules and consider disabling-- or even uninstalling-- modules that you don't need anymore (e.g. modules to support theme development once you're done building your theme, modules that didn't end up doing what you'd hoped they would do, etc.) See section 4.7 for more on disabling and uninstalling modules. Module clutter can build up once a site has been running for some time and has undergone iterative improvements, and it's worth periodically keeping in check.
Fully removing a module from your site requires three steps: first, disabling it; then, uninstalling it (which removes any database tables that the module added to your site); and finally, deleting the module from the modules directory of your site’s fileystem. Never simply delete the module without disabling it first; this will cause errors on your site.
If there’s an enabled module on your site that you’re not using and don’t plan to use, you should at least disable it, by unchecking the box(es) corresponding to the module on the List Modules page (admin/modules/list, or Functionality > List modules in the admin menu). Disabling a module means that your site is no longer impacted by security vulnerabilities in its code, and it will no longer be automatically updated. Disabling a module is a prerequisite for uninstalling it.
You can’t disable a module if other modules that are still enabled depend on it. Also, if the module provides a field type (e.g. date, link, etc.) you can’t disable it if fields of that type exist as part of content types on your site. You must delete those fields if you aren’t using them anymore (this should be the case, if you want to disable a module necessary for their continued existence). To see an overview of all the fields fields you have on your site, go to Reports > Fields > List fields using the administration menu; a link to this page is also available as part of the text for any field-providing module: “Required by: Backdrop (Field type(s) in use - see Field list)”.
Disabling a module makes it no longer active on your site, but changes you’ve made to the module’s default configuration settings are still stored in the database. If you choose to re-enable the module later, those settings will generally return in the state you left them. If you want to completely remove the module and tidy up your database in the process, or if you want to start completely from scratch with the configuration for a particular module, you should uninstall the module after you’ve disabled it.
Using the administration menu, go to Functionality > Uninstall modules, check the box next to the module(s) you want to uninstall, and click the “Uninstall” module.
Uninstalling a module removes all trace of the module from your database, but it does not remove the module code from the modules directory in your filesystem. As a result, the module will still appear on the list of all modules (albeit disabled), unless you remove the code by accessing the filesystem directly; there is no way to remove the code through the Backdrop UI.
Removing the module code is not necessary, but if you go through the process of disabling and uninstalling modules, it’s generally worth taking the extra step to clean up your modules directory by deleting the module code. All you need to do is connect to the server, navigate to the modules directory, click on the module’s folder, hit “delete”, and confirm that you want to delete it.
Keep in mind that removing the module code should always be the last step; never remove module code before you have disabled and, ideally, uninstalled the module. When a module is enabled, Backdrop will look for the module code, and the site will likely display errors if the module isn’t where Backdrop expects it. If you accidentally remove the code for the wrong module, you can fix the errors by re-installing the module via the filesystem (i.e. by downloading the code from backdropcms.org, unzipping it, and uploading it to the modules directory.)
This chapter has covered essential modules that will be useful on any kind of Backdrop site, which should be installed and enabled as a first step after you’ve installed Backdrop. It has also covered the process of installing and enabling modules; you will repeat this process numerous times for every Backdrop site you build, throughout the entire site development process. You have also learned how to search for modules that might meet the needs of your site, and what sustainability factors to consider before committing to using a module.
The next step is to plan out what the content types should be for your site-- what kind of data your site will store, and how it will be structured. Chapter 5 addresses these topics. To implement your content types (chapters 6-7), you will need more modules, so there will be plenty of additional opportunities to practice installing and enabling them.