Skip to content

Commit 424c1a5

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 424c1a5

File tree

1 file changed

+102
-55
lines changed

1 file changed

+102
-55
lines changed

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

Lines changed: 102 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,128 @@
1+
2+
---
3+
4+
```yaml
15
---
2-
title: Database fields
3-
tags:
4-
- mod_data
5-
- datafield
6-
- plugintype
7-
- subplugin
8-
documentationDraft: true
6+
title: "Database Fields for Moodle 4.4.3"
7+
last_updated: "2024-10-02"
8+
tags:
9+
- "mod_data"
10+
- "datafield"
11+
- "plugin"
12+
- "subplugin"
913
---
14+
```
15+
16+
# Database Fields for Moodle 4.4.3
17+
18+
*This documentation is a work-in-progress. Feel free to contribute.*
19+
20+
The **Database activity** in Moodle allows users to create structured collections of data. It supports various predefined field types like **text**, **date**, and **URL**. Developers can extend Moodle by creating custom field types, which are beneficial for specialized uses like discipline-specific, institution-specific, or module-specific needs.
21+
22+
## Custom Field Types Examples
23+
24+
- **Discipline-specific field types**:
25+
Example: *"Protein PDB code"* allows users to input a PDB code, displaying a 3D viewer of the protein structure or linking to molecular databases.
26+
27+
- **Institution-specific field types**:
28+
Example: *"Library reference number"* allows users to input reference numbers that convert into direct links for local library services.
29+
30+
- **Module-specific field types**:
31+
Example: *"Wiki page"* field provides a dropdown list of wiki pages, linking database entries to specific wiki content.
32+
33+
## File Structure for Field Sub-Plugins
34+
35+
Custom database field sub-plugins are located in `/mod/data/field`. Each plugin resides in a separate subdirectory and contains several required files.
36+
37+
## Key Files for Field Plugins
38+
39+
### 1. `field.class.php` (Required)
40+
41+
Defines the field type and its behaviors within a class named `data_field_[pluginname]`. This class must extend the `data_field_base` base class.
1042

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:
43+
### Key Functions to Override:
1244

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.
45+
- `display_add_field($recordid = 0)`: Generates HTML for adding or editing a record.
46+
- `display_browse_field($recordid, $template)`: Generates HTML for browsing records.
47+
- `update_content($recordid, $value, $name = '')`: Saves user input data.
48+
- `get_sort_sql($fieldname)`: Defines SQL for sorting records by the field.
49+
- `get_content_value($value)`: Retrieves and transforms the data for display.
1650

17-
import { ComponentFileSummary } from '../../../_utils';
51+
## Class Locations and Autoloading
1852

19-
## File structure
53+
Custom field definitions reside in `field.class.php`. **Moodle 4.4.3** does not autoload this file, so it is recommended to follow Moodle's [autoloading guidelines](https://moodledev.io/docs/guidelines/files/autoloading) to ensure future compatibility.
2054

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

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.
57+
**File Path:** `/mod.html` (Required)
2458

25-
<details>
26-
<summary>View an example directory layout for the `datafield_number` subplugin.</summary>
59+
This file defines the form for adding or editing the field's configuration. Moodle's **Form API** is used to create input elements. Here is an example:
2760

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
61+
```php
62+
$mform->addElement('text', 'fieldname', get_string('fieldname', 'datafield_[pluginname]'), 'size="30"');
63+
$mform->setType('fieldname', PARAM_TEXT);
64+
$mform->addRule('fieldname', null, 'required', null, 'client');
3965
```
4066

41-
</details>
67+
**Note**: The form retains some legacy elements, so developers are encouraged to update it to follow Moodle's [Form API guidelines](https://moodledev.io/docs/apis/core/dml/moodleform).
4268

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.
69+
## Security Best Practices
4470

45-
### Field class
71+
When creating custom fields, ensure inputs are properly validated and sanitized. Use Moodle's security functions, such as `required_param()` and `optional_param()`, to prevent SQL injection and XSS attacks.
4672

47-
<ComponentFileSummary
48-
filepath="/field.class.php"
49-
required
50-
summary="Definition of the field type"
51-
/>
73+
Example:
5274

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.
75+
```php
76+
$input = required_param('input', PARAM_ALPHANUM);
77+
```
78+
79+
## Testing and Compatibility
80+
81+
Custom field plugins should be tested for compatibility across Moodle 4.4.3's supported environments, including:
82+
83+
- **PHP 8.1**
84+
- **MariaDB 10.6.7**
85+
- **MySQL 8.0**
86+
- **PostgreSQL 13**
87+
- **MSSQL 2017**
88+
- **Oracle 19c**
5489

55-
:::danger Class locations
90+
Use Moodle's [unit testing framework](https://moodledev.io/docs/apis/core/testing/phpunit) for automated testing to ensure functionality across different environments.
5691

57-
The field definition is currently located in the `field.class.php` file and is not yet autoloaded by Moodle.
92+
## Form API Enhancements in Moodle 4.4.3
5893

59-
:::
94+
Moodle 4.4.3 introduces improvements to the **Form API** for better accessibility and user experience. Ensure that custom field forms are:
6095

61-
The base class defines some simple behaviours which you can override in your plugin. The following functions are of particular interest:
96+
- Mobile-responsive
97+
- Accessible
98+
- Optimized for modern browsers
6299

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
100+
Follow Moodle's accessibility guidelines to make sure your forms work well for all users.
68101

69-
### Field configuration form
102+
## Version Control and Deployment
70103

71-
<ComponentFileSummary
72-
filepath="/mod.html"
73-
required
74-
summary="Form definition for adding and editing the field configuration"
75-
/>
104+
To ensure smooth development and deployment of custom field types:
105+
106+
- Use Moodle's **Git version control** system.
107+
- Maintain proper versioning for compatibility with Moodle's plugin directory and version upgrades.
108+
109+
Developers should submit and maintain their plugins in the [Moodle Plugin Directory](https://moodle.org/plugins).
110+
111+
---
76112

77-
:::danger
113+
## Key Considerations for Moodle 4.4.3:
114+
115+
- Use **updated coding standards** to align with Moodle's guidelines for PHP 8.1.
116+
- Implement **security features** to avoid vulnerabilities.
117+
- Ensure **compatibility** across Moodle's supported environments.
118+
- Follow **best practices** for form creation and plugin configuration management.
119+
120+
By following these guidelines, developers can ensure their custom field types are secure, modern, and compatible with future Moodle releases.
121+
122+
---
123+
124+
**Last Updated**: 2 October 2024
125+
126+
---
78127

79-
The field definition is one of the older parts of Moodle and does not use best practice.
80128

81-
:::

0 commit comments

Comments
 (0)