Portals Administration

by Crag Wolfe and Ian Baker

ACS Documentation : Portals Documentation : Portals Administration


Understanding Portals

When building a complex web service, especially one with many distinct features and constantly changing content, it is often difficult to provide your users with a simple interface to the array of information available to them. Even if you can provide a simple, organized gateway to your site's vast functionality, you can't know which users will be interested in which sections. One solution to this problem: the portal.

A portal, as its name implies, is intended to be a starting point-- an organized overview of a lot of information, with links to drill-down to more specific information. Because users have differing interests and priorities, and groups within an organization have varied needs and foci, portals are highly customizeable. The portal does not contain any content of its own, but rather, is an effective way to combine and organize information from disparate areas of a site into a single, comprehensive view.

Examples of some popular portals are: My Yahoo! and Slashdot.

The purpose of the portals package is to provide a simple, standardized interface for the production of these configurable portals within ACS.

Portal Components

To understand how the package works, you'll need to understand some terminology.

A portal is made up of one or more portal pages, where the pages appear as links at the top of the portal. In this screenshot, the portal page we are viewing is called "MySloanSpace" and there are links to four other portal pages: Calendar, New Stuff, My Files, and Class Documents.

Within a portal page, there may be any number of portlets. In this screenshot, the portlet at the top left of the page is called "Announcements" and the portlet below is "My Tools." Portlets may be arranged in two columns on the page, or just one column in which case they span the width of the page.
More example portlets

A data feed provides the data inserted into a portlet. If a portal page is thought of as a screen full of boxes, and a portlet a single box, then a data feed would make up the contents of a box. A data feed's code may either be ADP, or Tcl in which case the code is usually just the name of a procedure to evaluate. Examples of both distribute with the portals package. On the default "users" portal page, installed by 04-load-default.sql, "My Tools" and "Search The Web" are simple ADP portlets. The other portlets are gateways into other ACS modules, and use Tcl procedures to generate their HTML.

Types of Portals

The Portals package provides for the creation of separate types of portals: user portals and group portals.

User Portals

Each user of the site has her own "user" portal. A site wide administrator may specify a default portal, a copy of which is made for each user when she enters her personal portal for the first time. Individual users have the option of reconfiguring their personal portals by adding, removing, and rearranging portlets. The administrator, however, may mark a specific portlet "required", in which case the user may not remove it.

By default, the user portal is located at /portal, although this setting Root URL can easily be changed by a site wide administrator. Although the URL is the same for everyone, the content changes depending on the user who's logged in.

Group Portals

A group portal may look very much like a user portal, the differences being that group portals are group specific and configured by administrators, not by ordinary users. Every member of a group will see the same portal for that group. Only members of a group are allowed to see its portal.

Portal Domains

All portals must belong to a Portal Domain. The Portal Domains type must either by "user" or "group," which is actually what determines whether a portal is a user or group portal. As hinted at above, portal domains are useful for providing defaults for portals, but provide further functionality.

An educational site that wants portals for all of its classes. These classes will have similar needs that can be addressed by portlets defined such as "lectures notes," "assignments," "class info," and "class schedule." So, we create a portal domain, say "edu_class," and define class related portlets for it. Then, we would provide a default configuration for the portal domain. If a class administrator did not like the defaults or thought a portlet was unnecessary, she could adjust the layout for individual class. Keep in mind one portal domain may exist for each group type. Thus, to create a portal domain for classes, a group type, "edu_class" must exist already.

By the default installation, one portal domain named "users" will exist for user portals. A site wide administrator may delete any portal domain.

Working with Portals


Personalizing a User Portal

The user may customize his or her user portal by moving portlets within a page, moving portlets between pages, and adding or deleting portlets.

This screenshot shows the user interface for customizing a portal. You can place any portlet on any page you see fit, by highlighting the portlet name and clicking one of the arrow keys. For instance, to move the "FILE STORAGE" portlet to the "Class Documents" page, you would highlight the "FILE STORAGE" in the "My Files" page and then click on the down arrow, located to the right of "FILE STORAGE" to move it. This action would seemingly result in an empty Page 4. But, don't worry, if you clicked the "FINISHED" button, the previous Page 4 would disappear altogether from your personal portal and page 5 would become the new page 4. If you wanted to add a page instead of delete one, you could simply move a portlet onto Page 6.

As you can see, the user has complete control over the number of pages in his or her portal, the names of each of the pages, and what portlets get displayed. The only restriction may be that some portlets are required, in which case you may not delete it.

Reverting a Portal

Suppose you have customized portlet but then decided you don't like it. Luckily, you are not stuck with your customization as you can revert your portal to the default layout by clicking the default link, as seen at the top left in this screenshot.

The Admin Pages

Most portals administration takes place under /admin/portals/, which you have to be a site wide administrator to access. From this page, you can create a new portal domain, edit a portal domain by clicking on it, or edit control panels. Clicking on a portal domain brings you to the "Manage Portal Domain" page where you can do portal domain specific things like adding, editing and deleting portlets, reverting portals, specifying the default portal configuration, and changing display properties.

There is also a page under /portals/admin/, where users will see all portals that they have administrative rights to, along with links to edit or view those portals. So, group administrators will see group portals for whatever groups they have admin priviledges for, and site wide administrators will see all group portals.

Customizing a Group Portal and Default Portal Configuration

In the "Manage Portal Domain" page, there is a link to specify the default layout of a portal domain. Fortunately, this interface is exactly the same as for personalizing a user portal. When a portal domain has a default portal configuration, this is what a portal within that domain will look like the first time it is visited. For instance, the first time Jane User accesses her user portal, it will be created from the defaults in the "users" portal domain. Another example would be the first time class XYZ is accessed-- it will be created from the defaults in the portal domain that corresponds to the class group type, or "edu_class" in this example.

Just as an individual may customize his or her User Portal, a group administrator may customize a Group Portal. For instance, if Professor Lawrence is an administrator for the group (and class) "Finance 101" and Professor Taylor is an administrator for the group "Data Structures," Professor Lawrence could customize the group portal for "Finance 101" and Professor Taylor could customize the group portal for "Data Structures," just as users personalize their own user portals. Luckily, you don't have to waste your time learning another user interface, since it is the same whether you're customizing a group portal or your personal portal.

The site wide administrator also has the option to revert all portals in a domain. Be careful with this one, though. If Joe User has painstaking customized his user portal to perfection, he may not appreciate you reverting them back to the default portal configuration.

Modifying the "Root URL"

The "Root URL" (also known as the URL root), may be modified for any portal domian. For user portals, this URL root defaults to "portal," which means a logged on user can access his or her portal through "yoursite.com/portal/". If you changed the URL root to "home", the user portal would then be accessible at "yoursite.com/home/".

Group portal URLs are defined a little differently. A group portal URL looks like "yoursite.com/url_root/short_name/". In this URL, the "url_root" comes from whatever the Root URL is specified as in the portal's portal domain. The "short_name" comes from the short name of the group and is not related to the portal domain. For instance, if the group "Finance 101" has the short name "finance101" and the portal domain for "edu_class" has a URL root of "class", the URL to access this group portal would be "yoursite.com/edu_class/finance101".

Be Very Careful when you change a URL root. When you change the URL root for a domain, you are registering a Tcl procedure for that URL root which takes care of displaying a portal. If another procedure has already been registered for that same URL root by someone else, say for another package, bad things may happen. You will be warned if you try to create a URL root with such a conflict, in which case you should decide on a new URL root. One thing you don't have to worry about is your URL root conflicting with a directory under www/, because you won't be allowed to create the URL root and you will get an error message stating why. Okay, you've been warned!

Creating Portlets

From the "Manage Portal Domain" page, you may create portlets. The name you give your portlet will also be the actual portlet title that shows up in the portal.

One decision to make while creating the portlet is whether to generate its HTML using ADP or Tcl. If logic is involved in generating the HTML, the best approach is to add a Tcl procedure in your yourserverdirectory/packages/portals/ directory rather than use ADP due to performance issues with ns_adp_parse. Then, you need to add this Tcl procedure as a predefined data feed into the portal_data_feeds table. When you go to create the portlet, you can just select the predifined data feed you just created. Obviously, you'll want to leave the coding and adding the data feed to a programmer. Alternatively, filling in ADP instead of selecting a "predefined" data feed can be handy when you just want to display some links with no or minimal logic, and you want non-programmers to be able to edit it.

Another decision to make is whether to specify an "Associated URL." If one is specified, an icon will appear at the top right of the portlet that will link to the URL. Traditionally, this has been used as an administrative URL. That is, if the icon appears, you have admin rights associated with that portlet. For instance, the URL for class handouts may point to a page where you can upload new handouts. You may want TAs and professors to see this link but not students. In this case, you can specify a Tcl proc for the Associated URL that will return an empty string for those who don't have admin rights and the URL for those that do. Since the Associated URL should be in ADP, you would specify your Tcl procedure using something like: <%=[maybe_return_url]%>. On the other hand, you may always want to a return a URL. For instance, if you have a "Stock Quotes" portlet, you would probably want all users to be able edit their stock symbols.

You must also specify whether the portlet is "required" or not. A required portlet entails that a portal will not be allowed to have a customization that omits the portlet. These are especially useful for user portals, because there may be some portlets such as "Announcements" that you don't want a novice user accidentally deleting in his or her personalization.

Editing and Deleting Portlets

To edit a portlet, you basically go through the same steps you did to create it.

You may also delete a portlet, which will remove it from the portal domain and any portals it exists in.

Removing a Portal Domain

Removing a portal domain is certainly an extreme action, which is probably why this option is provided under "Extreme Actions" on the "Manage Portal Domain" page. You will be asked once if you are sure you want to remove it. If you answer "OK", it will be removed along with all the portals that belong to the portal domain.

Display Properties

You may control how all the portlets within a portal domain look by clicking "Display Properties" in the "Manage Portal Domain" page. By changing "Table Header Color" and bgcolor in "TD Header HTML" you can change the color of the portlets' bars. Keep in mind that the "Table Header Color" and bgcolor should have the same values for the bars to be a consistent color. You can also control the font color, size and face of the portlets' titles in the font tag of "TD Header HTML". You may further edit display properties by changing some parameters in the parameters file. For further discussion of the paramters file, see the Portals Design Document.

Control Panels

Within a group portal, a "Control Panel" will be displayed as the last page if the user has administrative rights (is a group admin for the group or a site wide admin) and the control panel exists. The purpose of this page is to provide functionality for the administration of the group. For instance, we may want to provide a control panel for classes where a class administrator can add or drop students, TAs, and professors or evaluate students. Control Panels only make sense and are only available in the context of a group portal. That is, a portal domain may have one control panel as long as it is a group portal domain.

You can create, edit and delete control panels under /admin/portals/. Note that unlike portlets, control panels are not portal domain specific, so a control panel may be shared between domains. Note that control panels are really data feeds that have a display type of "admin". You may provide either ADP or Tcl (usually a Tcl procedure name as with portlets) to generate the HTML. You can not edit a control panel's name-- it will always have the name "Control Panel."

Finally, you can select a control panel for a given portal domain under the "Manage Portal Domain" page.

Permissions

Throughout this document, view and administer permissions are discussed by their default behaviour. If you want your permissions to behave differently, you can register you own permission procedures. See the Authorization API in the Portals Design Document for details.


$Id: index.html,v 1.1.1.1 2001/01/24 18:03:36 tarik Exp $
crag@arsdigita.com
ibaker@arsdigita.com