Custom module development: creating a module skeleton

You can extend your Developer Portal site by creating custom modules. The starting point for a new module is to create a module skeleton.

Before you begin

You must have administrator access to the Developer Portal to complete this task.

You must also have experience in Drupal and PHP development. For more information, see Custom module development: an introduction to Drupal tools for PHP development and Custom module development: background and prerequisites.

Important:
  • You are not permitted to include any IBM® API Connect modules within any custom modules that you create. Also, directly editing any API Connect themes, modules, included modules, or Drupal core on the file system is not permitted or supported, as edited versions of these files are overwritten when a fix pack or iFix is installed.
  • All custom development is your responsibility. Although the use of custom modules and themes is supported, IBM API Connect do not provide support in their development or modification.

About this task

Every custom module creation starts with creating an .info.yml file. This file, or module skeleton, is used to store the metadata about the custom theme. After the module skeleton is created, the module can be installed onto your site by using the Extend menu on the administrator dashboard of the Developer Portal UI. However, without any module specific code, your site won't be affected.

The following instructions guide you through creating a custom module skeleton. What to do next in your custom module creation depends on what you want your module to do. Options are shown at the end of this task.

Procedure

  1. Choose a short name, also known as a machine name, for your custom module.
    The machine name is used in several files and functions in your module, as well as by Drupal core to programmatically refer to your module. The name must conform to the following rules:
    • It must start with a letter.
    • It must contain only lowercase letters and underscores. (Note that if uppercase letters are used in the name, Drupal won't recognize any hook implementations in your module.)
    • It must not contain any spaces.
    • It must be unique within your Developer Portal site.
    • It should not be any of the following reserved terms: src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, Drupal.
  2. Create a module folder in a location of your choice, for example, /modules/module_name.
    You don't have to name the folder the same name as your module machine name, however, you must remember to use the machine name programmatically within your module's code and filenames.
  3. Create a module_name.info.yml file in your module folder.
    Where module_name is the short name, or machine name, that you chose in Step 1.
  4. Insert the metadata for your custom module into the module_name.info.yml file as follows:
    name: Example module name
    description: Description of the module.
    package: Custom
    
    type: module
    core: 8.x
    core_version_requirement: '^8 || ^9'
    version: 1.0
    
    dependencies:
      - module_name
    
    test_dependencies:
      - module_name
    
    configure: example.settings
    
    php: 7.1
    
    hidden: true
    where
    • name (required) is the name of your module, and is the text that is shown on the module administration page in the Developer Portal UI.
    • description (optional) is a description of your module, and is the text that is shown on the module administration page in the Developer Portal UI.
    • package (optional) is a key that enables you to group similar modules together.
    • type (required) is the type of extension that you are creating, for example, a module, theme or profile. In this instance you are creating a module.
    • core (optional) specifies with which Drupal core version your module is compatible.
    • core_version_requirement (required) specifies which versions of Drupal your module is compatible with. This example specifies that the module is compatible with all versions of Drupal 8 and 9.
    • version (required) is the version number of your module. Note that version is not required if you are publishing your module on Drupal.org.
    • dependencies (optional) is a YAML list of any modules that your module depends on. They must be namespaced in the format module_name, where module_name is the module's machine name.
    • test_dependencies (optional) is list of any modules (in the same format as dependencies) that are needed to run certain automated tests for your module on Drupal's automated test runner (DrupalCI), but are not needed as module dependencies in general.
    • configure (optional), if your module offers a configuration form, specify the route to this form here.
    • php (optional) is the minimum PHP version that is required for your module. For the Developer Portal the minimum PHP version is 7.1.
    • hidden (optional) is an option that, if set, will hide your module from the Extend section of the administrator dashboard on the Developer Portal UI. This option might be useful if your module only contains tests, or if the module is meant as an example to other developers.
  5. Save your module_name.info.yml.

Results

You successfully created your module skeleton.

Example

An example .info.yml file:
name: User field example
type: module
description: Developer Portal tutorial about a user field example
package: IBM API Connect Tutorials
core: 8.x
core_version_requirement: '^8 || ^9'
version: 8.x-0.0.1
dependencies:
  - ibm_apim
  - auth_apic

What to do next

You now need to create the appropriate content for your custom module, depending on what you want the module to do. For information about the various options, see Creating custom modules on Drupal.org. There is also a walkthrough example of creating a basic custom module that is available on Drupal.org, see: A "Hello World" custom page module.
Note: If you are defining URL paths in the routing file of your module, you must consider any potential implications of those paths, and avoid conflicts with other parts of the Developer Portal. For example, you are recommended not to prefix any paths with ibm_apic.

After you have created your custom module content, you need to package your custom module files up into a zip, tar, tgz, gz, or bz2 file. This file can then be installed onto your Developer Portal site by using the Extend menu on the administrator dashboard. For more information, see Installing custom modules.