217 lines
7.6 KiB
Text
217 lines
7.6 KiB
Text
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
|
|
|
|
In 6.2 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.
|
|
|
|
|
|
5.12 UTF-8 Required
|
|
|
|
As of 6.3 we're now requiring that all WebGUI sites use the UTF-8 character
|
|
set. The language packs distributed from the WebGUI Worldwide members will now
|
|
be converted to UTF-8, and you can get instructions on their sites as to how
|
|
to convert your content, if necessary.
|
|
|
|
|
|
5.13 Form Changes
|
|
|
|
The following form changes were made in 6.3:
|
|
|
|
The interval subroutine in WebGUI::Form and WebGUI::HTMLForm had an API
|
|
change. See the documentation for WebGUI::Form and WebGUI::HTMLForm for
|
|
details.
|
|
|
|
The select method in WebGUI::HTMLForm that has been depricated forever has
|
|
been removed.
|
|
|
|
Most of the subroutines in WebGUI::HTMLForm and WebGUI::Form now have a
|
|
parameter called "defaultValue" which will be used in the event that "value"
|
|
is not specified.
|
|
|
|
You can now dynamically add tabs to WebGUI::TabForms.
|
|
|
|
|
|
|
|
|