configuring.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE chapter 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;
]>
<chapter id="configuring-new-site">
<title>Configuring a new OpenACS Site</title>
<authorblurb>
<para>by <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink></para>
</authorblurb>
<para>In this chapter, <emphasis role="strong">Configuring</emphasis> refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. <emphasis role="strong">Customizing</emphasis> refers to changes that touch the filesystem, and require some planning if easy upgradability is to be maintained.</para>
<sect1 id="configuring-install-packages">
<title>Installing OpenACS packages</title>
<authorblurb>
<para>by <ulink url="mailto:jade@rubick.com">Jade Rubick</ulink></para>
</authorblurb>
<sect2>
<title>Installing OpenACS packages</title>
<para>An OpenACS package extends your website and lets it do
things it was not able to do before. You can have a weblog, a
forums, a calendar, or even do sophisticated project-management
via your website.</para>
<para>After you've installed OpenACS, you can congratulate
yourself for a job well done. Then, you'll probably want to
install a couple of packages.</para>
<para>To install packages, you have to be an administrator on
the OpenACS webserver. Log in, and you'll see a link to Admin or
the Control Panel. Click on that, then click on 'Install
software'. Packages are sometimes also referred to as
applications or software.</para>
<para>At this point, you'll need to determine whether or not
you're able to install from the repository, or whether you
should install from local files.</para>
<para>Basically, if you have a local CVS repository, or have
custom code, you need to install from 'Local Files'. Otherwise,
you can install from the OpenACS repository</para>
<para>If you want to install new packages, click on 'Install
from Repository' or 'Install from Local'. Select the package,
and click 'Install selected applications'. The system will check
to make sure you have all necessary packages that the package
you want depends on. If you're installing from Local Files, and
you are missing any packages, you may have to add the packages
your desired package depends on:
<xref linkend="upgrade-openacs-files"></xref>
</para>
<para>If you run into any errors at all, check your
/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log file, and
post your error on the OpenACS forums</para>
<para>Once the package has been installed, then you will need to
'mount' the package. The next section handles that.</para>
</sect2>
</sect1>
<sect1 id="configuring-mounting-packages">
<title>Mounting OpenACS packages</title>
<authorblurb>
<para>by <ulink url="mailto:jade@rubick.com">Jade Rubick</ulink></para>
</authorblurb>
<sect2>
<title>Mounting OpenACS packages</title>
<para>After you've installed your packages, you have to 'mount'
them in order to make them appear on your website.</para>
<para>Make sure you are logged in, and then click on the
'Admin' or 'Control Panel' link to get to the Site-Wide
Administration page (at /acs-admin). Click on the subsite you'd
like the application to be available at.</para>
<para>Subsites are a way of dividing your website into logical
chunks. Often they represent different groups of users, or parts
of an organization. </para>
<para>Now click on 'Applications' (applications are the same
thing as packages). You'll see a list of Applications and the
URLs that each is located at. To mount a new application, you
click on 'Add application', enter the Application, title
(application name), and URL (URL folder name), and you're
done.</para>
<para>Test it out now. The URL is based on a combination of the
subsite URL and the application URL. So if you installed a
package in the Main Subsite at the URL calendar, it will be
available at http://www.yoursite.com/calendar. If you installed
it at a subsite that has a URL intranet, then it would be
located at http://www.yoursite.com/intranet/calendar.</para>
</sect2>
</sect1>
<sect1 id="configuring-configuring-packages">
<title>Configuring an OpenACS package</title>
<authorblurb>
<para>by <ulink url="mailto:jade@rubick.com">Jade Rubick</ulink></para>
</authorblurb>
<sect2>
<title>Configuring an OpenACS package</title>
<para>After you've installed and mounted your package, you can
configure each instance to act as you would like. </para>
<para>This is done from the Applications page. Log in, go to the
Admin or Control Panel, click on the subsite the application is
in, and click on Applications. If you click on the 'Parameters'
link, you will see a list of parameters that you can change for
this application.</para>
</sect2>
</sect1>
<sect1 id="configuring-configuring-permissions">
<title>Setting Permissions on an OpenACS package</title>
<authorblurb>
<para>by <ulink url="mailto:jade@rubick.com">Jade Rubick</ulink></para>
</authorblurb>
<sect2>
<title>Setting Permission on an OpenACS package</title>
<para>After you've installed and mounted your package, you can
configure each instance to act as you would like. </para>
<para>This is done from the Applications page. Log in, go to the
Admin or Control Panel, click on the subsite the application is
in, and click on Applications. If you click on the 'Permissions'
link, you will see and be able to set the permissions for that
application. </para>
<para>Each application may have different behavior for what Read
Create Write and Admin permissions mean, but generally the
permissions are straightforward. If you find the behavior is not
what you expect after setting permissions, you can post a bug in
the OpenACS bugtracker.</para>
<para>'The Public' refers to users to the website who are not
logged in. 'Registered Users' are people who have registered for
the site. </para>
</sect2>
</sect1>
<sect1 id="how-do-I">
<title>How Do I?</title>
<sect2>
<title>How do I edit the front page of a new site through a web interface?</title>
<para>The easiest way is to install the Edit-This-Page package.</para>
<orderedlist>
<listitem>
<para>Log in to the web site as an administrator.</para>
</listitem>
<listitem>
<para>Click on Admin > Install Software > Install from OpenACS Repository / Install new application</para>
</listitem>
<listitem>
<para>Choose Edit This Page and install</para>
</listitem>
<listitem>
<para>Follow the instructions within <ulink url="/doc/edit-this-page/install">Edit This Page</ulink> (the link will only work after Edit This Page is installed).</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>How do I let anybody who registers post to a weblog?</title>
<para>Go to <computeroutput><ulink url="/admin/permissions">/admin/permissions</ulink></computeroutput> and grant Create to Registered Users</para>
</sect2>
<sect2>
<title>How do I replace the front page of a new site with the front page of an application on that site</title>
<para>Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.</para>
<orderedlist>
<listitem>
<para>On the front page, click the <computeroutput><ulink url="/admin">Admin</ulink></computeroutput> button.</para>
</listitem>
<listitem>
<para>On the administration page, click <computeroutput>Parameters</computeroutput> link.</para>
</listitem>
<listitem>
<para>Change the parameter <computeroutput>IndexRedirectUrl</computeroutput> to be the URI of the desired application. For a default weblogger installation, this would be <computeroutput><userinput>weblogger/</userinput></computeroutput>. Note the trailing slash.</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>How do I put custom functionality on front page of a new site?</title>
<para>Every page within an OpenACS site is part of a <emphasis role="strong">subsite</emphasis> <ulink url="/doc/acs-subsite">More information)</ulink>. The home page of the entire site is the front page is a special, default instance of a subsite, served from <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www</computeroutput>. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:</para>
<orderedlist>
<listitem>
<screen><userinput>cp <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-subsite/www/index*</computeroutput> <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www</computeroutput></userinput></screen>
</listitem>
<listitem>
<para>Edit the new <computeroutput>index.adp</computeroutput> to change the text; you shouldn't need to edit <computeroutput>index.tcl</computeroutput> unless you are adding new functionality.</para>
</listitem>
</orderedlist>
</sect2>
<sect2>
<title>How do I change the site-wide style?</title>
<para>Almost all pages on an OpenACS site use <ulink url="/doc/acs-templating">ACS Templating</ulink>, and so their appearance is driven by a layer of different files. Let's examine how this works:</para>
<itemizedlist>
<listitem>
<para>
A templated page uses an ADP/Tcl pair. The first line in the ADP file is usually:
</para>
<programlisting><master></programlisting>
<para>If it appears exactly like this, without any arguments, the template processor uses <computeroutput>default-master</computeroutput> for that subsite. For pages in <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www</computeroutput>, this is <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www/default-master.adp</computeroutput> and the associated .tcl file.
</para>
</listitem>
<listitem>
<para>The <computeroutput>default-master</computeroutput> is itself a normal ADP page. It draws the subsite navigation elements and invokes <computeroutput>site-master</computeroutput> (<computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www/site-master.adp</computeroutput> and .tcl)</para>
</listitem>
<listitem>
<para>The <computeroutput>site-master</computeroutput> draws site-wide navigation elements and invokes <computeroutput>blank-master</computeroutput> (<computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/www/blank-master.adp</computeroutput> and .tcl). </para>
</listitem>
<listitem>
<para><computeroutput>Blank-master</computeroutput> does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.</para>
</listitem>
</itemizedlist>
<figure>
<title>Site Templates</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/site-templates.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</sect2>
<sect2>
<title>How do I diagnose a permissions problem?</title>
<itemizedlist>
<listitem>
<formalpara>
<title>Steps to Reproduce</title>
<para>The events package does not allow users to register for new events.</para>
</formalpara>
<orderedlist>
<listitem>
<para>Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.</para>
</listitem>
<listitem>
<para>Select an available event</para>
</listitem>
<listitem>
<para>A link such as <computeroutput>Registration: Deadline is 03/15/2004 10:00am.
» Login or sign up to register for this event.</computeroutput> is visible. Click on "Login or sign up"
</para>
</listitem>
<listitem>
<para>Complete a new registration. Afterwards, you should be redirected back to the same page.</para>
</listitem>
</orderedlist>
<para>Actual Results: The page says <computeroutput>"You do not have permission to register for this event."</computeroutput></para>
<para>Expected results: A link or form to sign up for the event is shown.</para>
</listitem>
<listitem>
<formalpara>
<title>Finding the problem</title>
<para>We start with the page that has the error. In the URL it's <computeroutput>http://myserver.net/events/event-info.tcl</computeroutput>, so open the file <computeroutput>/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl</computeroutput>. It contains this line:</para>
</formalpara>
<programlisting>set can_register_p [events::security::can_register_for_event_p -event_id $event_id]</programlisting>
<para>We need to know what that procedure does, so go to <ulink url="/api-doc">/api-doc</ulink>, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply</para>
<programlisting>return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]</programlisting>
<para>This means that a given user must have the write privilege on the event in order to register. Let's assume that the privileges inherit, so that if a user has the write privilege on the whole package, they will have the write privilege on the event.</para>
</listitem>
<listitem>
<formalpara>
<title>Setting Permissions</title>
<para>A permission has three parts: the privilege, the object of the privilege, and the subject being granted the privilege. In this case the privilege is "write," the object is the Events package, and the subject is all Registered Users.</para>
</formalpara>
<orderedlist>
<listitem>
<para>To grant permissions on a package, start at the <ulink url="/admin/site-map">site map</ulink>. Find the event package and click "Set permissions". </para>
</listitem>
<listitem>
<para>Click "Grant Permission"</para>
</listitem>
<listitem>
<para>Grant the write permission to Registered Users.</para>
<figure>
<title>Granting Permissions</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/grant-perm-463.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</listitem>
</orderedlist>
<para>OpenACS 5.0 offers a prettier version at <ulink url="/admin/applications">/admin/applications</ulink>.</para>
<figure>
<title>Granting Permissions in 5.0</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/grant-perm-50.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
