Install new modules, themes and layouts directly from the admin interface of your site!
Project Installer
The Project Installer (called just Installer from here on) is a core module that is enabled by default. It allows you to download and install new projects (modules, themes and layout templates) directly from the admin interface of your site. For more information about modules, themes, and layouts see the respective documentation:
You can access the Installer by navigating to the appropriate project install link:
- Install modules: /admin/modules/install
- Install themes: /admin/appearance/install
- Install layout templates: admin/structure/layouts/install
The Installer is closely coupled with several core as well as remote components. If you are testing or developing locally on your computer, you will need online access for the Installer to work. If you are working on a public server, the Installer should just work because the server is already online. The main remote service that is required by the Installer is BackdropCMS’ Project Browser Server which maintains an up to date list of available projects for download. The following diagram illustrates the connections between the components required for a working Installer:
<IMG>
To put it simply, the Installer needs to have access to the online list of projects hosted on backdropcms.org.
The Installer Browser
The main component of the Installer module is the Browser. It allows you to browse and search all projects available on BackdropCMS.org, read information about each, add multiple of them in an installation queue and finally install them all with just a couple of clicks. The Browser is essentially the same for each project type, with the main difference being the "local task tabs" which head the page are slightly different for layouts (there's no uninstall tab for layouts). The components of the Browser are:
- The search bar
- The Sort links
- The project counter
- The Project list
- The project dialog
- The install queue
- The Manual installation link
- The pager
<IMG>
The Sort links, project counter, and pager are hopefully self-explanatory so that we will describe only the Search bar, Project list, Installation queue, and the Manual link in detail.
Search bar
The Search bar allows searching for projects by name. Search results will include projects in which the project name or description match the search term entered. After a search, the search entry persists in the textfield even after leaving the Browser and returning; the "Clear" button appears after each search and allows you to reset the search field to empty again.
<IMG>
The Project list
This is a list of all projects returned by a search term, or all projects available on BackdropCMS.org if no search term. The list is paged, with 20 projects per page.
Each project is represented by the official project title, and a truncated description followed by a "details" link; clicking either the project title or the "details" link pops up a dialog with further information about the project.
An "Add to installation queue" link allows you to add the project to a queue to be installed. Clicking the link adds the project via Ajax, and the link changes to read "Remove from installation queue." This is explained further below.
Finally, a report of the number of installations of this project shows how many times this project has been downloaded and installed on Backdrop sites.
<IMG>
Project dialogs
Project dialogs are launched by clicking on the "details" link for a project in the Project list, or by clicking the project title.
The dialog header shows the project name and the date the project code was last updated by the developer of the project. There is also a link to view the project on BackdropCMS.org. Finally, the installation count and the "Add to installation queue" links are duplicated in the dialog header.
The body of the dialog is the full description as can be found on BackdropCMS.org.
All dialog links open in a new window.
<IMG>
The installation queue
Multiple projects of any project type can be added to the queue at the same time. This means that you can install two or more modules, a theme or two, and a layout all at once by visiting the respective project Install links (see above), adding projects to the queue as you browse, and only complete the installation once you have finished browsing and selecting.
Once a project has been added, a removal icon (a gray X) appears next to the project name; clicking this will remove it from the queue. The "Install" button and "Clear queue" link also appear once projects are added to the queue. The clear queue link removes a project from the queues. Clicking the project's name in the queue also removes it from the queue.
The install button launches the next step in the installation process. It does not automatically cause the project to be installed as a few more verification steps are required before this happens.
<IMG>
The manual installation link
This launches the manual install dialog, which is described further below.
<IMG>
The project installer “wizard.”
After selecting projects and adding them to the installation queue, clicking the "Install" button launches the installation, which is a guided process, or "wizard." The possible steps in the wizard are as follows:
- Select versions
- Install projects
- Install dependencies
- Enable themes
- Enable modules
<IMG>
Not all steps will be required of course: if you did not download any themes, the Enable themes step will be skipped. Note also that there is no "Enable layout templates" step. Layout templates must be added to a particular layout path in the Layout UI, so it means they can't be enabled in the Installer. If you have downloaded a layout template, then you must go to the Layout UI to select and use it in a new layout. See layout documentation for more information. The other project types, however, can be enabled in Installer directly.
The first steps, Select versions, is common to all projects.
<IMG>
The Select versions step
This page allows you to decide which versions of each project you wish to install. Each project on BackdropCMS.org has a recommended version, which is usually the latest, and the Installer will list this version as a link (to the project page) followed by a "Change release" link. The project link is formatted with the project name, followed by the release number and the date of release. For example, a module called Fantastic Links, which has the latest release version 1.x-1.0.2 released on August 15, 2015, would be listed as
- Fantastic Links 1.x-1.0.2 - Aug 15 2015.
<IMG>
Selecting an alternative release
If Fantastic Links also has several other non-recommended releases, the "Change release" link allows you to pick another. Clicking this link converts the listing to a radio select list in the format:
<IMG>
Select release for Fantastic Links *
- Fantastic Links 1.x-1.0.2 - Aug 15, 2015
- Fantastic Links 1.x-1.0.1 - Aug 11, 2015
<IMG>
Choosing to install in Maintenance mode
Once you have selected your release, you can then proceed to the next step to download and install the selected releases. However, Installer suggests that the actual download and install be performed in Maintenance mode and offers a checkbox to select this. Once the install process is complete, Maintenance mode is usually turned off automatically, so it is safe, and best, to leave this option checked.
<IMG>
Install projects step
This stage is where the actual download and install occurs. A progress bar shows the progress so far. Projects are downloaded from BackdropCMS.org and installed to their respective folders on your webserver (modules into the '/modules' folder, themes into '/themes,' layout templates into '/layouts').
<IMG>
Install dependencies step
Some modules may require that other modules, which they depend on for required functionality, be installed and enabled first. If you have just installed a module and Backdrop finds that it requires another module, the Installer will enter this step.
For example, the Views Send module, which uses views to send emails, requires Mimemail to be installed before Views Send can be enabled. If you have added Views Send to the installation queue and have completed the Install projects step, Installer will detect that Mimemail is required for Views Send, and will enter into the Install dependencies step. This step will list Mimemail on a page which is identical to the select releases step, at which point you will be able to select a release of Mimemail, and proceed again to the Install projects step to install it.
<IMG>
Automatic redirection options after install
Once the Install and dependencies steps are complete, Installer redirects you to the appropriate location. The installer will adjust the pages to which you are redirected based on which project types you have just installed. The redirection options are determined as follows:
- If only layouts were installed, you would be redirected to the Layout list
- If only themes were installed, you would be redirected to the Appearance page (the theme list)
- If layouts and themes but no modules were installed, you would be redirected to the Installer's Enable themes page
- If any modules are installed you will go to the Enable modules page; if themes were installed as well, you would go to the Enable themes page first. Otherwise, this is skipped.
<IMG>
The enable themes step
On this page, the Installer lists all installed themes with thumbnails, along with a button to enable one of these themes and set it as default. Note that like on the Appearance page, enabling a new site theme does not cause any change in the appearance of the current page you are on (the Enable themes page) because this page is an Administrative page and so uses the Administrative theme. The theme which is being enabled changes the site theme, not the admin theme. To see your newly enabled theme in action, you would need to visit a non-admin page such as the front page.
<IMG>
The enable modules step
On this page, the Installer lists all the just-installed modules with checkboxes to enable them. A cancel button allows you to finish the Installer wizard without enabling any modules if you prefer.
If any recently installed modules have missing dependencies (that is, there are modules they depend on before they can be enabled), they will be listed separately and marked as missing dependencies and will be missing the checkbox to enable them. To get them enabled, you will have to search for and install the missing module; then on returning to the Enable modules page, they will be available for enabling.
<IMG>
The manual install dialog
The manual install dialog allows you to install projects without using the Installer Browser. There are three options, presented in collapsible fieldsets, in the dialog:
- Install projects by name
- Install from a URL
- Upload a module, theme, or layout archive to install
<IMG>
Install projects by name
This fieldset contains only a textarea in which you can type or paste the machine names of projects you wish to install, one per line. Machine names contain only letters, numbers, and underscores. The machine name can be discovered by hovering the mouse over the project name listed on BackdropCMS.org. For example, hovering over the listing for Views Send shows the project URL is https://backdropcms.org/project/views_send; the machine name is the last bit, "views_send." All projects have a machine name, which is sometimes quite different from the project name.
Once a list of projects is entered into the textarea, clicking "Install" results in each typed name being checked for validity and then the BackdropCMS.org project listing is queried for a project by this machine name. If any valid projects are found, Installer adds them to the installation queue and opens the Select versions page, from where installation continues as usual. Any invalid names (spelled wrongly, not found on BackdropCMS.org, already installed) will result in a warning message but does not prevent the Installer from proceeding.
<IMG>
Install from a URL
This option presents a textfield for typing or pasting the URL of a valid project archive. A valid archive is a file with the extension zip, tar, tgz, gz, or bz2. The notice at the top of the manual install dialog will say which archive types are allowed on your web server; this may vary from site to site.
Since the source of this archive is not always known, for security reasons the downloading takes place through a different process than the Installer. Once "Install" is clicked, Backdrop puts the site in a more secure mode where the install process has less access to critical site functions. A progress bar shows the process in action. Once complete, Backdrop offers options to proceed in the form of links. The options are:
- Manually install another module - this relaunches the Manual install page
- Enable newly added modules - this starts the Enable themes or Enable modules step of the Installer wizard
- Browse projects - this redirects to Installer module
- Module list - this redirects to the Backdrop module list
<IMG>
Upload a module, theme, or layout archive to install
This option presents a file field for uploading a valid project archive from your computer to the web server. Once "Install" is clicked, the process continues identically to the Install from a URL option.
Updating projects
Backdrop allows you to check if any of your modules, themes or layout templates are out of date and also to update these automatically. You may view a list of all installed non-core projects, or alternatively view a list of only those requiring updating.
The Available Updates page
To check the update status of all projects, go to the Available updates page at Admin > Reports > Available Updates > List available updates. This page lists projects grouped by type. Note that project packages are listed, and may include individual projects within the package. For example, the Devel package contains the Devel, Devel node access, and Devel generates modules.
If there is also an update available for Backdrop core, this will also be listed.
Each project row is labeled either as up to date, or if an update is available, the recommended version is listed, and a link is provided to download the update.
Update projects through Backdrop
Go to the project type's update page
- Appearance > Update themes
- Functionality > Update modules
- Structure > Layouts > Update layouts
If there are updates available, select the ones you want and click Download These Updates.
Once the updates are downloaded successfully, select Perform updates in site maintenance mode and click Continue.
The updates will run, and if there are any database updates required, you will have the option to do so. If there were no issues, your projects(s) will now reflect their new versions.
The Updates settings page
This form allows you to set the defaults for updates:
Check for updates - select how frequently you want to automatically check for new releases of your currently installed modules, themes, and layouts. Options:
- Daily
- Weekly
- Manually only - will only check for updates when the "Check manually link" is clicked.
Check for updates of disabled modules, themes, and layouts - will skip disabled project if unchecked
E-mail addresses to notify when updates are available - whenever your site checks for available updates and finds new releases, it can notify a list of users via e-mail. Put each address on a separate line. If blank, no e-mails will be sent.
Email notification threshold - you can choose to send e-mail only if a security update is available or to be notified about all newer versions. If there are updates available of Backdrop CMS or any of your installed modules, themes, and layouts, your site will always print a message on the status report page, and will also display an error message on administration pages if there is a security update. Options:
- All newer versions
- Only security updates