Basic Usage
This chapter covers the basics of constructing and displaying an editor.
Prior knowledge
- A basic knowledge of PHP is required, see http://www.php.net/tut.php
- A basic knowledge of how forms work in PHP is essential, see http://www.php.net/manual/en/tutorial.forms.php
- Because WysiwygPro is implemented as a class some knowledge of classes in PHP will help, see http://www.php.net/manual/en/language.oop.php
- WysiwygPro makes use of sessions to ensure that an editor configuration is available to dialog windows. Some knowledge of sessions in PHP will help, see http://www.php.net/manual/en/ref.session.php
A basic example
Displaying WysiwygPro is simple and intuitive, let's just launch straight into an example. We will discuss each relevant line of code in the example afterwards.
Create a new PHP file with the following code in it:
<?php
// include the WysiwygPro class
include_once("wysiwygPro/wysiwygPro.class.php");
// start a session
session_start();
?>
<html>
<head>
<title>My Editor</title>
</head>
<body>
<form name="wysiwygproForm" method="post" action="action.php">
<?php
// create a new editor instance:
$editor = new wysiwygPro();
// configure the editor:
// give the editor a name
//(equivalent to the name attribute on a regular textarea):
$editor->name = 'myeditor';
// set the content to be edited
//(equivalent to the value attribute on an input element or the content of a regular textarea):
$editor->value = '<p>some HTML code</p>';
// display the editor, the two paramaters set the width and height:
$editor->display('100%', '400');
?>
<input type="submit" value="Submit" name="submit">
</form>
</body>
</html>
Now let's discuss each relevant line of code:
// include the WysiwygPro class
include_once("wysiwygPro/wysiwygPro.class.php");
This line includes the wysiwygPro script file. Make sure that the include_once statement points correctly to the wysiwygPro.class.php file. For more information on include_once see http://www.php.net/manual/en/function.include-once.php
We recommend that this line be placed near the beginning of your script, before any HTML content. (But this is not a requirement)
// start a session
session_start();
By default WysiwygPro uses sessions to re-create your editor configuration within it's dialog windows. For this to work you should start a session by calling session_start(). The call to session_start() must be placed before any HTML content and before any editors have been constructed. If you are integrating WysiwygPro into an existing application then your application probably already includes this line somewhere. If this is the case then you will not need to add it again yourself. Calling session_start twice should be avoided.
For more information on session_start please see http://www.php.net/manual/en/function.session-start.php
If you forget this step WysiwygPro will attempt to start a session for you. This should work most of the time but may fail under some rare circumstances. For this reason we consider it best practice to start the session yourself.
If you are integrating WysiwygPro into an application that uses a custom session name (different to the one set in php.ini) or that uses a custom session save handler then you will need to set up the session configuration file located at wysiwygPro/conf/customSessHandlers.inc.php.
If you receive an error message about expired sessions every time you open a dialog window then you have probably missed this step OR you need to set up the session configuration file located at wysiwygPro/conf/customSessHandlers.inc.php
If you are having trouble getting sessions to work you could configure WysiwygPro to use it's own session engine instead of the PHP session engine. See Sessions.
// create a new editor instance:
$editor = new wysiwygPro();
This line creates a new editor object. You do not need to call the variable $editor, it can have any name you desire. Most of the examples throughout this manual assume you have called it $editor.
For a full API reference for the wysiwygPro class see wysiwygPro
// give the editor a name
//(equivalent to the name attribute on a regular textarea):
$editor->name = 'myeditor';
You should always give the editor a name. If you do not the default name is 'htmlCode'.
This is important because the name will become the key in the $_POST array when you go to retrieve the code from a form post.
For more information see name
If you are displaying several editors on the same page then each editor MUST be given a different name.
// set the content to be edited
//(equivalent to the value attribute on an input element or the content of a regular textarea):
$editor->value = '<p>some HTML code</p>';
Sets the HTML code to be edited.
If you omit this property or set it to an empty value then the editor will start with a new blank snippet. To start the editor with a new blank complete HTML document then set this value to a blank document including html, head and body tags.
You will probably want to load this value from a file or database.
For more information see value
// display the editor, the two paramaters set the width and height:
$editor->display('100%', '400');
Displays the editor. The editor should be displayed within an HTML form where you would normally have displayed a textarea.
For more information see display
There is an alternative to display called fetch that will return the code for displaying the editor. Please see fetch
There are numerous other configuration options that can be called before calling display. Please refer to the wysiwygPro API reference. In particular the following sections of the reference will be of interest:
If you are using the editor for editing emails then you will want to force absolute URLs, see fullURLs (version 3.0.0) or urlFormat (versions 3.0.1 and above, 3.0.1 is due late October 07)
If you are displaying the editor in several places throughout your application and you don't want to recreate your editor configuration every time you display the editor then you could store your configuration in a plugin. A basic discussion of this concept is available here.
We use a plugin on this website to store the file browser configuration settings for our demos so that we don't need to repeat this configuration for every demo. Full source code for each of our demos can be viewed on the demo pages along with a link to view the source for our demo plugin.
If you decide to use a wrapper class to extend the wysiwygPro class then you will need to include your class definition into wysiwygPro/conf/customSessHandlers.inc.php, otherwise you will receive an error on dialog windows.
Retrieving code from a form post
If you created and ran the above example you may have noticed that clicking the submit button produces an error. This is because we have not yet created a script to handle the form post. If you look at the form in the example above you will see that the action attribute is set to a value of 'action.php'. When the form is submitted the form data will be sent to this file. So let's create a PHP file called action.php
Please note that the method attribute of a form should always be set to 'post'.
Because we named the editor 'myEditor' we can retrieve the code generated by the editor using $_POST['myEditor'].
If we placed the following code in the action.php file it will simply output the code to the browser:
<?php
echo $_POST['myEditor'];
?>
You will probably want to save the code to a database or to a file. You can use PHP's built in functions to do this.
Basic MySQL Database Example, (help with MySQL databases is beyond the scope of this manual, please see http://www.php.net/manual/en/ref.mysql.php):
<?php
// retrieve the HTML code from the editor
$html = $_POST['myEditor'];
// Connecting, selecting database
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
or die('Could not connect: ' . mysql_error());
mysql_select_db('my_database')
or die('Could not select database');
// Performing SQL query
$result = mysql_query('INSERT INTO my_table (my_content) VALUES ('.mysql_escape_string($html).')')
or die('Query failed: ' . mysql_error());
// Closing connection
mysql_close($link);
?>
WysiwygPro includes several usefull functions for validating and processing the HTML code produced by the editor. Please see wproUtilities.
If you see back slashes in front of each double quote this is probably because you have magic_quotes_gpc enabled in your server's PHP configuration. To correct this issue you can use PHP's stripslashes function to remove the backslashes.
Multiple Instances
You can place as many instances of WysiwygPro in a page as you require so long as each instance has been given a unique name. If you have editors on the same page that
have the same name then you will receive an error.
Note that regardless of how many editors you display on a page you only need to include the WysiwygPro script file once and you only need to call session_start once.
Example:The following script will generate a page with three editors on it:
<?php
// include the WysiwygPro class
include_once("wysiwygPro/wysiwygPro.class.php");
// start a session
session_start();
?>
<html>
<head>
<title>My Editors</title>
</head>
<body>
<form name="wysiwygproForm" method="post" action="">
<?php
// Editor one -----------------------------------
// create a new instance of the wysiwygPro class:
$editor = new wysiwygPro();
//give the editor a unique name:
$editor->name = 'wp1';
// print the editor to the browser:
$editor->display(700, 400);
// Editor two -----------------------------------
// create a new instance of the wysiwygPro class:
$editor2 = new wysiwygPro();
//give the editor a unique name:
$editor2->name = 'wp2';
// print the editor to the browser:
$editor2->display(700, 400);
// Editor three -----------------------------------
// create a new instance of the wysiwygPro class:
$editor3 = new wysiwygPro();
// give the editor a unique name:
$editor3->name = 'wp3';
// print the editor to the browser:
$editor3->display(700, 400);
?>
</form>
</body>
</html>
Contents
This online documentation specifically covers version 3.0 and above, developers using earlier versions should refer to their PDF or MS-Word manual that was included in the product download.