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 |
P |
|
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[0]
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. Check out the full Developer's Manual HERE. General v2 to v3 information is available HERE. | |
| addbutton | addButton, addRegisteredButton, registerButton, registerFeature, registerAndEnableFeature |
| addspacer | addSpacer, addSeparator, registerSpacer, registerSeparator |
| disablebookmarkmngr | disableBookmarkMngr, disableFeature, disableFeatures |
| disableimgmngr | disableImgMngr, disableFeature, disableFeatures |
| disablelinkmngr | disableLinkMngr, disableFeature, disableFeatures |
| disablethumbnails | disableThumbnails, disableFeature, disableFeatures |
| escapeCharacters | escapeCharacters, escapeCharactersMappings, escapeCharactersRange |
| guidelines_visible | guidelines |
| loadmethod | loadMethod |
| print_editor | display, width, |
| removebuttons | removeButtons, disableFeature, disableFeatures |
| 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 | documentDir, documentURL |
| 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, linksBrowse |
| 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 | allowedDocExtensions |
| $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 | createFolders, 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 |
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.