Converting Wobjects To Asset Wobjects

In WebGUI 6.3 we made the first major change to the Wobject API. This should
be the last major change until versioning is introduced in 6.7. In order to
migrate your wobjects you will probably want to look at lib/WebGUI/Asset.pm,
and lib/WebGUI/Asset/Wobject.pm as well as the wobjects that come with WebGUI.

NOTE: Interweaved in the tips below are VIM regular expressions that can help
the conversion process.

The following tips should also help make your migration easer:

    1.2.1 The wobjectId field has been changed to assetId. In addition the Wobject ID
    should no longer be passed in the URL as wid. Instead all wobjects now have
    their own unique URL. Use this to call your methods.
    
    Old: WebGUI::URL::page("func=edit&wid=".$self->get("wobjectId"))
    New: $self->getUrl("func=edit")
    
    Remove wid part from urls. Wid part at end:
        :%s/&wid=["']\.\(\$self\|\$_\[0\]\)->get(['"]wobjectId["']))/')/gc

    Remove wid part from urls. Wid not at end:
    :%s/&wid=["']\.\(\$self\|\$_\[0\]\)->get(['"]wobjectId["']).['"]//gc

    Wid first form param:
    :%s/['"]wid=["']\.\(\$self\|\$_\[0\]\)->get(['"]wobjectId["']).\(['"]\)&/\2/gc

    Find remaining wids in URLs:
        /wid=

    1.2.2 You can no longer assume that your forms and links are on the page they need
    to be to be called. Therefore use the getUrl() method inherited from Asset to
    build your forms and links.
    
    EXAMPLE: WebGUI::Form::formHeader({action=>$self->getUrl});
    
    :%s/WebGUI::URL::page/$self->getUrl/gc
    :%s/WebGUI::URL::page/$_[0]->getUrl/gc
    :%s/WebGUI::HTMLForm->new\(();\|;\)/WebGUI::HTMLForm->new(-action=>$self->getUrl);/gc
    :%s/WebGUI::Form::formHeader\(();\|;\)/WebGUI::Form::formHeader({-action=>$self->getUrl});/gc

    1.2.3 Your wobject instance data (the data in the wobject table and the namespace
    table) will automatically be assigned an assetId. The wobjectId field in the
    namespace table will be left in place so that you have a reference of what the
    old ID was. Use this information (the assetId and wobjectId) to write a
    conversion script to convert the wobject data (if necessary).

    1.2.4 Use the definition of the the fields in your old new() method to create a
    new definition method. See other wobjects as an example.
    
    1.2.5 The concept of namespace no longer exists. While it still works very well
    in practice, it is no longer required that you call your table by the same
    name as your class. And the same goes for help, internationalization, etc. We
    still recommend using something like that, it's just not required.
    
    1.2.6 Because namespace no longer exists you can't call the namespace to get
    international ids etc. Instead, hard code the international namespace. This is
    important for a number of reasons, but the most pressing is inheritance.
    Wobjects are now truely objects in that they support inheritance. To avoid
    subclass wobjects having to define a whole new international file with the
    exact same labels you have in your your international file, you need to hard
    code your namespace.

    Old: WebGUI::International::get("label",$self->get("namespace"));
    New: WebGUI::International::get("label","Example");

    :%s/\($self\|$_\[0\]\)->get(["']namespace["'])/'Survey'/gc

    1.2.7 Convert your www_edit() method into the two methods getEditForm() and
    www_edit(). See other wobjects for details.

    1.2.8 Convert your www_view() method into a view() method. It should no longer
    have a check to see if the user can view it. The www_view() method in the
    Wobject superclass will do that.

    1.2.9 Add a getIcon() method to your wobject. See other wobjects for examples.
    If you don't wish to make icons, then exclude this method, it will be
    inherited from the Asset superclass with the generic asset icon.

    1.2.10 Rename your uiLevel() method to getUiLevel().

    1.2.11 Rename your name() method to getName().

    1.2.12 If your wobject used the forum system, then check out the new
    lib/WebGUI/Asset/Wobject/Collaboration.pm system.

    1.2.13 If your wobject used attachments, then check lib/WebGUI/Storage.pm and
    lib/WebGUI/Storage/Image.pm

    1.2.14 The parameters for the wobject processTemplate() method have changed.

    :%s/processTemplate(\([^,]*\),\([^,]*\)\(,[^,]*\)\=)/processTemplate(\2,\1)/gc

    1.2.15 If you were using the template system directly rather than
    using the wobject processTemplate() method, please note that it has
    been replaced by the WebGUI::Asset::Template asset.

    1.2.16 Since all assets are now pages, you need to provide your own
    view level security on your www_ methods like this:

    return WebGUI::Privilege::noAccess() unless ($self->canView);

    and like this:

    return WebGUI::Privilege::insufficient() unless ($self->canEdit);

Quick Read Assets

As of 6.7.0 Quick Read Assets have been removed. If you adopted quick read
assets between 6.3.0 and 6.7.0 you'll need to change the getLineage rule from
returnQuickReadObjects to returnObjects.

Versioning

If you're building any custom assets you'll need to write an upgrade script
for 6.6 to 6.7 that will add a revisionDate (bigint) field to your namespace
table. And you'll need to select the revisionDate from the asset table to
initially populate the field in your table. revisionDate along with assetId
should create a composite primary key for your table. Here are some example
SQL queries to get you started in your transition:

    alter table MyAsset add column revisionDate bigint not null;
    alter table MyAsset drop primary key;
    ...look up the revision date for each asset instance from the asset table...
    alter table MyAsset add primary key (assetId,revisionDate);

In addition, if you wish to version the attachments to your asset, you'll need
to add addRevision(), purge(), and purgeRevision() methods to your asset. See
WebGUI::Asset::File and WebGUI::Asset:Post for examples of what these methods
should look like.

Also, if you have written any queries to go against the "asset" table, you
should note that the asset table has been split into two tables "asset" and
"assetData". So you'll need to change your queries appropriately.

Other than that you shouldn't have to make any revisions to your asset to
support versioning. Your collateral tables need not have the revision date as
they'll be tied to the assetId regardless of the revision date.

Constructor API Change

In 6.7.0 the new() and newByDynamicClass() API's in WebGUI::Asset changed
slightly. In most situations the changes will not cause any problems, but for
some asset developers there may be a slight change.

Binary GUIDs

In 6.7.3 we noticed a problem with the GUID system. MySQL by default reads
varchar fields as case insensitive, which can cause a big overlap problem for
assetIds, userIds, and anything else that uses GUIDs. Therefore you need to
alter all your custom tables and add the binary operator to the GUID field
definitions like so:

alter table MyTable change assetId assetId binary not null;

processMacros() Method Removed

In 6.8 the long depricated method processMacros() was removed. No one should
be using this any longer anyway, but we thought we'd warn you just the same.

Output Chunking

Starting in 6.99 WebGUI www_ asset methods are capable of having full control
over the output buffer. They can use $session->output->print() to send chunks
of content back to the browser before the page is entirely processed. The
advantage here is that the page appears to load more quickly to the end user.
The disadvantage is that you must set up any HTTP and HTML headers before you
start to send any content. The view() method now has a companion method called
prepareView() in which HTML and HTTP headers must be set. See any of the
existing assets and wobjects for implementation details.

Removed Page Caching

The page caching system that was cacheTimeout and cacheTimeoutVisitor on
wobjects has been removed. Not everything caches in the same way and therefore
we can't use a generic caching mechanism as much as we'd like to. Likewise,
the www_view(1) cache override that has traditionally been used in wobjects is
now gone since it's useless. If your asset needs caching, you'll need to add
it yourself. See one of the dozen or so assets that come with WebGUI for
ideas. Examples include Article, SQL Report, File, and Folder.