Let the platform do the work
SugarClubContact+1 (877) 842-7276

TinyMCE

Overview

This article demonstrates how to work with the TinyMCE rich-editor field and customize its settings.

TinyMCE Field Type (htmleditable_tinymce)

Sugar provides a rich-text editor field using TinyMCE. This editor is used available when customizing templates and composing emails. As Sugar does not provide a way to create and use these field in Studio, we will demonstrate how to convert a text area field into a TinyMCE editor in the following sections.

Converting a Text Area to a TinyMCE Editor

As an example, we will use the Accounts' description field. The description fields type is by default text area. First of all, you will need to change the type of the field to htmleditable_tinymce using the displayParams vardef key.

  $dictionary['Account']['fields']['description']['type'] = 'htmleditable_tinymce';

Additionally, having a rich-text editor will require you to have a longer database field to store the HTML content. You will need to change the dbType to longtext and its length to 4294967295.

  $dictionary['Account']['fields']['description']['dbType'] = 'longtext';
$dictionary['Account']['fields']['description']['len'] = '4294967295';

After making these changes, the vardef definition will look as follows:

./custom/Extension/modules/Accounts/Ext/Vardefs/tinymce_description.php

    <?php
$dictionary['Account']['fields']['description']['type'] = 'htmleditable_tinymce';
$dictionary['Account']['fields']['description']['dbType'] = 'longtext';
$dictionary['Account']['fields']['description']['len'] = '4294967295';

Last, you will need to navigate Admin > Repairs and Perform Quick Repair and Rebuild.

Configuring the TinyMCE Editor

Configuring the TinyMCE editors can be done using the tinyConfig vardef key. The tinyConfig key maps to the TinyMCE configuration options. For example, if you would add a plugin into TinyMCE editor, you would modify the tinyConfig.plugins vardef key. An example of a vardef definition that will change the accounts description field to a custom TinyMCE Editor and modify its default TinyMCE settings is shown below.

./custom/Extension/modules/Accounts/Ext/Vardefs/tinymce_description.php

    <?php
$dictionary['Account']['fields']['description']['type'] = 'htmleditable_tinymce';
$dictionary['Account']['fields']['description']['dbType'] = 'longtext';
$dictionary['Account']['fields']['description']['len'] = '4294967295';
$dictionary['Account']['fields']['description']['tinyConfig'] = array(
    'plugins' => 'paste,autoresize,visualblocks,textcolor,table,emoticons,autolink,lists',
    'table_default_attributes' => array(
        'border' => '1',
    ),
    'target_list' => array(
        array(
            'title' => 'New page',
            'value' => '_blank',
        ),
    ),
    'default_link_target' => '_blank',
    'extended_valid_elements' => "a[href|target|data-mce-href]",
    'codesample_languages' => array(
        array('text' => 'HTML/XML', 'value' => 'markup'),
        array('text' => 'JavaScript', 'value' => 'javascript'),
        array('text' => 'CSS', 'value' => 'css'),
        array('text' => 'PHP', 'value' => 'php'),
    ),
    'toolbar1' => 'formatselect | bold italic underline strikethrough | bullist numlist | forecolor backcolor ',
    'toolbar2' => 'table tabledelete emoticons codesample | tableprops tablerowprops tablecellprops | tableinsertrowbefore tableinsertrowafter tabledeleterow | tableinsertcolbefore tableinsertcolafter tabledeletecol | visualblocks removeformat',
);

Since you are making changes in the vardef, you will need to navigate Admin > Repairs and run Quick Repair and Rebuild. Once you perform Quick Repair and Rebuild, the description of the Account records will have TinyMCE Editor that allows you to write rich-text content.

Plugins

Sugar is using TinyMCE v6. Most of the settings that you can define in tinyConfig are exist in TinyMCE documentation. However, it is important to know that plugins are limited with plugins that are provided by Sugar. These plugins can be found in ./include/javascript/tinymce6/plugins.

Sanitizing HTML Content

Sugar along with TinyMCE will strip HTML tags that do might pose risk when rendering the contents. TinyMCE itself has an option, defining which elements will remain in the edited text when the editor saves, called valid_elements and extended_valid_elements.

Sugar uses TinyMCE's default valid_elements as well as an extended tags available on file ./include/SugarTinyMCE.php.

Extending TinyMCE field (htmleditable_tinymce)

To extend the htmleditable_tinymce field, you should use the extension framework. Make sure that any configuration you add is compatible with TinyMCE v6.

If you've customized this file in the past and it still includes settings from previous versions of TinyMCE, it may not work properly with TinyMCE v6.

Example File

./custom/clients/base/fields/htmleditable_tinymce/htmleditable_tinymce.js

  /**
 * @extends View.Fields.Base.Htmleditable_tinymceField
 */
({
    extendsFrom: "Htmleditable_tinymceField",

    getTinyMCEConfig: function () {
        return {
            // Location of TinyMCE script
            script_url: 'include/javascript/tinymce6/tinymce.min.js?v=' + this.tinyMCEVersion,
            // Force loading of current version of tinyMCE plugin
            cache_suffix: '?v=' + this.tinyMCEVersion,

            // General options
            theme: 'silver',
            skin: app.utils.isDarkMode() ? 'oxide-dark' : 'oxide',
            content_css: [
                app.utils.isDarkMode() ? 'dark' : 'default',
                'styleguide/assets/css/sugar-theme-variables.css',
                'styleguide/assets/css/iframe-sugar.css',
            ],
            body_class: app.utils.isDarkMode() ? 'sugar-dark-theme' : 'sugar-light-theme',
            plugins: 'code,help,insertdatetime,table,charmap,' +
                'image,link,anchor,directionality,searchreplace,lists',
            browser_spellcheck: true,

            // User Interface options
            min_height: 250,
            menubar: false,
            statusbar: false,
            resize: false,
            toolbar_mode: 'wrap',
            toolbar: 'code | bold italic underline strikethrough | alignleft aligncenter alignright ' +
                'alignjustify | forecolor backcolor | fontfamily fontsize blocks | ' +
                'cut copy paste pastetext | search searchreplace | bullist numlist | ' +
                'outdent indent | ltr rtl | undo redo | link unlink anchor image | subscript ' +
                'superscript | charmap | table | hr removeformat | insertdatetime',
            // Sets the text of the Target element of the link plugin. To disable
            // this completely, set target_list: false
            link_target_list: [
                {
                    text: app.lang.getAppString('LBL_TINYMCE_TARGET_SAME'),
                    value: ''
                },
                {
                    text: app.lang.getAppString('LBL_TINYMCE_TARGET_NEW'),
                    value: '_blank'
                }
            ],

            // Output options
            entity_encoding: 'raw',

            // URL options
            relative_urls: false,
            convert_urls: false,

            // Insert image
            file_browser_callback: _.bind(this.tinyMCEFileBrowseCallback, this),

            // Allow image copy&paste
            paste_data_images: true,
            images_upload_handler: _.bind(this.tinyMCEImagePasteCallback, this)
        };
    },

})

Configuring the TinyMCE Editors used in BWC Modules

If you are looking for a solution with older TinyMCE that Sugar uses. You can try to create an override file and modify default settings. There are two different overrides that can be applied to buttons and default settings.

Overriding Buttons

The first override file is for the toolbar buttons. To do this, you must create ./custom/include/tinyButtonConfig.php. Within this file, you will be able to override the button layout for the TinyMCE editor.

There are 3 different layouts you can change:

  • default : Used when creating an email template
  • email_compose : Used when composing an email from the full form under the Emails module
  • email_compose_light : Used when doing a quick compose from a listview or subpanel

Example File

./custom/include/tinyButtonConfig.php

    <?php

    //create email template
    $buttonConfigs['default'] = array(
        'buttonConfig' => "code,help,separator,bold,italic,underline,strikethrough,separator,justifyleft,justifycenter,justifyright,justifyfull,separator,forecolor,backcolor,separator,styleselect,formatselect,fontselect,fontsizeselect,",
        'buttonConfig2' => "cut,copy,paste,pastetext,pasteword,selectall,separator,search,replace,separator,bullist,numlist,separator,outdent,indent,separator,ltr,rtl,separator,undo,redo,separator, link,unlink,anchor,image,separator,sub,sup,separator,charmap,visualaid",
        'buttonConfig3' => "tablecontrols,separator,advhr,hr,removeformat,separator,insertdate,inserttime,separator,preview"
    );

    //Standard email compose
    $buttonConfigs['email_compose'] = array(
        'buttonConfig' => "code,help,separator,bold,italic,underline,strikethrough,separator,bullist,numlist,separator,justifyleft,justifycenter,justifyright,justifyfull,separator,forecolor,backcolor,separator,styleselect,formatselect,fontselect,fontsizeselect,",
        'buttonConfig2' => "", //empty
        'buttonConfig3' => "" //empty
    );

    //Quick email compose
    $buttonConfigs['email_compose_light'] = array(
        'buttonConfig' => "code,help,separator,bold,italic,underline,strikethrough,separator,bullist,numlist,separator,justifyleft,justifycenter,justifyright,justifyfull,separator,forecolor,backcolor,separator,styleselect,formatselect,fontselect,fontsizeselect,",
        'buttonConfig2' => "", //empty
        'buttonConfig3' => "" //empty
    );

Overriding Default Settings

The second override file is for basic TinyMCE functionality. To do this, you must create ./custom/include/tinyMCEDefaultConfig.php. TinyMCE has quite a few settings that can be altered, so the best reference for configuration settings can be found in the TinyMCE Configuration Documentation.

Example File

./custom/include/tinyMCEDefaultConfig.php

    <?php

    $defaultConfig = array(
        'convert_urls' => false,
        'valid_children' => '+body[style]',
        'height' => 300,
        'width'    => '100%',
        'theme'    => 'advanced',
        'theme_advanced_toolbar_align' => "left",
        'theme_advanced_toolbar_location' => "top",
        'theme_advanced_buttons1' => "",
        'theme_advanced_buttons2' => "",
        'theme_advanced_buttons3' => "",
        'strict_loading_mode' => true,
        'mode'    => 'exact',
        'language' => 'en',
        'plugins' => 'advhr,insertdatetime,table,preview,paste,searchreplace,directionality',
        'elements' => '',
        'extended_valid_elements' => 'style[dir|lang|media|title|type],hr[class|width|size|noshade],@[class|style]',
        'content_css' => 'include/javascript/tiny_mce/themes/advanced/skins/default/content.css',
    );

Creating Plugins

Another alternative to customizing the TinyMCE is to create a plugin. Your plugins will be stored in ./include/javascript/tiny_mce/plugins/. You can find more information on creating plugins on the TinyMCE website.

the use and customization of TinyMCE.

Topics