Wrights HQ

A blog by Ian Wright - Front-end web developer

This post in a continuation post from Creating our module (part 1) and this time I’m going to explain how I built out the help and configuration pages. To me these two section are very important to a module. The help page may not be used by many developers as all modules tend to come with a README.txt file but I find the help page should either have the same information as the readme or have information which compliments it. For the configuration section, this allows for the end user (admin, site builder etc) to set certain options for the module.

Setting up the help page

For my module I wanted to have a help page which worked like a tutorial. I wanted the user to be able to read the page and understand what they needed to do, to get the best out of it. To do this I created a new file in the root /modules/custom/geoplotting/geoplotting.module. If you are a Drupal 7 developer you will notice this file name is the same (.module).

Just like Drupal 7 to create the help page we use hook_help(), the main difference now is the parameters which are passed. Below is an example of my geoplotting.module help function.

<?php

/**
 * @file
 * Creates a help page for our Geoplotting field formatter.
*/

use Drupal\Core\Routing\RouteMatchInterface;

/**
 * Implements hook_help().
 */
function geoplotting_help($route_name, RouteMatchInterface $route_match) {
 switch ($route_name) {
 case 'help.page.geoplotting':
  $output = '<h3>' . t('About') . '</h3>';
  $output .= '<p>'
   . t('The Geoplotting module allows you to set the field formatter to a google map for geofield fields.
   See the <a href="@field">Field module help</a> and the <a href="@field_ui">Field UI help</a>
   pages for general information on fields and how to create and manage them.',
   [
    '@field' => \Drupal::url('help.page', ['name' => 'field']),
    '@field_ui' => \Drupal::url('help.page', ['name' => 'field_ui'])
   ]
  )
  . '</p>';
  return $output;
  break;
 }
 return null;
}

Setting up the configuration page

In the previous post I explained how to create a routing file (geoplotting.routing.yml), this was to setup the path to our configuration page.

In the routing file we can no longer register a menu  path like we could with hook_menu(). In Drupal 8 this is handled differently. As I want to allow the user to be able to click a menu link from the configuration menu UI I created a new file /module/custom/geoplotting/geoplotting.links.menu.yml. This file will allow me to set the geoplotting config link and the position to the existing development menu.

geoplotting.config:
 title: 'Geoplotting Configuration'
 parent: system.admin_config_development
 description: 'Set API keys and global geoplotting settings'
 route_name: geoplotting.config
 weight: 10