What are Subsites?

Subsites are a feature for sub-dividing your portal site map into independent "portal site" trees. This enables use-case scenarios such as hosting two or more Jetspeed portals on the same portal instance (application server). With subsites, subsets of users can be configured to only view a sub-tree, or subsite, of the overall portal site. These users will never see content outside of their subsite. The creation of subsites is based upon profiling rules. You apply profiling rules to navigate users to their subsite root. In this example,

A Subsite Scenario: Subsite By Hostname

In order to direct users to different subsites, you will need to define a set of rules, known as profiling rules. These rules determine which subsite users and guests will visit. Rules are based on runtime parameters, such as username, roles of the current user, request parameters, session state, or more. In this example we will look at directing users to subsites based on the hostname portion of the URL. Use case scenario we are going to look at are:

  • A virtual hosting scenario where you are hosting different sites.
  • A single organization with two or more sites, which may also some content in common amongst those subsites.

Virtual Hosting

In our Virtual Hosting example, we are hosting three different portal subsites:

Here we have three subsites (four including localhost) defined for three different companies:

  • www.company-1.com - the subsite for "Company 1"
  • www.company-2.com - the subsite for "Company 2"
  • www.company-3.com - the subsite for "Company 3"

Single Organization

In our Single Organization example, we are hosting three different portal subsites within the organization:

Here we have three subsites (four including localhost) defined for three different companies:

  • employees.my-company.com - subsite for employees
  • partners.my-company.com - subsite for partners
  • www.my-company.com - subsite for the public

Site Manager

The screenshots above show using the Site Manager to configure your subsites. The Site Manager is useful for configuring a live site. When you configure a site initially, subsites are configured on the file system as folders, subfolders and pages. Optionally, these folders can be imported in the database. See the Database Page Manager for details on storing subsites in the database.

The Site Manager mirrors your file system (or database structure) in a tree view. Looking at the Site View screenshots above, there are several directories we need to take note of:

  • __subsite-root - this is a reserved directory, containing all subsite control roots
  • _hostname - this is a control directory (prefixed with underscore) containing all hostname-based subsites

Control directories must always begin with an underscore. Profiling rules navigate through control directories based on runtime parameters. In this example, we are creating subsites based on the hostname runtime parameter

/etc/hosts

Note that the localhost site is there only for developers. Even developers can simulate a virtual hosting environment by editing their /etc/hosts file on their local machines (on Windows under \windows\system32\drivers\etc\hosts) and making fake entries such as:

       
        127.0.0.1 www.company-1.com
        127.0.0.1 www.company-2.com
        127.0.0.1 www.company-3.com

        127.0.0.1 employees.my-company.com
        127.0.0.1 partners.my-company.com
        127.0.0.1 www.my-company.com

XML Seed Configuration

When initially setting up your Jetspeed portal, you will need to provide initial seed data for your portal. Here we demonstrate how to configure your XML seed data for a subsite. We will be initializing:

  • Profiling Rules
  • Users

Profiling Rules

                
<ProfilingRule id="subsite-by-hostname" standardRule="false">
	<description value="A rule based on role fallback algorithm with specified subsite and home page"/>
	<Criteria>
		<Criterion name="navigation">
			<type value="navigation"/>
			<value value="subsite-root"/>
			<fallBackOrder value="0"/>
			<fallBackType value="2"/>
		</Criterion>
		<Criterion name="hostname">
			<type value="hostname"/>
			<fallBackOrder value="1"/>
			<fallBackType value="2"/>
		</Criterion>
		<Criterion name="user">
			<type value="user"/>
			<fallBackOrder value="2"/>
			<fallBackType value="2"/>
		</Criterion>
		<Criterion name="navigation-2">
			<type value="navigation"/>
			<value value="subsite-root"/>
			<fallBackOrder value="3"/>
			<fallBackType value="2"/>
		</Criterion>
		<Criterion name="hostname-2">
			<type value="hostname"/>
			<fallBackOrder value="4"/>
			<fallBackType value="2"/>
		</Criterion>
		<Criterion name="role">
			<type value="role"/>
			<fallBackOrder value="5"/>
			<fallBackType value="2"/>
		</Criterion>				
		<Criterion name="path">
			<type value="path"/>
			<value value="home"/>
			<fallBackOrder value="6"/>
			<fallBackType value="2"/>
		</Criterion>
	</Criteria>
</ProfilingRule>                               

A profiling rule contains one or more criterion. Each criterion defines an instruction on how to locate a page in the physical portal site map. Criterion of the type navigation are used to navigate down the portal site tree. The fallBackOrder tag should normally just be listed sequential. You can almost always get by with a fallBackType of 2. All of the available criterion types are documented in the online Profiler Guide. The table below describes each criterion in our subsite rule and how it is used in a subsite location algorithm. This rule is a subsite location rule that uses a user-role-fallback algorithm. User-role-fallback algorithms first look for a page in the users home directory. If not found there, they then look for a page in each of the users corresponding role directories. There are other algorithms provided by out of the box such as role-fallback, group-fallback, mediatype/language fallback. Or you can create your own algorithms by creating new profiling rules in the XML seed data or with the Profiler Admininistrative portlet.

Name Type Value Description
navigation navigation subsite-root Navigates to the physical /__subsite-root directory.
hostname hostname (provided at runtime) Navigates to the control directory /__subsite-root/_hostname, and then to the subdirectory matching the runtime _hostname parameter. If the runtime _hostname parameter equals "localhost", then the physical location is /__subsite-root/_hostname/localhost.
user user (provided at runtime) Navigates to the control directory /__subsite-root/_hostname/user, and then to the subdirectory matching the runtime _user parameter. If the runtime _user parameter equals "dean", then the physical location is /__subsite-root/_hostname/localhost/_user/dean.
navigation-2 navigation subsite-root When a page is not found under the user directory, we start over and navigate back to the subsite root.
hostname hostname (provided at runtime) Then again navigate to the _hostname directory
role role (provided at runtime) Navigate to each role directory of the given user until we find the page. For example, for a role named "role1", navigate to the control directory /__subsite-root/_hostname/role, and then to the subdirectory matching each runtime _role parameters. If the runtime _role parameter is only "role1", then the physical location is /__subsite-root/_hostname/localhost/_role/role1.
path path home This is a constant used in all calculations, the path portion of the URL, such as home.psml, or /accounting/worksheet.psml. It is always appended to the calculated path to give the complete physical address of the page. In the case where there is no page specified, the default value provided in the rule "home" is used, and that actually maps to "home.psml" as the default page extensions.

The screenshot below shows the directory tree for a localhost subsite.

Notice the _user and _role directories. These are control directories based on the runtime parameters user and role. The user parameter represents the username of the currently logged on user. The role parameter can represent one or more roles of the current user. The subsite algorithm will navigate down to a user directory first, and look in the directory for the current user by name. It will look there for name of the current page requested on the URL. Given the following example runtime parameters, the tables below demonstrates the fallback search path algorthm used by the profiler in locating a page given our subsite profiling rule. Once it finds the page, the page is immediately returned and the algorithm is terminated. For each of the examples below, consider the following runtime parameters:

Username dean
Roles role1, role2, role3
Hostname localhost

http://localhost:8080/jetspeed/portal/calendar.psml

URL Site Physical Location
http://localhost:8080/jetspeed/portal/calendar.psml /__subsite-root/_hostname/localhost/_user/dean/calendar.psml
/__subsite-root/_hostname/localhost/_role/role1/calendar.psml
/__subsite-root/_hostname/localhost/_role/role2/calendar.psml
/__subsite-root/_hostname/localhost/_role/role3/calendar.psml
/__subsite-root/_hostname/localhost/calendar.psml
/__subsite-root/calendar.psml

http://localhost:8080/jetspeed/portal/accounting/worksheet.psml

URL Site Physical Location
http://localhost:8080/jetspeed/portal/accounting/worksheets.psml /__subsite-root/_hostname/localhost/_user/dean/accounting/worksheet.psml
/__subsite-root/_hostname/localhost/_role/role1/accounting/worksheet.psml
/__subsite-root/_hostname/localhost/_role/role2/accounting/worksheet.psml
/__subsite-root/_hostname/localhost/_role/role3/accounting/worksheet.psml
/__subsite-root/_hostname/localhost/accounting/worksheet.psml
/__subsite-root/accounting/worksheet.psml

http://localhost:8080/jetspeed/portal/

URL Site Physical Location
http://localhost:8080/jetspeed/portal/ /__subsite-root/_hostname/localhost/_user/dean/home.psml
/__subsite-root/_hostname/localhost/_role/role1/home.psml
/__subsite-root/_hostname/localhost/_role/role2/home.psml
/__subsite-root/_hostname/localhost/_role/role3/home.psml
/__subsite-root/_hostname/localhost/home.psml
/__subsite-root/home.psml

Associated Rules with Users

All users are either explicity or implicity associated with a profiling rule. The User Administration utility has a tab to setup the profiling rule associated with a user:

Additionally, you can associate users with profiling rules in the XML seed data configuration:

                
<Users>
...                
<User name="jetspeed">
	<credentials password="jetspeed" enabled="TRUE" requiresUpdate="FALSE"/>
	<roles>manager</roles>
	<groups>engineering</groups>
	<preferences/>
	<userinfo/>
	<Rules>
		<Rule locator="menu" rule="role-group"/>
		<Rule locator="page" rule="role-fallback"/>
	</Rules>
</User>
</Users>                

Looking at the Rule element of a User, the locator can be either:

  • page - use associated profiling rule to locate pages
  • menu - use the associated profiling rule to locate menus (if not specified, use the page locator)

The rule attribute on the Rule element of a User defines which profiling rule is associated to either a page or menu locator. If a user is not associated with a locator, then there is a system wide locator configured in the Spring configuration file profiler.xml. See the contructor-arg of index = 1. This locator is the default locator, system-wide, for when there is no-associated profiling rule. Normally, profiling rules are associated with user during activities such as the creation of new users with the User Administration portlet, or during new user registration.


<beans>
    <!-- Profiler -->
    <bean id="profilerImpl" class="org.apache.jetspeed.profiler.impl.JetspeedProfilerImpl" init-method="init">
        <constructor-arg index="0">
            <value>JETSPEED-INF/ojb/profiler_repository.xml</value>
        </constructor-arg>
        <constructor-arg index="1">
            <value>j2</value>
        </constructor-arg>                
        ....

Hostname Profiling Rule Configuration

There is an option for hostnames to use the entire hostname or a prefix. This is configured in the Spring configuration file profiler.xml.

                                
    <bean id='HostnameCriterionResolver' class='org.apache.jetspeed.profiler.rules.impl.HostnameCriterionResolver'>
      <!--  use the dot prefix, for ex: "accounting.xyz.com" returns "accounting" -->
      <constructor-arg type="boolean" index="0">
            <value>false</value> 
        </constructor-arg>    	
    </bean>                    

            

By settting the prefix boolean argument to true, the hostname resolve will only look at the prefix of the hostname. For example, with the dot prefix flag set to true, a hostname of "accounting.xyz.com" returns "accounting".

Administering Subsites with the User Manager

When creating a new user from User Manager Administration, you can specify two fields to enable and configure subsite behavior for that new user:

  • Profiling Rule: choose a profiling rule to assign to the new user that has built in subsite support such as the example used in this document: subsite-by-hostname.
  • Subsites: from the dropdown select the subsite to assign as the home subsite to the new user, or leave blank to use default /_user home.

When using the subsite-by-hostname profiling rule, make sure to select a subsite from the subsites drop-down, as these two attributes work together. The rule is the instructions on where to look for home pages, and the subsite selection tells the profiling rule which subsite will hold this user directory

Subsite management can also be delegated to managers of particular subsites. For example, you may want to setup User Manager Administration pages for each subsite. By modifying the deployment descriptor for the j2-admin application, each User Manager details portlet can be configured with a different default subsite:

Administering Subsites with User Registration

When creating a new user from the User Registration portlet, you can specify two fields to enable and configure subsite behavior for that new user:

  • rulesValues: choose a profiling rule to assign to the new user that has built in subsite support such as the example used in this document: subsite-by-hostname.
  • subsiteRootFolder: the full path to one unique subsite root folder.

NOTE: the User Registration portlet will store these preference values on a per user basis. Usually this means the preferences are stored for the administrative user only. If you will have administrators registering users, then this approach works fine. However, with self-registration portal, you will need to set these values in the defaults for the portlet. The defaults are usually set in the portlet.xml, for example:

                
...
        <preference>
     		<name>subsiteRootFolder</name>
            <value>/__subsite-root/_hostname/localhost</value>   
        </preference>        
        <preference>
     		<name>rulesNames</name>
            <value>page</value>   
        </preference>        
        <preference>
     		<name>rulesValues</name>
            <value>subsite-by-hostname</value>   
        </preference>        
...

You can also set defaults on a per page (PSML) intermediate level:

                
    <fragment id="example-subsite-1" type="portlet" name="j2-admin::UserRegistrationPortlet">
      <preference name="subsiteRootFolder">
        <value>/__subsite-root/_hostname/localhost</value>
      </preference>
      <preference name="rulesNames">
        <value>page</value>
      </preference>
      <preference name="rulesValues">
        <value>subsite-by-hostname</value>
      </preference>      
    </fragment>