Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update fields.md #1141

Closed
wants to merge 1 commit into from
Closed

Update fields.md #1141

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 98 additions & 55 deletions docs/apis/plugintypes/mod_data/fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,124 @@
---
title: Database fields
tags:
- mod_data
- datafield
- plugintype
- subplugin
documentationDraft: true

```yaml
---
title: "Database Fields for Moodle 4.4.3"
last_updated: "2024-10-02"
tags:
- "mod_data"
- "datafield"
- "plugin"
- "subplugin"
---
```
# Database Fields for Moodle 4.4.3

*This documentation is a work-in-progress. Feel free to contribute.*

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.

## Custom Field Types Examples

- **Discipline-specific field types**:
Example: *"Protein PDB code"* allows users to input a PDB code, displaying a 3D viewer of the protein structure or linking to molecular databases.

- **Institution-specific field types**:
Example: *"Library reference number"* allows users to input reference numbers that convert into direct links for local library services.

- **Module-specific field types**:
Example: *"Wiki page"* field provides a dropdown list of wiki pages, linking database entries to specific wiki content.

## File Structure for Field Sub-Plugins

Custom database field sub-plugins are located in `/mod/data/field`. Each plugin resides in a separate subdirectory and contains several required files.

## Key Files for Field Plugins

### 1. `field.class.php` (Required)

Defines the field type and its behaviors within a class named `data_field_[pluginname]`. This class must extend the `data_field_base` base class.

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

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

import { ComponentFileSummary } from '../../../_utils';
## Class Locations and Autoloading

## File structure
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.

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

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

<details>
<summary>View an example directory layout for the `datafield_number` subplugin.</summary>
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:

```console
mod/data/field/number
├── classes
│   └── privacy
│   └── provider.php
├── field.class.php
├── lang
│   └── en
│   └── datafield_number.php
├── mod.html
└── version.php
```php
$mform->addElement('text', 'fieldname', get_string('fieldname', 'datafield_[pluginname]'), 'size="30"');
$mform->setType('fieldname', PARAM_TEXT);
$mform->addRule('fieldname', null, 'required', null, 'client');
```

</details>
**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).

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

### Field class
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.

<ComponentFileSummary
filepath="/field.class.php"
required
summary="Definition of the field type"
/>
Example:

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.
```php
$input = required_param('input', PARAM_ALPHANUM);
```

## Testing and Compatibility

Custom field plugins should be tested for compatibility across Moodle 4.4.3's supported environments, including:

- **PHP 8.1**
- **MariaDB 10.6.7**
- **MySQL 8.0**
- **PostgreSQL 13**
- **MSSQL 2017**
- **Oracle 19c**

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

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

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

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

- `display_add_field($recordid = 0)` - Return some HTML for use when a user is adding/editing a record
- `display_browse_field($recordid, $template)` - Return some HTML for displaying a record
- `update_content($recordid, $value, $name = '')` - Store the data entered by a user for a record
- `get_sort_sql($fieldname)` - Specify SQL for how this field should be sorted
- `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
Follow Moodle's accessibility guidelines to make sure your forms work well for all users.

### Field configuration form
## Version Control and Deployment

<ComponentFileSummary
filepath="/mod.html"
required
summary="Form definition for adding and editing the field configuration"
/>
To ensure smooth development and deployment of custom field types:

:::danger
- Use Moodle's **Git version control** system.
- Maintain proper versioning for compatibility with Moodle's plugin directory and version upgrades.

Developers should submit and maintain their plugins in the [Moodle Plugin Directory](https://moodle.org/plugins).

---

The field definition is one of the older parts of Moodle and does not use best practice.
## Key Considerations for Moodle 4.4.3:

:::
- Use **updated coding standards** to align with Moodle's guidelines for PHP 8.1.
- Implement **security features** to avoid vulnerabilities.
- Ensure **compatibility** across Moodle's supported environments.
- Follow **best practices** for form creation and plugin configuration management.

By following these guidelines, developers can ensure their custom field types are secure, modern, and compatible with future Moodle releases.

---

**Last Updated**: 2 October 2024

---
Loading