Atto

Since 2.7

Atto is a JavaScript text editor built specifically for Moodle. It is the default text editor in Moodle from 2.7 onwards, and is implemented as a standard Moodle text editor plugin. Most of the code is written in JavaScript using YUI modules.

All of the buttons in Atto are implemented as Moodle subplugins. This means that the subplugins can do anything a subplugin can do including, using language strings, database tables, other JavaScript, and more.

Sunset of Atto

A new Editor was created for Moodle 4.1 and later using the latest version of TinyMCE.

It is likely that Atto will be removed in Moodle 4.6.

File structure

Atto plugins are located in the /lib/editor/atto/plugins directory.

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.

View an example directory layout for the atto_media plugin.

 lib/editor/atto/plugins/media
 |-- db
 |   └-- upgrade.php
 |-- lang
 |   └-- en
 |       └-- atto_media.php
 |-- yui
 |   └-- src
 |        └-- button
 |           └-- atto_media.php
 |           ├── build.json
 |           ├── js
 |           │   └── button.js
 |           └── meta
 |               └── button.json
 |-- settings.php
 └-- version.php

Some of the important files for the Atto plugintype are described below. See the common plugin files documentation for details of other files which may be useful in your plugin.

version.php

Version metadata

Required

File path: /version.php

The version.php contains metadata about the plugin.

It is used during the installation and upgrade of the plugin.

This file contains metadata used to describe the plugin, and includes information such as:

• the version number
• a list of dependencies
• the minimum Moodle version required
• maturity of the plugin

View example

[path/to/atto]/pluginname/version.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Version metadata for the atto_pluginname plugin.
 *
 * @package   atto_pluginname
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO;   // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO;   // Available as of Moodle 3.9.0 or later.
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
    'mod_forum' => 2022042100,
    'mod_data' => 2022042100
];

lib.php

Global plugin functions

File path: /lib.php

An optional file which can be used to implement optional component callbacks.

The available callbacks are:

• atto_[pluginname]_strings_for_js - To add strings required by the YUI code
• atto_[pluginname]_params_for_js - To get the parameters required to instantiate the plugin

View example

[path/to/atto]/media/lib.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Plugin functions for the atto_media plugin.
 *
 * @package   atto_media
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

/**
 * Initialise the js strings required for this plugin.
 */
function atto_media_strings_for_js(): void {
    global $PAGE;

    $PAGE->requires->strings_for_js([
        'add',
        'width',
    ], 'atto_media');
}

/**
 * Sends the parameters to the JS module.
 *
 * @return array
 */
function atto_media_params_for_js(): array {
    global $OUTPUT, $PAGE;
    $currentlang = current_language();
    $langsinstalled = get_string_manager()->get_list_of_translations(true);
    $params = [
        'langs' => [
            'installed' => [],
        ],
    ];

    foreach ($langsinstalled as $code => $name) {
        $params['langs']['installed'][] = [
            'lang' => $name,
            'code' => $code,
            'default' => $currentlang == $code,
        ];
    }

    return $params;
}

yui/src/button/*

Example Button JavaScript

File path: /yui/src/button/js/button.js

The plugin must implement a YUI module that will be included by the editor when the page loads.

That YUI module must be named button and must create a namespaced class in Y.M.[plugin name].

View example

[path/to/atto]/media/yui/src/button/js/button.js

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Example Button JavaScript for the atto_media plugin.
 *
 * @module   atto_media/button
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

Y.namespace('M.atto_media').Button = Y.Base.create(
    'button',
    Y.M.editor_atto.EditorPlugin,
    [],
    {
        initializer: function() {
            this.addButton({
                callback: this._toggleMedia,
                icon: 'e/media',
                inlineFormat: true,

                // Key code for the keyboard shortcut which triggers this button:
                keys: '66',

                // Watch the following tags and add/remove highlighting as appropriate:
                tags: 'media'
            });
        },

        _toggleMedia: function() {
            // Handle the button click here.
            // You can fetch any passed in parameters here as follows:
            var langs = this.get('langs');
        }
    }, {
        ATTRS: {
            // If any parameters were defined in the 'params_for_js' function,
            // they should be defined here for proper access.
            langs: {
                value: ['Default', 'Value']
            }
        }
    }
);

note

It is recommended that you extend the EditorPlugin class as described below. See: YUI/Modules for more information about YUI modules.

The plugin:

• must register a class at Y.M.atto_PLUGINNAME.button;
• must provide a constructor; and
• should extend Y.M.editor_atto.EditorPlugin.

EditorPlugin

It is up to the plugin author to decide how best to write their plugin, but it is highly advisable to extend EditorPlugin class, which provides a number of useful functions for dealing with the Editor, Toolbars, Keyboard Navigation, and other related areas.

Of particular interest are:

• addBasicButton - to add a basic button which directly uses document.execCommand with minimal effort;
• addButton - to add a button giving you a greater degree of control via your own callback;
• addToolbarMenu - to add a dropdown toolbar menu;
• markUpdated - should be called after making changes to the content area; and
• getDialogue - return a standard dialogue, creating one if it does not already exist.