Rebecca Rumble

This is carrying on from my earlier post Moodle 4 : Adding Course Image to Header . But using the Course Image rather than a separate Header image is not without its problems as we could end up loading numerous larger images than we needed in the course listing on the homepage and dashboard.

To combat this I want to add a separate field to the course settings so that we can choose a different image for the course header and have a smaller image for the course listing.

Researching how to do this turned up a couple of pieces of interesting information:

• moodledev.io/docs/apis/plugintypes/customfield
• docs.moodle.org/dev/Custom_fields_API
• www.elearningworld.org/moodle-custom-course-fields/

I’m not quite sure if this is the best way forward so far but exploring it for now!

Creating a Course Custom Field plugin

First I created a new plugin in customfield/field called image following the documentation here : moodledev.io/docs/apis/plugintypes/customfield

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Customfield checkbox plugin
 * @package   customfield_image
 * @copyright 2023 Author Name <email@example.ac.uk>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die();

$plugin->component = 'customfield_image';
$plugin->version   = 2023022300;
$plugin->requires  = 2022112800;

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Customfield checkbox plugin
 * @package   customfield_image
 * @copyright 2023 Author Name <email@example.com>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Image Upload';
$string['privacy:metadata'] = 'The image update field type plugin doesn\'t store any personal data; it uses tables defined in core.';
$string['specificsettings'] = 'Image Upload field settings';

and added /classes/data_controller.php and /classes/field_controller.php (more on these next)

Field Controller (classes/field_controller.php)

The field controller (/classes/field_controller.php)

• Adds in field settings using the Form API ( moodledev.io/docs/apis/subsystems/form )
• Allows our new field to appear in the option list in Site Administration -> Courses -> Course Custom Fields
• Allows us to customise the settings form to add additional options our custom field needs
• Validates the input of the settings (existing and new).

Create the file in classes/field_controller.php

Setup the file in the normal way. Note you should change the namespace to match your plugin’s component name.

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Customfields image upload plugin
 *
 * @package   customfield_image
 * @copyright 2023 Author Name <email@example.ac.uk>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace customfield_image;

defined('MOODLE_INTERNAL') || die;

Create the class. At a minimum, the following two items are required:

• the TYPE constant to match the name of the plugin; and
• the config_form_definition() function.

/**
 * Class field
 *
 * @package customfield_image
 * @copyright 2023 Author Name <email@example.ac.uk>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class field_controller  extends \core_customfield\field_controller {
	/**
	 * Plugin type
	 */
	const TYPE = 'image';

        // More code will go here....

}

Next we want to add the config_form_definition function which sets up additional form fields for any settings we might want the custom field to have. These will appear when we choose “Image Upload” from the Course Custom Field screen.

Since we want to have an image upload a good setting to add is how many images we want the field to allow.

	/**
	 * Add fields for editing a checkbox field. Should include any settings we want for this field
	 *
	 * @param \MoodleQuickForm $mform
	 */
	public function config_form_definition(\MoodleQuickForm $mform) {
		$mform->addElement('header', 'header_specificsettings', get_string('specificsettings', 'customfield_image'));
		$mform->setExpanded('header_specificsettings', true);
		
		$mform->addElement('float', 'configdata[filelimit]', get_string('filelimit', 'customfield_image'), array('size' => 30));
		$mform->setType('configdata[filelimit]', PARAM_INT);
	}

The plugin is using the Form API to create the form fields : moodledev.io/docs/apis/subsystems/form

Unfortunately the Form API doesn’t yet include a number field – but it does include float which will do for now.

Notes : change the field labels & names to match your new setting and add the relevant language strings to /lang/en/customfield_image.php

Next we want to validate the form fields

	/**
	 * Validate the data on the field configuration form
	 *
	 * @param array $data from the add/edit profile field form
	 * @param array $files
	 * @return array associative array of error messages
	 */
	public function config_form_validation(array $data, $files = array()) : array {
		$errors = parent::config_form_validation($data, $files);
		
		if (!is_numeric($data['configdata']['filelimit']) || $data['configdata']['filelimit'] < 1) {
			$errors['configdata[filelimit]'] = get_string('errorconfiglimit', 'customfield_image');
		}
		
		return $errors;
	}

It’s important we check that the value added in a numeric one and is 1 or more. If not an error we define in /lang/en/customfield_image.php will appear.

$string['pluginname'] = 'Image Upload';
$string['errorconfiglimit'] = 'The file limit field must be a number and at least 1';
$string['filelimit'] = 'File Limit';
$string['privacy:metadata'] = 'The image update field type plugin doesn\'t store any personal data; it uses tables defined in core.';
$string['specificsettings'] = 'Image Upload field settings';

Data Controller (/classes/data_controller.php)

This class handles adding in the custom form fields into the course settings. This is the bit the lecturers will be filling out when creating their courses.

Create the file in the normal way and change the details and component name to match your plugin.

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Customfield Upload Image plugin
 *
 * @package   customfield_image
 * @copyright 2023 Author Name <email@example.ac.uk>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace customfield_image;

use core_customfield\api;
use core_customfield\output\field_data;
use html_writer;
use moodle_url;
use MoodleQuickForm;
use stdClass;

defined('MOODLE_INTERNAL') || die;

I’m using the use keyword here as well to import some Moodle classes to use later in the code. Makes it a lot more straight forward to access them.

Create the class. At a minimum, the following two items are required:

• the datafield(): string function; and
• the instance_form_definition() function.

/**
 * Class data
 *
 * @package customfield_image
 * @copyright 2023 Author Name <email@example.ac.uk>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class data_controller extends \core_customfield\data_controller {

    // more code will go here...
	
}

Then add in the datafield. Note this describes which database field the data for the custom field is stored in. Options are shown here : moodledev.io/docs/apis/plugintypes/customfield#data-controller

The filemanager field will use an itemid string of numbers to represent the file within moodle so we are using intvalue here.

	 /**
	 * Return the name of the field where the information is stored
	 * @return string
	 */
	public function datafield() : string {
		return 'intvalue';
	}

Next add the instance_form_definition() function. This defines the fields that will appear on the course settings page.

This function uses the Form Api to create the form fields :

	 /**
	 * Add fields for editing a checkbox field.
	 *
	 * @param \MoodleQuickForm $mform
	 */
	public function instance_form_definition(\MoodleQuickForm $mform) {
		
		$field = $this->get_field();
		$config = $field->get('configdata');
		$elementname = $this->get_form_element_name();

		// If file upload is required 
		$isrequired = $field->get_configdata_property('required');
		
		$mform->addElement(
			'filemanager',
			$elementname,
			$this->get_field()->get_formatted_name(),
			null,
			$this->customfield_image_options($field)
		);
		
	}
	
	public function customfield_image_options($field) {
		global $CFG;
		
		$maxfiles = $field->get_configdata_property('filelimit');
		
		if(empty($maxfiles) && !empty($CFG->courseoverviewfileslimit)) {
			$maxfiles = $CFG->courseoverviewfileslimit;
		} else if(empty($maxfiles)) {
			$maxfiles = 1;
		}
		
		$options = array(
			'maxfiles' => $maxfiles,
			'maxbytes' => $CFG->maxbytes,
			'subdirs' => 0,
			'accepted_types' => array('png','jpg','jpeg','jpe','gif','svg','svgz')
		);
		
		return $options;
	}

Using the File Manager field from the Form API we add Moodle’s Image Uploader to the form:

Ref: moodledev.io/docs/apis/subsystems/form/usage/files#file-manager

I created a separate function ( customfield_image_options() ) here to set the file manager field options. This function uses the setting we created earlier in field_controller.php to set the file limit.

Accepted File Types are defined in /moodle/lib/classes/filetypes.php – I’ve limited these to some image types.

The above code however is not enough – you will probably find it will now probably throw an error on the homepage and course page. e.g.

Fatal error: Class customfield_image\data_controller contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (core_customfield\data_controller::get_default_value) in …/moodle/customfield/field/image/classes/data_controller.php on line 113

To fix this we just need to add a couple more functions (i.e. the remaining methods the error message mentions)…

	 /**
	 * Returns the default value as it would be stored in the database (not in human-readable format).
	 *
	 * @return mixed
	 */
	public function get_default_value() {
		return $this->get_field()->get_configdata_property('defaultvalue');
	}
	
	/**
	 * Returns value in a human-readable format
	 *
	 * @return mixed|null value or null if empty
	 */
	public function export_value() {
		$value = parent::export_value();
		if ($value === null) {
			return null;
		}
		
		return $value;
	}

Note that this is only saving the file as a user’s draft file which is a problem. We will need to adjust the code so that it saves the file correctly using Moodle’s File API Documentation as a reference.

First we need to make sure that the draft file is loaded into the settings form. If you take a look at the customfield data_controller class there is a class called “instance_form_before_set_data” it is this one we want to copy into our own data_controller class and extend to manage the draft file.

	public function instance_form_before_set_data(stdClass $instance) {

		$draftid = file_get_submitted_draft_itemid($this->get_form_element_name());
		$field = $this->get_field();
		$fieldname = $this->get_form_element_name();
		
		file_prepare_draft_area($draftid, $this->get_context()->id, 'customfield_image', $fieldname, $this->get('id'),$this->customfield_image_options($field));
		
		$instance->{$this->get_form_element_name()} = $draftid;

	}

We’re getting an unused draft item ID to use in this form using file_get_submitted_draft_itemid (see Moodle File Manager Documentation).

Then by using file_prepare_draft_area we are copying the previously uploaded draft file into the draft area of the form. Otherwise we won’t see the existing file in there.

Next we need to add another function taken from the customfield data_controller class to process and save the data coming from the form.

	public function instance_form_save(stdClass $data) {

		$fieldname = $this->get_form_element_name();
		$field = $this->get_field();

		// Trigger save.
		parent::instance_form_save((object) [$fieldname => $data->{$fieldname}]);
		
		file_save_draft_area_files($data->{$fieldname}, $this->get_context()->id, 'customfield_image', $fieldname,$this->get('id'), $this->customfield_image_options($field)); 

	}

The function file_save_draft_area_files is part of the file API and moves a copy of the draft file into the correct area using the parameters supplied. We need to reference the plugin’s component name and the file area name (this can be anything so long as you use the reference throughout – I’m using the field element name in case there are a number of image fields setup).

Because of how the filemanager works with Moodle Quick Form we also have to trigger the save data function so that there is a value in the custom field data – we can achieve this by running the parent class instance_form_save.

It’s also worth adding in a delete function so that when the field is deleted the files are also deleted.

	public function delete() {
		$fieldname = $this->get_form_element_name();
		get_file_storage()->delete_area_files($this->get_context()->id, 'customfield_image', $fieldname, $this->get('id'));
		
		return parent::delete();
	}

Ref: Moodle Documentation File API

File Display

Finally we need to get the file to display on the frontend rather than the file item id that is currently returned.

Because we will now need to get our accepted types twice I changed this into a function:

	 /**
	 * Returns the default accepted types for this field.
	 *
	 * @return mixed
	 */
	public function get_accepted_types() {
		return array('png','jpg','jpeg','jpe','gif','svg','svgz');
	}

And updated customfield_image_options function to call this new accepted types function:

	public function customfield_image_options($field) {
		global $CFG;
		
		$maxfiles = $field->get_configdata_property('filelimit');
		
		if(empty($maxfiles) && !empty($CFG->courseoverviewfileslimit)) {
			$maxfiles = $CFG->courseoverviewfileslimit;
		} else if(empty($maxfiles)) {
			$maxfiles = 1;
		}
		
		$options = array(
			'maxfiles' => $maxfiles,
			'maxbytes' => $CFG->maxbytes,
			'subdirs' => 0,
			'accepted_types' => $this->get_accepted_types()
		);
		
		return $options;
	}

We need to modify the export_value function in /classes/data_controller.php to display an image.

	public function export_value() {
		$fieldname = $this->get_form_element_name();
		
		$files = get_file_storage()->get_area_files($this->get_context()->id, 'customfield_image', $fieldname, $this->get('id'),'', false);
		
		if (empty($files)) {
			return null;
		}
		
		$html = '';
		
		foreach($files as $file) {
			$fileurl = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(),$file->get_itemid(), $file->get_filepath(), $file->get_filename());
			
			$html .= html_writer::tag('div',
									  html_writer::empty_tag('img', ['src' => $fileurl, 'loading' => 'lazy']),
									  ['class' => $this->get_form_element_name()]);
		}
		
		return $html;
		
	}

Using Moodle’s File API we fetch the file using the references we set earlier. If this is empty (i.e. there are no files of that name) the function just returns null.

If there are some files the function loops through these and creates the file url using moodle_url and then adds to the output html string using HTML_Writer. Finally the html string is returned.

Modifying the Theme Template to use our new field.

Create a new Custom Course Field

Once the new plugin is finished and installed we can go to Site Administration -> Courses -> Course Custom Fields.

Create a new category e.g. Additional Course Images

Add a new custom field – you should see “Image” in the dropdown now which is created by our new plugin.

Set the settings how you would like. e.g :

Name: Header Image
Shortname: headerimage
File Limit: 1

Save.

Add a Header Image to your course

Scroll down and you should see the new category “Additional Course Images”
Upload an image to that field.

Modify the Course Template / Renderer

In a previous post Moodle 4 : Adding Course Image to Header I created a renderer override within the theme to use the course image if there was one and place it in the header field. We can now modify that previously built renderer override to look for a course header image and insert that instead if one exists.

	public function course_header_image() {
		global $CFG;
		global $COURSE;
		
		if ($this->page->course->id == SITEID) {
			// return immediately and do not include /course/lib.php if not necessary
			return '';
		}
		
		// This section has been borrowed from course/renderer.php 
		require_once($CFG->libdir. '/filestorage/file_storage.php'); // need this for accessing file api.
		require_once($CFG->dirroot. '/course/lib.php'); // need this for checking custom fields
		
		// File API
		$fs = get_file_storage();
		
		// modified this line so we have the course id for the context.
		$context = context_course::instance($this->page->course->id);
		
		// This will be the final string.
		$contentimages = '';
		
		// We need these two for checking custom fields. 
		require_once($CFG->dirroot. '/course/classes/list_element.php');
		require_once($CFG->dirroot. '/customfield/classes/output/field_data.php');
		
		// Get the current list element for this course.
		$coursele = new core_course_list_element($COURSE);
		$cfurl = '';
		
		$cfshortname = 'headerimage';
		
		// check if we have any custom fields.... if not we can skip :)
		if ($coursele->has_custom_fields()) {
			
			global $PAGE;
			$output = $PAGE->get_renderer('core_customfield');
			$fieldsdata = $coursele->get_custom_fields();
			foreach ($fieldsdata as $key => $data) {
				
				$fd = new core_customfield\output\field_data($data);
				if($fd->get_shortname() == $cfshortname) {
					$cfurl = $fd->get_value();
				}
				
			}
		}
		
		if(empty($cfurl)) {
			$files = $fs->get_area_files($context->id, 'course', 'overviewfiles', false, 'filename', false);
			if (count($files)) {
				
				// modified this line so we have the course id
				$overviewfilesoptions = course_overviewfiles_options($this->page->course->id);
				
				$acceptedtypes = $overviewfilesoptions['accepted_types'];
				if ($acceptedtypes !== '*') {
					// Filter only files with allowed extensions.
					require_once($CFG->libdir. '/filelib.php');
					foreach ($files as $key => $file) {
						if (!file_extension_in_typegroup($file->get_filename(), $acceptedtypes)) {
							unset($files[$key]);
						}
					}
				}
				if (count($files) > $CFG->courseoverviewfileslimit) {
					// Return no more than $CFG->courseoverviewfileslimit files.
					$files = array_slice($files, 0, $CFG->courseoverviewfileslimit, true);
				}
			}
		}
		
		if(!empty($cfurl)) {
			$contentimages .= $cfurl;
		// This part has been borrowed and modified from course/classes/list_element.php
		} else if(!empty($files)) {
			foreach ($files as $file) {
				$isimage = $file->is_valid_image();
				$url = moodle_url::make_file_url("$CFG->wwwroot/pluginfile.php",
												'/' . $file->get_contextid() . '/' . $file->get_component() . '/' .
												$file->get_filearea() . $file->get_filepath() . $file->get_filename(), !$isimage);
				if ($isimage) {
					$contentimages .= html_writer::tag('div',
													html_writer::empty_tag('img', ['src' => $url,'loading' => 'lazy']),
													['class' => 'courseimage']);
				} 
			}
			
		}
		
		return $contentimages;
	}

Here I’m looping through the course’s custom fields and finding one that matches the right shortname ‘headerimage’ then I’m fetching the output for that (export_value) and returning that via $contentimages. There is very likely a quicker way of doing this since we know the shortname – something to look further into.