Rich Editor Documentation

Date: 13 april 2005, Version: 2.0

Table of Contents

1. About the Rich Editor

Rich Editor (RE) is a browser-based online WYSIWYG html editor. The editor is to be used in content management systems or just instead of <TEXTAREA> tags in forms to create/edit html formatted text and whole html pages.

100% script (javascript and php). Easy to install. No additional Java Applets or ActiveX components are required! Works with Internet Explorer 5.x+ (Windows only), Netscape 7.1 / Mozilla 1.4+. MSIE 6.x is recommended. Implemented as a PHP class. Multiple instances of RE on the same page are supported. Generates source code in common HTML and XHTML 1.0 format.

No knowledge of HTML required. Advanced work with images, including file uploading, tables, links, stylesheets, flash and more!

Active and simple modes of the editor. Adjustable toolbar. Works with server-side files and folders. Colored source code. Multilingual support. And more!

2. Features

• 100% DHTML, JavaScript and PHP code
• No slow Java applets or ActiveX components, no plugins required
• No programming skills required
• Interface is similar to Microsoft Word
• Edit content in WYSIWYG and source code mode
• Implemented as a PHP class - easy to use in scripts, in content management systems
• Multiple editors -- create as many editors on the same page, as you need, size of scripts loaded is the same
• Can be used instead of <TEXTAREA> tags in forms
• Possible to edit not only parts of html documents, but the whole web pages as well!
• You can change properties of html page you modify with the editor
• If user is not using browser supported, <TEXTAREA> tag is shown
• Work with remote files and remote directory structure
• Upload local files from client computer (no FTP knowledge required)
• Active mode -- button, pressing on which will take no effect, becomes inactive
• Simple mode (adjustable). Restricted number of buttons drawn -- useful for novice users
• XHTML mode. Generates source code in XHML 1.0 format
• Full screen mode. Editor expands on whole browser client area
• Html snippets (custom html code). In the snippet dialog window user can see preview of snippet selected before pasting it in document. Groups of snippets supported
• On-rightclick context menu
• Multilingual support
• You can re-brand it to offer as a part of your commercial products
• If you need something else, write us. Most popular features are added first!

• Toolbar buttons' state corresponds to formatting of text in the current cursor position
• Select paragraph, font type, font size and formatting (bold, italic, underline, strikethrough, superscript and subscript), remove formatting
• Change foreground and background color of text using color picker
• Indent and outdent
• Ordered and unordered lists
• Text alignment
• Cut, copy and paste text
• Advanced work with hyperlinks, including targets. Create hyperlinks to files at server; upload files from your computer. Select text or controls to create hyperlinks.
• Full stylesheet support. Create style class definitions and/or insert links to *.css files inside RE!
• Default stylesheet files. You can set any number of *.css files to be loaded in editor by default. It is useful when you edit parts of html pages, so you do not need to include style class definitions in each html text you edit separately to see their real looking
• Insert special chars
• Paste text from Microsoft Word

• Advanced work with tables. Insert and edit tables and table cells. Set border, alignment, cellpadding, cellspacing, bgcolor, background image and more!
• Insert/delete columns, rows or cells, merge/split cells
• Right click on table border or inside table cell to edit them
• Show invisible table borders feature

• Advanced work with images/flash. Insert and edit images/flash, upload new images/flash files from your computer; set image width, height, alt, border and more!
• Right click on image/flash to edit
• Preview local and server-side images/flash

Note: if you do not see local flash preview, please, install the latest version of flash player from macromedia.com.

• You can create and edit forms and form elements. Text field, text area, buttons, hidden field, checkbox, radio button and list box elements are supported
• Right click inside a form or on a form element to edit them
• Show invisible form borders feature

• Dutch
• English
• French
• Hungarian
• Japanese
• German
• Russian
• Spanish
• Turkish

3. Requirements

• Web browser: Internet Explorer 5.0+ (Windows), Netscape 7.1/Mozilla 1.4+ or other Gecko based browser (otherwise a normal <TEXTAREA> tag appears). Internet Explorer 6.0 is recommended
• JavaScript: must be enabled
• Web Server: Apache Web Server or Internet Information Server (IIS)
• Server Scripting Language: PHP 4.0 or above
• You must have rights to execute PHP scripts in your files and write in your directories at server

4. Installation&Using

You must have possibility to run PHP scripts inside your files and rights to write in your directories at server!

1. Copy directory 'class' on server. There must be access to this directory through an URL.
2. Add at the top of file, where you want RE to be used, code of the form:

<?php
	$class_path = "path to 'class' folder";
	require_once($class_path."class.rich.php");
?>

Here
"path to 'class' folder" is a string with path to folder 'class', where RE files are, e.g. "class/", if your script and this folder are in the same folder. The path should be relative to current folder of your script using RE

Alternative method


<?php
	$class_path = "path to 'class' folder relative to site root";
	require_once($path_to_class_folder."class.rich.php");
?>

Here
"path to 'class' folder relative to site root" is a string with path to folder 'class' relative to site root, eg '/re/class/' for folder 'http://www.yourdomain.com/re/class/'
"path_to_class_folder is a server side path to folder 'class' (could be set eg to $_SERVER['DOCUMENT_ROOT'].$class_path to be independent of where your script using RE is placed:

<?php
	$class_path = "/re/class/";
	require_once($_SERVER['DOCUMENT_ROOT'].$class_path."class.rich.php");
?>
In this case you do not need to change these settings even if you move the file using RE to another folder of your site

No global variables method

To avoid using of global variable $class_path it is possible to use function

	$editor->set_class_path($class_path);

where $class_path is path to folder 'class'

Such approach is necessary when you have to create editor's instances inside your own functions where global variables are not seen. In case when this function is not used to set path to folder 'class' the editor will use global variable $class_path

Note: variable $editor must be declared yet and function set_class_path must be called before methods get_rich() or draw()

3. Insert the following two strings inside tag <HEAD>:

<link rel="StyleSheet" type="text/css" href="<?php echo $class_path; ?>rich_files/rich<?php echo $rich_prefix; ?>.css">
<script language="JavaScript" src="<?php echo $class_path; ?>rich_files/rich<?php echo $rich_prefix; ?>.js"></script>
<script language="JavaScript" src="<?php echo $class_path; ?>rich_files/rich_xhtml.js"></script>

Note: the last line could be omitted if you do not use XHTML mode.

Also it is possible to insert the code using the following function:

	echo rich_get_head_code($class_path);

where $class_path is path to folder 'class'

or method

	echo $editor->get_head_code();

Note: In this case variable $editor must be declared yet

4. Code to create RE instance is of the form:

<?php
	$editor = new rich($caption, $name, $value, $width, $height, $files_path,
			$files_url, $page_mode, $absolute_path);
	$editor->draw(); // or echo $editor->get_rich();
?>

Here
$caption is a string, appearing before RE in page (caption of editor),
$name is name of the textarea element, which is used to send edited text through forms (must be unique, if you create several editors),
$value is a string with initial content of the editor (can be empty),
$width is width of the editor (can be in absolute values or in %s),
$height is height of the editor (can be in absolute values or in %s),
$files_path is a string with path to top directory for uploaded files relative to site root, eg '/files/', or to folder 'class', eg '../files/' (useful if you use aliases)
$files_url is string with url to top directory (directory $files_path) for uploaded files,
$page_mode - set it to true to edit the whole pages, otherwise can be omitted.
$absolute_path - set it to true to refer to files at server through absolute paths (default), otherwise -- through relative (to site root) paths.

Note: if $absolute_path is set to false, $files_url should specify url to folder for uploading relative to site root. I.e. if folder for uploading is 'http://www.yoursite.com/files/upload/', this variable should be set to '/files/upload/'. In this case, all urls in content will not depend on name of site domain. Value of $files_path does not depend on the mode used.

5. Add 'save_in_textarea_all' function to onsubmit event handler, e.g:

<form action="" method="post" onsubmit="save_in_textarea_all();">

RE appears on page in the place, where method draw() is called. Also you can use get_rich() method to get code of the editor and then output it to a variable or to browser. It could be useful if you are going to use the editor with a template engine.

File check_auth.inc.php contains variables that could be used to restrict user actions such as uploading, creating new folders, renaming of deleting files and folders. Also it is possible to specify file extensions available for files uploaded, to restrict size of files uploaded or the total size of folder for the files.

It is possible to set values for all settings defined in file check_auth.inc.php through API functions. These functions use session technique, so sessions should be set correctly on your server. Cookies support in cliens' browsers are not required.

To use the functions you should uncomment the following line in check_auth.inc.php:

Or you can uncomment it for all cases if you always use sessions

This line initially commented as sessions are not required by RE, but if sessions are not configured correctly on your server a warning will be printed by PHP every time session_start() is called

  Function list

• set_avail_paths($paths); //set paths available for uploading, renaming, etc
  Example: $editor->set_avail_paths(array('/files/uploaded/', '/files/shared/'));
   
• set_total_size($size); //max available size (in bytes) of files uploaded
  Example: $editor->set_total_size(1024*1024);
   
• set_can_upload($can_upload); //enable or disable uploading
  If $can_upload is set to true then uploading will be enabled. Otherwise disabled
   
• set_max_size($max_size); //set max size (in bytes) of file available for uploading
  Example: $editor->set_max_size(1024);
   
• set_allow_override($allow_override); //set permission to override existing files
  Set $allow_override to true to allow overriding, otherwise set it to false
 
• set_avail_files($files); //set file extensions available for uploading and renaming
  Example: $editor->set_avail_files(array ('zip', 'txt'));
   
• set_not_avail_files($files); //set file extensions not available for uploading and renaming
  Example: $editor->set_not_avail_files(array ('php', 'pl'));
   
• set_avail_images($images); //set image types available for uploading and renaming
  Example: $editor->set_avail_images(array ('gif', 'png'));
   
• set_not_avail_images($images); //set image types available for uploading and renaming
  Example: $editor->set_not_avail_images(array ('jpg'));
   
• set_max_image_size($width, $height); //set max size of images available for uploaded
  Example: $editor->set_max_image_size(1024, 768);
   
• set_max_image_flash($width, $height); //set max size of flash files available for uploaded
  Example: $editor->set_max_flash_size(1024, 768);
   
• set_can_create_dir($can_create); //set permission to create folders
  Action available if $can_create set to true. Otherwise disabled
   
• set_can_rename_dir($can_rename); //set permission to rename folders
  Action available if $can_rename set to true. Otherwise disabled
   
• set_can_delete_dir($can_delete); //set permission to delete folders
  Action available if $can_delete set to true. Otherwise disabled
   
• set_can_rename_file($can_rename); //set permission to rename files
  Action available if $can_rename set to true. Otherwise disabled
   
• set_can_delete_file($can_delete); //set permission to delete files
  Action available if $can_delete set to true. Otherwise disabled
   
• set_default_settings(); //erase all settings stored in session varibles (return to default settings)

To change settings to its default values defined in check_auth.inc.php call the appropriate functions without arquments, eg. $editor->set_allow_override();

To handle RE Simple mode add a sring of the form

	$editor->simple_mode($mode);

To hide some buttons use the method

	$editor->hide_tb($item, $mode);

Here

Using the hide_tb() function it is possible to hide some buttons of RE toolbar. Besides it, you can set up your own "simple mode" adding or deleting the function calls inside simple_mode() function.

The possible values of $item:

In this mode buttons pressing on which will take no effect become inactive.

To handle RE Active mode add a sring of the form

	$editor->active_mode($mode);

In XHTML mode editor generates source code in XHTML 1.0 format instead of common HTML.

To handle RE XHTML mode add a sring of the form

	$editor->xhtml_mode($mode);

Language and Charset settings

In XHTML mode you can specify language and charset for RE document.

	//set document language
	function set_doc_lang($lang);

	//set document charset
	function set_doc_charset($cs);

Here

To set default stylesheet files use the following function:

	$editor->set_default_stylesheet($style_path);

Here

To define html snippets for the editor use the following function:

	$editor->set_snippets($snippets, $group);

Here

	array('name' => 'name of the snippet', 'code' => 'code of the snippet')

HTML tags are available inside html snippets

To set a desired language use the following function:

	$editor->set_lang($lang);

Here

Supported languages (language codes):

The new language will be available by the code {code} in set_lang() method

To make borders visible by default call the function

	$editor->set_borders_visibility($set_on);

Here

	$editor->set_br_on_enter($set_on);

Here

To specify your own list of fonts and font sizes use the following functions:

	$editor->set_font_list($font_data);
	$editor->set_font_size_list($font_data);

Here

To use a toolbar button to submit form with Rich Editor instead of clicking on form submit button the following code should be used:

	//make the button visible
	$editor->hide_tb('save', false);
	//define reaction on the button click
	$editor->set_on_save_handler($code);

Here

Note: If you use the save button to submit form data, it is not necessary to add function save_in_textarea_all() to onsubmit form attribute

To get content of an editor from javascript use the following function:

	var editor_content = get_rich(editor_name);

Here

To set new content to an editor from javascript use the following function:

	var result = set_rich(editor_name, content);

Here

5. Examples

Note: full description of RE installation and using see in INSTALLATION&USING section and in file example.php. This is examples of RE php class using only.

Example1. Default mode

	$editor = new rich('Example #1', 'rich_name', 'initial_content',
		'100%', '100%', '/files/', 'http://www.yourdomain.com/files/');
	$editor->draw(); // or echo $editor->get_rich();

Example2. Active mode

	$editor = new rich('Example #2', 'rich_name', 'initial_content',
		500, 500, '/files/', 'http://www.yourdomain.com/files/');

	$editor->active_mode();

	$editor->draw(); // or echo $editor->get_rich();

Example3. Simple mode

	$editor = new rich('Example #3', 'rich_name', 'initial_content',
		'100%', 300, '/files/', 'http://www.yourdomain.com/files/');

	$editor->simple_mode();

	$editor->draw();

Example4. Adjustable toolbar (turn off image and table buttons)

	$editor = new rich('Example #4', 'rich_name', 'initial_content',
		500, '80%', '/files/', 'http://www.yourdomain.com/files/');

	$editor->hide_tb('image');
	$editor->hide_tb('table');

	$editor->draw(); // or echo $editor->get_rich();

Example5. Default stylesheets

	$editor = new rich('Example #5', 'rich_name', 'initial_content',
		'100%', '100%', '/files/', 'http://www.yourdomain.com/files/');

	//to load style1.css and style2.css you can write

	$editor->set_default_stylesheet('style1.css');
	$editor->set_default_stylesheet('style2.css');

	/*or (the same result)

	$editor->set_default_stylesheet(array('style1.css','style2.css'));

	*/

	$editor->draw(); // or echo $editor->get_rich();

Example6. Snippets

	$editor = new rich('Example #6', 'rich_name', 'initial_content',
		500, 500, '/files/', 'http://www.yourdomain.com/files/');

	$snippets = array();
	$snippets[] = array('name'=>'Snippet 1 name', 'code'=>'Snippet 1 code');
	$snippets[] = array('name'=>'Snippet 2 name', 'code'=>'Snippet 2 code');
	$editor->set_snippets($snippets);

	$editor->draw(); // or echo $editor->get_rich();

Example7. Relative paths

	$editor = new rich('Example #7', 'rich_name', 'initial_content',
		500, 500, '/files/', '/files/', false, false);

	$editor->draw(); // or echo $editor->get_rich();

Example8. Language

	$editor = new rich('Example #8', 'rich_name', 'initial_content',
		'100%', 400, '/files/', '/files/', true, false);

	$editor->set_lang('ru'); //set language of toolbar and dialogs to russian

	$editor->draw(); // or echo $editor->get_rich();

Example9. XHTML mode

	$editor = new rich('Example #9', 'rich_name', 'initial_content',
		'800', 400, '/files/', '/files/', false, true);

	$editor->xhtml_mode(); //generate code in XHTML 1.0 format
	$editor->set_doc_lang('de'); //set language of document to german
	$editor->set_doc_charset('iso-8859-1'); //set charset to iso-8859-1

	$editor->draw(); // or echo $editor->get_rich();

Example10. User-specified lists of fonts and font sizes

	$editor = new rich('Example #10', 'rich_name', 'initial_content',
		'100%', 600, '/files/', '/files/');

	$editor->set_font_list(array('Arial', 'Times New Roman'));
	$editor->set_font_size_list('3');
	$editor->set_font_size_list('4');

	$editor->draw(); // or echo $editor->get_rich();

6. License

Software License Agreement

RICH EDITOR AND ANY DOCUMENTATION PROVIDED TO YOU (COLLECTIVELY THE "SOFTWARE" OR "RE") COVERED BY THIS AGREEMENT IS COPYRIGHTED AND IS LICENSED, NOT SOLD. BY TAKING POSSESSION OF THE SOFTWARE, YOU AND YOUR COMPANY (COLLECTIVELY "YOU") ARE ACCEPTING AND AGREEING TO THE TERMS OF THIS LICENSE AGREEMENT

1. All copyrights to RE are exclusively owned by the author - Vyacheslav Smolin.

2. You agree to take reasonable steps to keep in confidence and protect the software provided to you from unauthorized copying or use. These steps include, without limitation, obtaining the agreement of all persons having access to the Software that they will respect the terms of this License and using the Software in such a way as to prevent unauthorized copying.

3. There are 3 basic types of licenses issued for the Software, these are:

a.

General license. You may not use the Software to create content for third parties, or that will be linked to or framed by other web sites related to you in any way, including without limitation third parties' web sites created by you unless third parties have a separate license for the Software. You may not use the Software in your commercial products.

b.

Commercial license. You may use the Software to create content for third parties. You may use the Software in your commercial product. In this case you must provide obtaining the agreement of all third parties and your customers having access to the Software that they will respect the terms of this license and use the Software in such a way as to prevent unauthorized copying. You may include the Software as a part of only one commercial product. Number of copies of the product is not limited.

c.

Rebrandable license. You may use the Software to create content for third parties. You may use the Software in your commercial products. In this case you must provide obtaining the agreement of all third parties and your customers having access to the Software that they will respect the terms of this license and use the Software in such a way as to prevent unauthorized copying. Number of products is not limited.

Once you paid a license fee, you are granted a non-exclusive right to use the Software only as authorized in this license. Number of servers and domains are not limited. All payments are non refundable. You may assign your right to use the Software to a third party provided that you cease using your licensed copy of the Software and the content produced by it.

4. THE SOFTWARE IS DISTRIBUTED "AS IS". NO WARRANTY OF ANY KIND IS EXPRESSED OR IMPLIED. YOU USE IT AT YOUR OWN RISK. NEITHER THE AUTHOR NOR THE AGENTS OF THE AUTHOR WILL BE LIABLE FOR DATA LOSS, DAMAGES, LOSS OF PROFITS OR ANY OTHER KIND OF LOSS WHILE USING OR MISUSING THIS SOFTWARE.

5. You may not sub-license, share, rent, or lease your right to use the Software. You also agree not to create derivative works of the Software for any reason. Any unauthorized use shall result in immediate and automatic termination of this license and may result in criminal and/or civil prosecution.

6. All copyright notices used throughout the Software, within the scripts and within the HTML that the scripts generate, must remain intact.

7. Installing and using the Software signifies acceptance of terms and conditions of the license.