My VT uPortal Quick Start

Virginia Tech is pleased to offer a uPortal 2.4.2 Quick Start with most of our My VT modifications applied. For a preview/summary of our changes, take a look at our online tour.

Documentation is a Work in Progress Please put comments at the end of this document if things are unclear/incomplete/incorrect and I will update the documentation. I'm just trying to get this out the door, so the document will evolve over time.

What's in the Quick Start

We did not apply all of our modifications to uPortal since some were specific to our institution. We tried to include all of the UI modifications and some sample fragments/channels to show you how they can be used. Here's a list:

• My VT look and feel in "khaki" and "grey"
• My VT customization interface which is a simplified Integraded Modes
• Updated Content Subscriber channel
  • Search and browse in one screen
  • Keywords support for channel
  • Word stemming and case-insensitivity for searches (uPortal 2.5 has case-insensitivity)
• Sample CNET News.com channel XML profile
• Sample fragments with example subtabs
• navigate.jsp to allow navigation among tabs/pages
• My VT frame for pulling in external content
• Debugging XML output to logging enabled by default

Getting the Quick Start Running

1. Download uportal-2-4-2-myvt-quick-start.zip
2. Unzip the file
3. Go to the uportal-2-4-2-myvt-quick-start directory
4. At the command line, run: ant hsql &
5. Then run: ant tomcatstart &
6. Access the portal at http://localhost:8080/uPortal/

You can log on as:

• demo/demo - template user
• admin/admin - administrative user with Administration tab (demo of subtabs)
• student/student
• faculty/faculty
• staff/staff

reportal.sh

In the quick start directory there is a shell script named reportal.sh. We used a script similar to this while developing My VT to allow us to quickly reset uPortal to an "out of the box" state. This allowed us to ensure that changes we made to the XSLT, code, and DB worked cleanly.

Sometimes, getting uPortal up and running requires modifying the default database data to get customizations to work. At Virginia Tech, rather than modifying the database data, we modified the data.xml file (which is used to initially populate the database) so that My VT was properly configured right from the start.

• Stop tomcat
• Deploy any code/XSLT changes you've made
• Reset the uPortal database using data.xml
• Publish a sample channel profile provided
• Publish the sample fragments
• Start tomcat

Initial My VT Setup

When you first start the quick start, the portal will not have features such as the shared column or the customizable Home tab. These instructions will walk you through setting up these features on the demo user. The demo user is used for all newly created users in the system.

Shared Column

1. Log on with demo/demo
2. Click the Change Content button
3. Create a new tab
4. Rename the tab to: column::shared-column
5. Click the Finished Changing Content button

Customizable Home Tab

1. Log on with demo/demo
2. Click the Change Content button
3. Create a new tab
4. Rename the tab to: tab::Chicken
5. Click the Add Default Page link
6. Click the Add Main Column link
7. Click the Add Side Column button
8. Rename the tab to: tab::Home
9. Click the Finished Changing Content button

Using Tab/Page/Column

Tab/Page/Column is a custom structure transform for uPortal that allowed us to have multiple levels of tabs using pushed fragments. Check out the sample fragments.xml to see an actual fragment definition XML. Here are the general guidelines for using Tab/Page/Column:

• Tabs are folders with a name: tab::<Tab Name>
• Pages are folders with a name: page::<Page Name>
• Columns are folders with a name: column::<Column Name>
• Channels are regular <channel> elements
• The root layout can contain Tabs and Columns
• Tabs can contain Tabs and Pages
• Pages can contain Pages and Columns
• Columns can contain Channels

<?xml version="1.0" encoding="UTF-8"?>
<layout>
    <folder ID="userLayoutRootNode" type="regular" hidden="false"
        unremovable="true" immutable="false" name="Root folder" priority="0">
        <folder ID="3" type="regular" hidden="false" unremovable="true"
            immutable="true" name="tab::Administration" priority="20003">
            <folder ID="14-2" type="regular" hidden="false"
                unremovable="true" immutable="true"
                name="tab::Channel Manager" priority="2147483646">
                <folder ID="14-3" type="regular" hidden="false"
                    unremovable="true" immutable="true"
                    name="page::default" priority="0">
                    <folder ID="14-4" type="regular" hidden="false"
                        unremovable="true" immutable="true"
                        name="column::main-column" priority="0">
                        <channel .../>
                    </folder>
                </folder>
            </folder>
            <folder ID="14-14" type="regular" hidden="false"
                unremovable="true" immutable="true" name="page::default" priority="2147483643">
                <folder ID="14-15" type="regular" hidden="false"
                    unremovable="true" immutable="true"
                    name="column::main-column" priority="0">
                    <channel .../>
                </folder>
            </folder>
        </folder>
        <folder ID="4" type="regular" hidden="false" unremovable="true"
            immutable="true" name="column::footer" priority="19998">
            <channel .../>
        </folder>
    </folder>
</layout>

<?xml version="1.0" encoding="UTF-8"?>
<layout userName="" newNodeID="6" ID="userLayoutRootNode" mode="edit"
    page="default" tab="5" authenticated="true">
    <tab name="Administration" ID="3" locked="yes" type="system">
        <tab name="Channel Manager" ID="14-2" locked="yes" type="system">
            <page name="default" ID="14-3" locked="yes" type="system">
                <column name="main-column" ID="14-4" locked="yes" type="system">
                    <channel .../>
                </column>
            </page>
        </tab>
        <page name="default" ID="14-14" locked="yes" type="system">
            <column name="main-column" ID="14-15" locked="yes" type="system"/>
        </page>
    </tab>
    <column name="footer" ID="4" locked="yes" type="system">
        <channel .../>
    </column>
</layout>

Navigating Tabs and Pages

Use the navigate.jsp file to create links inside of channels to tabs, pages, and channels. The JSP takes 4 parameters:

• tab - the ID or name of the tab to navigate to. Note: Navigating by name only works for tabs defined via tab::Name.
• page - the name of the page to navigate to. Note: You must specify a tab as well.
• channel - the fname of the channel to load full screen
• root=root - Returns to the "normal" view of the portal from a full screen channel

To go to the default page of the Home tab:
/uPortal/navigate.jsp?tab=Home&page=default

To show the CNET News.com channel in full screen:
/uPortal/navigate.jsp?channel=cnet-news-com

To return to normal view from full screen channel view:
/uPortal/navigate.jsp?root=root

Additional Colors

Someone noticed that the My VT quick start came packaged with only grey and khaki colors yet it referenced many others in the CSS file. The attached additional colors zip file provides the other colors used by My VT at Virginia Tech.  Just unpack the files to the same location of your grey and khaki folders (typically <myvt-quick-start_dist>/uPortal_rel-2-4-2/webpages/media/edu/vt/portal/layout/TabPageColumn/InlineCustomization/images/).  Please note that this zip archive also contains the original grey and khaki files so it will probably try to overwrite.

Using the Frame

The frame.jsp loads external content in an iframe that looks similar to the full screen channel mode. Used parameters are:

• myvt-title - title to display
• myvt-color - color of bar (supports grey and khaki themes)
• myvt-icon - the URL to the icon to display
• myvt-back-name - Name of the page to go back to
• myvt-back-url - URL of the page to go back to
• myvt-help - URL for the help link
• myvt-frame - URL for the contents of the frame
• myvt-logoff - URL for the log off link

Common Tasks

Publishing a Channel
At the command line, run: ant pubchan -Dchannel=<Channel Filename>

Publishing Fragments
At the command line, run: ant pubfragments -DfragmentFile=<Path to Fragments File from uPortal root>

Adding a User
At the command line, run: ant md5passwd -Dusername=<Username>

Known Bugs

• Images for folders and channels in the Content Subscriber channel do not work. The image files are licensed by VT and cannot be distributed, I have not yet updated the XSLT to point to generic versions.
• The uPortal 2.4.2 XHTML output sometimes puts a random > into the output. This is not a problem with the My VT mods, but a problem with out of the box uPortal.