<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="subsites-requirements" xreflabel="OpenACS 4 Subsites Requirements">
<title>Subsites Requirements</title>

<authorblurb>
<para>By <ulink url="http://planitia.org">Rafael H. Schloming</ulink> and Dennis Gregorovic</para>
</authorblurb>


<sect2 id="subsites-requirements-intro">
<title>Introduction</title>



<para>The following is a requirements document for OpenACS 4 Subsites, part of the
OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve
multiple user communities, by enabling the suite of available OpenACS
applications to be customized for defined user communities.</para>


</sect2>

<sect2 id="subsites-requirements-vision">
<title>Vision Statement</title>



<para>Many online communities are also collections of discrete subcommunities,
reflecting real-world relationships. For example, a corporate
intranet/extranet website serves both units within the company (e.g.,
offices, departments, teams, projects) and external parties (e.g., customers,
partners, vendors). Subsites enable a single OpenACS instance to provide each
subcommunity with its own &quot;virtual website,&quot; by assembling OpenACS
packages that together deliver a feature set tailored to the needs of the
subcommunity.</para>


</sect2>

<sect2 id="subsites-requirements-system-overview">
<title>System Overview</title>



<para>The OpenACS subsite system allows a single OpenACS installation to serve multiple
communities. At an implementation level this is primarily accomplished by
having an application &quot;scope&quot; its content to a particular package
instance. The <link linkend="rp-design">request
processor</link> then figures out which package_id a particular URL references
and then provides this information through the <computeroutput>ad_conn</computeroutput> api (<computeroutput>[ad_conn
package_id]</computeroutput>, <computeroutput>[ad_conn package_url]</computeroutput>).</para>



<para>The other piece of the subsite system is a subsite package that provides
subsite admins a &quot;control panel&quot; for administering their subsite.
This is the same package used to provide all the community core functionality
available at the &quot;main&quot; site which is in fact simply another
subsite.</para>


</sect2>

<sect2 id="subsites-requirements-use-cases">
<title>Use-cases and User-scenarios</title>



<para>The Subsites functionality is intended for use by two different classes of
users:</para>

<orderedlist>
<listitem><para>Package programmers (referred to as &#39;the programmer&#39;) must
develop subcommunity-aware applications.</para></listitem>

<listitem><para>Site administrators (referred to as &#39;the administrator&#39;) use
subsites to provide tailored &quot;virtual websites&quot; to different
subcommunities.</para></listitem>
</orderedlist>

<para>Joe Programmer is working on the forum package and wants to make it
subsite-aware. Using [ad_conn package_id], Joe adds code that only displays
forum messages associated with the current package instance. Joe is happy to
realize that parameter::get is already smart enough to return configuration
parameters for the current package instance, and so he has to do no extra
work to tailor configuration parameters to the current subsite.</para>

<para>Jane Admin maintains www.company.com. She learns of Joe&#39;s work and
would like to set up individual forums for the Boston and Austin offices of
her company. The first thing she does is use the APM to install the new
forum package.</para>

<para>Next, Jane uses the Subsite UI to create subsites for the Boston and
Austin offices. Then Jane uses the Subsite UI to create forums for each
office.</para>

<para>Now, the Boston office employees have their own forum at
http://www.company.com/offices/boston/forum, and similarly for the Austin
office. At this point, the Boston and Austin office admins can customize the
configurations for each of their forums, or they can just use the
defaults.</para>


</sect2>

<sect2 id="subsites-requirements-links">
<title>Related Links</title>


<itemizedlist>
<listitem><para><xref linkend="subsites-design"/></para></listitem>

<listitem><para>Test plan (Not available yet)</para></listitem>
</itemizedlist>

</sect2>

<sect2 id="subsites-requirements-api">
<title>Requirements: Programmer&#39;s API</title>



<para>A subsite API is required for programmers to ensure their packages are
subsite-aware. The following functions should be sufficient for this:</para>

<para><emphasis role="strong">10.10.0 Package creation</emphasis></para>

<para>The system must provide an API call to create a package, and it must be
possible for the context (to which the package belongs) to be specified.</para>

<para><emphasis role="strong">10.20.0 Package deletion</emphasis></para>

<para>The system must provide an API call to delete a package and all related
objects in the subsite&#39;s context.</para>

<para><emphasis role="strong">10.30.0 Object&#39;s package information</emphasis></para>

<para>Given an object ID, the system must provide an API call to determine the
package (ID) to which the object belongs.</para>

<para><emphasis role="strong">10.40.0 URL from package</emphasis></para>

<para>Given a package (ID), the system must provide an API call to return the
canonical URL for that package.</para>

<para><emphasis role="strong">10.50.0 Main subsite&#39;s package_id</emphasis></para>

<para>The system must provide an API call to return a package ID corresponding
to the main subsite&#39;s package ID (the degenerate subsite).</para>


</sect2>

<sect2 id="subsites-requirements-ui">
<title>Requirements: The User Interface</title>



<para><emphasis role="strong">The Programmer&#39;s User Interface</emphasis></para>

<para>There is no programmer&#39;s UI, other than the API described above.</para>

<para><emphasis role="strong">The Administrator&#39;s User Interface</emphasis></para>

<para>The UI for administrators is a set of HTML pages that are used to drive
the underlying API for package instance management (i.e. adding, removing, or
altering packages). It is restricted to administrators of the current subsite
such that administrators can only manage their own subsites. Of course,
Site-Wide Administrators can manage all subsites.</para>

<itemizedlist>
<listitem>
<para><emphasis role="strong">20.10.0 Package creation</emphasis></para>

<para><emphasis role="strong">20.10.1</emphasis> The administrator should be able to create a
package and make it available at a URL underneath the subsite.</para>
</listitem>

<listitem>
<para><emphasis role="strong">20.20.0 Package deactivation</emphasis></para>

<para><emphasis role="strong">20.20.1</emphasis> The administrator should be able to deactivate
any package, causing it to be inaccessible to users.</para>

<para><emphasis role="strong">20.20.5</emphasis> Deactivating a package makes the package no
longer accessible, but it does not remove data created within the context of
that package.</para>
</listitem>
</itemizedlist>


</sect2>

<sect2 id="subsites-requirements-rev-history">
<title>Revision History</title>



 
<informaltable>
<tgroup cols="4">
<tbody>
<row>
<entry><emphasis role="strong">Document Revision #</emphasis></entry>
<entry><emphasis role="strong">Action Taken, Notes</emphasis></entry>
<entry><emphasis role="strong">When?</emphasis></entry>
<entry><emphasis role="strong">By Whom?</emphasis></entry>
</row>

<row>
<entry>0.1</entry>
<entry>Creation</entry>
<entry>08/18/2000</entry>
<entry>Dennis Gregorovic</entry>
</row>

<row>
<entry>0.2</entry>
<entry>Edited, reviewed</entry>
<entry>08/29/2000</entry>
<entry>Kai Wu</entry>
</row>
</tbody></tgroup></informaltable>


</sect2>

</sect1>
