SPAW Editor PHP Edition v.2 Integrator's Guide

Table of Contents

• About
• System Requirements
• Installation
  • Upgrade Information
• Configuration
  • Core Configuration Settings
    • Path Related Settings
    • Editor Defaults
    • SPAW Engine Settings
    • Dropdown Data
    • Toolbar Sets
    • Colorpicker Predefined Colors
  • SPAW File Manager Plugin Settings
• Usage
  • Changing Configuration At Runtime
    • Global Configuration Settings
    • Instance Configuration Settings
  • Applying Settings
  • Adding Pages
  • Toolbars
    • Using Toolbars
    • Floating and/or Shared Toolbars
    • Custom Toolbars
  • FileManager Settings

About

SPAW Editor PHP Edition is a web based WYSIWYG HTML editor control used to replace standard textarea fields in Content Management Systems (CMS) and other web based solutions requiring advanced, non-technical user friendly HTML snippet editing.

This document is a guide for CMS developers describing aspects of SPAW Editor integration in their respective systems. This guide doesn't contain any information on development of SPAW Editor plug-ins, visual skins, localization or client usage. For a complete guide, please, visit documentation section of our web site.

System Requirements

SPAW Editor PHP Edition v.2 runs on any PHP4 (tested on newer versions) or PHP5 setup. In some cases extra configuration of SPAW Editor might be necessary.

Installation

Installation is as simple as extracting files from the archive and uploading them to your web server. If this is a new SPAW v.2 installation then you also have to copy (or rename) configuration file config.default.php to config.php in config subdirectory. This step is necessary so you don't accidentally overwrite your configuration file when upgrading to a newer version.

On most Apache/PHP installations you'll be able to see a working instance of SPAW Editor v.2 by pointing your browser to demo/demo.php script under your SPAW directory.

Upgrade information

In case you are upgrading from SPAW Editor version 1.x you have 2 options.

You can use wrappers for v.2 that allow you to seamlessly replace v.1.x installation without changing a line of your code (provided you have used your 1.x in a standard way and didn't use advanced techniques like dynamic image libraries). In this case backup your SPAW 1.x directory and upload new files in the same directory where SPAW 1.x files were residing.

It is recommended, however, that you replace old code with new one. This way you can take advantage of all the advanced v.2 features like multi-document interface, floating toolbar, etc.

In both cases you'll need to configure SPAW v.2 because configuration subsystem has changed dramatically.

Configuration

SPAW v.1.x was configured by setting a bunch of global variables. This approach is completely gone from SPAW v.2. From now all configuration settings are held in a repository inside a special SpawConfig class. What you need to know is that configuration values are set in config file by calling class method of SpawConfig class called setStaticConfigItem. The method accepts 3 parameters: setting name, setting value and a value specifying the way this setting is passed around different components of SPAW Editor and plugins. All configurable options are set in default configuration file so most of the time you, as integrator, will only need to modify the values of the items found there. Configuration API is described in greater detail in plugin developers guide.

Plugins can have their own configuration settings which can be included in the global configuration file (config/config.php) or in a local config file in config subdirectory of plugins folder. It is safe to move plugin configuration settings from local config files to the global config file for better maintainability (unless otherwise specified by plugins author).

Core Configuration Settings

This section describes static (default for all instances) configuration settings for features that come with core SPAW Editor PHP Edition v.2 distribution. You can change values of these configuration parameters by modifying them in config/config.php file. You can also modify these settings on per instance basis in your code (see chapter on usage). Plugin related settings are described in their respective documentation.

Path Related Settings

These settings determine locations SPAW uses to load it's files. These are automatically calculated in most instances, but if you get errors in demo script or can't see button images, etc. this is where the problem most likely is.

Editor Defaults

These editor settings are used when certain properties aren't specified for SPAW instance

SPAW Engine Settings

These settings determine inner behavior of various SPAW engine components

Dropdown Data

These items hold data used to populate dropdown lists in the toolbars and dialogs. Values of these settings are PHP arrays. Array key goes to dropdowns option value, array value is displayed as dropdown text.

Toolbar Sets

Toolbar sets are just lists of toolbars. You can specify toolbars to be shown in your instance one by one or you can specify a toolbar set that contains all the toolbars you need.  The following table contains a list of predefined toolbar sets. You can create your own toolbar sets. Standard toolbar names are: edit, format, font, insert, table, tools and plugins. Theme developers specify places for specific toolbars but you can substitute "standard" toolbar with your own. To substitute a standard toolbar in toolbarset you set array key to standard toolbar name (like format) and array value to your substitute toolbar name (like format_mini). See "mini" toolbar set definition in default config file for a sample. Toolbar set config item names start with "toolbarset_" followed by toolbar name. For detailed explanation of toolbar customization read toolbar customization section below.

Colorpicker Predefined Colors

Starting from version 2.0.3 you can customize predefined colors in colorpicker dialog. To do that you set config item called "colorpicker_predefined_colors". The value of this setting should be an array of 16 elements or less. Each element of the array represents a predefined color in CSS compatible format.

SPAW File Manager Plugin Settings

File Manager plugin allows managing files on the server and selecting them for embedding into the text being edited (i.e. images, flash movies). It's task also is to let you control how your users access these files and what they can do with them.
To configure SPAW File Manager to match your needs you have to specify two main parameters: a "global" settings array which specifies what can be done with the directories accessible to SPAW File Manager, and a directories list. The global settings can be overriden for each specific directory so you can allow handling only images in your "Images" directory, only flash movies in your "Flash movies" directory and so on. Here is the detailed description for each of these two main parameters:

Usage

To use SPAW Editor in it's simpliest form you need to add only 3 lines of code to your scripts.

1. First you include SPAW's main include file like this:
   include("spaw2/spaw.inc.php");
2. Then you create an instance of SpawEditor object
   $spaw = new SpawEditor("spaw1", $content);
   where "spaw1" is the name of SPAW editor's instance (and it's first page, more on pages later) and $content variable holds initial editor content
3. And then you replace your textarea with a call to SPAW's show() method (or getHtml() if you want to get SPAW's code in a variable for later use)
   $spaw->show();

IMPORTANT: Don't forget to place a call to show() method inside your HTML form. You should also use POST as method attribute of your form.

When your form is submited you can get edited content by reading $_POST['spaw1'] (or $HTTP_POST_VARS['spaw1'] in older PHP4 versions)

Changing Configuration At Runtime

You can override configuration settings at runtime either on per-script/page or per-instance basis

Global Configuration Settings

You can read and override settings set in configuration file by using static methods of SpawConfig class. Here is the list of methods useful for these purposes:

Note: you should override global configuration settings before you create the first instance of SpawEditor in your script

The following example changes default height of all the editor instances on this page to 500 pixels:

SpawConfig::setStaticConfigValue('default_height','500px');

Instance Configuration Settings

You can change configuration settings for each instance of the editor on the page. While specialized methods (see below) are available for most of the core settings some core settings and all the plugin settings are only accessible via these methods of SpawEditor class (see chapter on File Manager for examples):

Applying Settings

SpawEditor class provides methods to overide default editor settings for current SPAW instance

Adding Pages

You can edit multiple documents (html snippets) with a single instance of SPAW Editor v.2. When you instantiate SpawEditor object, the first page with the same name as editor itself is added. You add more pages (or overwrite current page data) by using addPage($page) method. It acceps SpawEditorPage object as it's only parameter. SpawEditorPage constructor accepts 4 arguments: $name - the name of the page (you can read the code edited on this page by reading $_POST[$name] after submission), $caption - this is what is shown to the user on page's tab, $value - initial page content and $direction - text direction ('ltr' - for left-to-right, 'rtl' - for right-to-left, default - 'ltr').

So, let's say you want your SPAW instance to have 2 pages: one for the English article and one for it's Hebrew translation. You have initial content of the article and it's translation retrieved into $article and $article_hebrew variables respectively. You can do this with the following code:

$spaw = new SpawEditor('article');
// overwrite first page with meaningful caption and initial value
$spaw->addPage(new SpawEditorPage("article","English article",$article)); // left-to-right direction is assumed by default
// add additional page for Hebrew translation
$spaw->addPage(new SpawEditorPage("article_hebrew","Hebrew translation",$article_hebrew, 'rtl'));

Toolbars

Using Toolbars

You can control which toolbars are included with your instance by adding a toolbar set to your instance via addToolbarSet() method. You pass a toolbarset name (defined in config file) as an argument to this method.

You can also add toolbars without using toolbar sets with the following methods:

Floating and/or Shared Toolbars

In SPAW Editor v.2 single toolbar can control one or several editor instances. It can either be attached to one of the instances or floating around.

To enable floating toolbar you call setFloatingMode() method. It accepts SpawEditor instance as an argument. If you don't pass any arguments this instance of SpawEditor uses it's own toolbar. If you pass other SpawEditor object this instance will be controlled by toolbar of the instance you've passed.

In case you don't want to use floating toolbars but still want several instances controlled by a single toolbar you can use setToolbarFrom() method the same way as you would use setFloatingMode()

Custom Toolbars

You can create custom toolbars by copying one of the standard toolbars in plugins/core/lib/toolbars/ subdirectory and removing/adding toolbar items in that file. Unless you are a plugin developer (see plugin developers documentation) you only need to copy/paste or delete rows in these files. Theme designers can designate special placements for standard toolbars so, if you want your custom toolbar to appear in a place of standard toolbar you should add it to the instance with addToolbar() method using standard toolbar name as a substitute parameter.

FileManager Settings

Note: when you change settings defined with SPAW_CFG_TRANSFER_SECURE transfer type (for example FileManager settings described here) PHP session should be started in your script (with session_start();) for these settings to propogate to dialogs like FileManager

All SPAW File Manager settings defined in the config file will apply to all SPAW editor instances you create. There will be cases when you will want to have different settings and/or directories for different SPAW editor instances. Here is how you can set global File Manager settings for a specific SPAW Editor instance:

// setting global SpawFm settings for a SPAW editor instance:
$spaw->setConfigItem(
  'PG_SPAWFM_SETTINGS',
    array(
      'allow_upload' => true,
      'allow_modify' => true,
      'max_upload_filesize' => 0,
      'allowed_filetypes' => array('images', 'flash', 'documents'),
    ),
  SPAW_CFG_TRANSFER_SECURE
);

Here is how you set directories available to the File Manager of a specific SPAW editor instance:

// setting directories for a SPAW editor instance:
$spaw->setConfigItem(
  'PG_SPAWFM_DIRECTORIES',
  array(
    array(
      'dir' => '/myuploads/images/2006/',
      'caption' => 'Images 2006',
      'params' => array(
        'allowed_filetypes' => array('images')
      )
    ),
  ),
  SPAW_CFG_TRANSFER_SECURE
);

Sometimes redefining settings and/or directories for each SPAW Editor instance from scratch is not convenient, if they differ only slightly from the basic settings defined in config file. In this case a simplier way is to (re)define specific single global setting(s) and/or directories by one.
NB: you should not use this method if no global filemanager settings and directories were defined before.

// redefining global settings
$spaw->setConfigValueElement('PG_SPAWFM_SETTINGS', 'allow_upload', true);
$spaw->setConfigValueElement('PG_SPAWFM_SETTINGS', 'allow_modify', true);

// adding additional directory with global settings
$new_dir = array(
  'dir' => '/yet/another/dir/',
  'caption' => 'Specific files',
);
$spaw->setConfigValueElement('PG_SPAWFM_DIRECTORIES', sizeof($spaw->getConfigValue('PG_SPAWFM_DIRECTORIES')), $new_dir);

This way you can configure SPAW File Manager plugin to let you or your users to access exactly those files you want them to at the specific point of your nice application.