Cms Drupal 7

This guide covers standard installation of CiviCRM on an existing Drupal 7 site. It assumes that you previously completed these tasks:

Drupal Content Management System. End-to-end Drupal Content Management System which brilliantly sculpted to meet your requirements perfectly! Make new strides in the market by building dynamic, robust, and enterprise-level Drupal 7, 8 & 9 web presence complemented by our Drupal experts. Why use Backdrop CMS? Built-in upgrade from Drupal 7. Backdrop has a built-in upgrade path from Drupal 7. Backdrop will be familiar to people with Drupal experience because it is so similar to Drupal, but includes numerous usability improvements and new features. Serve pages fast, even on shared hosting. Backdrop is lean and mean.

1. Install Drupal 7, and..

If you plan to develop patches for CiviCRM on Drupal 7, then please use the Developer Guide for information about Buildkit and civibuild.

Get the code¶

The CiviCRM download page provides a pre-built archive for use with Drupal 7. Atypical archive file is ~20mb and looks like civicrm-X.Y.Z-drupal.tar.gz. It contains a folder named civicrm/.

In Drupal 7, there is a folder for storing add-on modules: DRUPAL_ROOT/sites/all/modules.

Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:

This method does not require shell access on the server. You may adapt based your server's arrangement.

• On the CiviCRM download page, click the link for CiviCRM / Drupal 7. Save the file locally.
• Extract the archive locally. For example, in a Linux workstation, one might say:
• Observe the new folder civicrm/.
• Using your favor file-transfer system (SSH/SFTP, rsync, git, mv, etc), transfer the civicrm/ folder to DRUPAL_ROOT/sites/all/modules.

This method require shell access to the Drupal server.

• On the CiviCRM download page, note the current version.
• In the shell, navigate to the Drupal module folder (adjust as appropriate):
• In the shell, run the curl and tar commands. Adjust the version X.Y.Z to the appropriate value.

This is the easiest way for a new administrator. However, it may not work in all deployments orall versions. Forexample, if the Drupal server has a locked-down configuration, then it may encounter permission errorsor timeouts. The only way to find out is to try.

• On the CiviCRM download page, right-click the link for CiviCRM / Drupal 7. Copy the URL.
• Login to your Drupal site with administrator permissions.
• Navigate to Modules >> Install new module.
• Paste the URL
• Click 'Install'

In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted bythe Drupal 7 installer. This should work again in 5.31.

The Install new module page provides another option for uploading the archive from your local computer.In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.

In all cases, the final outcome should be the creation of a new folder

Get the translations¶

The basic CiviCRM release includes support for US English (en_US). To use another language or dialect, please download and extract the translation files.

Run the installer¶

The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (which is simpler) or the command-line interface (which has more options).

1. Enable the 'CiviCRM' module
   • Login to your Drupal site with administrator permissions.
   • Navigate to the 'Modules' page (admin/modules).
   • Find 'CiviCRM' and enable it.
   • At the bottom, click 'Save Configuration'.

2. After enabling, the status message will display a link to 'configure CiviCRM'. Click it.

   What if I didn't notice the link?

   Use the URL bar. Navigate to the civicrm page (e.g. https://example.com/civicrm).

3. The CiviCRM installer will open.

   • If there are unmet requirements, the installer will list them. Consult the Requirements documentation for additional advice.
   • If all the requirements are met, proceed through the brief questionnaire.
   • If you have a separate MySQL database for CiviCRM, then locate 'Environment: CiviCRM Database'. Click the edit icon and enter the database URL.
   • Finally, click 'Install CiviCRM'.

CiviCRM has a command-line administration tool, cv, which can perform installation. For details, see command-line installer.

Review the permissions¶

Note that Drupal tries to create the /files/ directory (and make it writeable), but only when saving admin/settings. Same holds for /temp directory, and a /uploads/ directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the CiviCRM module generates errors regarding the files directory, you must create it (writeable) manually.

• Go to the CiviCRM dashboard to see the CiviCRM menus:https://example.org/civicrm (or https://example.org/index.php?q=civicrm if you don't have Clean URLs enabled)

• Go to Administer » User management » Permissions

Permissions for the Anonymous Role

Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:

• access all custom data : If you plan on collecting 'custom' data from visitors in standalone forms or as they make a contribution - enable this permission.
• access CiviMail subscribe/unsubscribe pages : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
• access uploaded files : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
• make online contributions : If you plan on soliciting online contributions from visitors, enable this permission for the 'anonymous' role.
• profile listings and forms : If you plan on collecting name and address or other information from visitors, enable this permission for the 'anonymous' role.
• view event info and register for events : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the 'anonymous' role.
• view event participants : Enable this permission to allow anonymous users to access participant listing pages for events.

Synchronize the users¶

Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.

When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:

• Login to your Drupal site with an administrator-level login
• Click the CiviCRM link in the main navigation block
• If your Drupal site makes use of the db_prefix setting (in settings.php), in the top bar click Administer » System Settings » CMS Database Integration , and update the box for the Drupal Users Table Name so that it includes the prefix.
• Click Administer in the menu bar
• Click Users and Permissions from the drop-down menu, then select Synchronize Users to Contacts

Review the checklist¶

The Configuration Checklist provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from Administer » Administration Console » Configuration Checklist.

Test-drive CiviCRM¶

There should now be a CiviCRM link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.

Addenda¶

TLS for MySQL¶

If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.

Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.

See TLS for MySQL for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:

1. The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.

2. Verifies the server certificate, and doesn't require a client certificate.

   Host name must match certificate name

   Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the host you are using in $databases['default']['default']['host']. So if the host is db435.examplehost.com Chase bank online bill pay phone number. , then that must be the name on the SERVER certificate.

3. Client certificate/key pair (not self-signed), and do not verify the server certificate.

4. Client certificate/key pair (could be self-signed), and verify the server certificate.

Troubleshooting¶

• Review the Troubleshooting page for help with problems you may encounter during the installation.
• To check compatibility with other Drupal modules see: Drupal modules incompatible with CiviCRM

The Big Picture

Backdrop's codebase is similar to Drupal 7 and generally needs very few changes to convert. To make things even easier, Backdrop includes a Drupal compatibility layer which should enable Drupal functions (even those with the format 'drupal_XXX', such as drupal_set_message), to just work, for now. However, Backdrop still has significant advantages over Drupal 7, and it would make sense to fully port your module rather than depend on the compatibility layer.

This guide suggests a process for converting Drupal 7 modules to Backdrop, and the common issues which might arise during the conversion. (If your module is not Drupal version 7, we recommend you follow Drupal's module conversion guidelines to upgrade (or downgrade) to Drupal 7 before continuing.)

• Configuration Management
  • Using system_settings_form()

Before You Begin

Before you start porting a module, please create the two recommended issues stated on the Communicating section of the Converting Drupal code page.

Coder Upgrade

The Coder Upgrade module can carry out many of the required changes automatically. You should still, however, read through all of the below even if using Coder Upgrade, because there will likely need to be some 'touch-up' changes to the code after Coder Upgrade does its conversion.

Drupal Code Base to Backdrop Code Base

This would be for a module that had a 2.x release:

You can now see all of releases that are on the Drupal project page (e.g., https://www.drupal.org/project/[project_name]/releases) in your repository.

Note, however, if you are not yet a member of the backdrop contrib group you cannot push into the github.com:backdrop-contrib repository.

Modifying Your Module's .info File

For reference, also see the developer documentation for Backdrop modules. Here is a comparison of Drupal and Backdrop module info files:

and here is Backdrop:

The first and most important change is that a new Backdrop-specific core version needs to be added: 'backdrop = 1.x'. For modules that would like to support both Drupal 7 and Backdrop at the same time, the old Drupal core version can also remain, but for Backdrop-only modules this line should be removed: core = 7.x

Backdrop also distinguishes between different types of projects (modules, themes, layouts) by using the line type = module and the packaging script on backdropcms.org will fail if the type line is excluded.

In Backdrop the class registry has also been removed and replaced with a static class map (see the related change record). This means that you'll need to remove any lines in your info file that define files containing PHP classes: files[] = whatever.inc. To have this class loaded you'll need to implement hook_autoload_info() in your module file instead.

The exception is test classes. The .test files are loaded with a .tests.info file and not listed in hook_autoload_info(). For example: files = menu_import.test. Read more in next section.

in the Drupal 7 .info file:

in the Backdrop .module file:

In the .info file you should remove the version and datestamp as those will be generated automatically by Drupal.org as part of creating the release.

There is a new feature in Backdrop: tags in the .info file. More details here.

Example:

Organization of Module Files

There are now recommended locations for common module files. Javascript files are always kept in a js folder, CSS in a css folder, templates in a templates folder, and tests in a tests folder.

Backdrop recommends the following files be kept in the root of the module folder. Having these files immediately visible makes it more obvious that this module provides theme functions (and makes them easy for front-end developers to find), has a settings page, and provides user-facing pages. If a module provides too many additional .inc files it would also be reasonable to place those additional files into an includes folder also in the module root, or organize further as necessary.

• modulename.info
• modulename.module
• modulename.admin.inc
• modulename.pages.inc
• modulename.theme.inc
• modulename.api.php
• config
• css
• js
• templates
• tests

If your module contains tests, those tests should live within the tests directory. Information about the tests should be moved out of the getInfo() method in the test class, and instead moved into a new .info file located at tests/modulename.tests.info. Check out the Book test info file for an example.

Another example:

Old:

In the tests/menu_import.tests.info:

If your module contains the jQuery core file, you should remove it. Backdrop currently ships with updated jQuery. If the Drupal 7 module uses third-party scripts, which are in DRUPAL_ROOT/sites/all/libraries, then you can create a new directory BACKDROP_ROOT/libraries, and place the script files inside this directory.

The preferred method, though, is to integrate these files into your module: place inside the MODULE_ROOT/js directory, and register it with hook_library_info() in modulename.module. If the library is likely to be used by others, you should create a separate module for the library, then include that module in your module's dependencies (and then others can do the same).

If your module contains .make file, you should consider that Drush make is no longer maintained. Composer is the supported solution.

Configuration Management

Drupal 7 stores most module configuration in the variables table in the database. A trio of handy functions were provided to manipulate these variables: variable_get(), variable_set(), and variable_del().

In Backdrop, configuration is stored in flat files. These files are often called configuration (or config) files, and end in a .json extension. By default, active config files are saved into BACKDROP_ROOT/files/config_xxxx/active (where xxxx is a long alphanumeric string generated during install and entered into settings.php). Backdrop provides the corresponding config_get() and config_set() functions to manage the retrieval and writing to disk.

For the purpose of backwards compatibility with Drupal 7, both the variables database table and the 'variable_' functions still exist in Backdrop. They have been deprecated and will be removed in Backdrop 2.0, so conversion to 'config_' is highly recommended.

In Drupal 7, the variables table was something of a catch-all for small bits of data; it held not only configuration data (information that was typically set once and then never changed), but also environment-specific data that was regularly updated (for example, the last time that a particular cron function was called). In Backdrop, information of this latter type is called state data, is stored in the database, and is accessed using functions state_set() and state_get().

In the discussion that follows, we will assume all variables are to be converted to config and will be accessed with config_set(), and config_get(). As you plan your conversion, though, some variables may be more appropriate for state_set()/state_get(). See this change record for a fuller description of the distinction.

Config Storage File(s)

To convert variables to config, first identify all the module's current variables: use your editor, search, or grep. The aim is to get an idea of the number or variables and type of configuration your module requires.

To store configuration, the module will need its own config file. Config files are commonly named 'modulename.settings.json'. Sometimes it is appropriate to have more than one config file. For example, the settings for node module are saved by node type: node.type.article.json, and node.type.page.json. For a module with complex configuration modulename.first_set_of.settings.json, and modulename.second_set_of.settings.json may be a better fit. Think about how you would like to deploy this configuration. Would you be moving all module's settings at once, or one type at a time?

Changing the Code

Once you have decided on a single config file or several, you will need to replace every instance of a 'variable_' function. The standard method is as follows:

Instead of

Use

And instead of

Use

The above examples of config will read and write to a JSON file called modulename.settings.json in the active config directory.

An alternative method for saving config, usually when getting or setting more than one value at a time, is to create a config object and use the object's get and set methods.

This is especially useful when creating settings form arrays where you may need a '#default_value' for many form elements. It's also the preferred method for saving values in a form submit handler, where config is being saved:

Create Config Defaults

The function variable_get() has the useful capacity to declare default values; writing $setting = variable_get('my_setting', 'red') allows the developer to initialize the value 'red' if 'my_setting' variable has not been set. Conversely, though, this required an initialization value to be provided every place variable_get() was called, leading to lots of code duplication (or worse, non-duplication).

In Backdrop, there's no such thing as a variable that has not been set, and therefore config defaults need to be explicitly set at module enabling.

The simplest way to set default values for your config variables is to provide a default config file. This file should be placed into a config directory within your module: config/modulename.settings.json. When the module is enabled for the first time, the config file will be copied from this location into the active config directory.

Here is a sample config file to get started. Note the lack of a trailing comma after the last value; this is a JSON requirement.

Declare the Module's Config

Modules need to declare config files in hook_config_info() in modulename.module. This is how Backdrop knows that you have a config file that needs to copied when the module is enabled. It's also how Backdrop compares changes in config during deployment, and how it knows which config files need to be automatically removed when uninstalling a module.

Create an Upgrade Path

At this stage the module should be nearly completely converted to CMI; new installs will use CMI exclusively for storing config. However, existing users with this module installed on a Drupal site and who wish to convert to Backdrop will still need a process to convert existing settings stored as variables to the config system.

Backdrop uses the hook_update_N() system for upgrades and updates in modulename.install. For initial porting to Backdrop 1.x, N should be in the 1000s; most commonly, modulename_update_1000() is the update that converts variables to config.

Note that while the standard docblock summary line for implementation of a hook is 'Implements hook_NAME()', the docblock for implementations of hook_update_N()is special; it should describe what the update does, for example, 'Migrate variables to config.'

In this update, retrieve the values of existing variables and store them as config, then delete the variables. For example:

If you have renamed a column in a database table, you have to use the db_change_field() function.

For example when 'drupal' string is replaced with 'backdrop' in the name of a column:

Note that when upgrading a module, all previous updates should be deleted. If a module has updates numbered 6xxx or 7xxx, be sure to remove all these updates.

When removing these updates, you should provide an implementation of hook_update_last_removed() in modulename.install to indicate which version of the module schema you're expecting when an upgrade is performed:

Using system_settings_form()

Many settings forms use the system_settings_form() function to finish off creating the form. From the API of system_settings_form():

'This function adds a submit handler and a submit button to a form array. The submit function saves all the data in the form, using variable_set(), to variables named the same as the keys in the form array.'

Since variables are not used in Backdrop, system_settings_form() has been updated to save to a single config file. If your module saves all the settings in its form to a single file, you'll need to add a new #config key to the form array so system_settings_form() knows where to save the values in the form build function. Such settings form functions are commonly located in either the modulename.module or modulename.admin.inc files.

Old:

New:

If you need to save values into multiple config files, we recommend that you add your own submit button, and submit handler for the form instead, as follows.

Notice how with the new approach, you can remove the module name from the name of your variables (if you like) since the variables are saved in individual config files that contain the module name.

Keep in mind, though, that it's common to keep the module name as part of the variable name when upgrading a Drupal 7 module to Backdrop. If other modules will be depending on your module and its settings, if you change the name of your variables in the move to config, modules that depend on yours will need to do so, too in their calls to your module's config settings.

Classed Entities

Several entities in Backdrop are now classed objects which extend the Entity Class. Users, nodes, comments, files, taxonomy terms and vocabularies have been converted to extend the new base class. Therefore programmatic creation of these objects has changed in Backdrop. For example:

Old

New

You should search for these functions in the code (further details):

• node_save(), node_load(), node_delete()
• user_save(), user_load(), user_delete()
• file_save(), file_load(), file_delete()
• comment_save(), comment_load(), comment_delete()
• taxonomy_vocabulary_save(), taxonomy_vocabulary_load(), taxonomy_vocabulary_delete()

Node entity has a langcode property instead of a language property. Replace it:

Old:

New:

Core Modules Removed

There are several modules that were included in Drupal 7 that have been removed from Backdrop (see complete list). If your module implemented APIs for any of these modules, those hooks can be safely removed.

A commonly-used Drupal function was hook_help() in modulename.module. As the Help module was removed from Backdrop, this function no longer exists and so you should instead display any necessary help text on forms/pages directly, or in your module's GitHub Wiki.

Leaving these hooks in your code will not affect a Backdrop module in any way, since the code will simply not be called. You may leave them in place if you would like to be able run the same module on both Drupal and Backdrop sites.

Features Added to Core

The most commonly used Drupal 7 features are being added into Backdrop core. Check the list of modules those are added into Backdrop core or no longer necessary to include. If any of these is a dependency of your module, you should remove the dependencies[] line from your modulename.info file.

You should rewrite the dependencies[] if the module has been replaced or its functionality integrated into an another module. In the latter case, the integrated modules' functions may have changed, in which case you may need to fix the function call. For example, the functions of the Libraries API module have been changed.

Install and Uninstall Hooks

If the module implements hook_schema(), hook_install() will create the schema. So, backdrop_install_schema() is not needed to be called in hook_install() (nor is drupal_install_schema()). Similarly, backdrop_uninstall_schema() (and drupal_uninstall_schema) are unnecessary to call. Check the .install file to see if these hooks can be removed.

If your module provides separate configuration files, you should implement hook_config_info(). This will allow the config files to be automatically removed during the module uninstallation, without having to specifically do that 'manually' in an uninstall hook.

Cms Drupal 7

Without Drupal Compatibility

Drupal compatibility is enabled by default in the variable backdrop_drupal_compatibility within BACKDROP_ROOT/settings.php. The last step to completely port the module to Backdrop CMS, is to check that it works well with the Drupal compatibility disabled. To do that, you should replace

• drupal with backdrop,
• DRUPAL with BACKDROP,
• Drupal with Backdrop,

in all the files of the module and test its operation. Each is case sensitive. With this easy step we can avoid using deprecated functions (which could be the cause of warnings or errors). Note, however, these replacements should be done manually, not in bulk; there can be legitimate reasons for the continued existence of 'Drupal' (for example, in comments explaining the difference between a Backdrop feature and its Drupal predecessor).

Testing

Some suggestions:

• Set the 'All messages' option on the admin/config/development/logging page.
• Log page: admin/reports/dblog
• If your module contains a .test file, then you should enable the Testing module, and run the module's test on the admin/config/development/testing page. If you encounter an error message, you may need TestCase's classes descriptions.

Summary

These are a few of the common module changes which will be required for porting. However, other less common API changes exist. See the change records for a full list. Use the search bar on this page if you encounter an error message. If you find an unlisted API change, please report this on the Backdrop Issue Queue.

Some examples:

Cms Drupal 7 Training

• Search result of 'hook_page_build': New Layout module -> $page variable has been removed
• If the module uses the language key object within the $message array parameter in hook_mail(), now has a langcode property instead of language property. Replace it.

You can learn from the code of previously converted modules. Select a module on the Backdrop Modules site, follow the 'Project page' link to Github, and study the commits.

If your converted module is a contrib module, and you want to publish on Backdropcms.org, then read the Contributed Project Agreement for how to join the contrib group.

Tagging for Release

When tagging your Backdrop module for release, please use the same version number as the Drupal module being ported. For example, if you are porting the 7.x-4.15 version of webform module, that should become the 1.x-4.15.0 version of the Backdrop module. Any bug fixes would increment the last number to 4.15.1 or 4.15.2.

Cms Drupal 7 Login

When a new version of the Drupal module comes out (7.x-4.16) the minor-version number of the backdrop version can also be updated to match (1.x-4.16.0) and that version can contain all/any commits from the Drupal project that you'd like to include.

Drupal 7 Core

If the Backdrop and Drupal version numbers do not match for any reason, the Backdrop release description should contain the Drupal version that is comparable.

Drupal 7 Review

Pre-release modules can have a pre-release suffix, e.g., 1.x-1.0.0-alpha1, 1.x-2.0.0-beta4, etc. Creating a prerelease-tagged version is a good way to get usage feedback from users who are interested in the module and willing to try it out. Be sure to mark prerelease versions as such in Github when you create the release tag.

Cms Drupal

Happy converting!