WebGUI 6.x Plugin Migration Guide --------------------------------- This document is provided by the WebGUI 6.x development team in order to help you migrate your WebGUI 5.x plugins to the new API's. If you are not a WebGUI developer then this file won't make a lot of sense. CONTENTS 1. Wobject Migration 2. Macro Migration 3. Authentication Migration 4. Scheduler Migration 5. System Changes Affecting Migration 1. Wobject Migration -------------------- 1.1 Global Unique Wobject IDs In 6.2 we changed wobjects to use the new Global Unique ID system. See WebGUI::Id for details. This change means that wobject Ids are now 22 character text strings rather than integers. That means you'll need to update your database tables and code to account for the Ids being strings. Also, anything using the setCollateral method will start using GUIDs as well. 2. Macro Migration ------------------- 2.1 Navigation Macros As of WebGUI 6.0 there is no longer a need to develop custom navigation macros. WebGUI has an entirely new navigation system that is 100% configurable and templated. The legacy navigation system has been removed. Any nav macros that you've written will need to be removed from the system. Then just create a navigation configuration to do what your old nav once did. If you absolutely must write a navigation macro for some reason that our nav system does not accomodate you, then please check out the new API in WebGUI::Navigation. 3. Authentication Migration ----------------------------- 3.1 Authentication Modules Changes Authentication in WebGUI is now completely Object Oriented. The superclass WebGUI::Auth defines a loose set of rules by which to create authentication parameters. Subclasses MUST be WebGUI::Auth objects, however they can define thier own rules for authentication. No methods are required to be overwritten as it is up to the user to decide which methods may be called through WebGUI. The only method that MUST be calllable is the init routine which should define the starting point for authentication. For instance, WebGUI's init method calls the displayLogin function. Methods which remain compatible the auth modules distributed with WebGUI: www_createAccount www_deactivateAccount www_displayAccount www_displayLogin www_login www_logout www_recoverPassword There is no guarentee, however that any custom apps which call these routines will work for custom authentication instances. 4. Scheduler Migration ----------------------- 4.1 Nothing Yet There have currently been no changes to the scheduler API. 5. System Changes Affecting Migration ------------------------------------- 5.1 Set Date Format Changes In 6.0 the "set date" format used by WebGUI::Form::date() and other methods was changed from "MM/DD/YYYY" to "YYYY-MM-DD" and optionally "YYYY-MM-DD HH:MM:SS". If you are using WebGUI::FormProcessor to handle processing of your dates then you will notice no side effects from the format change. If you are not, then you should convert your plugin to use WebGUI::FormProcessor. In addition to the format change above, we also made one related API change. WebGUI::Form::dateTime() and WebGUI::HTMLForm->dateTime() no longer have "dateExtras" and "timeExtras", but rather just "extras" properties. This is because there is only one field to represent both the date and the time, unlike before. 5.2 Database Links The database links API was changed in 6.0. The getHash function was removed and replaced with a getList function that returns a hash reference. 5.3 Paginator In 6.0 almost all of the paginator methods were modified in an incompatible way, including the constructor. We removed depricated parameters from the methods, which will cause pagination not to function in items that have not been updated. 5.4 Dynamic Plug-in Loading In 6.1 plug-ins (Wobjects, Macros, and Auth) are all dynamically loaded. They used to be statically loaded at session open time. If you are writing something that uses a macro, wobject, or auth module outside of the usual mechanisms that call those plug-ins, then you'll need to write a piece of code to load the plug-in at use time. 5.5 Privilege API Change In 6.1 we moved isInGroup from WebGUI::Privilege to WebGUI::Grouping, where it belongs. We also moved canViewPage and canEditPage to WebGUI::Page and renamed them to canView and canEdit. And finally, we moved canEditWobject and canViewWobject to WebGUI::Wobject and renamed them canView and canEdit and converted them from regular functions into methods. 5.6 Template API Change In 6.1 we completely rewrote the underlying template framework to add template caching. Any plug-ins that use WebGUI::Template, must be updated to reflect the new API. 5.7 Internationalization and Help Change In 6.1 we moved the internationalization out of the database and into compiled perl modules. This helps tremendously in performance. It also allows for text-based tags to be used instead of integers for international ids. If you've written any plug-ins that use the internationalization system, you'll need to migrate them to the new system. We've created a tool that will auto-generate the new help and internationalization files from an existing 6.0 database. You can get it from the "tools" module in CVS or in the user contributions area on plainblack.com. The utility is called: gen61i18nfrom60data.pl We also made the International API object oriented. The old procedural version is still intact as well. See WebGUI::International for API changes. As a developer you can convert your translations (including English) and your help files using a script we provide. You can find the script here: http://www.plainblack.com/translations?wid=1552&func=viewSubmission&sid=1213 5.8 WebGUI::Session Changes In 6.1 we changed the session API to remove functions that didn't really belong in WebGUI::Session. The main changes of interest are that you no longer do HTTP redirects and set cookies via session. Take a look at WebGUI::HTTP for details. 5.9 Global Unique IDs In 6.2 we added global unique Ids to WebGUI. This means that a lot of the integer- based incrementer IDs will now be replaced with 22 character text IDs. You should update your code and database tables to take advantage of this. Some of the more important ID's that have been changed are User Ids, Group Ids, and Wobject Ids. See WebGUI::Id for more information. 5.10 POD We've switched to a new Plain Old Documentation (POD) format. See Ruling WebGUI for details. 5.11 Internationalization and URLs In 6.3 we moved URL compliance to the language file. We did this because the non-latin characterset languages were having trouble with WebGUI generated URLs. So now they can write in their own handlers to deal with WebGUI generated URLs. If your language uses a latin character set, you can just copy the makeUrlCompliant subroutine from lib/WebGUI/i18n/English.pm into your language file.