Loading

WYSIWYG Editors and File Browsers

WYSIWYG Editors and File Browsers

Dada Mail supports the use of third party WYSIWYG HTML editors to allow you to compose and edit HTML mailing list messages. This allows you to send rich text messages right in Dada Mail's list control panel without needing to know any HTML. If you know HTML, all the better! These editors also allow you to view the source of the messasge for fine-tuning.

The HTML produced by these WYSIWYG editors is pretty good for the use of HTML emails, as most of the text formatting is done with inline css styles and these editors also have the ability to make simple HTML tables for basic layouts. Formatting rich text email messages is different than designing a contemporary web page - text formatting and layout is, on the whole, going to have to be much more simplified to work with the incredible spectrum of Things That Read Email (Web-based email services, Desktop-based mail readers, smart phones, toasters...).

Supported Editors

Dada Mail supports the following WYSIWYG HTML editors:

Supported File Browsers

As well as the core WYSIWYG functionality, Dada Mail also supports the File Browsers/Uploaders, allowing you to browse a directory on the server itself, as well as upload new files. Images uploaded may then be inserted into your HTML messages. This file browser/uploader is also used to browser and attach file attachments, to your message.

Two file browsers/uploaders are available for Dada Mail. Configurating which one is use happens during install time - you cannot switch between them, after installation/configuration.

KCFinder

Dada Mail supports KCFinder in all three WYSIWYG editors that it also supports. Dada Mail does not ship with support for the CKFinder file browser, which is developed by the same company that develops CKEditor, because it requires an additional commercial license. KCFinder is free software.

Core5 FileManager

Dada Mail also comes with, and supports Core5's creatively named, FileManager, which does a very similar job to KCFinder.

One big difference between KCFinder and FileManager is the backend code used for the server-side duties. In KCFinder, it's written in php. In FileManager, although many different connectors are available, we're shipping with only the Perl connector available. We've made changes to the connector to add security, which is otherwise completely missing. Because no security is available in any of the shippedd connectors by default, we do not suggest using them.

You may want to use FileManager, rather than KCFinder, if you get problems with KCFinder, related to either php or because you get errors like the following:

 You don't have permissions to browse server.

When attempting to upload a file.

Mailing List Configuration

You choose which WYSIWYG editor you would like to use (or to use no editor at all) in the list control panel under, Your List Control Panel - Options

Installing and Configurating - use the Dada Mail Installer

By far the easiest way to install and configure any of the WYSIWYG editors/file browser that Dada Mail supports is to use the included Dada Mail Installer and configure the WYSIWYG editors during install/upgrade.

When using the installer, you will simply need to set the absolute server path to a directory that you would like the editors to be installed under, as well as set the corresponding URL. The Dada Mail Installer will do the rest of the configuration. A sane default should already be filled in for you, usually set to your base public HTML directory and the corresponding URL.

Double check that this URL/absolute path is correct!

For example, if you're site is:

http://example.com

and the absolute server path that corresponds to that directory is,

/home/youraccount/public_html

Dada Mail will install a new directory under this location called, dada_mail_support_files.

Under that directory, it will place the editors, browser/uploader, and upload directory for the browser/uploader - all in their own seperate directory. So, inside the dada_mail_support_files directory, you may have the following:

If you upgrade Dada Mail, and tell Dada Mail to create a new .dada_config file (as opposed to Use the current .dada_config file), the installer will also reconfigure your WYSIWYG installs! If you use the same location to have the dada_mail_support_files directory (which we recommend!), it will move any editors or browser/uploaders it finds and reinstall them. It will not move or remove the file_uploads directory.

If you upgrade Dada Mail, and select, Use the current .dada_config file, nothing in your dada_mail_support_files directory will be touched, nor will your .dada_config file.

Manual Installation and Configuration

To install any of the editors/file browser, see their individual documentation. If you already have a preferred and working installation of any of these editors, it's also a simple task of just replacing what's potentially already set for the editor installation you already have.

Configuration of the editors to work with Dada Mail is done in the configuration variable, $WYSIWYG_EDITOR_OPTIONS, which looks like this:

        $WYSIWYG_EDITOR_OPTIONS = { 
                ckeditor    => { 
                        enabled => 0, 
                        url     => '', 
                }, 
                tiny_mce => { 
                        enabled => 0, 
                        url     => '', 
                },
        };

For each editor's parameters (ckeditor, tiny_mce), there are two more named parameters, enabled and, url.

enabled can be set to 1 to enable the editor, or 0 to disable. Disabled editors will not be available to be used in your mailing lists, even if they're installed on your hosting account. If any of your mailing lists have selected a editor that you then disable, they will default in using no editor.

url should hold the base URL for the editor itself - make sure to have a full URL, starting with, "http://"

File Browser/Uploader

Configuration for the file browser/upload for Dada Mail is done in the $FILE_BROWSER_OPTIONS variable, which should look like this:

        $FILE_BROWSER_OPTIONS ||= { 
                kcfinder  => { 
                        enabled      => 0, 
                        url          => '', 
                        upload_dir   => '', 
                        upload_url   => '',
                        session_name => 'PHPSESSID', 
                        session_dir  => '/tmp',
                },
                core5_filemanager  => { 
                        enabled      => 0, 
                        url          => '', 
                        upload_dir   => '', 
                        upload_url   => '',
                        connector    => '', 
                },
        };

KCFinder

The, kcfinder parameter has additional parameters to configure:

enabled can be set to 1 to enable KCFinder, or 0 to disable.

url should hold the base URL for KCfinder itself.

upload_dir should hold the absolute server path to the directory you would like files that are uploaded using KCFinder to be saved at. You will want this path to be under your public HTML directory, so that you can access the files placed within it via your web browser.

upload_url should hold the corresponding URL to the upload_dir variable - the upload_dir and upload_url should map to each other.

session_name and session_dir are used to configure and manage the sessioning information between Dada Mail and KCFinder. KCFinder will only work in Dada Mail, if the correct sessioning information is passed from Dada Mail, to KCFinder. For more information, please see KCFinder's docs on Integration and Sessioning:

http://kcfinder.sunhater.com/docs/integrate

The default value for session_name should work for the majority of users.

Dada Mail (when configured using the Installer) will use a directory called, php_sessions located in the, .dada_files/.tmp direcotory, to save its own, local, app-specific PHP session files.

Additional configuration for all three supported editors will be required to get KCFinder working with Dada Mail and these editors, which is also explained on the above URL.

There's potential that the values set in session_name and session_dir won't work for your environment. We'd like to know about it and what does work for you.

This doc does not go over what exactly needs to be configured in Dada Mail, as the best way to configure the WYSIWYG Editor/KCFinder/Dada Mail is still in flux. Best thing to do is to set up these editors and KCFinder with the Dada Mail Installer and study its configuration. We'd love your feedback.

Although Dada Mail ships with these editors and the file upload/browser in the,

dada/extras/packages

directory. We don't encourage you to either set the url parameters to use editors/etc directly from where they are, or even copy/move the editors/etc to a better location.

Rather, it's best to download them directly from the editors/etc. own site. The former probably won't work at all if you're installing Dada Mail inside your cgi-bin.

FileManager

The, core5_filemanager parameter has additional parameters to configure:

enabled can be set to 1 to enable FileManager, or 0 to disable.

url, upload_dir, and upload_url work the same as they do in KCFinder.

FileManager does not have, nor has a need for the following paramaters: session_name, session_dir. This is because we only use the Perl connector, an thus use Dada Mail's own sessioing system, written in Perl - no additional sessioning system is needed.

connector is available as a parameter, but at the moment, the only valid value is, pl, for the Perl connector.

Additional Configuration Files

CKEditor and TinyMCE also expect an additional configuration file called, dada_mail_config.js to be saved in the base URL of the editor. These configuration file should hold any additional configuration you would like for Dada Mail specifically. Again, setting up these editors to work with KCFinder is not covered in the configuration examples below - for now, we suggest using the Dada Mail Installer for that type of integration, or using your own custom configuration.

Copies of the default configuration files are stored in Dada Mail as HTML::Template templates and the configuration files themselves are created during install. These default templates reside at:

Customizing these templates before an installation/upgrade will change the actual configuration file Dada Mail creates.

Below are bare-bone examples of what these configuration files should hold.

Tiny MCE

        tinyMCE.init({
                        theme : "advanced",
                        theme_advanced_toolbar_location : "top",
                        theme_advanced_toolbar_align : "left",
                        mode : "specific_textareas",
                        editor_selector : "html_message_body",
                        verify_html : false             
        });

CKEditor

There is nothing specific that the CKEditor needs in its dada_mail_config.js. You can start by copying the config.js file to a file called, dada_mail_config.js (saved in that same directory) and make any additional changes that you would like in this new file.

KCFinder

KCFinder does not require this additional JavaScript file, but it's own default configuration file, kcfinder/config.php will be edited by the Dada Mail Installer.

When looking over this config file, One thing of particular importance is a variable not changed by Dada Mail, which look like this:

        $_CONFIG = array(
        
            'disabled' => true,

Setting the, disabled variable to, false (it's confusing, we know!) will circumvent the security of the KCFinder that's afforded by the sessioning system and leave your account open to unauthorized file uploads and potential exploits. So don't do that!

Image Drag and Drop Support

When using a supported browser, Dada Mail supports dragging and dropping images into the HTML WYSIWYG editor.

Image data is embedded in the HTML source of the message you write. Dada Mail will convert this embedded data into a file that will be saved in the KCFinder image/file upload directory. The image will then be available by browsing your upload directory, using the file browser/uploader itself.

See Also

WYSIWYG editors and Clickthrough Tracker URLS

Long Story Short, WYSIWYG editors break any Dada Mail template tags you set in the, "href" of any HTML tag - including sadly, Clickthrough Tracker tags - and may also munge up any template tags. Please! Send a test message out, before comitting to a large mass mailing! We suggest using the, Clickthrough Track All Message Links, option in the Tracker Plugin.

See: http://dadamailproject.com/d/tracker.cgi.html#clickthrough_tags_and_wysiwyg_editors__ckeditor_tiny_mce

for more information.

Dada Mail Project

Download

Installation

Support