Development:NEWMODULE Documentation

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Template:New Module

This first draft of Moodle Docs page about the creation of a new module is divided into the following sections:

Danielle, did you know about Development:Modules, which is linked to from Developer_documentation#Make_a_new_plugin? You may be better off editing that, rather than starting a new page. However don't let me discourage you. That documentation is very limited, and badly needs to be expanded, so it is absolutely brilliant that you want to work on it.--Tim Hunt 12:03, 28 March 2008 (CDT)

Good point Tim! Anyway... I think we can use this as temporary root for Daniele's work and then, simply, move things to their final place. Let's see how this evolves. -- Eloy Lafuente (stronk7) 12:33, 28 March 2008 (CDT)

My powerpoint about creating moodle modules is a bit old (1.8) and maybe not that comprehensible but I use it when I'm trying to explain things to people. It includes a list of all the things you need to have in a module, except the ones I forgot (backuplib iirc is missing). Sam marshall 12:52, 28 March 2008 (CDT)

That's really great, Sam. For sure that presentation will help.Thanks! -- Eloy Lafuente (stronk7) 13:08, 28 March 2008 (CDT)

Getting started

To download the newmodule package, please refer to:

   * 1.8: http://download.moodle.org/plugins18/mod/NEWMODULE.zip
   * 1.9: http://download.moodle.org/plugins19/mod/NEWMODULE.zip
   * HEAD: http://download.moodle.org/plugins/mod/NEWMODULE.zip

Although you can download the newmodule package for moodle 1.8, such as 1.9 and head, this tutorial is intended for the newmodule development in Moodle 1.9 ONLY.

Let's start by getting an idea about what you find in the newmodule folder taken from http://download.moodle.org/plugins19/mod/NEWMODULE.zip

NEWMODULE:
01)    db:
02)        install.xml
03)        upgrade.php
04)    icon.gif
05)    index.php
06)    lang:
07)        en_utf8:
08)            help:
09)                newmodule:
10)                    index.html
11)                    mods.html
12)            newmodule.php
13)    lib.php
14)    mod_form.php
15)    README.txt
16)    version.php
17)    view.php

The path where you find each file is the correct one. So don't change the path of files and folders in this module package. Inside the db folder, at the beginning, you can only find install.xml and upgrade.php but sooner you will start to always add the new file "access.php"

01) db/install.xml is the file to write the xml describing the tables needed by the module. Tables are at least two, one named with the same name of the module, one named "log_display". They follow a strict syntax that you can learn by editing one of the several example you can find inside moodle modules. Ultimately the only thing to take care is the <<previous>> <<next>> connection between tables and fields. This is the mandatory file where you MUST write the structure of the tables your module is going to use. Tha table "log_display" is the tables where you are requested to list all the "actions" that you will add to the logs of your module.

02) db/upgrade.php is the file that you will write each time you need to change the structure of the tables of your module. To learn how to write this file, please refer to the examples you may find in the file itself.

03) icon.gif, it is a 10px per 10px icon identifying each instance of your module in the frame of a course

04) index.php is...

05) lang is the folder reserved to language packs. A module language pack is a folder named "xx_utf8" containing, in turn, a folder named "help" and a language file named with the same name of the module. xx is the two char long name of the language, i.e. en, de, es, it, fr and so forth.

Each language file is dedicated to a specific language. The lang folder may contain as much language packs as provided by different translators. The lang/xx_utf8/newmodule/ folder contains all the help files you want to provide to your module. In order to link a help file from inside the code of your module pages try:

helpbutton('<<name of your help file saved in lang/xx_utf8/newmodule/>>', get_string('your_string','newmodule'), 'newmodule');

or, in mod_form.php,

$mform->setHelpButton as stated in

06) lib.php is the pre-filled file with "core" functions needed by each module. Let me start by remembering the convention to name functions into lib.php and locallib.php.

See: https://docs.moodle.org/en/Development:Coding_style#Functions_and_Methods

or

https://docs.moodle.org/en/Development:Modules

Mandatory function are, at least:
function newmodule_add_instance($newmodule)
This function is executed after an editing teacher create an instance of newmodule
See, lib.php for more details just above the function.

function newmodule_update_instance($newmodule)
This function is executed after an editing teacher update an instance of newmodule
See, lib.php for more details just above the function.

function newmodule_delete_instance($id)
This function is executed after an editing teacher delete an instance of newmodule
See, lib.php for more details just above the function.

function newmodule_user_outline
See, lib.php for more details just above the function.

function newmodule_user_complete($course, $user, $mod, $newmodule)
See, lib.php for more details just above the function.

function newmodule_print_recent_activity($course, $isteacher, $timestart)
See, lib.php for more details just above the function.

function newmodule_cron()
Take care with this function.
Differently by all the other functions, this function is not called by passing it the $newmodule record. This means that this function, called by moodle core cron has to look for each newmodule instance id before operating.
Don't worry, even if you have more than a single instance of your module among moodle courses, this function will be executed just one time.

function newmodule_get_participants($newmoduleid)
See, lib.php for more details just above the function.

function newmodule_scale_used($newmoduleid, $scaleid)
See, lib.php for more details just above the function.

function newmodule_scale_used_anywhere($scaleid)
See, lib.php for more details just above the function.

function newmodule_install()
See, lib.php for more details just above the function.

function newmodule_uninstall()
See, lib.php for more details just above the function.

In my honest opinion some more functions should be added. Among these I want to list:
function newmodule_reset_course_form_definition(&$mform)
function newmodule_reset_course_form_defaults($course)
function newmodule_reset_userdata($data)
These functions are responsible for the mewmodule reset process during the more general course reset process. Please, refer to mod/data/lib.php or to mod/feedback/lib.php, for instance, to understand them better.

Two more functions that should be added to lib.php are, in my opinion:
function webdim_get_view_actions()
function webdim_get_post_actions()
They distinguish between read and post log actions.
This function is used by moodle core during log gather.
The action you list inside these two functions, are the same you listed in the table "log_display" in install.xml

As stated at the end of lib.php:
//////////////////////////////////////////////////////////////////////////////////////
/// Any other newmodule functions go here.  Each of them must have a name that
/// starts with newmodule_
/// Remember (see note in first lines) that, if this section grows, it's HIGHLY
/// recommended to move all functions below to a new "locallib.php" file.

One important issue is about the connection between lib.php and locallib.php
Who has to call the other and why?
It has to be locallib.php to call lib.php through
require_once("$CFG->dirroot/mod/newmodule/lib.php");
as first line.

In this way, if moodle core calls function inside mod/newmodule/lib.php no module specific function will be loaded in memory.
If it is your newmodule to call a function, it has to require_once('locallib.php'); that, in turn, will require_once('lib.php') o that your module will "see" all its available functions.

Documentation

Development:NEWMODULE Documentation

Getting started

See also