# SPAW Editor (PHP Edition) Documentation

## Table of Contents

1. About SPAW Editor
2. License
3. Installation
4. Configuration
5. Using SPAW Editor in your applications
6. Submiting bugs, feature request ,obtaining additional information
7. Credits

## About SPAW Editor

Solmetra's SPAW Editor is a web based WYSIWYG editor control enabling web site developers to replace a standard textarea html control with full-featured, fully customizable, multilingual, skinable web based WYSIWYG editor.

Check out the online demonstration (IE 5.5 or above required) or screenshots to get an idea how powerful the control is.

Subscribe to spaw-announce mailing list to be notified about new releases.

Features included in this release:

- Basic text editor features (cut, copy, paste, undo, redo);
- Basic formatting features (bold, italic, underline, fore color, background color, fonts, etc.);
- Management of HTML objects (images, links, tables, etc.);
- Applying CSS classes to text and objects;
- Advanced image manipulation - image library sub-control (upload, preview and select images);
- Advanced table manipulation - create, modify attributes of table and cells, insert/delete rows and columns, merge/split cells (including unique vertical merging feature!!!);
- Support for themes (skins) - 2 ready to use themes included;
- Fully customizable toolbars - 4 presets included;
- Multilanguage support - English, Lithuanian, Russian, German, Dutch, Italian, French, Hebrew, Turkish, Chinese new and Czech new language files included;
- Support for multiple fully independent instances of control on the same page (each instance can have different theme, toolbar, language, style classes, etc.);
- HTML code cleanup (useful for copy/pasting content from MS Word) new;
- Optional design time borders on borderless tables new;
- Demo script showcasing the use of the control;
- Basic documentation (this file).

Requirements for PHP edition:

- Server: PHP4 on any compatible OS
- Client: Microsoft Internet Explorer 5.5. or above on Windows.

## License

This program is copyright © 2003 by Solmetra.
By using this program you agree to the terms of License Agreement found in license.txt file in docs directory

## Installation

Unzip the contents of the distribution to some location on your computer. If the location is not a place you intend to run the control from, upload the spaw directory to the location under your web sites root. As of final version 1.0 of the control you'll need to rename the file spaw_control.default.config.php in config sub-directory to spaw_control.config.php when installing control for the first time. This is done to prevent accidental overwriting of the config file when upgrading from one version to another. If you installed the control to the root of your web site you should be able to run demo.php script from scripts directory.

## Configuration

All of the SPAW Editor configuration options are located in the config/spaw_control.config.php file. If you have installed SPAW Editor for the first time you will need to create this file by simply renaming spaw_control.default.config.php to spaw_control.config.php in the config subdirectory. As you may have guessed from the extension it's a PHP file so you can do whatever you can do in PHP in this file if you need to add some additional instructions.

Now let's take a look at the configuration options available in the config file:

$spaw_dir - directory where spaw files are located. Set this to a virtual directory value relative from the root of your website

$spaw_base_url - this is used as a base url for images inserted through image library. It was introduced for cases when you access your admin area via different hostname than the one used by visitors. Set this to your web hosts root including the trailing slash (i.e. http://www.mycompany.com/).

$spaw_root - this is the physical directory where spaw control resides. This is calculated automatically and you don't need to explicitly set this if only in some very rare cases.

$spaw_default_toolbars - default toolbar mode to be used if no toolbar mode specified. Valid values are the names of subdirectories in lib/toolbars/ directory.

$spaw_default_theme - default theme (skin) to be used if no theme specified. Valid values are the names of subdirectories in lib/themes/ directory.

$spaw_default_lang - default language to be used if no language is specified. This is also used as a backup if selected language file has no translation for specific phrase. For this reason we suggest that, even if you always use the control in Italian, you leave it as 'en' because English language file will always be up-to-date and other language files may lack latest additions in the upcoming versions. Names of the subdirectories in there are the valid values for the $lang parameter.

$spaw_default_css_stylesheet - default stylesheet file to be used for the control's content. Set this to the virtual path to the css file.

$spaw_inline_js - if set to true forces SPAW to output functional javascript inline the including page. Otherwise script is included as external file via src attribute of script tag.

$spaw_dropdown_data - array holding values and texts for the toolbar items of dropdown type like style, font, fontsize and paragraph in the following format: $spaw_dropdown_data['control_name']['value'] = 'text';.

Following settings apply to image library dialog only

$spaw_valid_imgs - file extensions allowed for uploaded images.

$spaw_upload_allowed - if set to true users will be allowed to upload images in image library. Otherwise upload functionality is disabled.

$spaw_imglibs - array of arrays describing image libraries (directories), each array consists of 'value' element holding the path to the directory from the root without starting slash and 'text' element is a description visible to user.

## Using SPAW Editor in your applications

Using SPAW Editor is pretty simple and straight-forward:

1. Set $spaw_root variable to a physical path to the control's directory
2. Include spaw/spaw_control.class.php
3. Create an instance of SPAW_Wysiwyg class
4. Call show() method of the object

So as you can see it is indeed pretty simple. The main factor affecting the look and feel of the control is what you pass to the contstructor. Those who like learning by example should now switch to the source code and output of demo.php script in scripts directory.

The full interface of SPAW_Wysiwyg contructor is:

    SPAW_Wysiwyg(
                  $control_name='spaweditor', // control's name
                  $value='',                  // initial value
                  $lang='',                   // language
                  $mode = '',                 // toolbar mode
                  $theme='',                  // theme (skin)
                  $width='100%',              // width
                  $height='300px',            // height
                  $css_stylesheet='',         // css stylesheet file for content
                  $dropdown_data=''           // data for dropdowns (style, font, etc.)
                )

Parameters:

$control_name - the name of the control. This will be used for the id of the field holding the contents of the control and you will use it to obtain the contents when submitted to the server (i.e. $HTTP_POST_VARS['spaweditor']). The default value is "spaw_editor". Don't forget to set this parameter to different values if using more than one instance of the control on one page.

$value - initial content of the control. This is what you want to be in the editable area when control loads. Use something like `stripslashes($HTTP_POST_VARS['spaweditor'])` if you want control to display what was typed prior to submitting.

$lang - this denotes the language to be used in the control's interface. The default is the value of $spaw_default_lang variable set in config file which by default is equal to "en" (English). If you specify a value other than set in $spaw_default_lang variable, the control loads language data for default language as a "backup". This is done so in case the translation is a little outdated control is still usable (i.e. you will get messages in default language (most likely English) instead of missing translations from your selected language files. Available languages can be determined by taking a look at lib/lang/ subdirectory. Names of the subdirectories in there are the valid values for the $lang parameter.

$mode - toolbar mode (layout). Toolbar mode specifies the toolbar layout to be used for the instance. It defaults to the value of $spaw_default_toolbars config variable. You can also think of it as a way to limit (or extend) the features available to the user (this is why it was called mode). Valid values are the names of subdirectories in lib/toolbars/ directory.

$theme - the skin (look) of the control. This affects the images and rollover effects used for toolbar buttons and controls css styles. The default is the value of $spaw_default_theme config variable. Valid values are the names of subdirectories in lib/themes/ directory.

$width - control's width. The default is 100%.

$height - control's height. The default is 300 pixels.

$css_stylesheet - CSS stylesheet file to be used for control's content. The default is the value of $spaw_default_css_stylesheet config variable.

$dropdown_data - the array holding values to be used in a dropdown type toolbar controls like style, font, fontsize and paragraph. The structure is `$dropdown_data['control_name']['value'] = 'Text'`. The default data is taken from $spaw_default_dropdown_data config variable. You may use it as a starting point when customizing the dropdown data. You will most likely want to customize the data for the "style" dropdown cause it's the most instance specific of all dropdowns. Don't forget to provide the style with value "default". This one is used to remove the class attribute.

### Examples

#### Example 1

This is the simpliest usage of the control with all the default parameters

    $sw = new SPAW_Wysiwyg('spaw1',stripslashes($HTTP_POST_VARS['spaw1']));
    $sw->show();

#### Example #2

Now let's try something else... let's specify width and height of the control, Lithuanian language and different toolbar mode (sidetable in this example).

    $sw = new SPAW_Wysiwyg('spaw2' /*name*/,stripslashes($HTTP_POST_VARS['spaw2']) /*value*/,
                           'lt' /*language*/, 'sidetable' /*toolbar mode*/, 'default' /*theme*/,
                           '550px' /*width*/, '350px' /*height*/);
    $sw->show();

#### Example #3

In this example we pass an url (demo_red.css) of the stylesheet file to the consturctor/p>

    $sw = new SPAW_Wysiwyg('spaw5' /*name*/,stripslashes($HTTP_POST_VARS['spaw5']) /*value*/,
                           'en' /*language*/, 'mini' /*toolbar mode*/, '' /*theme*/,
                           '250px' /*width*/, '90px' /*height*/, 'demo_red.css' /*stylesheet file*/);
    $sw->show();

#### Example #4

There is a way to customize the content of the dropdowns like styles, fonts, etc. You can customize it for all instances of the control by modifying $spaw_dropdown_data array in config file or in the script. Or you can specify specific data for dropdowns for each of the separate instances. This example shows how...

    // make a copy of $spaw_dropdown_data array
    $demo_array = $spaw_dropdown_data;
    // unset current styles
    unset($demo_array['style']);
    // set new styles
    $demo_array['style']['default'] = 'Default';
    $demo_array['style']['crazystyle1'] = 'Crazy style no. 1';
    $demo_array['style']['crazystyle2'] = 'Crazy style no. 2';
    $demo_array['style']['crazystyle3'] = 'Crazy style no. 3';

    // pass $demo_array to the constructor
    $sw = new SPAW_Wysiwyg('spaw6' /*name*/,stripslashes($HTTP_POST_VARS['spaw6']) /*value*/,
                           'en' /*language*/, 'default' /*toolbar mode*/, '' /*theme*/,
                           '550px' /*width*/, '90px' /*height*/, '' /*stylesheet file*/,
                           $demo_array /*dropdown data*/);
    $sw->show();

## Submiting bugs, feature request, obtaining additional information

SPAW Editor's web site is located at http://www.solmetra.com/spaw/.

Open source development of SPAW Editor is powered by SourceForge.net.

SPAW Editor's main page at SF.net - http://sourceforge.net/projects/spaw

Find answers to your questions in SPAW Editor FAQ

If you find a bug in SPAW Editor please submit it to our SF.net bug tracking system

Submit your feature requests to SF.net RFE system.

Discuss your problems and ideas in forums

Subscribe to spaw-announce mailing list to be notified about new releases

Address all other inquiries to spaw@solmetra.com

## Credits

SPAW Editor copyright © 2003 by Solmetra. All rights reserved.

- Programming, documentation, "classic" theme, English and Russian language files - Alan Mendelevich (alan@solmetra.com);
- "default", "blue" and "green" themes - Margarita Buksnaityte (marga@solmetra.com);
- Lithuanian translation - Martynas Majeris (martynas@solmetra.com), Saulius Okunevicius (saulius@solmetra.lt);
- German translation - Simon Schmitz (schmitz@unitedfuor.com), Matthias Höschele (matthias.hoeschele@gmx.net);
- Dutch translation: Koen Koppens (k.koppens@home.nl);
- Italian translation: Omar Di Marzio (omar@networking.it);
- French translation: Laurent Fasnacht (lf@o-t.ch);
- Hebrew translation: Yaron Gonen (lord_gino@yahoo.com);
- Turkish translation: Zeki Erkmen (erkmen@t-online.de);
- Chinese translation: (aman@wealthgrp.com.tw);
- Czech translation: BrM (BrM@bridlicna.cz).

SPAW Editor © 2003 by Solmetra. All rights reserved.
$Revision: 1.6 $, $Date: 2003/04/29 17:10:05 $