Reason Developer Zone

Reason uses the "HTML Editor" type to represent editor plugins. This feature allows you to support multiple rich editors (e.g. WYSIWYG or lightweight markup) in a single Reason instance. To make a site use an editor that has been plugged in to Reason, you can simply edit the site and select the desired editor under the HTML Editor link.

How it works

Each HTML Editor entity in the database has an name and a html_editor_filename field. The html_editor_filename field refers to a plugin file in either the core or local html_editors directory.

The editor plugin files

Each plugin file defines three strings in the $GLOBALS array:

1. $GLOBALS[ '_html_editor_plasmature_types' ][ basename( __FILE__) ]: this should be the name of the plasmature type that will actually generate the appropriate markup for the editor plugin

2. $GLOBALS[ '_html_editor_param_generator_functions' ][ basename( __FILE__) ]: this should be the name of the function that provides the appropriate parameters for the above plasmature type (since each plasmature type may have a different parameter scheme)

3. $GLOBALS[ '_html_editor_options_function' ][ basename( __FILE__) ]: this should be the name of the function to use to get the available options for the editor plugin

This file should also contain the two functions referenced above, and possibly the plasmature class (if the plasmature class is not defined in plasmature proper).

The parameter generation function

The function referenced in the _html_editor_param_generator_functions array should take a site id as its first parameter and a user id as its second parameter. The user id must be optional. This function should return an array that may be passed to the plasmature object specified in the_html_editor_plasmature_types array.

Example:

function get_some_basic_params($site_id, $user_id = 0)

{

    $params = array();

  $params['site_id'] = $site_id;

      return $params;

}

The editor options function

The function referenced in the _html_editor_options_function array must take no parameters and must return an array of options supported by the plugin. The array returned must consist of simple strings. One of the strings will be stored by Reason in the loki_options field on sites which use this plugin. A simple editor may have only a single "defualt" option; a sophisticated editor may contain many options. Please note that each site can only have a single option, so each option will likely map to a batch of editor features.

Example:

function get_my_editor_options()

{

  $options = array('basic','advanced','expert');

      return $options;

}

How to add an editor to Reason

In the code:

1. Create a new file in lib/local/html_editors/.
2. Create a paramater generation function as described above
3. Create an editor options function as described above
4. Create a plasmature type class that will actually generate the appriate markup. This class should extend another plasmature class, so it will implement the full plasmature interface.
5. Add the three global values specified above. You can use one of the html editor files in the core as a guide.

In the database:

1. Add a new HTML Editor in the Master Admin. Select the file you just created when you add it.
2. To make a site use this new editor, edit the site and associate your new editor to the site under the link "HTML Editor".
3. To make your entire instance of Reason use the new editor, specify the plugin's filename in the REASON_DEFAULT_HTML_EDITOR constant in lib/local/settings.php

How to convert a form field to a rich editor field

Reason relies of the Disco/Plasmature framework for all forms, so you will need to be working with a Disco form to proceed. You will need to know the site context, and, if available, the Reason user ID of the currently logged-in user.

The following code is in the context of a content manager, but you can see, generally, how it would work in other contexts:

$this->change_element_type(

              'content' ,

         html_editor_name($this->admin_page->site_id) ,

                html_editor_params($this->admin_page->site_id, $this->admin_page->user_id)

);