portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tay...@apache.org
Subject svn commit: r535440 - in /portals/jetspeed-2/trunk/xdocs/guides: guide-subsites.xml images/localhost-site.jpg images/subsites.jpg images/subsites2.jpg index.xml
Date Sat, 05 May 2007 02:49:52 GMT
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="taylor@apache.org" />
+        </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: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message