Ready to watch this entire course?
Become a member and get unlimited access to the entire skills library of over 4,971 courses, including more Developer and personalized recommendations.Start Your Free Trial Now
- View Offline
- Creating your first module
- Interacting with hooks
- Working with permissions and roles
- Controlling access
- Adding a menu item to an admin interface
- Using the Form API (FAPI) to quickly create a form
- Creating custom form validation
- Manually creating a custom content type
- Validating user input
- Importing content using feeds
- Creating a block
- Understanding best practices and coding standards
Skill Level Advanced
Drupal looks for modules in several places. While it may be tempting to put a contributed or custom module in the modules directory of the site root, this directory is reserved for Drupal core modules. Instead, additional modules are typically stored within the sites > all > modules directory of the web root. If you have installed contributed modules, you may see some directories there now. Best practice is to organize modules within subdirectories with clear headings, such as contrib and custom.
Contrib is short for contributed modules, which I previously mentioned, and custom is for custom modules, which I will be demonstrating. Each Drupal module has a human readable name and a machine name. The machine name is used throughout the module development, while the human readable name is only shown on administrative interfaces. Drupal module machine names follow a consistent naming convention. All lower case, no spaces, and concise as possible. You can use underscores in the module name, but it can get unwieldy if you have more than one.
Numbers are allowed, but are generally not recommended as a best practice. As the module name is also used in function names, module names cannot start with a number. Here are some good examples of naming conventions. These are real contributed modules available on drupal.org. Coder, a module for algorithmically assisting with code review, devel, which is development and collection of debugging tools, and google_analytics, which is a helper for adding a Google Analytics code to a website.
Next, some examples that are technically legal but are not recommended for various reasons; these module names are imaginary. Test1, it's a legal name but does not clearly describe the purpose of the module. A number should be avoided as well. Canoper_2, it's a legal name but it contains a specific version number. Cat_and_dog_administration_assistant _program, legal, but too verbose. Finally, some bad module names.
Again, these modules do not exist; MyModule with a capital M for both. The upper case and camel case are not appropriate for module names. Test with a capital T space Module, the spaces are not allowed and it starts with a capital letter. 2good; similar to PHP methods and functions, module names cannot start with a number. The first step in module creation is describing the module to Drupal. Instead of describing module metadata in a function which can have a lot of overhead and dependencies, the metadata is described in the PHP INI format.
The INI format is a very simple and widely used configuration formats which can be read directly from the file system. The metadata is stored within an .info file. The name refers to the naming convention and the file extension. A .info file consists of a module machine name followed by a period and the file extension info. For the purposes of the demonstration, I will develop a module to facilitate the management of a database of Wind Farms. A concise way of describing the module would be Wind Farms, which I will combine into one word, to keep the machine name simple.
I'm going to create the .info file for the module. Within the IDE or text editor, navigate to the directory's sites > all > modules, right-click on modules, and go to New > Other, select Other, then Empty file. File Name, this is the machine name for the module. So the filename should be windfarms.info. Remember, it's best practice to place all custom modules in a subdirectory called custom, then the module itself is contained in a folder with the same machine name.
Under Folder specify a subdirectory, /custom/ windfarms, then click Finish to create the file. .info files consist of a simple series of directives. Each directive contains a name, an equal sign for assignment, and a value. You can also place comments within .info files. Any line that begins with a semicolon is ignored by the Drupal INI Parser. I'm going to describe the windfarms module with only three required directives: name, description, and core.
The first directive to create is the name of the module. As the machine name is already specified in both the folder and the .info file, there is no need to explicitly declare it. However, the module must be able to be managed from the Drupal user interface, so human readable name needs to be assigned. The name directive can be created with the following syntax, name = Wind Farms. Next, a description is needed. This should be a single plain text description in one sentence that describes the purpose of the module; description = A database of wind farms.
Finally the core directive. This specifies the major version of Drupal that is required for this module. There is no need to specify particular minor version of Drupal, so the version wildcard x is used; core = 7.x, save the .info file. At this point the module is described to Drupal. However, if I open a browser and go to the Drupal module list, you will not see the module listed anywhere. One final component is still needed, a .module file.
A .module file is just a PHP file with a different file extension. This is the dynamic heart of the module that by convention contains all the major implementations of Drupal functionality. For the time being this file can be empty. In the IDE, right-click on the windfarms directory and go to New > Empty File, and name it windfarms.module, Finish to create the file. As this is a PHP file, open a new PHP code tag, but do not close it.
According to the Drupal coding standard, the closing PHP code tag is purposely omitted from the module and include files. This is done for several reasons; it eliminates the possibility of unwanted whitespace at the end of a file from causing header errors, XML validation issues and other similar problems. The closing delimiter is optional in PHP and php .net itself does not use closing delimiters. Therefore, the closing PHP tag can be omitted. Even though this file can be empty for now, Drupal coding standards dictate that each file has standardized comments containing documentation, also known a docblock at the beginning of the file.
These docblocks are formatted using the doxygen format, which is used by a document generator of the same name. To create a file level docbock, type forward slash followed by two asterisks then type Enter. Some IDs will automatically create a standard docblock, if not, indent one space and add a new asterisk followed by a space. Each file level docblock starts with a token @file on its own line. This indicates to the documentation parsers and people who are reading the source code that this documentation block contains a description of the contents of this file.
On the next line, still within the comment block, describe in a high level sentence the purpose of the module. In this case, Custom functionality for a wind farm database. If the comment block is not closed beneath, do so now. Finally, add a new line to the end of the file. This is considered a best practice and conforms the Drupal coding standard in order to make patches easier to read. Save the module, then go to the browser and click on Modules, scroll down to Other and the newly created Wind Farms module will be listed.
Note that there is no version or operations available and that the module is not enabled by default. There is no need for operations at this time, but not knowing the version of a module is not very helpful. When a module is packaged and available on drupal.org, the version is automatically added by the source control system. As this module is being developed outside drupal.org, the version will need to be manually specified. Return to the IDE and open the .info file.
The module version can be specified with the name version, followed by the assignment operator. The version itself should start with a core version of Drupal, which in this case is 7.x followed by a hyphen, then the module version in point format. Do not use spaces or underscores for the version. I will call this version, 0.1, an additional optional label can be specified after the module version. There are several common naming conventions for optional labels; dev for development only, which is often volatile; alpha, which is the first phase of software testing; beta, which is feature complete, and RC for release candidate final testing.
The optional label is set with a dash followed by the label. As this module is under development, I will label it as -dev. Save the .info file and return to the browser and refresh. The Wind Farms module now shows a version. The new custom module has been described to Drupal and is now recognized. There is now a placeholder where custom functionality will be placed. In the next segment, I will provide an overview of Drupal's application programming interface known as hooks.