Discussion

Anyone planning to become a developer, or just interested in the development process, should be on the WebGUI Developer's Discussion List. However, participating on the list requires some etiquette. Follow these simple rules and you'll be fine:

1. Don't trash someone else's thread. If someone asks a question or starts a discussion about a particular topic, stay on that topic when replying. If you have statements, comments, or questions about something that is unrelated, then start a new thread.
2. Don't whine on the list. It just makes JT go off on you and then you'll cry while everyone else laughs at you.
3. Don't join the list to ask for support. There are plenty of support options available; use one of them. This is not to say that you can't use the list to ask for help writing wobjects that you plan to freely distrubute, or modifications to the core that you plan on contributing back.

Perl

To be a real WebGUI developer you're going to need to learn Perl. This doesn't mean that you have to become a Perl expert. It just means you need to become familiar enough with Perl to hack around in it. There are plenty of good books around on the subject. If you can find it, Plain Black highly recommends the Perl Black Book or the Perl Little Black Book. Both of these books are out of print, but they are the best Perl books ever written in our opinion. One of the best ways to learn Perl is to hack around in someone else's Perl code. On a dev. system, try modifying some of WebGUI's macros and see what happens. When you get a little more bold, play around with wobjects.

Macros

WebGUI macros are the simplest of WebGUI's plug-ins to write. So simple, in fact, that we should cover them before we even discuss WebGUI's API.

To write a macro simply rename the _macro.skeleton file found in your WebGUI distribution. Then change the package name, and add the macro to your WebGUI config file and restart Apache. You now have a working macro, but it doesn't do anything yet. Now you need to add your own custom code to the process() subroutine.

Macros are simple to write, but even simpler to steal. When you start out writing macros, don't write your own unless you're already comfortable with Perl. Instead, steal code from other macros. If there's a macro that's already similar to what you want, then the best way to do this is to simply copy an existing macro to a new filename. Rename the package, and add a new entry to your WebGUI config file. Once you've got the same macro working under a new name, then start modifying it. Don't be afraid to play around. Just make sure you're experimenting on a test server so you don't have to worry about breaking your production web site.

The API

WebGUI has a rich set of APIs that is extended more and more with each new release. If you're becoming a more serious developer you'll want to start reading these API's so you know what's there and how to use it. This will help prevent you from reinventing the wheel.

The following is a listing of the API's you'll likely want to immediately know about. They are listed in order of the likelihood you'll use them:

1. WebGUI::SQL
2. WebGUI::Session
3. WebGUI::HTMLForm
4. WebGUI::Form
5. WebGUI::User
6. WebGUI::Group
7. WebGUI::Asset
8. WebGUI::Asset::Template

There are several other packages you can look at, but by the time you read and use the above, you'll know enough to do 80-90% of what you want to do with WebGUI.

 

If you need to edit one of the core modules, there is a way to safely do this. See Override Core Modules for details. 

Other Plug-ins

Besides macros, WebGUI also has assets, wobjects, workflow activities, and much more. The following list shows them in order of complexity to write:

1. Macros
2. Workflow Activities
3. Authentication Plug-ins
4. Assets / Wobjects
5. Template Engines

Even though it's easier to write auth and workflow activities, we suggest that you move on to assets and wobjects after macros. Why? Because you're much more likely to use wobjects than you are the other two.

The best way to start out with a wobject is in much the same way you started out with a macro, by using either the _NewAsset.skeleton or _NewWobject.skeleton included in your WebGUI distribution. And definintely read Wobject Development Tutorial

Asset Magic

Assets are the content workhorse of the WebGUI world. The asset superclass (WebGUI::Asset) has dozens of methods that make your life easier when coding an asset. That said, some of the stuff that goes on in assets is a little like magic, and confuses newbie developers. The following is a list of magical items that confuse newbie developers:

1. The asset namespace table, also known as the extended properties table. When you're creating an asset you must create a table that has the same name as your asset. So if you create an asset called MyAsset, then you must also have a table called MyAsset,and at minimum that table must have a column called assetId that is of type varchar(22) binary and another column called revisionDate that is of type bigint. While that in itself isn't so confusing, the way WebGUI uses the table might be. If you create an extended property in the  definition() method, then WebGUI will automatically populate that field in the extended properties table. In addition, if an asset instance is deleted or copied, the asset superclass will automatically delete or copy whatever is in that table.
2. The default view. How does WebGUI know method to call by default? If no method is specified, it will call www_view by default.
3. The marrying of func to subroutine. How does WebGUI know what methods are callable? Any method that starts with a www_ is callable as a func through the URL. So if you have a method called www_myMethod then you can call it through the URL by using func=myMethod.