Adding Configuration Settings to Your Moodle Block Using PHP

Welcome back! In this post, we’re diving into PHP development, specifically for those creating blocks in the Moodle LMS. While this applies to blocks, the principles can be used for other Moodle plugins as well. Our focus today is on adding configuration options to your plugin so administrators can customize it from the M Moodle administration area without needing to alter any code.

What Does This Mean in Practice?

Let’s jump into the Moodle admin to see an example. If you navigate to “Plugins,” then “Blocks,” and look at a block like “Courses,” you’ll find various options that can be set. For instance, in the “Courses” block, there might be an “Admin view” setting where you can decide if the admin sees all courses or only their own.

These settings have a label, a unique ID, a description, a default value, and a defined field type. We’re going to create a similar admin interface for our own block, which will include text areas and a checkbox as our settings. These settings can be saved and then need to be reflected within our plugin.

How Do We Achieve This?

Let’s look at the three configuration settings we’ll add to our admin interface:

  1. Welcome Video Text: Allow the admin to change the introductory text displayed.
  2. Show/Hide Video: Give the admin the option to decide whether the video is displayed or not.
  3. YouTube Video ID: Provide a field to change the video to a different YouTube video by using its ID.

Diving into the Code

Let’s examine the necessary code changes. We have our plugin folder (e.g., “ricoshae demo”). Inside, you’ll typically find:

  • Language file: Contains strings for labels, descriptions, etc.
  • Default template: The HTML structure for displaying content.
  • Block file: The main file where the block’s content is generated.
  • Settings file: This is the crucial one for configuration options.

We’ll start with the settings.php file. If you don’t have one, create it in your block’s folder.

Creating settings.php

Inside settings.php, we first check if the admin tree is available:

if (admin->fulltree) {
    // Add our settings here
}Code language: PHP (php)

Then, we add each field using settings_add. Here’s how we add our three settings:

1. Welcome Text (Config Text)

settings_add(new admin_setting_configtext(
    'block_ricoshae_demo/welcome', // Unique ID
    get_string('setting_welcome_label', 'block_ricoshae_demo'), // Label
    get_string('setting_welcome_description', 'block_ricoshae_demo'), // Description
    'Welcome', // Default value
    PARAM_TEXT, // Data type
    120 // Text field length
));Code language: JavaScript (javascript)
  • block_ricoshae_demo/welcome: This is a unique identifier for this setting, combining the block name and the field name.
  • get_string(…): These functions retrieve the label and description from your language file.
  • ‘Welcome’: The default text for the welcome message.
  • PARAM_TEXT: Specifies that this is a text field.
  • 120: Sets the maximum length of the text field.

2. YouTube ID (Config Text)

settings_add(new admin_setting_configtext(
    'block_ricoshae_demo/youtube_id', // Unique ID
    get_string('setting_youtube_id_label', 'block_ricoshae_demo'), // Label
    get_string('setting_youtube_id_description', 'block_ricoshae_demo'), // Description
    '', // Default value (empty)
    PARAM_TEXT, // Data type
    60 // Text field length
));Code language: JavaScript (javascript)
  • This is similar to the welcome text, but with a different unique ID and a default empty value. The text field length is set to 60, as YouTube IDs are typically not longer than this.

3. Show Video (Config Checkbox)

settings_add(new admin_setting_configcheckbox(

    'block_ricoshae_demo/show_video', // Unique ID
    get_string('setting_show_video_label', 'block_ricoshae_demo'), // Label
    get_string('setting_show_video_description', 'block_ricoshae_demo'), // Description
    0 // Default value (0 for unchecked)
));Code language: JavaScript (javascript)
  • admin_setting_configcheckbox: This creates a checkbox setting.
  • 0: The default value is 0, indicating the checkbox is unchecked by default. When the checkbox is ticked, the value will be 1.

Connecting Settings to Your Language File

The get_string functions in the settings file reference strings in your language file. For example, in your language file (e.g., block_ricoshae_demo/lang/en/block_ricoshae_demo.php), you would have entries like:

$string['setting_welcome_label'] = 'ricoshae Block Welcome Text';
$string['setting_welcome_description'] = 'Enter the welcome text for the block.';
// Add similar entries for youtube_id and show_videoCode language: PHP (php)

These entries provide the actual text for the labels and descriptions displayed in the Moodle admin.

Seeing the Settings in Moodle

After saving your settings.php file and refreshing the Moodle admin, you should now see your new block with the configuration options you’ve added under “Plugins” -> “Blocks.” You can enter values for the text fields and tick/untick the checkbox.

Reflecting Settings in Your Block

Having the settings in the admin is only the first step. We need to make sure these settings are used to control the behavior and content of our block. This is done in your block’s main file (e.g., block_ricoshae_demo/block_ricoshae_demo.php).

Inside your block file, you’ll retrieve the saved configuration settings using get_config.

1. Using the Welcome Text

To use the welcome text entered by the admin, you would retrieve it like this:

$welcome_text = get_config('block_ricoshae_demo', 'welcome');Code language: PHP (php)

Then, in your block’s template file (e.g., block_ricoshae_demo/templates/default.html), you would use a placeholder (e.g., handlebars {{welcome_text}}) to display this text:

<h2>{{welcome_text}}</h2>Code language: HTML, XML (xml)

2. Using the Show/Hide Video Setting

To control whether the video is displayed, you retrieve the checkbox value:

$show_video = get_config('block_ricoshae_demo', 'show_video');Code language: PHP (php)

In your template, you can use conditional logic (e.g., handlebars #show_video and /show_video) to show or hide the video based on the $show_video value:

{{#show_video}}

{{/show_video}}Code language: PHP (php)

This will only display the video embed code if $show_video is 1 (checkbox is ticked).

3. Using the YouTube ID

To use the YouTube ID entered by the admin, you retrieve it:

$youtube_id = get_config('block_ricoshae_demo', 'youtube_id');Code language: PHP (php)

In your template, you would use this $youtube_id to construct the video embed URL:

<iframe src="https://www.youtube.com/embed/{{youtube_id}}" ...></iframe>Code language: HTML, XML (xml)

Putting It All Together

By following these steps, you can create a Moodle block with customizable configuration settings that administrators can easily manage. This allows for greater flexibility and usability of your plugins without requiring code changes.

Hopefully, this explanation has provided a clear understanding of how to set up configuration settings in your Moodle block using PHP. If you have any questions or need further assistance, feel free to ask!