Expression Engine Rich Text Editor Tools

Question

I'm trying to follow along with the rich text editor documentation in expression engine, but it's a little unclear to me:

http://ellislab.com/expressionengine/user-guide/development/rte_tools.html

I created a php file like this:

Class center_text {

    public $info = array(
        'name'        => 'Center Text',
        'version'     => '1.0',
        'description' => 'Center Aligns Text',
        'cp_only'     => 'y'
    );

    private $EE;

    /**
     *  Constructor
     */
    function __construct()
    {
        // Make a local reference of the ExpressionEngine super object
        $this->EE =& get_instance();
    }

    /**
     *  Globals we need defined
     */
    function globals()
    {
        $this->EE->lang->loadfile('center_text');
        return array(
            'rte.center_text.label' => lang('center_text')
        );
    }


    /**
     *  RTE tool Definition
     */
    function definition()
    {
        return '

        WysiHat.addButton('center_text', {
            label: EE.rte.center_text.label,
            handler: function()
            {
                // Button Logic
            }
        });

        ';
    }

}
// END center_text_rte class

/* End of file rte.center_text.php */
/* Location: ./system/expressionengine/third_party/center_text/rte.center_text.php */

Named and placed as mentioned in the comments. I realize that this wouldn't exactly do anything just yet (I still don't know how to make that happen) - but I would expect it to show up as an option now in the toolset of the rich text editor, but it's not.

Does anyone have an example tool they've built for the RTE, or can point me to the default tools so I can see how they're set up. All I really want to do is define some very simple styles that CMS users can apply to their text, and the css will handle the rest (such as center, left, or right aligning text).

Thanks for any help or clarification on this.

• • UPDATE - -

I found the rte_tools folder in the system > expressionengine directory, and copied the "bold" example, and just changed the names to center_text, then saved to that same directory, but still nothing shows up.

Here's the revised code:

<?php  if ( ! defined('BASEPATH')) exit('No direct script access allowed');

/**
 * ExpressionEngine - by EllisLab
 *
 * @package     ExpressionEngine
 * @author      Mike Heavers
 * @copyright   Copyright (c) 2012, Mike Heavers
 * @license     http://expressionengine.com/user_guide/license.html
 * @link        http://expressionengine.com
 * @since       Version 2.5
 * @filesource
 */

// ------------------------------------------------------------------------

/**
 * ExpressionEngine Bold RTE Tool
 *
 * @package     ExpressionEngine
 * @subpackage  RTE
 * @category    RTE
 * @author      Mike Heavers
 * @link        http://mikeheavers.com
 */
class Center_text_rte {

    public $info = array(
        'name'          => 'Center Text',
        'version'       => '1.0',
        'description'   => 'Centers Text',
        'cp_only'       => 'n'
    );

    private $EE;

    /**
     * Constructor
     *
     * @access  public
     */
    function __construct()
    {
        // Make a local reference of the ExpressionEngine super object
        $this->EE =& get_instance();
    }

    // --------------------------------------------------------------------

    /**
     * Globals we need
     *
     * @access  public
     */
    function globals()
    {
        $this->EE->lang->loadfile('rte');
        return array(
            'rte.center_text'  => array(
                'add'       => lang('center_text'),
                'remove'    => lang('remove_center_text')
            )
        );
    }

    // --------------------------------------------------------------------

    /**
     * JS Definition
     *
     * @access  public
     */
    function definition()
    {
        ob_start(); ?>

        WysiHat.addButton('center_text', {
            label:          EE.rte.center_text.add,
            'toggle-text':  EE.rte.center_text.remove
        });

<?php   $buffer = ob_get_contents();
        ob_end_clean(); 
        return $buffer;
    }

} // END Center_text_rte

/* End of file rte.center_text.php */
/* Location: ./system/expressionengine/third_party/center_text/rte.center_text.php */

Answer 1

Ok, this is something it looks like Ellis is not ready to really let people do even though it's in documentation, except perhaps developers who would provide via a full add-on installer and handling. However, it is possible.

a. First, there is an EE interface to install new button features, but it is not called anywhere, Addons_installer:install_rte_tool. All it does is add a record to the database table exp_rte_tools, which you can do manually via phpMyAdmin or similar, comparable to other records in the table.

Here we've added Mytool:

However, you'll want to have your Mytool_rte class source code in place before you do this, as there is a feature in EE that automatically removes these tool records when the Rich Text field starts up, if the source isn't present. You can read about that here.

So let's get everything else set up, and then you can to add your database record before testing.

b. Where should you put your source code, and what are particulars it needs?

• You put your button source folder in system/third_party
• You name your source folder with a single lowercase base name; example mytool
• The tool filename is rte. plus this name; example rte.mytool.php
• The class inside is the name with initial cap, plus _rte; example Mytool_rte

At this point, go through the file and change all references to the example you copied from so that they match mytool, or My Tool, etc., instead of the original. Also put what you like in the $info array values.

c. locate the function definition(). This is going to insert JavaScript into the user interface as your button is added. You're on your own as far as discovering what may be necessary to put in it as far as events, etc., but I want to warn on one point. Do not have a line defining 'name:' within WysiHat.addButton('mytool'){}. It's a possible WysiHat feature, but if you use it, you'll blank the entire RTE button bar. Something Ellis.

I would just stick with using a label: at first. Here's an example, with a label line instead, and a name line commented out to remind:

function definition()
    {
        ob_start(); ?>

        WysiHat.addButton('mytool', {
            // name:        'MyTool'
            label:      'MyTool'
        });

<?php   $buffer = ob_get_contents();
        ob_end_clean(); 
        return $buffer;
    }

d. Ok, now add your database record as in item 1. When you are successful, then you can go to Add-Ons>Modules>Rich Text Editor in the Control Panel, and click on the default Toolset, to get a drag-drop panel which should contain your MyTool on the left side. Drag it to the right side and position it in the order where you want it, then Submit.

e. At this point, you should be able to try a Publish page with a Rich Text field, and see your button in position. It will be blank, grey, and small.

f. Can we get an appearance as Ellis has for the stock RTE buttons? Actually, we can, and more easily than I had thought, as their interface and behavior is sensible.

Most buttons use CSS background images, defined in a multi-image sprite here: themes\cp_themes\default\images\rte_images\button-sprite.png. The appropriate images (note there are two per button, one a greyed version) are selected by background-position CSS.

There's one button which doesn't use an image, but shows its label text, the one on the right end to View Code. Let's emulate that one, as you can build your own pngs or sprite later if you want image buttons.

g. Alter or add a function as the following in your class. Note that it's attuned to mytool, and don't forget the 'b', as it's targeting what will be bold text markup on your label. This function will stack CSS in with what the CP already provides. In this case the markup removes the background image, and makes some minor placement for your label's text:

        function styles()
        {
            ob_start(); ?>

            .WysiHat-editor-toolbar .mytool b {
                background-image: none;
                            text-indent: 0;
                            padding-top: 1px;
            }

    <?php   $buffer = ob_get_contents();
            ob_end_clean(); 
            return $buffer;
        }

Now reload the Publish page in the CP, and you should have a Rich Text menubar like this, with your mytool button nicely showing. Notice that the button auto-sized to fit your text, and that you could add a line borrowed from the View Code style function CSS if you wanted it all capitalized, etc. Spaces in the original label:, as 'My Tool', would also have been fine:

Ok, I think we're complete. If you made the images for your buttons, you can alter the CSS here to use them, following the examples in themes\cp_themes\default\css\rte.css, and being sure to allow for the greyed versions and so forth by defining :hover, :disabled, aria-pressed=true etc. as is done there.

I'd put the full source here, but as it's derivative of Ellis, and given their recent legalities even though their intent is to be copied in this case, seems better not.

Good fortune with this, and it's been a good exercise to see what's going on in today's EllisLab work.