wysiwygPR0
PHP Edition Version 2.2.3
Developers Manual
Contents
Introduction
Package Contents
Requirements
Upgrading From An Earlier Version
Installation
Embedding in a PHP script
PHP API
set_name
set_instance_lang
subsequent
set_code
usexhtml
set_charset
set_doctype
usep
set_baseurl
usefullurls
guidelines_visible
set_stylesheet
set_formatmenu
set_classmenu
set_fontmenu
set_sizemenu
removebuttons
addbutton
addspacer
set_savebutton
disableimgmngr
set_inserts
set_color_swatches
set_links
disablebookmarkmngr
disablelinkmngr
set_img_dir
set_doc_dir
Multiple Instances
Multiple Languages
Saving configurations and notes on file caching
JavaScript API
Before you start!
getCode
getPreviewCode
getSelectedText
setCode
insertAtSelection
updateHTML
updateWysiwyg
showDesign
showCode
showPreview
updateAllHTML
updateAllWysiwyg
moveFocus
openDialog
Inserting code when the document loads
Calling the file browsers from outside of WysiwygPro
Retrieving code from a form post
Dealing with malicious code
Tidying up your code
Dealing with PHP tags or other non-html content
Extending the editor
Adding a spell checker
Connecting to an existing file management system.
Frequently Asked Questions
I see a number of Warning messages such as:
I see an error message that says: Warning: Cannot add header information
The editor displays but the toolbar buttons appear as broken images
The image or document manager displays but images appear as broken images
The “Please Wait” message never goes away
How can I insert code into the editor so that I can edit an existing record
I want to locate my image folder under a different domain to the editor
The code that I am editing will be placed under a different domain to the editor
I want to set different image and document directories for different users
I want to have more than one editor on the same page
I want to translate the editor to a different language
Licensing and Disclaimer
Installation of this software means that you agree to be bound by the terms of the enclosed license agreement.
Make sure that you have read and understand the license before installing.
EMOTICON COPYRIGHT NOTICE: The animated emoticons provided with WysiwygPro are included under an agreement with the copyright holder, Bruce Corkhill and WebWizGuide.com. Purchasing a WysiwygPro license allows you to use the animated emoticons ONLY as part of the WysiwygPro editor component. Emoticons may not be used, copied or redistributed outside of the WysiwygPro product, without explicit permission from Bruce Corkhill.
DISCLAIMER:
WysiwygPro is only an editor; how you get code into WysiwygPro and what you do with code generated by WysiwygPro is your business.
It is your responsibility to ensure that you use WysiwygPro in a secure manner that will not leave your server open to attack or other damage.
ViziMetrics accepts no responsibility for damages resulting from the use of WysiwygPro.
Introduction
WysiwygPro is a WYSIWYG editing component that you can embed in any PHP script. It allows you to replace regular <textarea> tags with a rich text HTML editor.
WysiwygPro makes use of the MSHTML editing component in Internet Explorer and the Midas Editing component in Gecko based browsers.
For support, updates or error reporting please visit us online at
Email:
When looking at the syntax for functions described in this manual refer to the following:
boolean indicates that the following parameter should be true or false.
string indicates that the following parameter should be a string
int indicates that the following parameter should be in integer
array indicates the following parameter is an array.
Parameters enclosed in square brackets are optional.
Please be careful when copying and pasting code from this manual. Due to the nature of Word documents the example code in this manual features curly quotes where there should be straight quotes, most code editors will convert these when you paste but some do not.
Package Contents
Editor_files
This folder contains the WysiwygPro application. Copy this folder to your web server. See the installation section for further instructions.
Examples
Contains example scripts that demonstrate how to use WysiwygPro in you own web applications. You may copy or use these examples in any way you wish.
Pop_Up_Editor
This example demonstrates a simple method for editing textareas in non-PHP documents.
Pop_Up_File_Manager
This example demonstrates how to use the Image and Document managers outside of WysiwygPro.
Simple_File_Editor
This example demonstrates how to create an application that uses WysiwygPro to edit HTML documents on your server.
Goodies
Contains optional extras.
Requirements
Supported browsers:*
Windows (all) / OS 8.6 and 9.x / Mac OS X/Linux/UnixInternet Explorer 5.0+
Netscape 7.1+
Mozilla 1.4+
Firefox 0.7+
Or any browser based on Mozilla 1.4+ / Any browser based on Mozilla 1.3+, you can find one here:
(This link is correct as of 2nd April 2004) / Netscape 7.1+
Mozilla 1.4+
Firefox 0.7+
Or any browser based on Mozilla 1.4+
*In Gecko based browsers such as Mozilla the cut, copy, and paste buttons are not available due to security restrictions in these browsers. Standard keyboard shortcuts for these functions are still available.
Server Requirements:
PHP 4.1.0 or newer
Upgrading From An Earlier Version
Be sure to backup your old installation before proceeding to install this one. You can obtain copies of all previous and future versions from:
Upgrading from ZeusEdit 0.x, 1.x
If you are upgrading from ZeusEdit you will need to start your installation again from scratch as WysiwygPro 2.x is a completely different product. Note that WysiwygPro requires PHP.
Upgrading from versions 2.0 – 2.1
Simply install the new product over your old installation. Note that the configuration file may be significantly different to your current version. You will need to set up the new configuration file. JavaScript API is also significantly different. You will need to check any JavaScript that you are using to communicate with your editor. See the section on JavaScript API.
Things to watch out for:
- If you intend to use multiple instances make sure you give each instance a unique name with the set_name function.
- Versions prior to 2.2 would generate HTML mark-up in IE, but in Mozilla they would generate inline styles. This meant that IE could not edit formatting done in Mozilla and vice-versa. As of 2.2 the editor produces the same HTML mark-up in both browsers. THIS MEANS THAT EXISTING FORMATTING DONE IN MOZILLA BASED BROWSERS WITH VERSIONS PRIOR TO 2.2 MAY BE UNEDITABLE IN THIS VERSION!
- You no-longer need to use onsubmit=”submit_form()” and should remove it from all your form tags.
- If using multiple instances you no-longer need to use the subsequent function. This function will be called automatically for you.
What’s new in versions 2.2.x?
- Multiple instances (2.2)
- Multiple user interface languages (2.2)
- Customise the color palate with the set_color_swatches function (2.2)
- Set the image directory using the set_img_dir function (2.2)
- Set the document directory using the set_doc_dir function (2.2)
- Preview tab (2.2)
- Background images for tables and table cells (2.2)
- The same behaviour when you press enter in both Mozilla browsers and IE. (2.2.2)
- guidlines_visible method allows you to set whether guidelines are on or off by default (2.2.2)
- fixcharacters function allows you to encode special characters (2.2.2)
- email_encode function allows you to hex encode email links (2.2.2)
- comm2asp function allows you to convert ASP code back into ASP code (2.2.2)
- wp_current_obj JavaScript object allows you to access the currently active editor if there is more than one editor on a page(2.2.2)
- Context menus in Mozilla/Netscape/Firefox (2.2.3)
- New set_charset function allows you to specify the charset of your document. Use this when editing a document fragment. (2.2.3)
- New set_doctype function allows you to override the default document type declarations. (2.2.3)
- You no-longer need to add onSubmit=”submit_form()” to your form tag. (2.2.3)
- New SMILEY_FILE_DIRECTORY and SMILEY_WEB_DIRECTORY constants in config.php allow you to specify your own directory of emoticon smilies. (2.2.3)
Installation
Step 1:
Copy the ‘editor_files’ folder onto your web server. The folder can be placed inside any directory under the document root.
If you’re integrating WysiwygPro with MAMBO, upload the contents of the WP editor_files folder into the MOS editor folder and rename it to “wysiwygpro”. Also, set the “WYSIWYG Editor” parameter in the MOS global configuration to “wysiwygpro”
Step 2:
Open ‘config.php’ in your favourite PHP code editor (You can open it in Notepad if you have nothing else)
Step 3:
Set the global variables at the top of the file to match your web server configuration. You will find detailed instructions before each variable.
If you are having difficulty setting up your config.php file feel free to send us an email. Your web hosting company might also be able to help.
The other variables in this file affect file permissions in the image and document manager windows, you can change these if you wish.
Step 4:
If you are intending to use WysiwygPro’s configuration saving features make sure you have set the file permissions for the SAVE_DIRECTORY to read/write, see the section on Saving configurations and notes on file caching for more information.
Similarly if you intend to use any file management features in the image and document dialogs make sure the file permissions for the IMAGE_FILE_DIRECTORY and DOCUMENT_FILE_DIRECTORY are also set to read/write.
This usually means setting your directory permissions to 757. You should be able to do this using almost any FTP program.
If you are having difficulties setting file permissions on your web server please contact your Web Hosting Company or the company that supplied your server.
Troubleshooting
To check your installation create the PHP script below and run it on your server.
If there are any errors in your config.php file WysiwygPro should inform you.
If the editor displays but all the toolbar buttons show as broken images you need to check you WP_WEB_DIRECTORY setting in config.php.
If the image manager displays but the images show as broken links then you need to check your IMAGE_WEB_DIRECTORY setting in config.php.
Similarly if the document manager displays but the images show as broken links then you need to check your DOCUMENT_WEB_DIRECTORY setting in config.php.
If you are having difficulty installing and running WysiwygPro please check the Frequently Asked Questions at the end of this manual.
Embedding in a PHP script
Create a PHP file and put the following code in it:
(Please be careful when copying and pasting code from this manual. Due to the nature of Word documents the example code in this manual features curly quotes where there should be straight quotes, most code editors will convert these when you paste but some do not.)
<?php ob_start(); ?>
<html>
<head>
<title>My Editor</title>
</head>
<body>
<form name="wysiwygproForm" method="post" action=""
<?php
// include the config file and editor class:
include_once (‘editor_files/config.php’);
include_once (‘editor_files/editor_class.php’);
// create a new instance of the wysiwygPro class:
$editor = new wysiwygPro();
// print the editor to the browser:
$editor->print_editor(700, 400);
?>
</form>
</body>
</html>
<?php ob_end_flush(); ?>
Run the script and you should see the editor embedded in the page.
Note that before any HTML tags, echo statements or any other browser output you must put ob_start(); and after all browser output put ob_end_flush(); In most cases this simply means putting ob_start(); at the top of your script and ob_end_flush(); at the end. If you get errors that say ‘headers already sent by…’ this means that you have forgotten to use ob_start() and ob_end_flush()
Note that the editor should always be printed within a form.
The width and height of the editor is set in the print_editor () function. If you do not provide width and height parameters the editor will use its default dimensions of 680x390. You can set the width of the editor as a percentage but the height must always be fixed. To set the width as a percentage enclose it in speech marks: $editor->print_editor(‘100%’, 500);
There is an alternative function to print_editor() called return_editor() this function returns all the HTML and JavaScript as a variable rather than printing it to the browser. This is useful if you want to display the editor using a template engine.
Example:
$procode = $editor->return_editor([int width, int height]);
You can then print $procode using your template engine.
If you are having difficulty installing and running WysiwygPro please check the Frequently Asked Questions at the end of this manual.
PHP API
The WysiwygPro class has a number of configuration functions that you can call before calling print_editor(). These functions allow you to customise the appearance and functionality of wysiwygPro.
Example: to start the editor with some HTML ready for editing:
<form name="wysiwygproForm" method="post" action=""
<?php
// include the config file and editor class
include_once (‘editor_files/config.php’);
include_once (‘editor_files/editor_class.php’);
// create a new instance of the wysiwygPro class
$editor = new wysiwygPro();
// insert some HTML
$editor->set_code(‘<p>This is the HTML code I want to edit<p>‘);
// print the editor to the browser
$editor->print_editor(700, 400);
?>
</form>
set_name
Syntax: $editor->set_name(string name);
The single parameter sets the name of the textarea that will hold the edited HTML code, by default this is named ‘htmlCode’. This is important because this will become the name of the index in the $_POST array when you go to retrieve the code from a form post. For more information see the section on Retrieving code from a form post.
If you are replacing a <textarea> tag with WysiwygPro use set_name to give WysiwygPro the same name as the <textarea> you are replacing.
If you intend to place more than one editor on the same page you must give each editor a unique name. See the section on Multiple Instances.
This name will also be the name you use to access the editor with JavaScript. See the section on JavaScript API.
NOTE: certain names can cause the editor to fail. The following names have been reported to cause problems: “body”, “description”, “head” or any name that does not match A-Za-z0-9_
set_instance_lang
Syntax: $editor->set_instance_lang(string language_file);
This function overrides the DEFAULT_LANG setting in config.php. Call this function to generate an instance of the editor in a different language to the default language.
The single parameter is the language file to use.
See the section on Multiple Languages for further information.
subsequent
Syntax: $editor->subsequent(true);
If you have more than one editor on a page it is recommended that you call the subsequent() function on all editors except the first editor. The subsequent function will generate a specially configured editor that will share resources with the first editor on the page. This will greatly improve performance. Note that if you do not use the subsequent() function your multiple instances will still run, but may load slower than necessary. Also be aware that if you call subsequent for every editor on the page then none of the editors will run. This is because subsequent editors are entirely dependant on the first editor, so if the first editor is also subsequent the script resources will not be available and the editors will not initiate.
NOTE: as of version 2.2.3 this function will be called automatically if your script contains more than one editor, therefore you no-longer need to use this function.
If for any reason you need to disable this new behaviour set a global scope variable called $wp_has_been_previous to false before calling print_editor().
Example:
$wp_has_been_previous = false;
$editor->print_editor();
set_code
Sets the code that will be inserted into the editor at start-up.
Syntax: $editor->set_code(string html_code);
The single parameter is the code you want inserted. You will probably want to get this from a file or database. You do not need to do any pre-processing of the HTML code before sending it to the editor class. WysiwygPro will do all necessary formatting of your code to achieve correct display in the editor including stripslashes.
usexhtml
Tells the editor to generate XHTML 1.0 transitional instead of the default HTML 4.01 transitional.
Syntax: $editor->usexhtml(true, [string charset, string lang]);
The first parameter is true or false. It should always be true.
The second parameter is the charset that the editor should use for the XML declaration, this will affect the way the editor renders your HTML code so be sure to set this correctly. The default is “ISO-8859-1”.
The third parameter is the value for lang attributes for the HTML tag. The default is “en”
If you are using the editor to edit PHP documents please read the section on Dealing with PHP tags or other non-html content
set_charset
Sets the charset used to create and render HTML code.
Syntax: $editor->set_charset(string charset);
This function is intended for when you are editing a fragment of HTML code but need to use a particular charset for the code to render properly.
If you are editing a complete HTML document DO NOT use this function, rather you should place your charset in a meta tag at the head of your document.
set_doctype
Sets the doctype used to create and render HTML code.
Syntax: $editor->set_doctype(string doctype);
If you are editing a complete HTML document the doctype will be added to the top of your code instead of the default doctype used by the editor.
If you are editing a fragment of HTML code the doctype will not appear in the source code but it may still affect rendering of code in both the preview and WYSIWYG views.
Be sure to call this function after calling usexhtml otherwise the doctype may be overridden by the editor’s default XHTML doctype.
usep
Syntax: $editor->usep(true);
Tells the editor to use <p> on enter rather than the default <div>