Dispatchers

From KnowledgeTree Document Management Made Simple

Contents 1 Actions and Methods 2 Getting Data Out 3 Getting around between functions 3.1 Redispatching 3.2 Subdispatching 4 Setting up 5 Persistance 6 UI Helpers 7 See Also

Actions and Methods

A module for KnowledgeTree will typically provide a number of different screens or pages - which we call "actions". For example, in the "user administration" section of KT:

• the first page is an "action" - its the default view
• the "create new user" page is an action
• the code which deals with actually creating the user is an action, which in turn sends the user to the front page.

etc.

To handle this very common situation, and to provide a convenient wrapper to handle a large number of tasks, KT's dispatchers are built around the action concept. Dispatchers provide a lot of infrastructure, and are very easy to extend.

To use an action, simply add "action=myactionname" to the query parameters of the URL of the dispatcher, and then add a function that looks something like this:

function do_myactionname() {
    return "this is what the user will see in the middle of the page";
}

That's all you need to do: once KT decides that your dispatcher is the one that'll be handling this request, then it will automatically check for the "do_<action>" and call it if its present. If no action is specified, or the specified action does not exist, it will attempt to access "main". The return value from that function will be passed through the general page template to produce what will appear to be a "normal" KT page.

Before it actually calls your function, however, a number of other things happen:

1. the current user's "User" object is stored on $this->oUser (you need to be logged in, or it will send you to the login page)
2. it calls the dispatcher's check method. If this returns false then it will deny the user access.
3. it calls the dispatcher's predispatch method so that it can do any housekeeping work
4. finally, it calls the do_<actionname> method.

The most common way to generate the output is to use the Templating system.

Getting Data Out

Getting information back from the user requires that you access the $_REQUEST global variable. That means you'll be writing a lot of code along the lines of

$my_var = KTUtil::arrayGet($_REQUEST, 'my_var', 'cat');

For more info on arrayGet, see KTUtil.

Getting around between functions

A very common situation is to have the following sequence of actions:

1. display an "overview" page, which includes e.g. an "add an object" link
2. when that link is clicked, show a form
3. when the form is submitted, some work is done and the user is either bounced back to (2) or sent to (1) with a nice friendly "success" message

To make this kind of thing easier, there are two handy functions

successRedirectTo($sAction, $sMessage, $aParams)
errorRedirectTo($sAction, $sMessage, $aParams)

The "successRedirectTo" version will commit any active transaction, add the message to the "message queue" (see Info and Error Messages) and then send the user to the action specified (with the $aParams added to the querystring). "errorRedirectTo" adds the message to the "error" queue, rolls back the current transaction and then redirects the user.

As you'll see later, these functions are even clever enough to remember parts of the current request-variables so you don't have to pass them around all the time.

Redispatching

Sometimes the action needs to behave differently depending on values in other variables besides action. To reduce namespace problems, it may also be useful to use an alternate prefix besides do_ in the function names. The redispatch method allows for this.

For example, a particular dispatcher might use subdispatch to another dispatcher only when a certain action is used. This is the case with do_editUserSource in the authentication administration pages, which allows, for example, a password to be set, to force a password to be changed on next login, and so forth. Only editUserSource is passed through to the authentication provider, but the authentication provider can use redispatch on another variable (subaction, in this case) to allow for alternate actions to be done while still within the editUserSource action.

   class KTBuiltinAuthenticationProvider extends KTAuthenticationProvider {
       ...
       
       function do_editUserSource() {
           $this->redispatch('subaction', 'editUserSource');
           exit(0);
       }
       
       function editUserSource_main() {
           ...
       }
       
       function editUserSource_forcePasswordChange() {
           ...
       }
       
       function editUserSource_updatePassword() {
           ...
       }

Subdispatching

Sometimes it is necessary to pass control from the current dispatcher to another dispatcher - like when the dispatcher in action.php looks up the action in question (or when admin.php's dispatcher looks up the admin page), and passes control to another dispatcher. The subdispatch method was created for this purpose.

   class LoginPageDispatcher extends KTDispatcher {
       ...
       
       function do_providerVerify() {
           ...
           
           $oProvider =& KTAuthenticationUtil::getAuthenticationProviderForUser($this->oUser);
           $oProvider->subDispatch($this);
           exit(0);
       }
       
       ...
   }

Subdispatch transfers the existing breadcrumbs, transaction start information, user, session, and other information from the existing dispatcher to the new dispatcher.

Note: subdispatch is called on the new dispatcher, with the existing dispatcher passed as a parameters

Setting up

check()
predispatch()

also:

• security (for document/folder actions)

Persistance

A common problem is keeping certain variables around within the request, while the user is in your common area. For example, it may be useful to always have the current document's ID around, or the Document ID, or a User's ID if you're editing the user, etc. To keep all of this, dispatchers (and a few other pieces) have built-in support for it. All you need to do is call

$this->persistParams(array('Var1','Var2','Var3'));

on the current dispatcher, and then all the functions which generate a local url will "remember" the values of those request parameters unless they're explicitly overridden. This includes (but isn't limited to)

successRedirectTo
errorRedirectTo
subdispatch

etc.

You can also take advantage of this for links in your templates, where the {addQS} {/addQS} will accept a context=$dispatcher option. This will use the dispatcher's persist set to ensure that the link does what you expect. This is one more good reason to always add a "context" parameter to your templates. See also: Templating.

UI Helpers

For the most part, you'll use Templating to generate the actual UI. A lot of different pieces are automatically handled for you (menu, portlets, etc.) in the majority of situations. Other minor items you might want to know:

1. $this->aBreadcrumbs is an array containing all the breadcrumbs for this dispatcher.
2. $this->oPage->setTitle($sTitle) will let you set the page's title.
3. $this->oPage->setBreadcrumbDetails($sDetail) will set the "detail" section of the breadcrumbs (light grey, in brackets at the end).
4. $this->addInfoMessage($sMessage) and $this->addErrorMessage($sMessage) add info / warning messages to the next page to be displayed. (e.g. if you return an actual page, it will be that. If you redirect the user, that page will show the messages.)

See Also

A few other things you'll want to look into:

• Forms
• Widgets
• Validators