Text formats 2.0

There have only been slight changes in how user-entered content is handled in 2.0, because there was not time to do a better job.

We are talking about the kind of rich HTML content that was input using the HTML editor, or other means.

Database structure

Any column that stores rich content input by the user should have a corresponding format column. For example, the forum.intro column has an associated forum.introformat column that days which format the data in the intro column is. The introformat column is holds an integer that is one of the FORMAT_MOODLE, FORMAT_HTML ... constants.

As another example, in the question table, there are two columns that hold rich-text, question.questiontext and question.generalfeedback and they both need a separate format column, so there are columns question.questiontextformat and question.generalfeedbackformat.

(Note that Moodle 1.x code should have done this, but it was not done consistently. In Moodle 2.0, all the missing ...format columns were added.)

Outputting

Like before, when you want to output content like this, you have to use the format_text function. You need to pass the appropriate content type to that function, and now, in Moodle 2.0, that format is always available because it is stored in the database with the content.

Editing

Rich content like this is edited using the editor formslib element type. How to use this element type is explained in the File API documentation.

Upgrading tables from Moodle 1.9

When upgrading to Moodle 2.0, you need to inspect all your database table, and find any missing format columns, and add them.

Then you need to go through all the existing data and fill in the correct format type, and possibly modify the content. In more detail, what you need to do is:

Inspect the old code, and work out how it is treating this content. Presumably it is being output using format_text. What format type is passed to those calls (hopefully it is the same everywhere). You need to set the format column to that value.
If, in future, people will be editing this content using the editor element, then convert any old FORMAT_MOODLE content to FORMAT_HTML, because that will work better in future. See #Example_1 below.
Change all the format_text calls you found to use the format type that is now stored in the database, rather than the old hard-coded constants.

Example 1

Here is some upgrade code from the forum module. The forum.introformat column already existed in Moodle 1.9, so we just need to convert any old FORMAT_MOODLE content to FORMAT_HTML.

We only do this if $CFG->texteditors !== 'textarea'. $CFG->texteditors is an admin setting that controls which acutal editors are available for use by the editor formslib element. If only the textarea editor is in use, then we do not covert. In all other situations we do convert.

To do the conversion, we call text_to_html() with the old content, and then the options false, false, true. If you look at how text_to_html() works, you will see why those are the appropriate options.

// Taken from mod/forum/db/upgrade.php
        if ($CFG->texteditors !== 'textarea') {
            $rs = $DB->get_recordset('forum', array('introformat'=>FORMAT_MOODLE), '', 'id,intro,introformat');
            foreach ($rs as $f) {
                $f->intro       = text_to_html($f->intro, false, false, true);
                $f->introformat = FORMAT_HTML;
                $DB->update_record('forum', $f);
                upgrade_set_timeout();
            }
            $rs->close();
        }

Example 2

This is a tricky case. I hope the comment explains it.

        // Update question_answers.
        // In question_answers.feedback was previously always treated as
        // FORMAT_HTML in calculated, multianswer, multichoice, numerical,
        // shortanswer and truefalse; and
        // FORMAT_MOODLE in essay (despite being edited using the HTML editor)
        // So essay feedback needs to be converted to HTML unless $CFG->texteditors == 'textarea'.
        // For all question types except multichoice,
        // question_answers.answer is FORMAT_PLAIN and does not need to be changed.
        // For multichoice, question_answers.answer is FORMAT_MOODLE, and should
        // stay that way, at least for now.
        $rs = $DB->get_recordset_sql('
                SELECT qa.*, q.qtype
                FROM {question_answers} qa
                JOIN {question} q ON a.question = q.id');
        foreach ($rs as $record) {
            // Convert question_answers.answer
            if ($record->qtype !== 'multichoice') {
                $record->answerformat = FORMAT_PLAIN;
            } else {
                $record->answerformat = FORMAT_MOODLE;
            }

            // Convert question_answers.feedback
            if ($CFG->texteditors !== 'textarea') {
                if ($record->qtype == 'essay') {
                    $record->feedback = text_to_html($record->feedback, false, false, true);
                }
                $record->feedbackformat = FORMAT_HTML;
            } else {
                $record->feedbackformat = FORMAT_MOODLE;
            }

            $DB->update_record('question_answers', $record);
        }
        $rs->close();

Documentation