# 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. Using advanced SPAW Editor features
7. Submiting bugs, feature request ,obtaining additional information
8. 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 or Mozilla/Firefox/Netscape 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, Czech, Brazilian Portuguese, Swedish, Danish, Hungarian, Bulgarian, Polish, Finish, Estonian, Japanese, Galego, Norwegian, Slovak, Catalan, Portuguese, Slovenian, Greek, Thai, Vietnamese, Korean, Ukrainian and Croatian 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);
- Optional design time borders on borderless tables;
- Active toolbar reflecting applicable features and current style;
- 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, modern Gecko based browsers on other OSs.

## License

This program is copyright © 2003-2004 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_active_toolbar - if set to true enables "active toolbar" feature. If you plan that editor will be used by users on slow computers you better set this to false.

$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_img_delete_allowed - if set to true delete button is shown in image library dialog.

$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.

$spaw_imglib_include - path to the include file to be included in image library. You can dynamically modify $spaw_imglibs array (set image libraries dynamically) and toggle upload and delete function on and off. $request_uri variable is set to the URI of the script where SPAW is located. You can parse it set libraries and other settings accordingly.

$spaw_a_targets - array holding selectable targets for hyperlinks (via hyperlink dialog). array index - target value, value - default text in dropdown. For example: $spaw_a_targets['_top'] = 'Top';. Control first tries to get the text from language file (hyperlink_targets block), if there's no text default text is used.

$spaw_img_popup_url - url to the image popup sript (inserted when image popup feature is used). You may use included script (default value) or create your own. Image url is passed via img_url query string parameter.

$spaw_internal_link_script - url to the script returning hyperlink data for links to internal content management system pages. See Advanced features for detailed information.

$spaw_disable_style_controls new - if set to true disables all style related properties in table and table cell dialogs when css class is selected.

## 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. Note: show() method should be called from the place in the script surrounded by <form></form> tags

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. $_POST['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($_POST['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($_POST['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($_POST['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($_POST['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($_POST['spaw6']) /*value*/,
                           'en' /*language*/, 'default' /*toolbar mode*/, '' /*theme*/,
                           '550px' /*width*/, '90px' /*height*/, '' /*stylesheet file*/,
                           $demo_array /*dropdown data*/);
    $sw->show();

## Using advanced SPAW Editor features

SPAW Editor has a number of advanced features allowing you to customize and control editor functions to even greater extent. These features are described in this section.

### Dynamic image libraries

You can create your own custom PHP script to manage image libraries dynamically based on user logged to your CMS or section of the site being edited or some other parameters. Specify path to this script via $spaw_imglib_include variable in config file. This file will be included in img_library.php (Image library dialog script). $request_uri variable will be set to the URL of the page where SPAW Editor instance resides. In your script you should set $spaw_imblibs array items to the image libraries you want to show in the image library for this instance. You can also enable/disable image upload and image deletion functions by setting $spaw_upload_allowed and $spaw_img_delete_allowed to true or false respectivelly.

### Internal links

Now you can provide a way for your users to add links to internal content management system pages via special dialog. You just have to create a script allowing user to select a page from the CMS and return the selection to SPAW in a special format.

To utilize this feature set $spaw_internal_link_script to the url of your script. "intlink" toolbar contains a special button declared like this:

    array(
    	'name' => 'internal_link',
    	'type' => SPAW_TBI_BUTTON
    ),

Adding such item to your toolbar enables internal link button. Now you need to return selected item from your script via JavaScript.

Your script will be show via showModalDialog JavaScript method. Object with the following properties will be passed (if it's link editing) and should be returned from your script:

- href - link url
- name - anchor name
- target - link target window/frame
- title - link title (shown as tooltip when mouse pointer is over a link in browser)
- description - hyperlink text (part between <a></a> tags)

You can get passed data in your dialog via window.dialogArguments JavaScript property. To return selected item assign the object to window.returnValue property before closing the window.

You can use SPAW's hyperlink dialog (dialogs/a.php) as an example of such script.

## 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-2005 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ôþchele (matthias.hoeschele@gmx.net);
- Dutch translation: Koen Koppens (k.koppens@home.nl), Alex Timmermans;
- Italian translation: Omar Di Marzio (omar@networking.it), Stefano Luchetta;
- French translation: Laurent Fasnacht (lf@o-t.ch);
- Hebrew translation: Yaron Gonen (lord_gino@yahoo.com), Boris Aranovich;
- Turkish translation: Zeki Erkmen (erkmen@t-online.de);
- Chinese translation: (aman@wealthgrp.com.tw);
- Czech translation: BrM (BrM@bridlicna.cz);
- Brazilian Portuguese translation: Fernando JosôþKarl (fernandokarl@superig.com.br);
- Swedish translation: Tomas Jogin (tomas@jogin.com);
- Danish translation: Morten Skyt Eriksen (xgd_bitnissen@hotmail.com);
- Hungarian translation: Bagoly Sôþdor Zsigmond (sasa@networldtrading.com);
- Bulgarian translation: Atanas Tchobanov (atanas@webdressy.com);
- Polish translation: Jacek Czekala (jacek_czekala@post.pl), Slawomir Jasinski;
- Finish translation: Teemu Joensuu (teemu.joensuusaunalahti.fi);
- Estonian translation: Maku (maktak@phpnuke-est.net);
- Japanese translation: DigiPower (http://pwr.jp/);
- Galego translation: Pedro Telmo (p.telmo@valminor.info);
- Norwegian translation: Torkil Johnsen (torkil@torkiljohnsen.com);
- Slovak translation: Pavel Koutny (pavel.koutny@inetix.sk);
- Greek translation: Saxinidis B. Konstantinos;
- Slovenian translation:Vladimir Ota;
- Portuguese translation: Ricardo Vidal;
- Catalan translation: Jordi Cato;
- Thai translation: Chanon Mee-iam;
- Vietnamese translation: Nguyen Viet Son;
- Croatian translation: dragan@pfri.hr;
- Ukrainian translation: Alexandr Kaplun;
- Korean translation: zionweb@hotmail.com.

SPAW Editor © 2003-2004 by Solmetra. All rights reserved.
$Revision: 1.2 $, $Date: 2005/05/04 15:13:48 $