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
-
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
.
-
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.
-
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.
-
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.
-
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.