Author: taylor
Date: Fri May 4 19:49:51 2007
New Revision: 535440
URL: http://svn.apache.org/viewvc?view=rev&rev=535440
Log:
subsite documentation
checkpoint, still have a few sections to complete
Added:
portals/jetspeed-2/trunk/xdocs/guides/guide-subsites.xml
portals/jetspeed-2/trunk/xdocs/guides/images/localhost-site.jpg (with
props)
portals/jetspeed-2/trunk/xdocs/guides/images/subsites.jpg (with props)
portals/jetspeed-2/trunk/xdocs/guides/images/subsites2.jpg (with props)
Modified:
portals/jetspeed-2/trunk/xdocs/guides/index.xml
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-subsites.xml
URL:
http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/guide-subsites.xml?view=auto&rev=535440
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-subsites.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-subsites.xml Fri May 4
19:49:51 2007
@@ -0,0 +1,258 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Jetspeed Subsites</title>
+ <subtitle>Guide to Jetspeed Subsites</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="[EMAIL PROTECTED]" />
+ </authors>
+ </properties>
+ <body>
+ <section name="What are Subsites?">
+ <p>
+ 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,
+ </p>
+ </section>
+ <section name='A Subsite Scenario: Subsite By Hostname'>
+ <p>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 <b>hostname</b> portion of the URL.
+ Use case scenario we are going to look at are:</p>
+ <ul>
+ <li>A virtual hosting scenario where you are hosting different
sites.</li>
+ <li>A single organization with two or more sites, which may also
some content in common amongst those subsites.</li>
+ </ul>
+ <subsection name='Virtual Hosting'>
+ <p>In our Virtual Hosting example, we are hosting three different
portal subsites:</p>
+ <img src='images/subsites2.jpg' border="0"/>
+ <p>Here we have three subsites (four including localhost) defined for
three different companies:
+ </p>
+ <ul>
+ <li>www.company-1.com - the subsite for "Company 1"</li>
+ <li>www.company-2.com - the subsite for "Company 2"</li>
+ <li>www.company-3.com - the subsite for "Company 3"</li>
+ </ul>
+ </subsection>
+ <subsection name='Single Organization'>
+ <p>In our Single Organization example, we are hosting three different
portal subsites within the organization:</p>
+ <img src='images/subsites.jpg' border="0"/>
+ <p>Here we have three subsites (four including localhost) defined for
three different companies:
+ </p>
+ <ul>
+ <li>employees.my-company.com - subsite for employees</li>
+ <li>partners.my-company.com - subsite for partners</li>
+ <li>www.my-company.com - subsite for the public</li>
+ </ul>
+ </subsection>
+ <subsection name='Site Manager'>
+ <p>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 <a href='guide-psml.html'>Database Page
Manager</a> for details on storing subsites in the database.
+ </p>
+ <p>
+ 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:
+ </p>
+ <ul>
+ <li><b>__subsite_root</b> - this is a reserved directory, containing
all subsite control roots</li>
+ <li><b>_hostname</b> - this is a <i>control</i> directory (prefixed
with underscore) containing all hostname-based subsites</li>
+ </ul>
+ <p>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</p>
+ </subsection>
+ <subsection name='/etc/hosts'>
+ <p>Note that the localhost site is there only for developers. Even
developers can simulate a virtual hosting environment
+ by editing their <b>/etc/hosts</b> file on their local machines (on
Windows under <b>\windows\system32\drivers\etc\hosts</b>)
+ and making fake entries such as:
+ </p>
+<source>
+<![CDATA[
+ 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
+]]>
+</source>
+ </subsection>
+ </section>
+ <section name="XML Seed Configuration">
+ <p>
+ 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:</p>
+ <ul>
+ <li>Profiling Rules</li>
+ <li>Users</li>
+ </ul>
+ <subsection name='Profiling Rules'>
+
+<source test="">
+ <![CDATA[
+<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">
+ <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>
+]]>
+</source>
+<p>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 <i>navigation</i> are used to navigate down the portal
site tree.
+The <i>fallBackOrder</i> tag should normally just be listed sequential. You
can almost always get by with a <i>fallBackType</i> of 2.
+All of the available criterion <i>types</i> are documented in the online <a
href='guide-profiler.html'>Profiler Guide</a>.
+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.
+</p>
+<table>
+<tr><th>Name</th><th>Type</th><th>Value</th><th>Description</th></tr>
+<tr><td>navigation</td><td>navigation</td><td>subsite-root</td><td>Navigates
to the physical /__subsite-root directory.</td></tr>
+<tr><td>hostname</td><td>hostname</td><td>(provided at
runtime)</td><td>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.</td></tr>
+<tr><td>user</td><td>user</td><td>(provided at runtime)</td><td>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.</td></tr>
+<tr><td>navigation-2</td><td>navigation</td><td>subsite-root</td><td>When a
page is not found under the user directory, we start over and navigate back to
the subsite root.</td></tr>
+<tr><td>hostname</td><td>hostname</td><td>(provided at runtime)</td><td>Then
again navigate to the _hostname directory</td></tr>
+<tr><td>role</td><td>role</td><td>(provided at runtime)</td><td>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.</td></tr>
+<tr><td>path</td><td>path</td><td>home</td><td>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.</td></tr>
+</table>
+<p>
+The screenshot below shows the directory tree for a <i>localhost</i> subsite.
+</p>
+<img src='images/localhost-site.jpg'/>
+<p>
+Notice the _user and _role directories. These are control directories based on
the runtime parameters <i>user</i> and <i>role</i>.
+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:
+<table>
+<tr><td>Username</td><td>dean</td></tr>
+<tr><td>Roles</td><td>role1, role2, role3</td></tr>
+<tr><td>Hostname</td><td>localhost</td></tr>
+</table>
+</p>
+<p>
+<b>http://localhost:8080/jetspeed/portal/calendar.psml</b>
+<table>
+<tr><th>URL</th><th>Site Physical Location</th></tr>
+<tr><td>http://localhost:8080/jetspeed/portal/calendar.psml</td><td>/__subsite_root/_hostname/localhost/_user/dean/calendar.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role1/calendar.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role2/calendar.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role3/calendar.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/calendar.psml</td></tr>
+<tr><td></td><td>/__subsite_root/calendar.psml</td></tr>
+</table>
+</p>
+
+<p>
+<b>http://localhost:8080/jetspeed/portal/accounting/worksheet.psml</b>
+<table>
+<tr><th>URL</th><th>Site Physical Location</th></tr>
+<tr><td>http://localhost:8080/jetspeed/portal/accounting/worksheets.psml</td><td>/__subsite_root/_hostname/localhost/_user/dean/accounting/worksheet.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role1/accounting/worksheet.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role2/accounting/worksheet.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role3/accounting/worksheet.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/accounting/worksheet.psml</td></tr>
+<tr><td></td><td>/__subsite_root/accounting/worksheet.psml</td></tr>
+</table>
+</p>
+
+<p>
+<b>http://localhost:8080/jetspeed/portal/</b>
+<table>
+<tr><th>URL</th><th>Site Physical Location</th></tr>
+<tr><td>http://localhost:8080/jetspeed/portal/</td><td>/__subsite_root/_hostname/localhost/_user/dean/home.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role1/home.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role2/home.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/_role/role3/home.psml</td></tr>
+<tr><td></td><td>/__subsite_root/_hostname/localhost/home.psml</td></tr>
+<tr><td></td><td>/__subsite_root/home.psml</td></tr>
+</table>
+</p>
+ </subsection>
+ <subsection name='Associated Rules with Users'>
+<p>
+All users are either explicity or implicity associated with a profiling rule.
+</p>
+ </subsection>
+ </section>
+ <section name="Hostname Profiling Rule Configuration">
+ <p>
+ There is an option for hostnames to use the entire hostname or a
prefix.
+ </p>
+ <source test="">
+ <![CDATA[
+]]>
+ </source>
+ <p>
+ </p>
+
+ </section>
+
+ </body>
+</document>
Added: portals/jetspeed-2/trunk/xdocs/guides/images/localhost-site.jpg
URL:
http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/localhost-site.jpg?view=auto&rev=535440
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/localhost-site.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: portals/jetspeed-2/trunk/xdocs/guides/images/subsites.jpg
URL:
http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/subsites.jpg?view=auto&rev=535440
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/subsites.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: portals/jetspeed-2/trunk/xdocs/guides/images/subsites2.jpg
URL:
http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/subsites2.jpg?view=auto&rev=535440
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/subsites2.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: portals/jetspeed-2/trunk/xdocs/guides/index.xml
URL:
http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/index.xml?view=diff&rev=535440&r1=535439&r2=535440
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/index.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/index.xml Fri May 4 19:49:51 2007
@@ -50,6 +50,7 @@
<li><a href="guide-user-attributes.html">Guide to
defining user attributes (PLT.17 user information configuration)</a></li>
<li><a href="guide-profiler.html">Guide to using
profilers</a></li>
<li><a href="guide-aggregation.html">Guide to
Aggregation</a></li>
+ <li><a href="guide-subsites.html">Guide to
Subsites</a></li>
<li><a href="guide-migration.html">Guide to Migration
from 2.0 to 2.1</a></li>
</ul>
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
