Whence Editable, Has Help, and Has About?

One of the kind folks who delivers training for Unicon asked me today:

When I publish a channel and arrive at the Channel Controls pane in the channel publication workflow as presented by the Channel Manager, how are the 'Editable', 'Has Help', and 'Has About' populated with relevant data…. I guess I am asking where these help files are stored and how does a school go about editing them?

What an excellent question. I'm always heartened to see someone seeking to understand the opportunities uPortal presents.

What are channel controls, anyway?

IChannel is an API for developing drop-in widgets for inclusion in user layouts and presentation to eventual end users via uPortal. It is the non-standardsy, adhoc, uPortal-local predecessor to JSR-168. IChannels were designed with a handful of considerations in mind. One was making common development tasks easy. Since it's a worthwhile best practice to make every channel easy to publish and configure, there's a technology for making it very easy to deliver simple channel publication workflows. A "channel publishing document" (CPD) defines the workflow for publishing a particular "channel type".

"Controls" are the little buttons typically at the upper right of a channel as rendered in uPortal (placement of buttons and their use at all depends on the theme and skin.)

They control things like editing the channel, getting information about the channel, and getting help with the channel. These controls are handled by the IChannel code itself -- your particular channel can do something special in response to each of these. Other typical uPortal controls are those to maximize the channel, minimize the channel, and detach the channel into a new window. Those controls are handled by the portal framework (almost always the theme transform) rather than the IChannel itself.

What determines whether these controls are available?

One of the elements in a CPD defines the presence of these controls in the channel publication workflow for a particular channel type.

          
<controls>
      <control type="edit" include="no" override="no"/>
      <control type="about" include="no" override="no"/>
      <control type="help" include="no" override="no"/>
 </controls>

   

The "include" attribute indicates whether this control should be displayed with (included in the display of) the channel. "no" suggests to uPortal not to display the control, whereas "yes" suggests that uPortal to display the control. I say "suggests" because this is ultimately mediated by the theme transform, which is customizable. So you could choose to enable or disable these controls on some criteria other than CPD configuration. In fact, Academus, Unicon's productized uPortal, overrides the default behavior around the "help" control to provide links to static help content.

The "include" element actually only defines the default value of the checkbox in the Channel Manager channel publishing workflow. The administrator publishing the channel can override this default value if the "override" attribute is "yes". If the "override" attribute is "no" then the checkbox is disabled in the channel publication UI and the channel publisher cannot override the value specified in the CPD.

That behavior makes a lot of sense because of the fact that these controls are only meaningful if the underlying channel supports them. Some channel types support these controls, while others don't.

The nuance differentiating "include" and "override" means that it is possible to multiply publish a given channel, in some configurations including these controls and in others not. Couple this feature with the ability to restrict the availability of a given channel publication to specific user groups, and you have a workable way to deliver more and less privileged views on the same channel to different user groups.

How do channels know when their controls have been clicked?

When you click an "edit", "about", or "help" control in uPortal, the portal framework translates this to a PortalEvent which it then presents to the IChannel via the receiveEvent() method:

          
public void receiveEvent (PortalEvent ev);

   

(Notice that the description of the configuration in the Channel Controls pane was in terms of whether the portal would propagate events or not.) Some channels ignore the relevant PortalEvents. These channels do not support these controls. Their CPDs reflect this to discourage portal administrators from configuring channels to have useless controls. If you did manage to publish a channel with controls generating events not supported by the underlying IChannel, it wouldn't be that big of a deal -- you'd just have control buttons that don't do anything.

Other channels handle the relevant PortalEvents. For instance, let's consider my favorite channel, CWebProxy. (CWebProxy is the subject of another of my blog posts.) CWebProxy allows you to define alternative URLs to display in response to the user clicking channel controls. You could proxy "http://myschool.edu/reallyneat/info" as the default display of a CWebProxy instance, and configure it to display the content of "http://myschool.edu/reallyneat/help" when the user clicks the help button. Likewise you can associate URLs with the edit and about events.

So, if you were developing a custom application to be presented via CWebProxy, you could include a help user experience and even a preferences editing user experience, and of course an about user experience giving yourself due credit for a job well done, and configure CWebProxy to display each of these experiences in response to clicks on the channel controls. You get to spend your time writing interesting help and building worthwhile end user customization user experiences, rather than figuring out how to get users to them.

CPortletAdapter in uPortal translates IChannel PortalEvents to JSR-168 PortletModes. Portlets can but do not always support EDIT and HELP modes. There is no standard ABOUT mode, so by default the About channel event doesn't map to any JSR-168 portlet mode and is not applicable for portlets.

Of course, any custom IChannel you might develop can be made to handle these events in interesting ways.

Summary

uPortal Channel Controls are available for publication or not depending on Channel Type declaration, are actually displayed with any given channel or not based on channel publication configuration, and actually do anything useful or not depending on how the underlying IChannel handles the event. Where and how a school might edit the help content depends on exactly which channel we're talking about and how that channel handles the events. In the case of CWebProxy a school can host and manage help content in a way similar to however they're managing other HTML content.

One clever trick demonstrated in Academus is to at a theme level generate help links based on channel type and associate help with different channel types, thereby sparing the IChannels involved from having to actually handle the Help event.