by Crag Wolfe and Ian Baker
ACS Documentation : Portals Documentation : Portals Administration
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.
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.
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.
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.
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.
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.
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.
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!
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.
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.
Working with Portals
Personalizing a User Portal
The Admin Pages
Customizing a Group Portal and Default Portal Configuration
Modifying the "Root URL"
Creating Portlets
Editing and Deleting Portlets
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.
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.