Skip to content

Book Tool

A booktool plugin adds new tools or actions to be used within the Book activity, which allows for structured content with chapters and subchapters, making it a highly organized resource for learners.

Understanding the Book Module's Structure

The Book module provides a hierarchical structure of chapters and subchapters, and a booktool plugin interacts with this structure. The main idea of a booktool plugin is to provide additional functionality (like exporting, printing, annotating, etc.) inside the context of a Book activity.

  • The Book module’s core functionality (/mod/book/).
  • The way chapters and subchapters are stored and managed.
  • How navigation between chapters works.

Plugin Structure and Location

A booktool plugin resides within the /mod/book/tool/ directory. Each plugin gets its own subfolder inside this directory. The basic structure looks like:

/mod/book/tool/
    /yourbooktool/
        version.php
        lang/
        lib.php
        index.php
        settings.php (optional)

Adding Functionality to the Book (lib.php)

The lib.php file is crucial for defining the plugin’s integration points with the Book module. Here, you'll implement callbacks to add buttons, actions, or tools to the Book activity interface.

Important functions to implement:

  • booktool_yourtool_extend_navigation(): Adds your tool to the book's navigation block.
  • booktool_yourtool_extend_settings_navigation(): Adds your tool to the settings navigation for a book.

Example: 

function booktool_yourtool_extend_navigation($navigation, $book, $cm, $context) {
    $url = new moodle_url('/mod/book/tool/yourtool/index.php', array('id' => $cm->id));
    $navigation->add(get_string('yourtool', 'booktool_yourtool'), $url, navigation_node::TYPE_SETTING, null, null, new pix_icon('i/gear', ''));
}

This function will add a link to your booktool inside the Book module’s navigation or settings block. Depending on the tool’s purpose, this could lead to an export function, a print option, or another form of interaction.

Interaction with Book Data (index.php)

The index.php file is the entry point for your plugin’s functionality. This file contains the logic for interacting with the book's chapters and subchapters, and performs the main functionality of the tool (such as exporting, printing, or providing additional content for each chapter).

Key aspects:

  • Use Moodle’s page context and book data structures to interact with the Book content (chapters, subchapters).
  • Always ensure the user has the necessary permissions (require_login() and require_capability()).

Example index.php: 

require_once(__DIR__.'/../../../config.php');
require_once($CFG->dirroot.'/mod/book/lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID.
$cm = get_coursemodule_from_id('book', $id, 0, false, MUST_EXIST);
$context = context_module::instance($cm->id);

require_login($cm->course, true, $cm);
require_capability('mod/book:view', $context);

$PAGE->set_url('/mod/book/tool/yourtool/index.php', array('id' => $id));
$PAGE->set_title(get_string('yourtool', 'booktool_yourtool'));
$PAGE->set_heading($COURSE->fullname);

// Perform your tool's main function here (e.g., export, print, annotate).

Permissions and Capabilities (db/access.php)

Permissions define which roles can use your booktool. In the db/access.php file, you can define custom capabilities for your tool.

Example access.php: 

$capabilities = array(
    'booktool/yourtool:view' => array(
        'riskbitmask' => RISK_PERSONAL,
        'captype' => 'read',
        'contextlevel' => CONTEXT_MODULE,
        'archetypes' => array(
            'teacher' => CAP_ALLOW,
            'student' => CAP_PREVENT,
        ),
    ),
);

User Interface and Styling

Booktool plugins often provide user-facing tools (buttons, options). Ensure the UI is clean and intuitive by using Moodle’s standard renderers and templates. Where necessary, include custom styles or JS, but try to integrate with the existing theme as much as possible.

You can add styles via a styles.css file inside your plugin directory: 

/mod/book/tool/yourtool/styles.css

Conclusion

The most important aspects of developing a booktool plugin in Moodle involve understanding the structure of the Book module, integrating your tool seamlessly into its interface, and managing permissions, data handling, and functionality effectively. Properly structuring the plugin, using Moodle’s API functions, ensuring efficient navigation, and maintaining security and performance are crucial for creating a reliable and useful tool within the Book module.