Migrating from Version 2

This chapter covers the differences between WysiwygPro 3.x and 2.x as well as covering tips to help you upgrade smoothly.

If you are not migrating from version 2 please skip straight to the installation chapter.

PHP API

Basic Migration

All of the documented PHP API and techniques from WysiwygPro 2.x will continue to work in version 3. You should be able to simply drop the new version into your application then copy your old config.php file over the new config.php file and everything should continue to work as expected.

Note that the editor_files folder has been re-named wysiwygPro. You can re-name it back to editor_files if you like. This folder can be given any name you desire and this has always been the case. If you do change the name of the folder please note that all of the example files and the examples in this manual assume that the folder is still named wysiwygPro.

Version 2 Compatibility Mode

If you do a basic migration as described above the editor will run in version 2 compatibility mode. In this mode default settings and behaviors are the same as they were in version 2. The default toolbar layout is also the same as it was in version 2.

Version 2 compatibility mode is triggered by the inclusion of the config.php file. Including the config.php file will cause all editors in the script to display in compatibility mode.

Full Migration

To run the editor in native version 3 mode simply don't include the config.php file. In native version 3 mode WysiwygPro does not use the config.php file at all. Instead settings such as your file manager configuration that were configured through the config file can now be configured using the new properties and methods of the WysiwygPro class. The new API provides unlimited flexibility by allowing you to have a completly different configuration for each editor instance rather than having all editors share their configuration through a single config file.

To learn how to configure the new file manager see Configuring the file managers

Example:

The following script is an example of how WP was used in version 2:

// include the config file
include('wysiwygpro/config.php');

// include the wysiwygpro class
include('wysiwygpro/editor_class.php');

// create a new editor
$editor = new wysiwygPro();

// display the editor
$editor->print_editor();

The following script is an example of how WP should be used now if you don't need version 2 compatability, note that there is no need to include any config file first and that the main script file is now called wysiwygPro.class.php NOT editor_class.php (but editor_class.php still works) also the print_editor and display_editor functions are depreciated in favour of display and fetch:

// include the wysiwygpro class
include('wysiwygpro/wysiwygPro.class.php');

// create a new editor
$editor = new wysiwygPro();

// display the editor
$editor->display();

Differences between version 2.x, version 3 in compatability mode, and version 3 in native mode:

 

Version 2 

Compatibility Mode 

Native Mode 

Default toolbar layout 

Version 2 layout 

Version 2 layout

Version 3 layout

Load settings from config.php 

Yes 

Yes 

No 

Separators 

The addSpacer function will add a separator

The addSpacer function will add a separator

The addSpacer function will add a spacer.

Default HTML version 

HTML 4 Transitional 

HTML 4 Transitional 

XHTML 1.0 Transitional 

Default line returns 

DIV 

DIV 

Default load method

onload

onload

inline

Post processing code

You should no-longer use the fixCharacters function.

WysiwygPro can now escape characters within the editor. To enable this set the escapeCharacters property when constructing the editor.

JavaScript API

Basic Migration

In most cases you shouldn't need to make any changes, all documented API should still work. However the practice of accessing each editor as a global object is now depreciated and you are strongly advised to upgrade your scripts.

Full Migration

There has been a significant change made to the JavaScript API. In version 2 each editor object was available as a global variable with the same name as the editor. This was problematic if the editor had the same name as an existing JavaScript object.

Each editor should now be accessed through the WPro.editors collection like this:

WPro.editors['editorName']

Or if you don't know the name of an editor you can use a numeric index where 0 represents the first editor on the page, 1 the second, 2 the third and so on:

WPro.editorsĪŽ]

Or you can access the editor through the form element:
For this to work the editor must be displayed within a form

document.formName.elements['editorName'].editor 

The old method from version 2.x where each editor object was accessed through a global variable should no longer be used.

v2 PHP API v3 PHP API and link to documentation
Please note that wysiwygPro v3 has a significantly more advanced PHP and Javascript API.   While this is a listing of v2 to v3 equivalents... there are MANY more properties and methods in v3 that can be used to customize your wysiwygPro implementation.
addbutton addButton, addRegisteredButton, registerButton, registerFeature, registerAndEnableFeature
addspacer addSpacer, addSeparator, registerSpacer, registerSeparator
disablebookmarkmngr disableBookmarkMngr, disableFeature, disableFeatures
disableimgmngr disableImgMngrdisableFeaturedisableFeatures
disablelinkmngr

disableImgMngrdisableFeaturedisableFeatures

disablethumbnails disableThumbnails, disableFeaturedisableFeatures
escapeCharacters escapeCharacters, escapeCharactersMappings, escapeCharactersRange
guidelines_visible guidelines
loadmethod loadMethod
print_editor display, width, height
removebuttons

removeButtons disableFeaturedisableFeatures

return_editor fetch
set_baseurl baseURL
set_charset editorCharset, htmlCharset, htmlDirection, htmlLang
set_classmenu stylesMenu
set_code value, emptyValue
set_color_swatches colorSwatches
set_doc_dir documentDirdocumentURL
set_doctype doctype, htmlVersion
set_fontmenu fontMenu
set_formatmenu not used in v3. 
set_img_dir imageDir, imageURL, mediaDir, mediaURL
set_inserts snippets
set_instance_lang lang
set_links links, linksBrowseURL
set_name name
set_savebutton saveButton, saveButtonHeight, saveButtonLabel, saveButtonURL, saveButtonWidth
set_sizemenu sizeMenu
set_stylesheet addStylesheet
usefullurls urlFormat
usep lineReturns
usexhtml not used in v3
subsequent not used in v3
   
config.php FILE v2 No need to use config.php in v3.  All of these things can be dynamically set in your code
WP_WEB_DIRECTORY editorURL
IMAGE_FILE_DIRECTORY imageDir, mediaDir
IMAGE_WEB_DIRECTORY imageURL, mediaURL
DOCUMENT_FILE_DIRECTORY documentDir
DOCUMENT_WEB_DIRECTORY documentURL
$trusted_directories http://www.wysiwygpro.com/index.php?id=301
SMILEY_FILE_DIRECTORY emoticonDir
SMILEY_WEB_DIRECTORY emoticonURL
DEFAULT_LANG lang, langFolderDir, langFolderURL
DOMAIN_ADDRESS editorURL
$image_types allowedImageExtensions, allowedMediaExtensions
$document_types allowedMediaExtensions
$max_image_width maxImageWidth
$max_image_height maxImageHeight
$max_file_size maxImageSize, maxMediaSize
$max_documentfile_size maxDocSize
$delete_files deleteFiles
$delete_directories deleteFolders
$create_directories deleteFolders, copyFolders
$rename_files renameFiles, moveFiles
$rename_directories renameFolders, moveFolders
$upload_files upload
$overwrite overwrite
WP_FILE_DIRECTORY not required.  Edit config.inc.php in unusual circumstances.
CHMOD_MODE folderCHMOD
FILE_CHMOD_MODE fileCHMOD
   
JavaScript API v2 JavaScript API v3
As with the PHP API, the wysiwygPro v3 Javascript API is significantly more advanced than the wysiwygPro v2 JavaScript API.  Please visit the Developer's Manual Javascript API details HERE for a full discussion.
getCode getValue
getPreviewCode getPreviewHTML, getSelectedHTML
getSeletedText getSelectedText
setCode setValue
insertAtSelection insertAtSelection, insertImage
updateHTML updateValue
updateWysiwyg updateDesign
showDesign showDesign
showCode showSource
showPreview showPreview 
updateAllHTML same, but accessed through the wPro global javascript object: INFO
updateAllWysiwyg same, but accessed through the wPro global javascript object: INFO
moveFocus focus, showDesign, showPreview, showSource, _initFocus
openDialog openDialog, openDialogPlugin