Introduction. Welcom to The WebGUI API

Transcription

1 Introduction Welcome to The WebGUI API Introduce me If you are attending all my classes, I apologize in advanced as you are going to get very bored of this intro Frank Dillon Currently Director of development and project Plainblack I've only officially been with Plainblack since May, however I've been developing wobjects professionally since WebGUI's first release in Written more than 100 assets, wobjects, macros, and hourly scripts ranging from small 4 or 5 line macros to projects that have > lines of PERL code Been developing with PERL professionally for almost 10 years I've worked with many other technologies which flavor my experience I've done a lot of work with JAVA Web Technologies Cold Fusion BroadVision Oracle Portal API Worked with a wide variety of Databases Oracle MS SQL MYSQL IMS I hold college degrees in both Mathematics and Computer Science Class Introduction Welcom to The WebGUI API Class is part of a series which intends to teach those of you who are new to programming in WebGUI some of the basics, and to fill those of you familiar with WebGUI in on some of the new and exciting features. Assume you have some programming knowledge (not going to cover programming topics) Open forum I'll take questions as you have them. If we start falling behind, I'll ask you to hold your questions until the end. Assume you have a working knowledge of the WebGUI. Goal is to walk through the API and discuss some of the functions and features available to developers. Summary System Utility What tools are available for dealing with WebGUI on a system level. We will discuss WebGUI Sessions, Authentication, and dealing with the HTTP construct. Application Utility Here we will discuss the tools available for building applications, be they assets, wobject, macros, hourly scripts, etc. The Application level API is rather extensive, so I've grouped packages into logical groups which should better help you to understand the APIs usefulness Asset Tools APIs needed for writing assets. We will not cover all of the Asset API in this

2 class as there are Asset and Wobject classes which will deal with these more in depth Manipulating Resources Connecting to external resources (Database servers, LDAP servers) File storage and retrieval HTML in WebGUI Dealing with forms Functions for parsing and cleaning HTML Dealing with icons, macros, styles, and URLs Users, Groups, and Privileges Accessing User and Group data Determining User and Group privileges Messaging & ErrorHandling Sending Mail / Using the Message Log Dealing with Errors Miscellaneous Features Dealing with Date and Time The Utility package The Paginator Following the API WebGUI's API documentation can be found on the plainblack website underneath the nightly builds section of the downloads area WebGUI is documented using POD, so it is displayed in POD format. Name the name of the PERL module Description what the PERL module does Synopsis public methods available Methods a description of each public method. Optional parameters are in brackets System Utility System utilities are those APIs which let you deal with WebGUI on a System Level. The first API we'll take a look at is also the most important. WebGUI::Session This package is the heart of WebGUI. Utilizing this package, your application gains access to WebGUI's session variable which contains everything WebGUI needs to know in order to operate. Opening and closing a session The only time you will need to implicity open or close a WebGUI session is if you are building something external to WebGUI that you wish to have use the session API. In the case of applications that plug into WebGUI (assets, wobject, macros), you need only use the WebGUI::Session package. WebGUI::Session::open(webguiRoot,configFilename) opens a WebGUI session. Pass in the location of the webgui root and the name of the config file (not the path). WebGUI::Session::start(userId) start a session for the userid passed in WebGUI::Session::end(sessionId) Removes the specified user session from memory and database. WebGUI::Session::close() - Cleans up WebGUI session information from

3 memory and disconnects from any resources opened by the session Updating session information From time to time, your applications will need to refresh session information. You may want to dynamically load a user into session, update session variables you may have overwritten with data stored in the database, or update a session to reflect new asset information. The following API methods can be used for updating session information: WebGUI::Session::refreshPageInfo(assetId) - Updates the WebGUI session to reflect new asset information WebGUI::Session::refreshSessionVars(assetId) - Updates the user session variables from the database. WebGUI::Session::refreshUserInfo(userId) - Refreshes the user's information from the database into this user session. WebGUI::Session::convertVisitorToUser(sessionId,userId) - Converts a visitor session to a user session. Dealing with Session Scratch Session scratch allows you the flexibility to set data by session that is specific to your application. They allow developers to easily store data in a user sessoin from page to page. Session scratch is assoicated with a session and stored in the database, it is around until either you implicitly remove it, or until the session expires. WebGUI::Session::setScratch(name,value) Sets a scratch variable for this user session. WebGUI::Session::deleteScratch(name) Deletes the scratch variable name for the current session WebGUI::Session::deleteAllScratch(name) - Deletes the scratch variable name for all users. This function must be used with care as it will affect all sessions including ones that are currently open and in use. Admin Utilities Often you find yourself writing applications that have special features available only to administrators. Sometimes, you only want to display those features if the administrator has enabled admin mode in WebGUI. The following Session methods allow you to detemine if admin mode has been enabled, and to dynamically enable and disable it. WebGUI::Session::isAdminOn() - returns a boolean indicating whether admin mode is on or not WebGUI::Session::switchAdminOff() - Enables admin mode WebGUI::Session::switchAdminOn() - Disables admin mode WebGUI::Auth The WebGUI::Auth API is almost exclusively used for building custom authentication methods. For that reason, I will only be mentioning a few methods that come in handy in the WebGUI Application enviornment On occasion, the need arises to retrieve or set Authentication information about a user. For instance, in the LDAP Auth method, distinguished name and connection dn are stored as authentication properties. These cannot be retrieved or set through the User method, and rather than go directly against the database (which is subject to change from version to version), you can get these using the Auth API WebGUI::Auth->new(authMethod,userId) The Auth Class is Object Oriented which means in order to use it, you must first create a new instance of the class. Use this method to create a new instance of the auth method for a user. You must

4 pass in the user's id and authmethod, both of which can be retrieved from the WebGUI::User API which we will discuss later WebGUI::Auth->getParams() - Returns a hash reference with the user's authentication information. Returns name value pairs of all the data stored in the authentication table. WebGUI::Auth-> saveparams(userid,authmethod,data) - Saves the user's authentication parameters to the database. An unamed developer, who was working late nights to try to complete the Auth module, should have used the data stored in the object here. Perhaps someday he'll go in there and clean up that module! Data should be passed in as name/value pairs WebGUI::Auth->deleteParams() - Removes the user's authentication parameters from the database for all authentication methods. This is primarily useful when deleting the user's account. WebGUI::HTTP The WebGUI::HTTP package allows the manipulation of HTTP protocol information. The following methods are available WebGUI:: generates and returns an HTTP header WebGUI:: Returns the current mime type being returned (stored in WebGUI's Session) WebGUI:: returns the current HTTP status if one has been set (400, 302, etc) WebGUI:: returns whether the current page will redirect to another location (basicall returns getstatus() eq 302) WebGUI:: allows you to set session cookies. If no timetolive is passed in, the cookie will default to 10 years WebGUI:: - Override the default filename for the document, which is usually the page url. Usually used with setmimetype(). This is used to tell the browser to serve up a document for download rather than as HTML. If no mimetype is passes in, application/octetstream is used WebGUI:: Overrides the mime type for the document, which is by default text/html. WebGUI:: Disables the printing of a HTTP header. Useful in situations when content is not returned to a browser (export to disk for example). WebGUI:: - Sets the necessary information in the HTTP header to redirect to another URL. WebGUI:: - Sets the HTTP status code. Application Utility Application Utilities are those which are most useful in building applicatoins such as macros, assets, wobject, and hourly scripts. We'll take a look at groups of APIs. Since there is so much to cover here, I am going to move quickly. Just knowning that WebGUI has this functionality built in can save you a lot of time in development. I will try to explain things that seem confusing, but time is short and my list is long! Asset Functionality These API methods are used primarily by Assets (including wobject). In some cases, such as the Asset API, they are required.

5 WebGUI::Asset The Asset API, like the Auth API is is almost exclusively used for building custom assets. We will be discussing this more in detail during the Writing Assets class tomorrow, so today I am going to only mention a few useful methods that I won't be spending much time on tomorrow WebGUI::Asset->newByDynamicClass(assetId [,revisiondate]) - This method will dynamically create an asset instance for you on the fly. It is extremely useful in situations that require you to access asset data outside the asset itself. It returns undef if it can't find the classname. WebGUI::Asset->newByUrl([url]) Similar to newbydynamic class, but returns a new Asset object based upon current url, given url or defaultpage (if no url is passed in, the current url or defaultpage assets are returned). Since each asset has it's own URL, the url of the asset (not the layout on which the asset is a child) must be passed in here. Once you have a valid asset instance, the following are useful for retrieving data. WebGUI::Asset->get([propertyName]) - Returns the value of propertyname. If propertyname is not passed in, a reference to a list of all the properties of an asset instance is returned. This method access the asset properties directly (doesn't check cache) WebGUI::Asset->getId() - Returns the assetid of an asset instance. WebGUI::Asset->getUrl([params]) - Returns the relative URL of an asset instance. There are methods in WebGUI::URL that allow you to return the full URL. Anything in the params string will be added to the end of the url. These should be name value pairs in the format seperated by colons (to ensure XHTML compliency) name1=value1;name2=value2;name3=value3 WebGUI::Asset->getValue (key) - Returns the value of anything it can find with an index of key, or else it returns undefined. This method is similar to get, but faster since it will retrieve data from cache if it finds it. WebGUI::Id Has one method which is used by everything in WebGUI to generate global unique identifiers (guids) WebGUI::Id::generate() - generates a global unique id. WebGUI::International - This package provides an interface to the internationalization system. WebGUI::International::get(internationalId[,namespace,languageId]) - Returns the internationalized message string for the user's language. If there is no internationalized message, this method will return the English string. WebGUI::International::getLanguage([languageId,propertyName]) - Returns a hash reference to a particular language's properties. Defaults to English WebGUI::International::getLanguages() - Returns a hash reference to the languages (languageid/lanugage) installed on this WebGUI system. WebGUI::International::makeUrlComplient(url[,language]) - Manipulates a URL to make sure it will work on the internet. It removes things like non-latin characters, etc. The rules for for makeurlcomplient are specified in each language package (English.pm, etc) Additinonally, the International system can be called as an object by calling WebGUI::International->new([ namespace, languageid ]). Manipulating Resources These API methods are used for dealing with resources

6 be them external databases, LDAP servers, or local files. WebGUI::DatabaseLink - This package contains utility methods for WebGUI's database link system. The database link system allows users to set up database properties in a central location, and use those links in applications (such as SQL Reports) which utilize database links. This API is useful whenever writing an application that connects to a external database. It prevents having to store database connection information in multiple locations. WebGUI::DatebaseLink::getList() Returns a hash reference containing all the available database links. This method is a static member of the class WebGUI::DatabaseLink->get(databaseLinkId) Returns a hash containing data from a single database link. This method is a static member of the class WebGUI::DatabaseLink->new(databaseLinkId) creates a new databaselink object reference to the databaselinkid passed in. WebGUI::DatabaseLink->disconnect() - disconnects cleanly from the current databaselink properly closing all open connections. WebGUI::DatabaseLink->dbh() - Returns a DBI handle for the current database link, connecting if necessary. The DBI handle can in turn be used with the WebGUI::SQL package (which we will discuss next) WebGUI::SQL This package interfaces with SQL databases. It implements Perl DBI functionality in a less code-intensive manner and adds some extra functionality. It also makes it easy to perform database transactions and return data. This is one of the most widely used packages in WebGUI. Returning Simple Data Returning simple data is just as it sounds, simple. The API handles the database connection completely (including cleanup), executes the query against the database, and returns the data in the format specified by the function. Use these whenever possible. WebGUI::SQL->buildArray ( sql [, dbh ] ) - Builds an array of data from the first column in the query. WebGUI::SQL->buildArrayRef ( sql [, dbh ] ) - Builds an array reference of data from the first column in the query. WebGUI::SQL->buildHash ( sql [, dbh ] ) - Builds a hash of name value pairs of the first two columns of data in the query. WebGUI::SQL->buildHashRef ( sql [, dbh ] ) - Builds a hash reference of name value pairs of the first two columns of data in the query. WebGUI::SQL->getRow ( table, key, keyvalue [, dbh ] ) - Returns a single row of data as a hash reference from the specified table. Name value pairs are returned where the name is the column and the value is the value of the column. WebGUI::SQL->quickArray ( sql [, dbh ] ) - Executes a query and returns a single row of data as an array. Also useful in returning specific data from the database (demonstrate) WebGUI::SQL->quickCSV ( sql [, dbh ] ) - Executes a query and returns a comma delimited text blob with column headers. WebGUI::SQL->quickHash ( sql [, dbh ] ) - Executes a query and returns a single row of data as a hash. WebGUI::SQL->quickHashRef ( sql [, dbh ] ) - Executes a query and returns a single row of data as a hash reference.

7 WebGUI::SQL->quickTab ( sql [, dbh ] ) - Executes a query and returns a tab delimited text blob with column headers. Returning Lists of Data - The methods below return statement handlers which are object references to the class. Special object methods are available to retrieve data from these statement handlers. A special note, methods that produce statement handlers DO NOT close database connections. You must explicitly call the finish() method described in the next sub-section. WebGUI::SQl->read ( sql [, dbh, placeholders ] ) - This is a utility method that runs both a prepare and execute all in one. WebGUI::SQL->unconditionalRead ( sql [, dbh, placeholders ] ) - An alias of the ``read'' method except that it will not cause a fatal error in WebGUI if the query is invalid. This is useful for user generated queries such as those in the SQL Report. Returns a statement handler. WebGUI::SQL->prepare ( sql [, dbh ] ) - To be used in creating prepared statements. Use with the execute method. Statement Handler Functions With a statement handler created from a valid sql query in one using one of the above functions, the following methods are available for reading the data, metadata, and cleaning up the connections. $sth-> array () - Returns the next row of data as an array. $sth->getcolumnnames - Returns an array of column names. Use with a ``read'' method. $sth->errorcode - Returns an error code for the current handler. $sth->errormessage - Returns a text error message for the current handler. $sth->execute([ placeholders ]) - Executes a prepared SQL statement. $sth->finish () - Ends a query after calling the ``read'' method. $sth->hash () - Returns the next row of data in the form of a hash. Must be executed on a statement handler returned by the ``read'' method. $sth->hashref () - Returns the next row of data in the form of a hash reference. Must be executed on a statement handler returned by the ``read'' method. Writing to the database the following methods can all be used to write data to your database. In order to write transactionally (commit, rollback), you must be using a database that supports those transactions. WebGUI::SQL->beginTransaction ( [ dbh ]) - Starts a transaction sequence. To be used with commit and rollback. Any writes after this point will not be applied to the database until commit is called. WebGUI::SQL->commit ( [ dbh ]) - Ends a transaction sequence. To be used with begintransaction. Applies all of the writes since begintransaction to the database. WebGUI::SQL->rollback ( [ dbh ]) - Ends a transaction sequence. To be used with begintransaction. Cancels all of the writes since begintransaction. WebGUI::SQL->setRow ( table, key, data [, dbh, id ] ) - Inserts/updates a row of data into the database. Returns the value of the key. This method eliminates the need to check to see if a value already exists in the database, it detects that based on the key passed in. Extremely useful WebGUI::SQL->write ( sql [, dbh ] ) - A method specifically

8 designed for writing to the database in an efficient manner. It handles all database connectivity including cleanup Utility Methods Utility methods are exported from the SQL package and can be called directly from your code as long as it uses WebGUI::SQL getnextid (idname) - Increments an incrementer of the specified type and returns the value. You must create a column in the incrementer table in order to use this function. quote (string[,dbh]) - Returns a string quoted and ready for insert into the database. This function only works if the database handler API supports the quote method. quoteandjoin (arrayref[,dbh]) - Returns a comma seperated string quoted and ready for insert/select into/from the database. This is typically used for a statement like ``select * from sometable where field in (''.quoteandjoin(\@strings).``)''. This function only works if the database handler API supports the quote method. WebGUI::LDAPLink similar to DatabaseLink, LDAPLink contains utility methods for WebGUI's LDAPLink system. The LDAPLink system allows users to create and store information for connection to and authenticating against LDAP servers. These links can then be used by applications which connect via LDAP. WebGUI::DatebaseLink::getList() Returns a hash reference containing all the available database links. This method is a static member of the class WebGUI::DatabaseLink->get(databaseLinkId) Returns a hash containing data from a single database link. This method is a static member of the class WebGUI::LDAPLink->new(ldapLinkId) constructs a new LDAPLink from the ldaplinkid passed in WebGUI::LDAPLink->bind() - Authenticates against the ldap server with the parameters stored in the class, returning a valid ldap connection, or 0 if a connection cannot be established WebGUI::LDAPLink->getErrorMessage([ldapErrorCode]) - Returns the error string representing the error code generated by Net::LDAP. If no code is passed in, the most recent error stored by the class is returned WebGUI::LDAPLink->unbind() - unbinds cleanly from the current ldaplink. The LDAPLink class has a destructor which calls unbind in cases where this is not called. WebGUI::LDAPLink->getProperty(dn,property) - Returns the value of the property passed in based on distinguised name search. WebGUI::LDAPLink->recurseProperty(base,array,property [,alternatekey]) Recursively searches base, building array (passed in as an array ref) by value, recuring on property or alternatekey if one is passed in. While complicated, this is useful in finding items that are refereneced by pointers in LDAP such as a groups of groups system. WebGUI::Storage The WebGUI Storage package provides a mechanism for storing and retrieving files that are not put into the database directly Creating Storage The methods here are used when creating Storage locations. Storage locations are created by hashing the storageid and placing the files in the last folder in the hash. Since guids are unique, files should never be overwritten

9 WebGUI::Storage->create - Creates a new storage location on the file system, creating a new storage id WebGUI::Storage->get(storageId) - Returns a WebGUI::Storage object using the storage id passed in Streaming Files These methods are used to write data from a destination to the storage location on the filesystem. WebGUI::Storage->addFileFromFilesystem(pathToFile) - Grabs a file from the server's file system and saves it to a storage location and returns a URL compliant filename. WebGUI::Storage->addFileFromFormPost(formVarName) - Grabs an attachment from a form POST and saves it to this storage location WebGUI::Storage->addFileFromHashref(filename,hashref) - Stores a hash reference as a file and returns a URL compliant filename. Retrieve the data with getfilecontentsashashref. WebGUI::Storage->addFileFromScalar(filename,content) - Adds a file to this storage location, storing content as the file. It returns a URL compliant filename. Retrieving Storage These methods are used to retrieve files from a storage location. WebGUI::Storage->getFiles - Returns an array reference of the files in this storage location. If you have more than one file in your storeage location, you may need to loop through this array in and choose the right one to work with. WebGUI::Storage->getFileContentsAsHashref(filename) - Returns a hash reference from the file. Must be used in conjunction with a file that was saved using the addfilefromhashref method. This is due to the way the method stores the hashreference in the file. This is particularly useful if the need should arise to serialize data. WebGUI::Storage->getFileContentsAsScalar(filename) - Reads the contents of a file into a scalar variable and returns the scalar. Storage Information The following methods provide useful information regarding storage as well as meta data regarding files in the storage location. WebGUI::Storage->getErrorCount - Returns the number of errors that have been generated on this object instance. WebGUI::Storage->getFileExtension(filename) - Returns the extension or type of this file. WebGUI::Storage->getFileIconUrl(filename) - Returns the icon associated with this type of file. WebGUI::Storage->getFileSize(filename) - Returns the size of this file. WebGUI::Storage->getId - Returns the unique identifier of this storage location. WebGUI::Storage->getLastError - Returns the most recently generated error message (useful for debugging) WebGUI::Storage->getPath(filename) - Returns a full path to this storage location. WebGUI::Storage->getUrl(filename) - Returns a URL to this storage location.

10 Filesystem Utilities These methods allow you to manipulate files on the filesystem WebGUI::Storage->copy - Copies a storage location and it's contents. Returns a new storage location object. Note that this does not copy privileges or other special filesystem properties. WebGUI::Storage->tar(filename) - Archives this storage location into a tar file and then compresses it with a zlib algorithm. It then returns a new WebGUI::Storage object for the archive WebGUI::Storage->untar(filename) - Unarchives a file into a new storage location. Returns the new WebGUI::Storage object. WebGUI::Storage->delete - Deletes this storage location and its contents (if any) from the filesystem and destroy's the object. WebGUI::Storage->deleteFile(filename) - Deletes a file from it's storage location. WebGUI::Storage->rename(filename,newFilename) - Renames an file's filename. WebGUI::Storage->setPrivileges(userId,groupIdView,groupIdEdit) - Set filesystem level privileges for this file. Used with the uploads access handler. Dealing with HTML These API methods are all used to deal with HTML level functions. From generating form elements, to processing macros, these tools give you everything you need to create WebGUI specific HTML. WebGUI::Form The WebGUI::Form API generates and returns raw HTML for many different types of HTML form elements, saving you hours of work. WebGUI comes standard with 40 different form types. I know you are saying, but Frank, there are only a few HTML form types, how does WebGUI have 40 of them? WebGUI form elements are functional, meaning they are designed for a specific, common form functions in WebGUI. Some examples of WebGUI form elements are Integer which only allows integer input, Group which returns a select list of WebGUI groups, and Yes/No which returns a radio button list marked yes and no with values 1 and 0. I'm not going to describe each what each and every form function does (and how to use them we'll be here all day), but most of them are self explanatory. Here is a list (see slideshow). The Forms API is useful when creating form elements that you want to lay out yourself, or provide to the end user as a template variable so he/she can decide where it goes. In addition to the 40 form elements in the Forms package, the following API methods are also available WebGUI::Form::formHeader(hashref) Creates the opening form tag <form...> The following can be set on the command line by passing in a hash reference of name/value pairs: action (which whould always be passed in as $self->geturl by assets) defaults to the current page, method which defaults to post, enctype which defaults to multipart/form-data, and extras which, if supplied, will be added raw to the end of the form tag WebGUI::Form::formFooter() - Creates the closing form tag </div></form> WebGUI::HTMLForm WebGUI::HTMLForm takes the Form package one step further by auto creating tables around your forms. Since most forms are two column tables, this package takes the work out of laying out your form.

11 WebGUI::HTMLForm is an object oriented class, so you must first create your object. From your object pointer, you will have access to the same forms as the forms package with the additional capability to provied a label for each of the form elements you add to the object. Form elements are pluggable. If WebGUI does not have a functional Form Element your application uses a lot, you can create your own. In addition to the 40 form elements in the HTMLForm package, the following API methods are also available WebGUI::HTMLForm->new ( [ action, method, extras, enctype, tableextras ] ) - creates a new HTMLForm object. Action defaults to the current page (although you should always pass in $self->geturl when developing assets), method defaults to post, enctype defaults to multipart/form-data. WebGUI::HTMLForm->print() - Returns the HTML for this form object. WebGUI::HTMLForm->printRowsOnly() - Returns the HTML for this form object except for the table header and footer. WebGUI::HTMLForm->raw(value) - Adds raw data to the form. This is primarily useful with the printrowsonly method and if you generate your own form elements. This is useful when you need to format a portion of the form differently WebGUI::HTMLForm->trClass() Sets a CSS class for the Table Row. By default the class is undefined. WebGUI::FormProcessor Now that you've build your form, you need a way to retrieve all the data and format it for the database. You could do this manually accessing $session{form} directly, but a much easier way to do this is to use the Form::Processor equivalent of the WebGUI::Form or WebGUI::HTML form you used to collect the data. Methods exist for each form element which accepts user data which handles converting it into something you can store in the database and easily be re-used as the value of the next HTMLForm. Once again, I'm not going to go through all of the methods available here as there are far too many. There is one additional methods in the WebGUI::FormProcessor package which allows you to dynamically process data from a form post: WebGUI::FormProcessor::process(name,type [,default]) - Returns whatever would be the expected result of the method type that was specified. This method also checks to make sure that the field is not returning a string filled with nothing but whitespace. WebGUI::HTML WebGUI::HTML contains utility functions for manipulating and massaging HTML. WebGUI::HTML::cleanSegment(html) - Returns an HTML segment that has been stripped of the <BODY> tag and anything before it, as well as the </BODY> tag and anything after it. It's main purpose is to get rid of META tags and other garbage from an HTML page that will be used as a segment inside of another page. This filter does have one exception, it leaves anything before the <BODY> tag that is enclosed in <STYLE></STYLE> or <SCRIPT></SCRIPT> tags. WebGUI::HTML::filter(html[,filter]) - Returns HTML with unwanted tags filtered out. Valid filters are: "all", "none", "macros", "javascript", or "most". Defaults to "most". "all" removes all HTML tags and macros; "none"

12 removes no HTML tags; "javascript" removes all references to javacript and macros; "macros" removes all macros, but nothing else; and "most" removes all but simple formatting tags like bold and italics. WebGUI::HTML::format(content [,contenttype]) - Formats various text types into HTML. Valid content types are 'html', 'text', 'code', and 'mixed'. Defaults to mixed. WebGUI::HTML::html2text(html) - Converts html to text. It currently handles only text, so tables or forms are not converted. WebGUI::HTML::makeAbsolute(html [,baseurl]) - Returns html with all relative links converted to absolute. WebGUI::HTML::processReplacements(html) - Processes text using the WebGUI replacements system. WebGUI::Icon - A package for generating user interface buttons. These subroutines do nothing other than to create a short way of doing much longer repetitive tasks. They simply make development easier through fewer keystrokes and less cluttered code. The icons produced come from the icon scheme that is set in WebGUI settings. I'm not going to bore you by going through each one and explaining what is already obvious, however I will mention methods that stray from the norm. The deleteicon accepts confirmtext as a third parameter. If you enter somthing here, when the user clicks the icon, they will be challeged with a javascript confirm box containing your text. Otherwise there is no challenge. The second oddity is WebGUI::Icon::getToolbarOptions() which returns a hash reference containing the list of toolbar icon sets to be selected in user profile. WebGUI::Icon::copyIcon(urlParameters [,pageurl]) WebGUI::Icon::cutIcon(urlParameters [,pageurl]) WebGUI::Icon::deleteIcon(urlParameters [,pageurl,confirmtext]) WebGUI::Icon::dragIcon() WebGUI::Icon::editIcon(urlParameters [,pageurl ]) WebGUI::Icon::exportIcon (urlparameters [,pageurl]) WebGUI::Icon::getToolbarOptions() - returns a hash reference containing the list of toolbar icon sets to be selected in user profile. WebGUI::Icon::helpIcon(helpId [,namespace]) WebGUI::Icon::lockedIcon(urlParameters [,pageurl]) WebGUI::Icon::manageIcon(urlParameters [,pageurl]) WebGUI::Icon::moveBottomIcon(urlParameters [,pageurl]) WebGUI::Icon::moveDownIcon(urlParameters [,pageurl]) WebGUI::Icon::moveLeftIcon(urlParameters [,pageurl]) WebGUI::Icon::moveRightIcon(urlParameters [,pageurl]) WebGUI::Icon::moveTopIcon(urlParameters [,pageurl]) WebGUI::Icon::moveUpIcon(urlParameters [,pageurl]) WebGUI::Icon::pageIcon() WebGUI::Icon::pasteIcon(urlParameters [,pageurl]) WebGUI::Icon::shortcutIcon(urlParameters [,pageurl]) WebGUI::Icon::viewIcon(urlParameters [,pageurl]) WebGUI::Icon::wobjectIcon() WebGUI::Macro - This package is the interface to the WebGUI macro system. Note: This entire system is likely to be replaced in the near future. It has served WebGUI well since the very beginning but lacks the speed and flexibility that WebGUI users will require in the future. WebGUI::Macro::filter(html) - Removes all the macros from the HTML

13 segment. WebGUI::Macro::getParams(parameterString) - A simple, but error prone mechanism for getting a prameter list from a string. Returns an array of parameters. This particular algorithm tends to work well with comma delimited text files such as CSV files WebGUI::Macro::negate(html) - Nullifies all macros in this content segment. WebGUI::Macro::process(html) - Runs all the WebGUI macros to and replaces them in the HTML with their output. Iff you are doing something in which you want your users to be able to use macros for adding dynamic content, this is what you should call WebGUI::Style - This package contains utility methods for WebGUI's style system. WebGUI::Style::process(content,templateId) - Returns content wrapped in the template style passed in (based upon the current WebGUI session information). If makeprintable is set, the WebGUI printable style for the session will be displayed WebGUI::Style::setLink (url,params) - Sets a <link> tag into the <head> of this rendered page for this page view. This is typically used for dynamically adding references to CSS and RSS documents. WebGUI::Style::setMeta(params) - Sets a <meta> tag into the <head> of this rendered page for this page view. WebGUI::Style::setRawHeadTags(tags) - Sets data to be output into the <head> of the current rendered page for this page view. WebGUI::Style::setScript(url,params) - Sets a <script> tag into the <head> of this rendered page for this page view. This is typically used for dynamically adding references to Javascript or ECMA script. WebGUI::Style::generateAdditionalHeadTags() - This method performs the work of adding tags that were set using setlink, setmeta, setscript, and setrawheadtags. WebGUI::URL - This package provides URL writing functionality. It is important that all WebGUI URLs be written using these methods so that they can contain any extra information that WebGUI needs to add to the URLs in order to function properly. WebGUI::URL::append(url,pairs) - Returns a URL after adding some information to the end of it. WebGUI::URL::escape(string) - Encodes a string to make it safe to pass in a URL. Synonmous to url encode WebGUI::URL::gateway(pageURL [,pairs]) - Generate a URL based on WebGUI's gateway script. This method is called by $self->geturl for Assets. You should only need to use this method outside of the asset construct WebGUI::URL::getScriptURL() - Returns the URL for the gateway script. You may need to append this when creating absolute urls if you have a gateway script that is anything besides "/" (ex: /index.pl). It's usually good practice to add this anyway in case your server settings change. WebGUI::URL::getSiteURL() - Returns a constructed site url. The returned value can be overridden using the setsiteurl function. This method should also be prepended to $self->geturl or WebGUI::URL::gateway() if you wish to

14 provide an absolute URL to a page WebGUI::URL::makeCompliant(string) - Returns a string that has made into a WebGUI compliant URL based upon the language being submitted. WebGUI::URL::makeAbsolute(url [,baseurl]) - Returns an absolute url. You can also use this method to return the absolute URL from assets. WebGUI::URL::page([pairs,useSiteUrl,skipPreventProxyCache ])- Returns the URL of the current page. WebGUI::URL::setSiteURL(url) - Sets an alternate site url in session. This is one of those things you would use WebGUI::Session::refreshSessionVars() to clear. WebGUI::URL::unescape(string) - Decodes a string that was URL encoded. WebGUI::URL::urlize(string) - Returns a url that is safe for WebGUI pages. User, Groups, & Privileges - These API methods are all used to deal with Users, Groups and Privileges. WebGUI::User - This package provides an object-oriented way of managing WebGUI users as well as getting/setting a users's profile data. WebGUI::User->new([userId,overrideId]) - Creates a new user object from which you can get and set user information. If no userid is passed in, the Visitor is returned. If userid is set to "new" a new user is created. WebGUI::User->authMethod([value]) - Used to get or set the auth method for this user. Pass in a value to set the auth method (this can be dangerous if you aren't familiar with the auth pluggin you are changing the user to be using. There are additional auth settings that may need to be created in order for the user to be able to log in propertly) WebGUI::User->dateCreated() - Returns the epoch for when this user was created. WebGUI::User->karma([amount,source,description]) - used to get the current level of karma the user has earned. If amount, source, and description are bassed in, the user's karma will be updated to reflect this first. Note that karma can be positive or negative WebGUI::User->lastUpdated() - Returns the epoch for when this user was last modified. WebGUI::User->profileField (fieldname,[value]) - Returns a profile field's value. If "value" is specified, it also sets the field to that value. WebGUI::User->status([value]) - Returns the status of the user. If value is present, it sets the status as well. WebGUI::User->username([value]) - Returns the username of the user. If value is present, it sets username as well. WebGUI::User->userId() - Returns the userid of the user. WebGUI::User->addToGroups(groups [,expireoffset]) - Adds this user to the specified groups. Specify the groups as an array reference WebGUI::User->deleteFromGroups(groups) - Deletes this user from the specified groups. Specify the groups as an array reference WebGUI::User->delete() - Delete's the user and all associated data including authentication data. WebGUI::Privilege - This package provides access to the WebGUI security system and security messages.

15 WebGUI::Privilege::adminOnly() - Returns a message stating that this functionality can only be used by administrators. This method also sets the HTTP header status to 401. WebGUI::Privilege::insufficient() - Returns a message stating that the user does not have the required privileges to perform the operation they requested. This method also sets the HTTP header status to 401. WebGUI::Privilege::noAccess() - Returns a message stating that the user does not have the privileges necessary to access this page. This method also sets the HTTP header status to 401. I prefer to use this method since it will prompt the user to login if they are not already. WebGUI::Privilege::notMember() - Returns a message stating that the user they requested information about is no longer active on this server. This method also sets the HTTP header status to 400. WebGUI::Privilege::vitalComponent() - Returns a message stating that the user made a request to delete something that should never delete. This method also sets the HTTP header status to 403. WebGUI::Group - This package provides an object-oriented way of managing WebGUI groups and groupings. While some of these topics are interesting, I can't cover how the grouping functions work. That is a topic for a content management session. WebGUI::Group->new([groupId]) - Creates a new group object from which you can get and set group information. If no groupid is passed in, default values for everything are returned. If groupid is set to "new" a new group is created. WebGUI::Group->find(name) - An alternative to the constructor "new", use find as a constructor by name rather than id. WebGUI::Group->autoAdd([value]) - Returns an boolean stating whether users can add themselves to this group. If value is specified, the autoadd is set to that value WebGUI::Group->autoDelete([value]) - Returns an boolean stating whether users can delete themselves from this group. If value is specified, the autodelete is set to that value WebGUI::Group->dateCreated() - Returns the epoch for when this group was created. WebGUI::Group->deleteOffset([value]) - Returns the number of days after the expiration to delete the grouping. If value is specified, dateoffest is set to that value. Defaults to -14 WebGUI::Group->description([value]) - Returns the description of this group. If value is specified, the description is set to that value WebGUI::Group->expireNotify([value]) - Returns a boolean value whether or not to notify the user of the group expiry. If value is specified, expirynotify is set to that value WebGUI::Group->expireNotifyMessage([value]) - Returns the message to send to the user about expiration. If value is specified, exirenofitymessage is set to that value WebGUI::Group->expireNotifyOffset([value]) - Returns the number of days after the expiration to notify the user. If value is specified, expirenotifyoffset is set to that value

16 WebGUI::Group->expireOffset([value]) - Returns the number of seconds any grouping with this group should expire after. If value is specified, expireoffset is set to that value WebGUI::Group->groupId() - Returns the groupid for this group. WebGUI::Group->karmaThreshold([value]) - Returns the amount of karma required to be in this group. If value is specified, the karma threshold is set to that value WebGUI::Group->ipFilter([value]) - Returns the ip address range(s) the user must be a part of to belong to this group. If value is specified, the ip range is set to that value WebGUI::Group->isEditable([value]) - Returns a boolean value indicating whether the group should be managable from the group manager. System level groups and groups autocreated by wobjects would use this parameter. If value is specified, iseditable is set to that value WebGUI::Group->lastUpdated() - Returns the epoch for when this group was last modified. WebGUI::Group->name([value]) - Returns the name of this group. If value is specified, the name of the group is set to that value WebGUI::Group->scratchFilter([value]) - Returns the scratch filter to be used in order to dynamically set users to groups. If value is specified, the scratch filter is set to that value WebGUI::Group->showInForms([value]) - Returns a boolean value indicating whether the group should show in forms that display a list of groups. System level groups and groups autocreated by wobjects would use this parameter. WebGUI::Group->dbQuery([value]) - Returns the dbquery for this group. If value is specified, the dbquery for the group will be set to that value. WebGUI::Group->databaseLinkId([value]) - Returns the databaselinkid for this group. If value is specified, the databaselinkid is set to that value. WebGUI::Group->dbCacheTimeout([value]) - Returns the dbcachetimeout for this group. If value is specified, the dbcachetimeout is set to that value. WebGUI::Group->ldapGroup([value]) - Returns the ldapgroup tied to this group. If value is specified, the ldapgroup tied to this group is set to that value. WebGUI::Group->ldapGroupProperty([value]) - Returns the ldap group property tied to this group. If value is specified, the ldapgroupproperty this group is tied to is set to that value. WebGUI::Group->ldapRecursiveProperty([value]) - Returns the ldap recursive property tied to this group. (this is used for a recursive search of groups of groups in ldap). If value is specified, the ldap recursive property tied to this group is set to that value. WebGUI::Group->addGroups(groups) - Adds groups to this group. Groups should be passed in as an array reference of groupids WebGUI::Group->addUsers(users) - Adds users to this group. Users should be passed in as an array reference of userids WebGUI::Group->deleteGroups(groups) - Deletes groups from this group. Groups should be passed in as an array reference of groupids WebGUI::Group->deleteUsers(users) - Deletes users from this group. Users should be passed in as an array reference of userids

17 WebGUI::Group->delete() - Deletes this group and all references to it including groupings and groupgroupings WebGUI::Grouping - This package provides an interface for managing which users belong to which groups as well as user/group privileges WebGUI::Grouping::addGroupsToGroups(groups,toGroups) - Adds groups to a group. Groups and togroups should be passed in as array references WebGUI::Grouping::addUsersToGroups(users,groups [,expireoffset]) - Adds users to the specified groups. Users and groups should be passed in as array references. WebGUI::Grouping::deleteGroupsFromGroups(groups,fromGroups) - Deletes groups from these groups. Groups and fromgroups should both be passed in as array references. WebGUI::Grouping::deleteUsersFromGroups(users,groups) - Deletes a list of users from the specified groups. Users and groups should both be passed in as array references. WebGUI::Grouping::getGroupsForGroup(groupId) - Returns an array reference containing a list of groups the specified group is in. WebGUI::Grouping::getGroupsForUser(userId [,withoutexpired ]) - Returns an array reference containing a list of groups the specified user is in. Set withoutexpired to exlude groups which have already expired. WebGUI::Grouping::getGroupsInGroup(groupId [,recursive]) - Returns an array reference containing a list of groups that belong to the specified group. If recursive is set to true, groups of groups will be searched. WebGUI::Grouping::getUsersInGroup(groupId [,recursive ]) - Returns an array reference containing a list of users that belong to the specified group. If recursive is set to true, groups of groups will be searched. WebGUI::Grouping::isInGroup([groupId,userId ]) - Returns a boolean (0 1) value signifying that the user has the required privileges. Always returns true for Admins. This function is commonly used when building assets that have custom privileges. WebGUI::Grouping::userGroupAdmin(userId,groupId[,value]) - Returns a 1 or 0 depending upon whether the user is a sub-admin for this group. If value is set, user will be set or unset as a sub-admin depending on the value. WebGUI::Grouping::userGroupExpireDate(userId,groupId [,epoch ]) - Returns the epoch date that this grouping will expire. If value is specified, epoch data will be set to that value Messaging & Error Handling - These API methods are all used to deal with messeages to and from the system. WebGUI::Mail Provides a common method for sending messages from WebGUI using SMTP based services. This method bypasses the MessageLog. WebGUI::Mail::send(to,subject,message [,cc,from,bcc]) - Sends an SMTP message to the specified user. WebGUI::MessageLog WebGUI::MessageLog::addEntry(userId,groupId,subject,message [,url,status,from]) - Adds an entry to the message log and sends out

18 notification to user in the manner the user has specified in the profile (ICQ, pager, , etc). UserId can be left blank if sending to a group of users. WebGUI::MessageLog::addInternationalizedEntry (userid,groupid,url,internationalid [,namespace,status]) - Adds an entry to the message log using a translated message from the internationalization system and sends out notifications to users. As in the addentry method, notification is sent to the user in the manner specified in the profile. WebGUI::MessageLog::completeEntry(messageLogId) - Set a message log entry to complete. Updates the status to 'complete' and specifies the date. WebGUI::ErrorHandler This package provides simple but effective error handling, debugging, and logging for WebGUI.. WebGUI uses Log::Log4perl to set log levels and write error messages. More information on Log::Log4perl can be found on the cpan website or in the perl docs for this module. WebGUI::ErrorHandler::audit(message) - A convenience function that wraps info() and includes the current username and user ID in addition to the message being logged. WebGUI::ErrorHandler::debug(message) - Adds a DEBUG type message to the log. These events should be things that are only used for diagnostic purposes. WebGUI::ErrorHandler::error(message) - Adds a ERROR type message to the log. These events should be things that are errors that are not fatal. For instance, a non-compiling plug-in or erroneous user input. WebGUI::ErrorHandler::fatal(message) - Adds a FATAL type message to the log, outputs an error message to the user, and forces a close on the session. This should only be called if the system cannot recover from an error, or it would be unsafe to recover from an error like database connectivity problems. WebGUI::ErrorHandler::getLogger() - Returns a reference to the logger. WebGUI::ErrorHandler::getSessionVars() - Returns a text message containing all of the session variables. WebGUI::ErrorHandler::getStackTrace() - Returns a text formatted message containing the current stack trace. Very useful for debugging application level code. You can add this method at any point in code and have it return an entire record of what has been called. WebGUI::ErrorHandler::info(message) - Adds an INFO type message to the log. This should be used for informational or status types of messages, such as audit information and FYIs. WebGUI::ErrorHandler::security(message) - A convenience function that wraps warn() and includes the current username, user ID, and IP address in addition to the message being logged. WebGUI::ErrorHandler::showDebug() - Creates an HTML formatted string which dumps a number of session variables to the screen. Useful in debugging code. As a side note, you can enable show debug in any WebGUI enviornment to see this method in action WebGUI::ErrorHandler::warn(message) - Adds a WARN type message to the log. These events should be things that are potentially severe, but not errors, such as security attempts or ineffiency problems. Miscellaneous Features WebGUI::DateTime Synonmous for causing a large majority of headaches in