From f3ca38530867da533446aa360a9a80ff5b92f2da Mon Sep 17 00:00:00 2001 From: Kainaat Zaidi <110599444+kainaat0110@users.noreply.github.com> Date: Wed, 2 Oct 2024 16:10:43 +0530 Subject: [PATCH] Update fields.md --- docs/apis/plugintypes/mod_data/fields.md | 145 ++++++++++++++--------- 1 file changed, 89 insertions(+), 56 deletions(-) diff --git a/docs/apis/plugintypes/mod_data/fields.md b/docs/apis/plugintypes/mod_data/fields.md index 3d1bf3e009..0e6d87ffdd 100644 --- a/docs/apis/plugintypes/mod_data/fields.md +++ b/docs/apis/plugintypes/mod_data/fields.md @@ -1,81 +1,114 @@ + --- -title: Database fields -tags: - - mod_data - - datafield - - plugintype - - subplugin -documentationDraft: true ---- -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: +# 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. + +### 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) -
- View an example directory layout for the `datafield_number` subplugin. +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'); ``` -
+**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. - +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 - +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 + +---