Skip to content

Commit 6bf239e

Browse files
kainaat0110kainaat0110
authored
Update fields.md
This documentation should provide developers with a clear understanding of how to create, configure, and manage custom database fields in Moodle 4.4.3.(This version of the documentation adheres to markdown linting standards).
1 parent dfe8c9b commit 6bf239e

File tree

1 file changed

+100
-55
lines changed

1 file changed

+100
-55
lines changed

‎docs/apis/plugintypes/mod_data/fields.md‎

Lines changed: 100 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,126 @@
1+
2+
3+
## **Database Fields for Moodle 4.4.3**
4+
5+
*This documentation is a work-in-progress. Feel free to contribute.*
6+
7+
The **Database activity** in Moodle allows users to create structured collections of data, including support for predefined field types such as **text**, **date**, and **URL**. Developers can create custom field types for more specialized uses, ensuring flexibility and adaptability across different institutions or academic needs.
8+
9+
### **Custom Field Types Examples**
10+
- **Discipline-specific field types**:
11+
Example: *“Protein PDB code”* allows users to input a PDB code, which displays a 3D viewer of the protein structure or links to molecular databases.
12+
13+
- **Institution-specific field types**:
14+
Example: *“Library reference number”* enables users to input reference numbers that can convert into direct links for local library services.
15+
16+
- **Module-specific field types**:
17+
Example: *“Wiki page”* field provides a dropdown list of wiki pages, allowing users to link database entries to specific wiki content.
18+
119
---
2-
title: Database fields
3-
tags:
4-
- mod_data
5-
- datafield
6-
- plugintype
7-
- subplugin
8-
documentationDraft: true
20+
21+
### **File Structure for Field Sub-Plugins**
22+
23+
Custom database field sub-plugins are located in `/mod/data/field`. Each plugin is in a separate subdirectory with several required files, as well as any additional files developers might use.
24+
925
---
1026

11-
The [Database activity](https://docs.moodle.org/en/Database_module) included with Moodle includes support for several predefined [field types](./fields.md), including text, date, and URL. It is also possible to create new field types. For example, you might like to create:
27+
### **Key Files for Field Plugins**
1228

13-
- Discipline-specific field types - For example "Protein PDB code": users can enter the PDB code for a protein, and then the display 3D viewer for the protein structure, or link out to molecular databases.
14-
- Institution-specific field types - For example "library reference number": Allow users to enter a reference number which can be automatically turned into a direct link for local library services.
15-
- Module-specific field types - For example "wiki page": users see a drop-down list containing the names of pages in your wiki, and can choose which page this particular entry refers to.
29+
#### **1. `field.class.php` (Required)**
30+
Defines the field type, behaviors, and properties in a class named `data_field_[pluginname]`. This class must extend the `data_field_base` base class.
1631

17-
import { ComponentFileSummary } from '../../../_utils';
32+
#### **Key Functions to Override:**
33+
- `display_add_field($recordid = 0)`: Generates HTML for adding or editing a record.
34+
- `display_browse_field($recordid, $template)`: Generates HTML for browsing records.
35+
- `update_content($recordid, $value, $name = '')`: Saves data entered by the user.
36+
- `get_sort_sql($fieldname)`: Defines SQL for sorting the field.
37+
- `get_content_value($value)`: Retrieves the content that users will see, potentially transforming data before display.
1838

19-
## File structure
39+
---
40+
41+
### **Class Locations and Autoloading**
42+
43+
Custom field definitions reside in `field.class.php`, and **Moodle 4.4.3** still does not autoload this file. It is recommended to follow Moodle’s [autoloading guidelines](https://moodledev.io/docs/guidelines/files/autoloading) to future-proof your code and maintain compatibility with upcoming releases.
44+
45+
---
2046

21-
Database field sub-plugins are located in the `/mod/data/field` directory.
47+
### **Field Configuration Form**
2248

23-
Each plugin is in a separate subdirectory and consists of a number of _mandatory files_ and any other files the developer is going to use.
49+
#### **File Path:** `/mod.html` (Required)
2450

25-
<details>
26-
<summary>View an example directory layout for the `datafield_number` subplugin.</summary>
51+
This file defines the form for adding or editing the field configuration. It uses Moodle's **Form API** to create input elements.
2752

28-
```console
29-
mod/data/field/number
30-
├── classes
31-
│   └── privacy
32-
│   └── provider.php
33-
├── field.class.php
34-
├── lang
35-
│   └── en
36-
│   └── datafield_number.php
37-
├── mod.html
38-
└── version.php
53+
```php
54+
$mform->addElement('text', 'fieldname', get_string('fieldname', 'datafield_[pluginname]'), 'size="30"');
55+
$mform->setType('fieldname', PARAM_TEXT);
56+
$mform->addRule('fieldname', null, 'required', null, 'client');
3957
```
4058

41-
</details>
59+
**Note**: The form creation process for fields retains legacy elements and does not follow modern best practices. Developers are encouraged to update these forms and follow Moodle’s [Form API guidelines](https://moodledev.io/docs/apis/core/dml/moodleform).
4260

43-
Some of the important files for the database field plugintype are described below. See the [common plugin files](../../commonfiles/index.mdx) documentation for details of other files which may be useful in your plugin.
61+
---
4462

45-
### Field class
63+
### **Security Best Practices**
4664

47-
<ComponentFileSummary
48-
filepath="/field.class.php"
49-
required
50-
summary="Definition of the field type"
51-
/>
65+
Moodle 4.4.3 enforces updated security protocols. When creating custom fields, ensure that inputs are properly validated and sanitized. Use Moodle's security functions like `required_param()` and `optional_param()` to prevent attacks such as SQL injection and cross-site scripting (XSS).
5266

53-
The field, its behaviours, and its properties, are defined in a class named `data_field_[pluginname]` located in `field.class.php`. This class must extend the `data_field_base` base class.
67+
Example:
5468

55-
:::danger Class locations
69+
```php
70+
$input = required_param('input', PARAM_ALPHANUM); // Only accepts alphanumeric characters
71+
```
5672

57-
The field definition is currently located in the `field.class.php` file and is not yet autoloaded by Moodle.
73+
---
5874

59-
:::
75+
### **Testing and Compatibility**
6076

61-
The base class defines some simple behaviours which you can override in your plugin. The following functions are of particular interest:
77+
Custom field plugins must be tested for compatibility across Moodle 4.4.3 supported environments:
78+
- **PHP 8.1**
79+
- **MariaDB 10.6.7**
80+
- **MySQL 8.0**
81+
- **PostgreSQL 13**
82+
- **MSSQL 2017**
83+
- **Oracle 19c**
6284

63-
- `display_add_field($recordid = 0)` - Return some HTML for use when a user is adding/editing a record
64-
- `display_browse_field($recordid, $template)` - Return some HTML for displaying a record
65-
- `update_content($recordid, $value, $name = '')` - Store the data entered by a user for a record
66-
- `get_sort_sql($fieldname)` - Specify SQL for how this field should be sorted
67-
- `get_content_value($value)` - Useful if the info stored in the database if different from the info that ends up being presented to the user
85+
Developers should use Moodle’s [unit testing framework](https://moodledev.io/docs/apis/core/testing/phpunit) to automate testing and ensure plugin functionality in diverse environments.
6886

69-
### Field configuration form
87+
---
88+
89+
### **Form API Enhancements in Moodle 4.4.3**
90+
91+
Moodle 4.4.3 brings further improvements to the **Form API**, especially in terms of accessibility and UX. Ensure that custom field forms are:
92+
- **Mobile-responsive**
93+
- **Accessible**
94+
- **Optimized for modern browsers**
95+
96+
Make use of Moodle's standard form elements, ensuring that your forms adhere to accessibility guidelines.
97+
98+
---
99+
100+
### **Version Control and Deployment**
101+
102+
To ensure smooth development and deployment of custom field types:
103+
- Use Moodle’s **Git version control** system.
104+
- Maintain proper versioning to ensure compatibility with Moodle's plugin directory and version upgrades.
105+
106+
Developers should submit and maintain their plugins through the [Moodle Plugin Directory](https://moodle.org/plugins).
70107

71-
<ComponentFileSummary
72-
filepath="/mod.html"
73-
required
74-
summary="Form definition for adding and editing the field configuration"
75-
/>
108+
---
109+
110+
**Tags**: `mod_data`, `datafield`, `plugin`, `subplugin`
111+
112+
---
76113

77-
:::danger
114+
**Last Updated**: 2 October 2024
78115

79-
The field definition is one of the older parts of Moodle and does not use best practice.
116+
---
117+
118+
### **Key Considerations for Moodle 4.4.3:**
119+
- Use **updated coding standards** to align with Moodle’s guidelines for PHP 8.1.
120+
- Ensure that **security features** are in place to prevent vulnerabilities.
121+
- Maintain **compatibility** across all supported platforms and environments.
122+
- Follow **best practices** for creating forms and managing plugin configuration.
80123

81-
:::
124+
By adhering to these guidelines, you can ensure that your custom field types are modern, secure, and compatible with future Moodle versions.
125+
126+
---

0 commit comments

Comments
 (0)