The Official Xaraya Installation & Getting Started Guide

Installing & Configuring a Xaraya Community Site

Drew Vogel

   Guide version: 0162. Built 03-August-2004.
   Please see http://www.xaraya.com/documentation/userguide/xarayaguide.txt
   for the latest version.

   Copyright © 2002-2003 Drew Vogel drew@xaraya.com.

   This Guide provides instruction on obtaining the Xaraya
   software and installing, configuring, and maintaining a Xaraya
   website.

   The Official Xaraya Installation & Getting Started Guide is
   licensed and distributed under the GNU Free Documentation
   License.

   Parts are copyright (c) 2003 mikespub <postnuke@mikespub.net>.
   Used with permission.

   Parts are copyright (c) 2003 Skribe
   <skribe@plug.linux.org.au>. Used with permission.

   Parts are copyright (c) 2003 Mahmood Al-Yousif
   <mahmood@alyousif.tv>. Used with permission.

   Parts are copyright (c) 2003 John Cox
   <niceguyeddie@xaraya.com>. Used with permission.

   Parts are copyright (c) 2004 Chris Dudley <miko@xaraya.com>.
   Used with permission.

   Permission is granted to copy, distribute and/or modify this
   document under the terms of the GNU Free Documentation
   License, Version 1.2 or any later version published by the
   Free Software Foundation; with the Invariant Sections being
   "Introduction by John Cox", "Document Thanks", "About the
   Author", and "Dedications", no Front-Cover Texts, and no
   Back-Cover Texts. A copy of the license is available at
   http://www.gnu.org/licenses/fdl.html.
     _________________________________________________________
     _________________________________________________________

Dedication

   The Xaraya Project is dedicated to the memory of Greg Allen
   (adam_baum), March 6, 1973-June 16, 2002. Xaraya is his
   legacy.

   Drew dedicates this Guide to my darling Wendy, the keeper of
   my heart and the delight of my eyes.

   Figure 1. Powered by Xaraya

   [xaraya_logo_250.jpg]

   Table of Contents
   1. Introduction & Information about Xaraya

        1.1. Introduction by John Cox
        1.2. Document Disclaimer
        1.3. About this Guide
        1.4. Document Thanks
        1.5. Files Included with this Guide
        1.6. An Introduction to Content Management Systems
        1.7. An Overview of Xaraya
        1.8. Features of Xaraya
        1.9. What does Xaraya mean?
        1.10. How is Xaraya pronounced?
        1.11. Assumptions

   2. Getting Xaraya

        2.1. Getting Xaraya onto the webserver
        2.2. Setting Permissions

   3. Installing Xaraya

        3.1. Installation Guide
        3.2. Increase site security
        3.3. A Quick Look at Xaraya's Interface
        3.4. Click-Paths
        3.5. Removing the Reminder Block

   4. General Configuration

        4.1. Base Module Config

   5. Templates in Xaraya

        5.1. Xaraya Themes Module
        5.2. Xaraya Blocks Module
        5.3. Xaraya Adminpanels Module
        5.4. Xaraya Cache System

   6. Categories in Xaraya

        6.1. Editing and Creating Categories
        6.2. Categories Conclusion

   7. Modules in Xaraya

        7.1. Xaraya Modules -- A New Approach
        7.2. Module Listing: Display & Navigation
        7.3. Managing Modules
        7.4. Modules in Xaraya
        7.5. KNOWLEDGE REVIEW: Manipulating Modules (Adding and
                Removing Modules)

   8. Hooks in Xaraya

        8.1. KNOWLEDGE REVIEW: Handling Hooks

   9. Articles in Xaraya

        9.1. Articles Module Overview

   10. Publication Types

        10.1. Introduction to Publication Types

   11. Dynamic Data in Xaraya

        11.1. Introduction to Dynamic Data

   12. Roles: Users & Groups

        12.1. How to use Roles?

   13. Privileges: Building Blocks for Site Access

        13.1. How to use Privileges

   14. Xaraya Authentication Modules

        14.1. AuthSystem Module
        14.2. AuthLDAP Module
        14.3. AuthInvision Module
        14.4. AuthSSO Module

   15. Managing Content in Xaraya

        15.1. Polls Module
        15.2. XarBB Module
        15.3. Headlines Module
        15.4. Addressbook Module
        15.5. Contact Module
        15.6. Newsletter Module
        15.7. Newsgroups Module
        15.8. Uploads Module
        15.9. Calendar Module
        15.10. Messages Module

   16. Transforming Content in Xaraya

        16.1. Autolinks Module
        16.2. BBCode Module
        16.3. BBClick Module
        16.4. Censor Module
        16.5. Comments Module
        16.6. Changelog Module
        16.7. Hitcount Module
        16.8. Keywords Module
        16.9. Pubsub Module
        16.10. Ratings Module
        16.11. Search Module
        16.12. Subitems Module
        16.13. Smilies Module
        16.14. Workflow Module
        16.15. Wiki Module
        16.16. XLink Module
        16.17. XarLinkMe Module
        16.18. XSLT Module
        16.19. Figlet Module
        16.20. MyBookmarks Module
        16.21. Overlib Module

   17. Maintaining Your Xaraya Site

        17.1. Logging
        17.2. Sitetools Module
        17.3. HTML Module
        17.4. Mail Module
        17.5. Sniffer Module
        17.6. Stats Module
        17.7. Referer Module
        17.8. Opentracker Module

   18. Using Web Services with Xaraya

        18.1. MetaWeblogApi Module
        18.2. BloggerApi Module
        18.3. Soapserver Module
        18.4. XMLRPCServer Module
        18.5. XMLRPCSystemApi Module
        18.6. XMLRPCValidatorApi Module
        18.7. Trackback Module
        18.8. Ping Module

   19. Miscellaneous Xaraya Modules

        19.1. Translations Module
        19.2. Window Module
        19.3. BKView Module
        19.4. Facilities Module
        19.5. Multisites Module
        19.6. Recommend Module
        19.7. Example Module
        19.8. Dyn_Example Module

   20. Conclusion
   A. Xaraya License
   B. Creating the Xaraya database via phpMyAdmin
   C. Enabling Short URL support in Apache

        C.1. Short URLs in Apache 1.x
        C.2. Short URLs in Apache 2.x

   D. Creating a Xaraya Theme
   E. Converting from PostNuke to Xaraya
   F. Installing & Configuring Red Hat 9.0 to run Xaraya
   G. Standards Compliance

   List of Figures
   1. Powered by Xaraya
   3-1. Language selection.
   3-2. Xaraya license agreement
   3-3. System Settings Check.
   3-4. Database Settings Collection.
   3-5. Administrator Account Creation
   3-6. Available Configurations
   3-7. Choose Configuration Options
   3-8. Installation complete!
   3-9. Xaraya's interface after installation.
   6-1. Windows Explorer-like tree
     _________________________________________________________

Chapter 1. Introduction & Information about Xaraya

   This chapter will give you an introduction to Xaraya, it's
   features, the format of this Guide, and the assumptions under
   which this Guide was written. Also included is a handy Xaraya
   pronunciation guide!
     _________________________________________________________

1.1. Introduction by John Cox

   Building a better mouse trap has always been a desire for
   inventors since the beginning of time.

   For the Xaraya team that was the motivation. Our desire and
   drive came from the idea of doing something that has not been
   done before, which in my opinion has been accomplished. Xaraya
   is the culmination of the work of several of the world's best
   software designers working within the PHP language at this
   time.

   The Official Xaraya Installation & Getting Started Guide will
   introduce you to concepts that are, most likely, unfamiliar to
   you. Having complete control over the output of the software
   is the nirvana that most designers of Open Source Content
   Management Systems only dream of. Beyond the control of the
   output, though, is the control of the input as well, which to
   my knowledge has not been attempted.

   Xaraya will ask you to re-examine your expectations as to what
   Content Management Systems can -- and should -- offer you.

   The Official Xaraya Installation & Getting Started Guide
   itself is the culmination of well over a year's worth of work
   to not only document what can be done, but to explain in
   common terms and phrases what Xaraya will do for you. It is
   not only the comprehensive guide to Xaraya, but it is a
   narrative which will walk you through the collective knowledge
   of the Xaraya team. The guide has been written by Drew Vogel
   (and others) who have likely spent more time documenting than
   others have spent coding.

   Welcome to the Official Xaraya Installation & Getting Started
   Guide.

   And welcome to Xaraya -- the next generation of Content
   Management Systems.

   - John Cox
     _________________________________________________________

1.2. Document Disclaimer

   While every reasonable precaution has been taken in the
   preparation of this document, neither the author nor the
   Xaraya development team assumes responsibility for errors or
   omissions, or for damages resulting from the use of the
   information contained herein.

   The information contained in this document is believed to be
   accurate. However, no guarantee is provided. Use this
   information at your own risk.
     _________________________________________________________

1.3. About this Guide

   This Guide will assist you with installing, configuring,
   running, and maintaining a Xaraya Community Site. It is
   intended for Xaraya installers or those individuals interested
   in Xaraya installation and configuration issues.

   This Guide is designed to be read from start to finish.
   Certain sections may be skipped (for example, if you're
   upgrading, you may not need to read the first-time
   installation instructions). However, reading this entire Guide
   from start to finish will provide the maximum educational
   benefit.

   Throughout the Guide, there are examples for you to follow.
   The examples add new features or illustrate concepts and are
   all designed to work together. Generally, the examples include
   Animals, Music, or Food but the concepts that they teach can
   be customized to your particular tastes.

   Throughout this Guide, we use several terms that you should
   understand.

     * "Anonymous users" are defined as users that have not
       registered/logged into an account on the site.
     * "Registered users" are defined as users that have
       registered for an account on the site and have logged into
       the site with their username and password.
     * "Site Administrators" are defined as one or more
       individuals who have administrative access to the site.
       Many sites have only one site administrator while some
       sites have an site administration team.
     * <webdir>: This is the local directory on your site from
       which pages are served by the webserver. For example, if
       you're using a modern Red Hat installation your <webdir>
       is usually /var/www/html. Consult your operating system
       manual for information on determining your <webdir>.
     * <xarroot>: This is the local directory on your site in
       which Xaraya is installed. If you choose to install your
       <xarroot> into your <webdir>, then the two terms have the
       same meaning -- they point to the same directory. However,
       if your <webdir> is /var/www/html, and you install Xaraya
       into a sub-directory called "xaraya", then your <xarroot>
       is /var/www/html/xaraya.
     * <theme_dir>: This is the local directory on your site in
       which Xaraya themes are stored. This directory location is
       defined in the Admin->Base->Modify config, Default Theme
       Directory field.
     * <theme_name>: This is the name of a theme on your Xaraya
       site.
     * http://www.mywebsite.com: This URL is used as a stand-in
       for your site's URL. If you install Xaraya into a
       sub-directory of <webdir>, your site's URL will include
       the sub-directory. So, for example, if your <webdir> is
       /var/www/html, and you install Xaraya into a sub-directory
       called "xaraya", then your site's URL will be
       http://www.mywebsite.com/xaraya.
     _________________________________________________________

1.4. Document Thanks

   Xaraya was written by the Xaraya Team. Xaraya is, as with many
   successful open-source projects, a huge collaborative effort
   relying on many talented contributors from across the globe.
   Without their vision, this document would not exist.

   The Official Xaraya Installation and Getting Started Guide was
   written by Drew Vogel. Abundant thanks to the Xaraya
   development team for answering Drew's endless questions.
   Thanks to the contributing authors, reviewers, Greg Allen
   (adam_baum), John Cox, mikespub, Doug Daulton (Apakuni),
   Skribe, Craig Hamlin, Chris Dudley (Miko), Carl Corliss
   (Rabbitt), Mahmood Al-Yousif, Michael Cortez (mcortez),
   marcinmilan, Joanna Dalle Nogare (jojodee), Marcel van der
   Boom (MrB), Jason Judge, Marjolein Katsma, SpiritTech, and
   Pedro Innecco. Special thanks to Gregor Rothfuss (thalinor)
   for many things.

   If this Guide is sucessful and proves to be useful in helping
   you install, configure, and manage your Xaraya site, a healthy
   measure of credit is due the individuals listed above. If not
   -- if the Guide is somewhat off the mark -- the author accepts
   full responsibility for the shortcomings.

   This document was written in DocBook and then converted using
   XSLT to various output formats. Thanks to the Linux
   Documentation project for their docbook utils and stylesheets
   which made the process much easier.

   Thank you to the Xaraya Team for declaring this to be the
   "Official" guide.
     _________________________________________________________

1.5. Files Included with this Guide

   The following files are included with this guide.

     * callouts directory -- These are files used by this Guide.
       It is not necessary to copy these files to your Xaraya
       installation.
     * resources directory -- These are files used by this Guide.
       It is not necessary to copy these files to your Xaraya
       installation.
     * html.css -- This file is used by this Guide. It is not
       necessary to copy this file to your Xaraya installation.
     * images/recipes/NoPhoto.gif -- Used in the Recipe
       Publication Type example (see EXAMPLE: Adding a new
       Publication Type that uses Dynamic Data). Displayed when
       no recipe photograph is available. Copy to
       <xarroot>/images/recipes directory, creating directories
       as necessary.
     * images/recipes/applechestnutsoup.jpg -- Used in the Recipe
       Publication Type example (see EXAMPLE: Adding a new
       Publication Type that uses Dynamic Data). Photograph for
       the SampleRecipe.txt file. Copy to
       <xarroot>/images/recipes directory, creating directories
       as necessary.
     * modules/articles/xartemplates/user-display-recipes.xd --
       Used in the Recipe Publication Type example (see EXAMPLE:
       Adding a new Publication Type that uses Dynamic Data).
       Template for displaying the new Recipe Publication Type.
       For a default site-wide template, copy to
       <xarroot>/modules/articles/xartemplates directory,
       creating directories as necessary.
     * modules/articles/xartemplates/user-summary-recipes.xd --
       Used in the Recipe Publication Type example (see EXAMPLE:
       Adding a new Publication Type that uses Dynamic Data).
       Template for displaying the new Recipe Publication Type.
       For a default site-wide template, copy to
       <xarroot>/modules/articles/xartemplates directory,
       creating directories as necessary.
     * modules/categories/xarimages/*.jpg -- Category files for
       use with the categories created in the new Recipe
       Publication Type (see EXAMPLE: Adding a new Publication
       Type that uses Dynamic Data). For site-wide use, copy
       these files to the <xarroot>/modules/categories/xarimages
       directory.
     * Tutorials/PubType/SampleRecipe.txt -- Used in the Recipe
       Publication Type example (see EXAMPLE: Adding a new
       Publication Type that uses Dynamic Data). A sample recipe
       to add at the end of the Recipe Publication Type example
       (and a darned good recipe by Drew Vogel, too!).
     _________________________________________________________

1.6. An Introduction to Content Management Systems

1.6.1. A glance toward the past...

   As the internet and world-wide web started to emerge as a
   major repository for storage, retrieval, and display of data,
   the main avenue for accessing that data was static,
   hand-coded, HTML (Hyper-Text Markup Language). Static HTML
   means that each and every web page on a site is created
   individually; links between content elements are managed by
   hand; and changes can be made only by a site administrator
   following a multiple-step process involving the downloading,
   editing, and uploading of new or modified pages.

   For users with moderate technical skills, the creation of web
   pages using static HTML is fairly easy. But because the
   content is not separated from the code, a lot of time is spent
   wrapping the content with HTML code so that it can be
   presented in a meaningful way. Composing pages in static HTML
   is time-intensive and can interfere with content; it's
   comparable to asking a book author to tackle typesetting,
   printing, and binding, which would certainly detract from the
   writer's primary goal: to provide content.
     _________________________________________________________

1.6.1.1. Challenges of developing and maintaining a static HTML
website

   Without the separation of code and content, many aspects of
   managing a static HTML site are difficult. It is complicated
   to establish the 'look' of a site, and not easy to change that
   look once set. Searching for information on a site, even one
   with a limited number of pages, is an inaccurate,
   time-consuming task. It is impractical to collaborate on pages
   with colleagues unless additional administrative (FTP)
   accounts are configured or access codes are shared; both
   scenarios present a security risk.

   For many people, HTML editing programs like FrontPage and
   DreamWeaver present a better approach to website design,
   implementation, and maintenance. These programs offer tools
   for defining a site-wide 'look' using site templates, as well
   as additional features to make it easier to create and edit
   static HTML pages. However, even when using these tools,
   adding or modifying content still requires a combination of
   writing and coding, which can be tricky and time consuming
   difficult to accomplish for anyone with lower than moderate
   technical skills.

   For example typical publication cycle for a static HTML site
   might follow this pattern: An article is written; then passed
   to the web maintainer who creates a new page (following the
   site's design) either from a template or from scratch. The
   article is converted to HTML code and pasted into the new
   page; which, depending on the maintainer's workload may take
   several hours or more to be posted on the website. The new
   page is uploaded to the website and then manually linked to
   other pages as necessary, with related pages updated as
   necessary. That's a lot of time and a lot of work.

   In a limited number of contexts, static HTML may be quite
   suitable for a website. If the content on the site does not
   get updated frequently, is updated by a limited number of
   individuals, does not need to be searchable, does not require
   pleasant presentation, and if there is a technical individual
   who is willing to edit HTML and download & upload changes, you
   may not need the advanced features of a Content Management
   System. However, before you put this book down and walk away,
   understand this: on the same hardware that runs your static
   HTML site, you can have a full-featured, easy-to-use Content
   Management System that makes updating content much easier and
   allows a huge variety of advanced features that simply were
   not available with static HTML sites.

   This represents a glance toward the past -- or maybe this is a
   look at the way you're currently doing things, and you have
   found yourself with too much data to manage effectively. But
   there is a better way. A way that will allow you create and
   present meaningful content on your website without
   downloading, coding, and uploading -- from anywhere on the
   Internet. A way that will allow advanced features -- features
   like site-wide searches, user accounts, private messages, and
   much more -- features that are simply not possible with static
   HTML.

   A Content Management System could be the solution to your
   problems.
     _________________________________________________________

1.6.2. ...a step toward the future.

   The answer to all the wasted time and effort of maintaining
   static HTML websites is to use a Content Management System.
   Static HTML was insufficient for the management of content on
   even a modest website; it was clearly too much data and too
   much work. Though HTML editing tools streamlined the procedure
   for maintaining a static HTML site, a better method of data
   management was necessary.

   Web technology unveiled new competitive scenarios for
   companies: improved customer interaction, better
   business-to-business communication, and a more vibrant
   distribution of internal information. Today, many companies
   are turning to the web as a new playing field for innovation;
   tapping a wide variety of content and delivering it instantly
   to users around the globe. Some of the key goals of a Content
   Management System (CMS) are to provide users with
   personalized, transparent access to relevant information
   inside and outside of the organization; and to allow authors
   to easily contribute information to the knowledge base by
   managing content in a reliable, secure, and dependable way.
     _________________________________________________________

1.6.2.1. Dynamic Content Management as the way of the future

   Content Management Systems allow content to be handled and
   updated dynamically and makes it easy for non-technical people
   to create and modify content. What is 'dynamic content'?
   Dynamic content is content that may change frequently, is
   separated from the display (HTML) code, and is made into an
   'element' that can be manipulated by the Content Management
   System. Dynamic content elements are usually stored in a
   database which is running the website.

   Good Content Management Systems are designed so that nearly
   anyone can publish, browse, and revise information without
   knowing much more than how to use a browser or a word
   processor. The technical details are hidden from site users,
   thus eliminating their need to learn about software
   programming, HTML, network protocols, or how and where to
   publish and retrieve files to work on them. With a click of a
   button, authorized users can contribute any content to areas
   of the site to which they have been granted access.

   Compared with static HTML, Content Management Systems:

     * Separate code from content making it easier to focus on
       content
     * Offer a consistent, non-technical, easy-to-use interface
       for both users and administrators. Content contributors
       log into a secure area of the website, enter the date,
       title, and body of their news submission, and click
       submit, and the news article is published to the website
       with no hassle.
     * The entire look and feel of a website can be changed very
       easily. Some CMS packages even allow users to customize
       the way they see a website -- everything from language to
       colors to the on-screen placement of features.
     * Are feature-rich, and support additional, specialized
       features -- forums, galleries, live chat boards, private
       messaging, local weather, and more.
     * Are searchable because they rely on a database. This
       feature alone makes CMS an exceptional choice when
       compared to static HTML.
     * Allow for community involvement and collaboration. While
       CMS-based sites can be run effectively by one person, the
       community can easily comment on a website's content
       without requiring special access.
     * Gives administrators complete control over what each user
       or group of users can do within a web site. Administrators
       can control access to sections of a site, and assign user
       privileges and permissions to individuals or groups as
       we'll see in Chapter XX.

   Once users have made the transition to a CMS, they will no
   longer feel incapacitated and unable to contribute to the
   website community. Often, the availability of all the new
   features provided by a CMS can be intimidating at first, and
   the learning curve can appear rather steep when compared to a
   static HTML page because while a static HTML page does not
   allow community involvement, CMS readily welcome it. CMS
   managed sites are simply so much easier to maintain than
   static HTML sites. To update a CMS site, all you need to do is
   surf to it and click on links to update the site. So, if you
   know how to surf the 'Net, you can maintain the site; very
   little other work is necessary!

   So far in this discussion, we have discussed only the most
   basic functions of a CMS, but there are hundreds of different
   functions available in an advanced Content Management System
   like Xaraya. Fortunately, it's fairly easy to learn the main
   functions, ignoring the rest of the features until you need to
   use them. This is another advantage of using a CMS instead of
   ordinary HTML pages: the advanced functionality allows users
   to search the site, post on forums, leave user information
   which is easily manageable -- in short, anything that can be
   done with advanced database management.

   A CMS implementation provides a win-win solution for business
   end-users, webmasters, and business management. It provides a
   complete environment that brings the power of distributed
   content management down to the average end-user, while at the
   same time addressing the most important requirements of the IT
   department, webmasters, and business management to provide a
   secure, fast, and effective portal; however commercial CMS
   packages (like Microsoft Content Management Server, Vignette,
   Stellent, and Obtree) can be prohibitively expensive. A quick
   internet search for commercial CMS packages reveals prices
   ranging from less than $99 through hundreds of thousands of
   dollars. Fortunately, there are several Open Source Software
   CMS solutions that cost very little or are completely free to
   use. Xaraya is a robust, free Content Management System that
   runs on all platforms that support the PHP scripting language,
   a web server, and a relational database management system
   (RDBMS).

   Open Source software is software which may be freely
   distributed and whose programming code is available and also
   modifiable by anyone, within the terms of a particular
   license.

   The basic idea behind Open Source Software is very simple:
   When programmers can study, redistribute, and modify the
   source code for a piece of software, that software evolves.
   People improve it, people adapt it, and people fix bugs. These
   modifications can be folded back into the development
   community, benefiting everyone. And this can happen at a speed
   that, if one is used to the slower pace of conventional
   software development, may seem astonishing.

   And you guessed it: the Xaraya Content Management System and
   all the pieces of software required to make it work are Open
   Source!

   In the next section we'll take a closer look at Xaraya and
   explore some of the many features that it has to offer.
     _________________________________________________________

1.7. An Overview of Xaraya

   A quick look at how Xaraya works.

   The documentation for this part of the Guide is being
   developed.

     * What are the basic building blocks of Xaraya? How do they
       interoperate?
       The Core (the files in the <xarroot>/includes directory)
       handles each page request. Modules provide units of
       functionality, and can be added, extended, or disabled as
       required. Some modules are mandatory, meaning that the
       core expects them to be available on the site. Other
       modules are optional and can be turned on or off as
       needed.
     * What is an Article?
     * What is a Publication Type?
       Publication Types are specific "types" of Articles on the
       site (for example, News Articles, Frequently Asked
       Questions, Pictures, or Recipes are all examples of
       specific Article "types"). See the overview on
       Admin->Articles for more information.
     * What is a Template?
       A Template is a file that defines how content items on the
       site are displayed (rendered). A Template receives output
       from a module and formats the output according to various
       rules. Templates can be very simple or very sophisticated.
       A normal page typically consists of many templates, each
       nested within another.
       Each module has a default set of templates that it uses,
       but templates can be over-ridden by creating a Theme. You
       can switch Themes at will, and each request for a
       particular page will check if there is an over-riding
       Template in the current Theme before using a default
       template.
     * What is a Theme?
       Themes are a collection of templates, images, etc. that
       represent a particular Theme (layout, style, or skin) for
       your site. Typically, you would have at least the page
       templates in the Theme directory, and possibly some
       overrides for default module and block templates.
       Special themes include the "print" theme, where the page
       template does not include any blocks and so will only show
       the output of the main module function, and the "rss"
       theme, that doesn't generate XHTML at all but XML for
       syndication by other sites.
     * Are Articles, Publication Types, and Templates related? If
       so, how?
       Each Publication Type uses a specific template to display
       content of a particular type. This means each Publication
       Type can have a different layout or format.
     * How are Articles sorted into Sections/Categories/Topics?
       Articles can be placed into Categories (one or more). The
       Categories may mean different things from site to site,
       depending on how they were configured. The default Xaraya
       installation of the Articles module contains a set of
       Categories familiar to administrators of other Open Source
       CMS products (PHP-Nuke, PostNuke, Envolution, etc.) where
       news articles are categorised in two independent ways
       (Topics & Categories) and documents are categoriesed into
       Sections.
       New Xaraya sites will often use generic categories across
       all Publication Types, instead of having separate
       hierarchies for each of them. See overview on
       Admin->Articles for more information.
     * How, and by what, are Articles displayed?
       Articles are displayed by the Articles module, in
       cooperation with a bunch of 'hooked' utility modules
       (categories, hitcount, ratings, comments, and other
       modules).
     * What do Categories do? Are they the only way of sorting
       Articles, or are they just an example?
       You can organize your Categories however you see fit --
       the Categories provided at installation are just an
       example which may be modified, extended, or completely
       removed as you require.
       Articles can be browsed by Publication Type, by Category,
       and/or by Author, and sort the results by date, title, and
       other criteria.
     * Do Articles need to be sorted into a simple hierarchy or
       can they be sorted into a multidimensional array with each
       Article fitting into several independent hierarchies
       simultaneously or using category flags instead of a
       hierarchy at all?
       Each "base category" is organised as a hierarchy, but
       several independent base categories (and their
       hierarchies) can be assigned to each of the Publication
       Types in Articles.
       For instance, a travel site might have one hierarchy with
       countries and cities, and another hierarchy with
       particular interests (for example, culture, sports,
       restaurants, etc.). An Article about a restaurant in
       Brussels can, for example, be placed in the category
       "Brussels" and also in the category "Restaurants", and
       people can then view all articles about Brussels, about
       restaurants, or about restaurants in Brussels.
       And if you work by Publication Type, you could let people
       browse only through reviews (a particular Publication
       Type) about restaurants in Brussels.
     _________________________________________________________

1.8. Features of Xaraya

   Xaraya is a buzzword-compliant, extensible, open source
   web-development software platform written in PHP and licensed
   under the GNU General Public License. Xaraya utilizes robust
   permissions, data management, and multilingual systems to
   dynamically integrate and manage content.

   Xaraya's modular, database-independent architecture provides
   tools which separate form, function, content, and design on
   the site. Xaraya delivers the requisite infrastructure for a
   fully dynamic multi-platform Content Management Solution
   (CMS).

     * Database-driven website engine (PHP-ADODB compliant)
     * Extensible through a variety of third-party modules
     * Powerful security module for multi-level
       user/administrator logins
     * Distribute workload using User/Administrator management
       tools
     * Robust article management system
     * Fully editable & manageable News, Links, Downloads, and
       FAQ Sections
     * BlockLayout Theme Engine: Display your site your way
     * News Feed Manager: Access thousands of RSS-compliant news
       feeds
     * Site Statistics: Tracks browser & operating system, top
       news & articles, and more
     * Easy install on most Unix/Linux and Windows platforms
     * Import information from PostNuke and Moveable Type
       installations
     * Xaraya is compliant with RSS, CSS, XHTML, and W3C
       accessibility standards.

   Xaraya reduces web site development costs by introducing
   sophisticated administration tools & services which separate
   form, function, content, and design. With Xaraya, you work in
   a simple, structured environment to rapidly develop your
   website with diverse content, including:

     * News Articles
     * Web Links Directory
     * Job Boards
     * Frequently Asked Questions
     * File Downloads
     * Photo Gallery
     * Member profiles
     * Web forums (message boards)
     * Articles Repository (i.e.: Knowledge base, cooking
       recipes, product reviews, news articles, etc.)

   With more than forty active developers spanning five
   continents and ten languages, the Xaraya Development Team is a
   blend of some of the best and brightest developers in the open
   source community. We expect the best of one another. As a
   result, you can expect the best from Xaraya.
     _________________________________________________________

1.9. What does Xaraya mean?

   The name Xaraya was selected by the development team after an
   internal contest. Submitted by Marty Vance (Dracos), Xaraya
   does not really mean anything. We were looking for a name
   which was both interesting and unique. Xaraya certainly fit
   the bill.

   That said, the word Xaraya is reminiscent of 'raya', the
   Spanish word for Manta Ray. The development team rather likes
   the nautical feel of that reference, particularly when one
   thinks of the Internet as an "ocean" of information. The
   Xaraya logo concept by Marty Vance, logo design by LaDalle
   Hunt.
     _________________________________________________________

1.10. How is Xaraya pronounced?

   It is not as difficult as it may look. In fact, saying Xaraya
   is actually sort of fun. Phonetically, it looks like this:
   Zuh-rye-ah.

   To hear Xaraya pronounced by Xaraya Team member Marie
   Altobelli (LadyofDragons), visit
   http://www.xaraya.com/xcommon/media/xaraya.wav.
     _________________________________________________________

1.11. Assumptions

   Xaraya allows unprecedented levels of customization, it is
   therefore impossible to list every possible configuration. To
   provide familiarity with how Xaraya functions this Guide makes
   the following assumptions:

   * That you plan to run a Community Site and:

     * Do not permit anonymous users to submit articles or post
       comments until they register.
     * Allow ALL users to read all articles & related comments on
       the site.
     * Allow Registered users to:
          + Submit articles to the site.
          + Post comments.
     * Site Administrator(s) have complete access to the site.
     * That you have created a web-readable "images" directory in
       your Xaraya installation directory (<xarroot>/images). We
       will store any non-core and non-module images needed by
       the site in this directory.

     * That you already have a working webserver (Apache or IIS),
       PHP 4.1.2 or higher (4.2.x or higher is strongly
       recommended), an email subsystem, and a database
       (currently MySQL) installed, configured, and operating
       correctly. The installation and configuration of these
       tools are beyond the scope of this Guide. See
       http://www.php.net and http://www.mysql.com for assistance
       with these issues.
     _________________________________________________________

Chapter 2. Getting Xaraya

   Xaraya is distributed in three pieces, the "Core", the "Base",
   and "Full". The most current version of Xaraya is always
   available at http://www.xaraya.com.

     * The "Xaraya Core" distribution is the absolute minimum
       installation of Xaraya.
     * The "Xaraya Base" distribution is the recommended
       installation for most users because it includes all the
       files of the "Base" distribution, plus several useful
       modules.
     * The "Xaraya Full" distribution contains more modules that
       further extend the functionality of Xaraya beyond the
       "Core" or "Base" installation.

   Modules may be added to your site at any time after
   installation.

   The Xaraya Base, Core, and Full distributions are available in
   ZIP (Windows) & TAR.GZ (Linux/OSX/BSD/Unix) format.

   Download the Xaraya Base distribution distribution from the
   Downloads section of http://www.xaraya.com.

   This document shows how to install & configure the Xaraya Base
   distribution on your website. Later in this document, you are
   taught how to integrate additional modules into your Xaraya
   Base installation.

     * Using the appropriate unarchiving utility, unarchive the
       Xaraya Base distribution into a temporary directory.
       Consult the manual for the unarchiving utility if you're
       unfamiliar with how to extract archives. For example, on
       Linux:
          + "mkdir /tmp/xar"
          + "cd /tmp/xar"
          + "tar -xzvf </path/to/XarayaBase.tar.gz>"

     * Using your text editor, edit
       /tmp/xar/html/var/config.system.php and make the following
       changes as necessary:
          + Database Username: The username that will be used to
            connect to the database. Do not use 'root' or 'admin'
            account names as they present a security risk. This
            user should already exist and have privileges in your
            database. For example, if the database user was to be
            "db-user", change the line to:
            $systemConfiguration['DB.UserName'] = 'db-user';
          + Database Password: The password that will be used to
            connect to the database. For example, if the database
            password was to be "db-user-password", change the
            line to:
            $systemConfiguration['DB.Password'] =
            'db-user-password';
          + Database Host: The host name where the database
            server is located. In most cases this will be
            'localhost'. Otherwise, you need to include a fully
            qualified domain name (FQDN) here, for example,
            'mybox.mydomain.com' or the IP number of the machine.
            For example, if the database host was to be
            "localhost" (meaning that the database is on the same
            server as Xaraya), change the line to:
            $systemConfiguration['DB.Host'] = 'localhost';
          + Database Name: The name of the database to which to
            connect. Case-sensitive.
            $systemConfiguration['DB.Name'] = 'Xaraya';
          + Database Type: The database server type.
            $systemConfiguration['DB.Type'] = 'mysql';
          + Database TablePrefix: Used when you wish to run
            multiple sites off the same database. That way, user
            accounts will be available across all the sites. This
            feature is not currently implemented into Xaraya, but
            will be available in a future release. The prefix
            chosen here will be prepended to each of the tables
            of your database to give each a unique name across
            multiple installs. For example, if the database table
            prefix was to be "xar", change the line to look like
            this:
            $systemConfiguration['DB.TablePrefix'] = 'xar';
     * Save your changes and exit the text editor.
     _________________________________________________________

2.1. Getting Xaraya onto the webserver

   Move Xaraya Base from the temporary directory into your
   <webdir> (or a sub-directory of your <webdir>) to make Xaraya
   accessible to the web.

   For example, under Linux, assuming that you wish to install
   Xaraya into a sub-directory of <webdir> called "xaraya", that
   your <webdir> is "/var/www/html" (as it is on modern Red Hat
   systems -- users of other operating systems should check their
   manual to find the path to the correct <xarroot> location and
   directory), and that you have extracted the XarayaBase archive
   to a temporary directory called "/tmp/xar":

     * "cd /tmp/xar/html"
     * "mkdir <webdir>/xaraya" (or the correct <xarroot> for your
       installation)
     * "cp -r /tmp/xar/html/* <webdir>/xaraya" (or the correct
       <xarroot> for your installation)

   If you need to UPLOAD your site, ensure that the files are
   transferred in ASCII or Text format.

   It may be necessary to set ownership & permissions for the
   directory where Xaraya is installed.
     _________________________________________________________

2.2. Setting Permissions

   Now that you've installed the files in the correct place on
   your webserver, you need to ensure that all the files can be
   read by the web server. This should be the default situation,
   but if it isn't then consult your operating system manual for
   information about changing that. The best route is to change
   the group of the file and directories to the same group used
   by the web server (NOTE: This presents a reduced security
   risk). However the webserver user ID should not own the files,
   but the webserver's group ID can have group ownership. This
   gives the advantage that not everyone needs to have read
   access to the files - just those in the webserver group. It is
   best if the webserver user ID does not own the files itself
   because then the webserver could change the permissions of the
   files without your knowledge and that could make it easier to
   hack the site. Under Red Hat Linux, check the "User" and
   "Group" settings in /etc/httpd/conf/httpd.conf to determine
   the user & group values. For example, under Linux and assuming
   that your user/group that is used by the webserver is user:
   "web" and group: "apache":

     * "chgrp -R apache <xarroot>"

   There is a file and some directories to which the web server
   must have 'write' access. They are:

     * "<xarroot>/var/config.system.php": Set with "chmod 666
       <xarroot>/var/config.system.php"
     * "<xarroot>/var/cache/templates": Set with "chmod -R 777
       <xarroot>/var/cache/templates"
     * "<xarroot>/var/cache/rss": Set with "chmod -R 777
       <xarroot>/var/cache/rss"
     * "<xarroot>/var/cache/adodb": Set with "chmod -R 777
       <xarroot>/var/cache/adodb"

   It is likely that these permissions are correct already
   because the installer checks them for you.
     _________________________________________________________

Chapter 3. Installing Xaraya

   Once Xaraya has been moved onto your site (either via a copy
   command or an upload), you must install it before using the
   site. Follow these steps to install Xaraya.

   Note

   If you are a Windows user and also use ZoneAlarm, be sure to
   DISABLE or EXIT ZoneAlarm before installing Xaraya on a
   Windows machine. ZoneAlarm may cause problems when installing
   Xaraya on a Windows machine.

   From your browser, launch
   http://www.mywebsite.com/xaraya/install.php (replace with the
   correct path to your Xaraya installation's "install.php"
   file).
     _________________________________________________________

3.1. Installation Guide

3.1.1. Choose a Language

   Select your language from the drop-down list. Click
   "Continue".

   Figure 3-1. Language selection.

   [install01.jpg]
     _________________________________________________________

3.1.2. License Acceptance

   Read & agree to the license. Click "Continue". If you do not
   agree to the license, you cannot install Xaraya.

   Figure 3-2. Xaraya license agreement

   [install02.jpg]
     _________________________________________________________

3.1.3. System Settings Check

   This panel tells you if you have set up Xaraya correctly. It
   runs checks and determines whether you're running the correct
   version of PHP and whether the permissions are set correctly,
   and more. If there is a problem then follow the advice given.
   If no failures or warnings are reported, click "Continue". If
   an error or problem is reported, fix it before continuing.
   Once you have fixed any issues, press "Check Again" to
   re-check the system settings.

   Figure 3-3. System Settings Check.

   [install03.jpg]

     * FAILURE: PHP Version is less than 4.1.2.
       This error can be fixed by installing an updated version
       of PHP that is equal to or greater than version 4.1.2.
     * FAILURE: The installer cannot write to the configuration
       file. Please verify that your webserver has write access
       to the var/config.system.php file.
       This error can be fixed by changing the permissions of the
       <xarroot>/var/config.system.php" file, for example, "chmod
       666 <xarroot>/var/config.system.php".
     * FAILURE: The installer cannot write to
       var/cache/templates. Please verify that your webserver has
       write access to the var/cache/templates directory.
       This error can be fixed by changing the permissions of the
       <xarroot>/var/cache/templates" directory, for example,
       "chmod 777 <xarroot>/var/cache/templates".
     * FAILURE: The installer cannot write to the var/cache/rss
       directory.
       This error can be fixed by changing the permissions of the
       <xarroot>/var/cache/rss" directory, for example, "chmod
       777 <xarroot>/var/cache/rss".
     * FAILURE: The installer cannot write to the var/cache/adodb
       directory.
       This error can be fixed by changing the permissions of the
       <xarroot>/var/cache/adodb" directory, for example, "chmod
       777 <xarroot>/var/cache/adodb".
     _________________________________________________________

3.1.4. Database Settings

   Review (and edit if necessary) the Database Settings on the
   next panel. The default database settings displayed on this
   panel come from the 'config.system.php' file we edited above.

   Figure 3-4. Database Settings Collection.

   [install04.jpg]

     * The database types currently supported by Xaraya are MySQL
       or PostGRESQL. Choose the one that you are using.
     * Click "Create the database" to have the Xaraya installer
       attempt to create the database. Click "Continue".

   If Xaraya cannot create the database for you, see Appendix B:
   Creating the Xaraya database via phpMyAdmin.
     _________________________________________________________

3.1.5. Administrator Account Creation

   This panel creates the site Administrator's account. This
   account has unlimited access to the site.

   Figure 3-5. Administrator Account Creation

   [install05.jpg]

     * Enter Full Name -- the Administrator's full name.
     * Enter Username -- (required) used by the Administrator to
       log into the site.
     * Enter Password -- (required) used by the Administrator to
       log into the site.
     * Enter Password again to verify (required).
     * Enter Administrator Email address (required).
     * Click "Continue".
     _________________________________________________________

3.1.6. Available Configurations

   Figure 3-6. Available Configurations

   [install06.jpg]

     * 'Community Site' prepares a site where Registered users
       have read access to all modules and Anonymous users can
       either read non-core modules or be limited essentially to
       the first panel (depending on the configuration option
       selected at installation).
     * 'Intranet' configuration is very restrictive where users
       who aren't logged in (Anonymous users) are limited to the
       first panel. Registered users have read access to non-core
       modules. There is also another group of users called
       'Oversight' that have Administrative rights to everything
       except the Roles and Privileges modules.
     * 'Public' assumes a site where Anonymous users can do more
       than just read. They have the option to post comments to
       articles in non-core modules, while Registered users can
       be given moderate rights to all modules.
     * 'Upgrade from Postnuke' is currently not available.

   From the list of Available Configurations, select "Community
   Site". Click "Continue".
     _________________________________________________________

3.1.7. Choose Configuration Options

   Once you've chosen your configuration from the Available
   Configurations, specify which modules you wish to initialise
   via the installer. The listed modules are a subset of all the
   modules available for Xaraya, but this provides a nice
   starting place. For this example, select the installation
   defaults unless you have specific reasons to select otherwise.

   Figure 3-7. Choose Configuration Options

   [install07.jpg]

   If you make a mistake or forget to install a module that you
   need, don't worry -- modules can be installed or removed at
   any time.
     _________________________________________________________

3.1.8. Installation Complete

   Click "Continue".

   Figure 3-8. Installation complete!

   [install08.jpg]

   Your Xaraya installation is complete! Click "Launch the site!"
   to go to your new Xaraya website, logged in as the
   Administrator.
     _________________________________________________________

3.2. Increase site security

   There are two steps that are recommended after installation to
   increase the security of the website.

    1. To increase site security after installation, delete the
       'install.php' and 'upgrade.php' files from the Xaraya
       installation directory ("<xarroot>"). These two files are
       not needed for normal site operation. For example, on
       Linux:
          + "cd <xarroot>"
          + "rm install.php"
          + "rm upgrade.php"
    2. Change the file permissions for
       <xarroot>/var/config.system.php to "444" (read-only). This
       can be done by using the command "chmod 444
       config.system.php" from within the Xaraya's /var
       directory. For example, on Linux:
          + "cd <xarroot>/var"
          + "chmod 444 config.system.php"
     _________________________________________________________

3.3. A Quick Look at Xaraya's Interface

   After the first installation, Xaraya's interface looks similar
   to other Content Management Systems.

   Figure 3-9. Xaraya's interface after installation.

   [install10.jpg]

   At the top is the title bar of the browser which says, "Your
   Site Name :: Base :: Welcome" by default. Below that, at the
   top left of the screen, is the Xaraya logo which is part of
   the 'header' region. Click the logo at any time to go to the
   front page of your site.

   Down the left side, since you're logged in as an
   Administrator, appears the Administration menu which may be
   divided into groups (Global, Content, Users & Groups, etc.)
   depending on your configuration selection in
   Admin->Adminpanels->Modify config. The Administration menu
   appears only for members of the Administrator group; regular
   users (anonymous and registered users) do not see this menu.
   At the bottom of the Administration menu is the "[admin
   logout]" link which should be used to log out of the site when
   you're done administrating Xaraya. Below the Administration
   menu is the Main Menu as it is displayed for regular users.

   At the bottom of the browser window is Xaraya's 'footer'
   region. After installation, you'll see the Xaraya "powered by"
   logo, copyright statement, and your site slogan (which is
   "Your Site Slogan" after installation).

   The large pane that uses most of the browser window is the
   content region. This is where the majority of site information
   is displayed to users.

   Everything you see in Xaraya is configurable. Xaraya's
   powerful theming engine, BlockLayout, makes it easy to
   customize your site to your exact specifications. The colors,
   the fonts, the placement of information is all configurable by
   changing themes or templates on your Xaraya site. Don't like
   the Administration menu on the left? It's quite simple to move
   it. Want to put your own logo in place of the Xaraya logo at
   the top? No problem!
     _________________________________________________________

3.4. Click-Paths

   For the remainder of this document, we indicate where to click
   by using "click-paths".

   "Click-paths" are a series of clicks you make in your web
   browser. An example of a "click-path" is indicated as follows:

   Admin->Blocks->View Instances

   This example click-path instructs you that while logged in as
   the Administrator ('Admin'), click the link for Blocks and
   finally on the next page click 'View Instances'. Generally,
   the click-path is followed with a specific instruction, as you
   see in REMOVING THE REMINDER BLOCK, below.
     _________________________________________________________

3.5. Removing the Reminder Block

   There is a REMINDER block that is displayed on the left side
   menu of a newly-installed or updated Xaraya site which reminds
   the Administrator to delete the install.php and upgrade.php
   files from <xarroot>. Since we've already deleted those files,
   we can safely remove the REMINDER block. Follow the steps
   below to remove the REMINDER block.

     * Admin->Blocks->View Instances:
          + In the line with REMINDER in the title, click the
            "Delete" operation and "OK" to confirm deletion. The
            REMINDER block is deleted.
     _________________________________________________________

Chapter 4. General Configuration

   Now that we've installed Xaraya, we should begin to configure
   it. The pages in this section should help guide you through
   some of the more basic configuration options and start you on
   the path to customizing your Xaraya site.
     _________________________________________________________

4.1. Base Module Config

   This section describes some of the settings and options
   available from the base module.

   Admin->Base->Modifyconfig: This panel allows you to change
   some of the settings controlling the core behaviour of the
   site.

     * Website display configuration:
          + For this example, set the Default Module to
            "articles" so that the articles module is displayed
            when a visitor hits the site. Select "articles" from
            the drop-down list of available modules.
          + Default Module Type: From the drop-down list, "User".
          + Default Module Function: "main"
          + Default Theme Directory (relative to <xarroot>):
            "themes"
          + CHECK "Enable Short URL Support" -- this is the
            'master switch' for Short URL support on your site.
          + CHECK "Fix HTML Entities" -- this will ensure that
            characters such as the copyright sign and
            international symbols like umlauts are displayed
            correctly.
     * Sessions and Security
          + Security level: From this drop-down list, configure
            the general security level for your site. If a user
            CHECKS the "Remember Me" box displayed in the login
            panel when logging in, the user's session is not
            purged for the duration set in the settings below. If
            a user does NOT check the "Remember Me" box when
            logging in, they must log into the site each time
            they visit. For our example, select "Medium"
            security.
               o High: Users must log on each time they return to
                 the site.
               o Medium: Users stay logged on for the number of
                 days specified in Session Duration, below.
               o Low: Users stay logged in 'forever' (well, it's
                 not actually FOREVER, but a really long time!).
          + Session duration (in days): This setting determines
            how long (in days) a user's session will last before
            it expires, forcing the user to re-log in with their
            existing username and password. Set the session
            duration to "7" days.
          + Session inactivity time out: If Xaraya detects that a
            user's session has been idle for a certain period of
            time and that the Security level is High or Medium,
            it will expire the session. This setting determines
            how many minutes Xaraya will wait before expiring the
            session due to inactivity. Set the inactivity time to
            "90" minutes.
          + Click "Update Base Configuration" to save changes.
     * Languages and Locales
     * Other

   Admin->Base->System Information: This panel displays a variety
   of information about the PHP installation on the site. Should
   you ever need to determine what version of PHP the site is
   running, or what modules are compiled into PHP, this is where
   to find that information. This information may be helpful if
   you need to submit a Xaraya bug report or a feature request.

   Admin->Base->Extension Releases: This panel syndicates a news
   feed from www.xaraya.com listing recent module and theme
   releases.
     _________________________________________________________

Chapter 5. Templates in Xaraya

   Xaraya displays information to site visitors by using
   TEMPLATES. Templates are available in the following varieties:
   "function templates", "block templates", "page templates",
   "block group templates", or module templates.

     * "Function Templates" are Content Layout templates that
       display a view of a particular function of Xaraya. Xaraya
       separates function templates for users and administrators.
       User function templates have "user-" at the beginning of
       the template filename, and administrator function
       templates have "admin-" at the beginning of the template
       filename. For example, one of Xaraya's default function
       templates is called 'user-display-news'. This template
       defines the layout of the news area in your page as it is
       displayed to users of the site. The administrator view is
       defined by the 'admin-display-news' template).
     * "Page Templates" are Content Layout templates that display
       a view of a whole page, which can include function and
       block templates. These files reside in the
       <xarroot>/<themes_dir>/<theme_name>/pages directory.
     * "Block Templates" are Block Layout templates that display
       a view of a particular block within Xaraya. Block
       templates exist in
       <xarroot>/modules/<module_name>/xartemplates/blocks,
       creating directories as necessary (give new directories
       appropriate permissions). So, for the articles module, the
       block templates exist in
       <xarroot>/modules/articles/xartemplates/blocks.
       Customize default block templates with the equivalent
       ".xt" override template in the
       <xarroot>/<theme_name>/modules/<module_name>/blocks
       directory, creating directories as necessary (give new
       directories appropriate permissions). You also have
       specific override custom block templates that you name
       when you create a new block. The name of the template file
       (without the ".xt" extension) is entered into the custom
       template field when creating a block instance. These
       specific override template files are in the
       <xarroot>/<theme_name>/blocks directory.
     * "Block Group Templates" are Block Layout templates that
       contain a collection of individual block templates. The
       Block Group template files reside in the
       <xarroot>/<themes_dir>/<theme_name>/blocks directory.
     * "<module_name>.xt Template" is a Content Layout template
       that overrides the default page template for
       <module_name>. These files reside in the
       <xarroot>/<themes_dir>/<theme_name>/pages directory.

   Function templates, block templates, page templates, and block
   group templates can be defined as either site-wide or
   theme-specific. It is advisable to make template files
   theme-specific by default. By doing so, you minimize the
   amount of work necessary if you decide to add additional
   themes to the site later.

     * Site-Wide templates: A site-wide template is used to
       change the look & feel of the site, no matter what theme
       is being used. Site-wide templates are overridden by
       theme-specific templates, if one exists. These files exist
       in the <xarroot>/modules/<module_name>/xartemplates
       directory.
     * Theme-specific templates: Theme-specific templates change
       the look & feel of the site only when displayed through a
       particular theme. These files exist in the
       <xarroot>/<themes_dir>/<theme_name>/modules/<module_name>
       directory.

   If template files exist in both site-wide, theme-specific
   locations, the theme-specific templates take precedence over
   site-wide templates.
     _________________________________________________________

5.1. Xaraya Themes Module
     _________________________________________________________

5.1.1. Themes Module

   Enable/disable themes to change site appearance.
   Admin->Themes.

   Make your selected theme load as default by selecting it in
   the Admin->Themes->Modify config panel.

     * View Themes:
          + Style: Defines the display of the module list. Select
            the display style from the drop-down list.
               o Plain (fast): Default. Displays an unadorned
                 listing of Themes. Options (activate,
                 deactivate, etc.) are listed as clickable text.
               o Pro Icons: Displays a listing of Themes adorned
                 with icons. Options (activate, deactivate, etc.)
                 are listed as clickable icons, with a legend at
                 the bottom.
               o Developer: Not currently implemented.
          + View: To limit the types of themese that are
            displayed, select from the drop-down list.
               o All Themes: Default. Shows all themes on the
                 system.
               o Active: Shows only themes that have been
                 activated.
               o Inactive: Shows only themes that have not been
                 activated.
               o Uninitialized: Shows only themes that have not
                 been initialized.
          + Sort by:
               o Name [a-z]: Sort the display in alphabetical
                 order of theme name.
               o Name [z-a]: Sort the display in reverse
                 alphabetical order of theme name.
          + Regenerate: When a theme is added to or deleted from
            the site's theme directory, the system needs to
            'Regenerate' the file structure to recognize the
            change in the theme directory. To force the system to
            regenerate the themes list, CHECK "Regenerate" and
            click "Refresh". Regeneration is necessary only when
            themes have been added to or deleted from the site's
            theme directory.
          + Click "Refresh" to reload panel with new display
            settings.
          + Theme list:
               o Name: The name of the theme as it is displayed
                 to users.
               o Version: The version number of the theme.
               o Reg.ID: Shows the Registered ID of the theme.
                 Each theme is assigned a unique Registered ID.
               o Upgrade: If an upgrade to this theme is
                 available, you are notified in this field. If no
                 upgrade is available, "n/a" is displayed.
               o Info: Shows information about the theme,
                 including creator, description, installation
                 directory, version, and more.
               o Status: Shows the status of the theme.
               o Actions:
                    # Initialize:
                    # Deactivate:
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Site Display Options:
               o Default Theme: From this drop-down list, select
                 the theme to be used as the site's default. A
                 theme will be displayed in this drop-down list
                 only after it has been installed and
                 initialized. Themes are placed into the
                 <xarroot>/themes directory by default.
               o Site Name - Module Name - Page Name: Displays as
                 "Your Site Name :: Themes :: Your Site Slogan"
                 by default.
               o Site Name - Page Name: Displays as "Your Site
                 Name :: Your Site Slogan" by default.
               o Copyright: Defaults to "&copy; Copyright 2003
                 <administrator name>". Change the text as
                 necessary.
               o Footer note: The 'footer' is displayed at the
                 bottom (the 'foot') of each and every page on
                 your site. This is an excellent place to give
                 credit, state copyright, or put links that you
                 wish to appear on every page of the site.
          + Page Title Options
               o Module Name - Page Name - Site Name: Displays as
                 "Themes :: Your Site Slogan :: Your Site Name"
               o Page Name - Module Name - Site Name: Displays as
                 "Your Site Slogan :: Themes :: Your Site Name"
               o Theme Driven: The page title order is determined
                 by the theme's configuration.
          + Page Title Options
               o Page Title Separator:
               o Page Title Order: Determines how the page title
                 is displayed. The results of the display options
                 are:
                    # Site Name - Module Name - Page Name:
                      Displays as "Your Site Name :: Themes ::
                      Your Site Slogan"
                    # Site Name - Page Name: Displays as "Your
                      Site Name :: Your Site Slogan"
                    # Module Name - Page Name - Site Name:
                      Displays as "Themes :: Your Site Slogan ::
                      Your Site Name"
                    # Page Name - Module Name - Site Name:
                      Displays as "Your Site Slogan :: Themes ::
                      Your Site Name"
                    # Theme Driven: The page title order is
                      determined by the theme's configuration.
          + Template Debugging Options
               o Show template filenames in HTML comments:
               o Click "Submit" to save changes.
     * Certified Releases:
     _________________________________________________________

5.2. Xaraya Blocks Module
     _________________________________________________________

5.2.1. Blocks Module

   Blocks Module: Administration of block instances and groups.
   Admin->Blocks.

   Within Xaraya, Blocks act as building blocks to construct your
   site. Blocks are provided by the core Xaraya engine, or
   virtually 'bolted on' by modules. Core Xaraya blocks provide
   basic system functionality such as menus, while modules
   provide enhanced functionality or additional features. Using
   Blocks, the Administrator can customize the look of the site
   by adding, removing, or changing the position of Blocks.

   Go to Admin->Blocks and use the sub-functions to add, edit,
   view, or delete Blocks from your website. The Blocks display
   is sorted by Group.

     * View Types: This panel displays every block type that is
       available on your site. View Instances (below) displays
       block types that you're currently using on your site.
          + Module: Click the name of the module to go to its
            Administration panel.
          + Type: The types of blocks provided by a particular
            module. See Add Instance, below, for a listing &
            description of the block types included with a
            default Xaraya installation.
     * View Instances: This panel displays block types that are
       currently in use on your site. View Types (above) displays
       every block type that is available for use on your site.
          + Group: The Block Group to which the block instance is
            assigned. To edit Block Groups (including the
            ordering of block instances within a Group), click
            the Group name. For example, to edit the "center"
            group, click "center".

            Note

   Block Groups are Theme dependant. The Block Groups listed
   below are based on the Xaraya_Classic theme.
               o Left: The new block instance is displayed on the
                 left side of the site.
               o Right: The new block instance is displayed on
                 the right side of the site.
               o Header: The header group gets put inside the
                 <head></head> in the template. This is useful,
                 for example, to place JavaScript or other
                 miscellaneous features on the site.
               o Syndicate:
               o Admin: The new block instance is displayed in
                 the admin panel of the site. Items in this panel
                 are available only to site administrators.
               o Center: The new block instance is displayed in
                 the center panel of the site.
               o Topnav: The new block instance is displayed in
                 the menu navigation at the top of a site.
          + Title: The title for the block instance. Alphanumeric
            text, maximum of 256 characters.
          + Type: The type of the block instance. To view a
            listing of all available block types, click any block
            type or click Admin->Blocks->View Types.
          + Template: You can define custom display templates for
            each Block. To tell Xaraya to use a different
            template for a Block, enter the name of the template
            file in this field. Enter the filename without the
            ".xt" extension. To use the default page template,
            leave this field blank. See TEMPLATES IN XARAYA for a
            thorough discussion of templates.
          + State: Default state for the block instance.
               o Hidden: The block instance is not displayed.
                 Setting a block instance's state to "Hidden"
                 makes the block instance inactive.
               o Minimized: Not all block instances support the
                 Minimized state. The block instance is presented
                 minimized. If the site visitor wishes to display
                 the block instance, it can be maximized.
               o Maximized: Default. The new block instance is
                 fully displayed.
          + Operations: These functions permit editing or
            deleting of block instances.
               o Edit:
                    # Title: Edit the title for the block
                      instance in this field. Alphanumeric text,
                      maximum of 256 characters.
                    # Type: Displays the type of the block
                      instance.
                    # Group: Modify the placement of the block
                      instance by selecting the group from this
                      drop-down list. The block instance will be
                      displayed in this group.
                         @ Click "Update" to save changes.
                    # Template (optional): Type the filename of
                      the template to be used when displaying
                      this block instance. The file must exist in
                      one of two places:
                         @ Module-dependant: Module-dependant
                           file must exist in
                           <xarroot>/<module_name>/xartemplates/b
                           locks
                         @ Theme-dependant: Theme-dependant file
                           must exist in:
                           <xarroot>/<themes_dir>/<theme_name>/mo
                           dules/<module_name>.
                              - Theme dependant templates
                                override module templates in
                                <xarroot>/<themes_dir>/<theme_nam
                                e>/modules/<module_name>
                              - Theme dependant templates
                                override module blocks in
                                <xarroot>/<themes_dir>/<theme_nam
                                e>/modules/<module_name>/blocks
                    # Default state: From this drop-down list,
                      modify the default state for the block
                      instance.
               o Delete: If you wish to delete a block instance,
                 click the "Delete" operation next to the block
                 instance to be deleted. You are asked to confirm
                 your intention to delete on the next page. Press
                 the "Delete" button to delete the block
                 instance.
     * View Groups: Block Groups are Theme dependant.
          + Name: The name of the block group containing member
            block instances.
          + Members: The block instances that are contained in a
            group, in the order they are presented on the site.
          + Template: If a display template is used for the
            group, the name of the template is listed, otherwise
            this field is blank.
          + Operations: These functions permit editing or
            deleting of block groups.
               o Edit:
                    # Name: Edit the group name in this field.
                    # Members: Change the order of presentation
                      of member block instances by left-clicking
                      on the block instance to be moved and
                      clicking on the UP or DOWN arrows to move
                      the block instance up or down.
                    # Template: You can define custom display
                      templates for each Block Group. To tell
                      Xaraya to use a different template for a
                      Blockl Group, enter the name of the
                      template file in this field. Enter the
                      filename without the ".xt" extension. To
                      use the default page template, leave this
                      field blank. See TEMPLATES IN XARAYA for a
                      thorough discussion of templates.
                    # Click "Update" to save changes.
               o Delete: If you wish to delete a block group,
                 click the "Delete" operation next to the block
                 group to be deleted. You are asked to confirm
                 your intention to delete on the next page. Press
                 the "Delete" button to delete the block group.
                 OTTO: What happens to Block Instances in a Group
                 if the Group is deleted?
     * Add Instance: Click Add Instance to begin adding a new
       block instance to your site. Adding a block instance is a
       two-step process. First, complete the fields below in the
       following panel. Click "Create Instance" to add the new
       block instance. Secondly, in the new panel that appears,
       configure block-specific options.
          + Title: Enter the title for the block instance in this
            field. Alphanumeric text, maximum of 256 characters.
            The Title is not always displayed to site visitors;
            sometimes a block instance overrides this Title field
            and displays its own block title. However, Title text
            is displayed in Admin->Blocks->View Instances.
          + Type: From this drop-down list, select the block type
            you wish to add. The contents of this drop-down list
            will vary based on the modules that are active in
            your Xaraya installation. View a listing of available
            block types by going to Admin->Blocks->View Types.

   Note

   The following sub-items are common across all block types.
   These items are not repeated in the listing & description of
   each block type, below.
               o Title: The title of the block instance.
               o Type: Selected when a new block instance is
                 added, this indicates the block type.
               o Group: The group to which the new block instance
                 will be added. See the description of Groups,
                 above.
               o Template (optional): Type the filename of the
                 template to be used when displaying this block
                 instance. The file must exist in one of two
                 places:
                    # Module-dependant: Module-dependant file
                      must exist in
                      <xarroot>/<module_name>/xartemplates/blocks
                    # Theme-dependant: Theme-dependant file must
                      exist in:
                      <xarroot>/<themes_dir>/<theme_name>/modules
                      /<module_name>.
                         @ Theme dependant templates override
                           module templates in
                           <xarroot>/<themes_dir>/<theme_name>/mo
                           dules/<module_name>
                         @ Theme dependant templates override
                           module blocks in
                           <xarroot>/<themes_dir>/<theme_name>/mo
                           dules/<module_name>/blocks
               o Default state: The default state for the block
                 instance.
               o Group: From this drop-down list, select the
                 grouping to which the new block instance will be
                 added. See the description of Groups, above.
               o Template (optional): Type the filename of the
                 template to be used when displaying this block
                 instance. The file must exist in one of two
                 places:
                    # Module-dependant: Module-dependant file
                      must exist in
                      <xarroot>/<module_name>/xartemplates/blocks
                    # Theme-dependant: Theme-dependant file must
                      exist in:
                      <xarroot>/<themes_dir>/<theme_name>/modules
                      /<module_name>.
                         @ Theme dependant templates override
                           module templates in
                           <xarroot>/<themes_dir>/<theme_name>/mo
                           dules/<module_name>
                         @ Theme dependant templates override
                           module blocks in
                           <xarroot>/<themes_dir>/<theme_name>/mo
                           dules/<module_name>/blocks
               o Default state: From this drop-down list, select
                 the default state for the new block instance.
               o Click "Create Instance" to save changes.
     * Add Group: Block Groups are Theme dependant.
          + Name: Enter the name for the new Block Group in this
            field.
          + Default template (optional): Type the filename of the
            template to be used when displaying this block
            instance. The file must exist in one of two places:
               o Module-dependant: Module-dependant file must
                 exist in
                 <xarroot>/<module_name>/xartemplates/blocks
               o Theme-dependant: Theme-dependant file must exist
                 in:
                 <xarroot>/<themes_dir>/<theme_name>/modules/<mod
                 ule_name>.
                    # Theme dependant templates override module
                      templates in
                      <xarroot>/<themes_dir>/<theme_name>/modules
                      /<module_name>
                    # Theme dependant templates override module
                      blocks in
                      <xarroot>/<themes_dir>/<theme_name>/modules
                      /<module_name>/blocks
          + Click "Create Group" to save changes.

   Below is a listing of the available block types that are
   available for use in Admin->Blocks->Add Instance within the
   default Xaraya installation.
     _________________________________________________________

5.2.1.1. adminpanels/adminmenu

   Block instance containing the Administration menu. The
   Administration menu is displayed only to users with
   Administrative privileges.
     _________________________________________________________

5.2.1.2. adminpanels/waitingcontent

   OTTO
     _________________________________________________________

5.2.1.3. articles/featureditems

   Block instance that displays featured articles on the site.
   The site administrator defines the articles to feature.

     * Articles Filter: The articles filter section of this panel
       allows the site administrator to filter the available
       articles on the site to simplify the task of finding the
       desired article.
          + Publication Type: From this drop-down list, select
            the Publication Type under which the featured article
            is published, or select "All" to deactivate this
            filter.
          + Category: From this drop-down list, select the
            Category in which the featured article is published,
            or select "All" to deactivate this filter.
          + Status: From this drop-down list, select the status
            of the featured article, or select "All Published" to
            deactivate this filter.
          + Limit: Enter the number of articles you wish to see
            in the Featured Article drop-down list & Alternate
            Title box. For example, to return 25 articles, enter
            "25" into this box.
          + Click "Update" to filter articles.
     * Featured Article: From this drop-down list, select the
       specific article to be featured.
     * Alternate Title: If you would like to display an alternate
       title for the featured article, enter the alternate title
       in this field and the alternate title is displayed instead
       of the article title in the block instance. If this field
       is empty, the article's title will be displayed.
     * Show Summary: If you would like to display a summary of
       the article (usually the Introduction block of the
       article), CHECK this box. The article title (or Alternate
       Title) is displayed followed by a summary. UNCHECK this
       box and only the article title (or Alternate Title) is
       displayed.
     * Additional Headlines: To select additional featured
       headlines, select the headline(s) from this box.
          + Select a single headline by left-clicking on it.
          + Select a range of headlines by left-clicking on the
            first headline in the range, holding down the SHIFT
            key, and left-clicking on the last headline in the
            range.
          + Select individual headlines by holding the CTRL key
            while left-clicking on the individual headlines to
            add.
     * Sort by: This sort option defines the way items are
       displayed on this panel.
          + Hit Count: Sort by the number of times an article has
            been viewed. Articles with more hits are displayed
            before articles with fewer hits.
          + Rating: Sort by the rating of an article. Articles
            with higher ratings are displayed before articles
            with lower ratings.
          + Date: Sort by the date of an article. Newer articles
            are displayed before older articles.
     * Show sort value: Displays the value of the "Sort by"
       parameter (above). For example, if "Sort by" is set to
       "Hit Count" and this field is CHECKED, the number of hits
       for an article is displayed after the article title in the
       block instance. If you do not want the sort value (hits,
       in this example) displayed, UNCHECK this field. Likewise,
       if "Sort by" is set to "Date" and this field is CHECKED,
       the publication date of an article is displayed after the
       article title in the block instance.
     * Show summary: If CHECKED, article titles are displayed
       with summaries. If UNCHECKED, article titles are displayed
       without summaries.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.4. articles/related

   Block instance that displays articles that are related (same
   category, same author) to the current article being displayed.
   This block instance functions only when an article is being
   displayed; it is not useful on the front page of a site.

     * Number of items: Enter the number of related items to be
       displayed in this field. For example, to display 5 related
       items, enter "5" here.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.5. articles/topitems

   Block instance containing the top items for a particular
   Publication Type (or for the currently-displayed Publication
   Type) based on administrator-defined criteria.

     * Number of items: Enter the number of items to be displayed
       in this field. For example, enter "5" to display the top 5
       items.
     * Publication Type: From this drop-down list, select the
       Publication Type for which the top items are displayed.
       Select "Default / Current" from the drop-down list to
       display the top items for whatever Publication Type the
       user is currently viewing. For example, if this field is
       set to "Default / Current" and the user is viewing the
       'Documents' Publication Type, Xaraya will display the top
       items in 'Documents'. If the user then switches to the
       'Reviews' Publication Type, Xaraya will display the top
       items in 'Reviews'.
     * Sort by: From this drop-down list, select the sort
       criteria that will be used to select articles for display
       in this block instance.
          + Hit Count: Sort by the number of times an article has
            been viewed. Articles with more hits are displayed
            before articles with fewer hits.
          + Rating: Sort by the rating of an article. Articles
            with higher ratings are displayed before articles
            with lower ratings.
          + Date: Sort by the date of an article. Newer articles
            are displayed before older articles.
     * Show sort value: Displays the value of the "Sort by"
       parameter (above). For example, if "Sort by" is set to
       "Hit Count" and this field is CHECKED, the number of hits
       for an article is displayed after the article title in the
       block instance. If you do not want the sort value (hits,
       in this example) displayed, UNCHECK this field. Likewise,
       if "Sort by" is set to "Date" and this field is CHECKED,
       the publication date of an article is displayed after the
       article title in the block instance.
     * Show summary: If CHECKED, article titles are displayed
       with summaries. If UNCHECKED, article titles are displayed
       without summaries.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.6. base/finclude

   Block instance that includes a file from the website.

     * File: OTTO -- where is the file location?
     _________________________________________________________

5.2.1.7. base/html

   Block instance that displays HTML-formatted code. Permitted
   HTML codes are defined in Admin->HTML.

     * Block Expiration: From this drop-down list, select the
       expiration date for this block instance.
          + Unlimited: This block instance does not expire, and
            will always be displayed.
          + 1, 2, 5, 15, 30 Days: Select the number of days that
            this block instance will be displayed. When the block
            expires, it is not displayed anymore.
     * HTML: Enter the HTML-formatted content in this block.
       Permitted HTML codes are defined in Admin->HTML.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.8. base/menu

   Block instance that creates a new menu for the site. Menu
   items can be modules that exist on the site, URLs to other
   on-site resources, or complete URLs to off-site resources.

     * Display modules: CHECK this option to display all active
       modules that are installed in <xarroot>/modules.
     * Marker: In this field, define the marker to be displayed
       next to the active menu item. Leave this field blank to
       disable display of a marker.
     * Menu Content:
          + Title: Enter the title of the menu item. The title is
            displayed to users.
          + URL: Enter the URL to the resource. If the resource
            is on your site, you may enter the path to & filename
            of the resource. If the file is external to your
            site, be sure to enter a complete URL, including
            "http://". If the resource is a module, enter the
            case-sensitive module name in brackets ("[" and "]").
            For example, to add the Polls module, type "[Polls]"
            in the URL field.
          + Description (optional): Enter an optional description
            of the menu item in this field. The description is
            presented as a mouse-over (if supported by the user's
            browser).
          + Delete: CHECK this box to delete a menu item.

            Note

   No confirmation is requested before the menu item is deleted.
          + Child: CHECK this box to make the item a child of the
            item above it.
          + Insert blank after: To insert a blank menu line,
            CHECK this box on the line with the menu item after
            which you would like to insert a new line.
          + Click "Update" to save changes.
     _________________________________________________________

5.2.1.9. base/php

   Block instance that executes a PHP script within the site.
   Meant to include small blocks of PHP code, like a Stock Ticker
   from http://www.hotscripts.com or similar.
     _________________________________________________________

5.2.1.10. base/text

   Block instance that displays the text contents of the Content
   field.

     * Block Expiration: From this drop-down list, select the
       expiration date for this block instance.
          + Unlimited: This block instance does not expire, and
            will always be displayed.
          + 1, 2, 5, 15, 30 Days: Select the number of days that
            this block instance will be displayed. When the block
            expires, it is no longer displayed.
     * Text: Enter the text content in this block. This text will
       be displayed to site visitors.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.11. categories/navigation

   Block instance that displays a listing of site categories as
   defined in Admin->Categories.

     * Category Layout:
          + Tree (side block): Displays a vertical 'tree'
            structure of the site's categories; most useful along
            the side of a page.
          + Crumbtrail (top block): Displays a 'crumb trail'-type
            horizontal structure of the site's categories; most
            useful at the top of a page.
          + Prev/Next (bottom block): Displays previous- and
            next-type links; most useful at the bottom of a page.
     * Show count per category: If you would like to display the
       number of items per category, CHECK this box. If you do
       not want to display the number of items per category,
       UNCHECK this box.
     * Show children:
          + None: Show no children.
          + Direct children only:
          + All children: Show all children.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.12. ephemerids/ephem

   Block instance that displays an ephemerid for today, if the
   Ephemerids module is active and if an entry exists for today.
   No additional configuration options.
     _________________________________________________________

5.2.1.13. example/first

   OTTO
     _________________________________________________________

5.2.1.14. example/others

   OTTO
     _________________________________________________________

5.2.1.15. headlines/rss

   Block instance that displays an admin-selected RSS feed, if
   the Headlines module is active and has RSS feeds configured.

     * RSS File URL: From this drop-down list, select the RSS
       feed to display in this block instance. See
       Admin->Headlines->Add to add an RSS feed to your site for
       syndication.
     * Display article descriptions: If this box is CHECKED and
       supported by the feed, short article descriptions are be
       displayed below the syndicated article titles. If
       UNCHECKED, only article titles are displayed.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.16. messages/newmessages

   If the Messages module is active, this block instance displays
   notification of waiting private messages. If new private
   messages are waiting, a count of total and unread private
   messages is displayed with a link to read new private
   messages. If no new messages are waiting, "No Unread messages
   in mailbox" is displayed. No additional configuration options.
     _________________________________________________________

5.2.1.17. polls/poll

   Block instance that displays a site Poll.

     * Poll to display: From this drop-down list, select the poll
       you wish to be displayed in this block instance, or select
       "Latest Poll" to select the most recently-added poll.
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.18. quotes/daily

   Block instance that displays a random quote from the site's
   quote database, if the Quotes module is active. No additional
   configuration options.
     _________________________________________________________

5.2.1.19. roles/language

   OTTO
     _________________________________________________________

5.2.1.20. roles/login

   Block instance that displays the site login block. No
   additional configuration options.
     _________________________________________________________

5.2.1.21. roles/online

   Block instance that displays a count of users & guests who are
   currently visiting the site. No additional configuration
   options.
     _________________________________________________________

5.2.1.22. roles/user

   OTTO -- description. No additional configuration options.
     _________________________________________________________

5.2.1.23. search/search

   Block instance that displays a Search box on the site. No
   additional configuration options.
     _________________________________________________________

5.2.1.24. smilies/smiley

   Block instance that displays a random smiley icon and the
   ASCII text needed to generate the smiley within site content.
   No additional configuration options.
     _________________________________________________________

5.2.1.25. themes/meta

   Block instance that defines metadata for your site.
   Information in this block instance is not displayed to users.
   This block type is generally assigned to a "header" block
   group.

     * Meta description: Enter a description of your site in this
       field. The contents of this field are sent as a metadata
       "Description" for the site.
     * Meta keywords: One of the challenges when running a web
       site is letting external search engines know that your
       site exists. Meta keywords categorize your site. Many
       search engines send out robots (also called 'spiders') to
       search the Web for content. When you define Meta Keywords
       for your site though this configuration option, you make
       it easier for the search-engine robots to categorize your
       site, and your site will be categorized more appropriately
       since you are defining the options. Enter words & phrases,
       separated by commas, that describe the focus of your web
       site. Capitalization is not important in this field. Many
       search engines limit the number of keywords that you can
       use. Therefore, you should choose your words carefully and
       use no more than 10-15 keywords that best describe your
       site's content.
       If your site is all about rock and roll music, for
       example, you might enter the following information in this
       field: "music, rock, roll, beatles, aerosmith, guitar,
       drum, bass, sing, singer, singing"
       For additional information on Meta Keywords, please visit
       Web Developer-META Tag Resources
       (http://www.webdeveloper.com/html/html_metatag_res.html)
       or The META Tag Builder
       (http://vancouver-webpages.com/META).
     * Use GeoURL (http://www.geourl.org): GeoURL is a
       location-to-URL reverse directory. This will allow you to
       find URLs by their proximity to a given location. Find
       your neighbor's blog, perhaps, or the web page of the
       restaurants near you. GeoURL's page provides tools for
       determining your location's latitude and longitude.
          + Your Longitude: In this field, enter your longitude
            in the format "W 84.520407".
          + Your Latitude: In this field, enter your latitude in
            the format "N 39.283899".
     * Use Dynamic Keywords: In addition to defining your own
       keywords for your site (in Meta keywords, above), you can
       choose to have meta keywords generated dynamically. When
       this option is CHECKED, meta keywords are generated
       dynamically whenever the full text of an article is
       displayed. All the words in the article are used as meta
       keywords. CHECKING this function has a small performance
       cost.
     * Copyright page: OTTO
     * Help page: OTTO
     * Glossary: OTTO
     * Click "Update" to save changes.
     _________________________________________________________

5.2.1.26. themes/syndicate

   No additional configuration options.
     _________________________________________________________

5.2.1.27. EXAMPLE: Adding, modifying, and deleting block instances

   Within this example, we explore methods for adding, modifying,
   and deleting block instances.

     * Adding block instances
       For these examples, we'll add a few block instances to
       work with. Following the instructions in
       Admin->Blocks->Add Instance (above), add the following
       three blocks:
          + Block 1:
               o Title: Base HTML Block 1
               o Type: Base \ HTML
               o Group: Center
               o Leave the other items set at their default.
               o Click "Create Instance" to save changes.
               o In the HTML field that appears in the next
                 panel, type:
                 "<b>This is BASE HTML BLOCK # 1.</b>" (no
                 quotes)
               o Click "Update" to save changes.
          + Block 2:
               o Do the same steps as with Block #1, substituting
                 "Base HTML Block 2" for the title and "<b>This
                 is BASE HTML BLOCK # 2.</b>" for the HTML field.
          + Block 3:
               o Do the same steps as with Block #1, substituting
                 "Base HTML Block 3" for the title and "<b>This
                 is BASE HTML BLOCK # 3.</b>" for the HTML field.
       If you go to the front page of the site (click the Xaraya
       logo in the top left corner of the default theme), you'll
       see these three blocks displayed in ascending numerical
       order.
     * Modifying block instances
       If you wish to modify a block instance, go to
       Admin->Blocks->View Instances. Click "Edit" on the line
       next to the block instance you wish to modify. On the next
       panel, make your changes and click the "Update" button to
       save changes.
          + For our example, edit Block #2's title to read "The
            Second Base HTML Block" and the HTML to read "Here's
            the <i>second</i> HTML block". Be sure to "Update" to
            save your changes.
     * Deleting block instances
       To delete a block instance, go to Admin->Blocks->View
       Instances. Click "Delete" on the line next to the block
       instance you wish to delete. On the next panel, confirm
       your intention to delete.
     _________________________________________________________

5.2.1.28. EXAMPLE: Changing the order of blocks within Groups

   Follow this example, using the three blocks we added in
   "Adding block instances", above, to learn how to change the
   order of block instances within Groups.

     * If you don't have the three sample block instances from
       "Adding block instances", above, create them now.
     * Go to Admin->Blocks->View Groups. Click "Edit" on the line
       next to the block group you wish to modify. In this
       example, click "Edit" on the line next to the "Center"
       block group. On the next panel, modify the order of block
       instances. Left-click on an instance to select it, then
       use the UP and DOWN arrow icons to change the placement of
       the selected block instance in the block group. Click the
       "Update" button to save changes.
          + For our example, move the block instances we created
            into the following orders, saving changes between
            each:
               o 3, 2, 1
               o 1, 3, 2
               o 2, 1, 3
     * When you have finished this example, delete the three
       block instances. Follow instructions in 'Deleting block
       instances', above.
     _________________________________________________________

5.2.1.29. EXAMPLE: Manipulating Block Groups

   OTTO

     * Adding a Block Group
     * Modifying a Block Group
     * Deleting a Block Group
     _________________________________________________________

5.3. Xaraya Adminpanels Module

5.3.1. Adminpanels Module

   Core Module, Displays the Administration menu block.
   Admin->Adminpanels.

   The Adminpanels module configures how the Administration menu
   block is displayed to the site administrators.

     * Modify config:
       This panel allows modification of configuration options
       for this module.
          + Configure Adminmenu
               o Always on top: Sets position of administration
                 menu in block group. If CHECKED, the
                 Administration menu is always at the top of the
                 block group in which it is placed. If UNCHECKED,
                 the Administration menu's position is determined
                 by its order in Admin->Blocks->View Instances.
               o Mark active item: CHECK if you would like a
                 marker displayed next to the active menu item.
                 UNCHECK if you do not wish to have a marker
                 displayed next to the active menu item.
               o Specify marker: Specify the marker to be used if
                 "Mark active item" (above) is CHECKED. Default
                 is "[x]".
                 AN EASTER EGG: What version of Xaraya was first
                 the PUBlic release? Type your answer in this
                 field. If your answer is right, as site
                 administrator, you may catch sight of the
                 elusive 'red manta'. This Easter egg exists in
                 versions .906 and later.
               o Sort admin menu items:
                    # By Name: Displays the Administration menu
                      sorted alphabetically.
                    # By Category: The Administration menu is
                      displayed by category (Content, Global,
                      Users & Groups, Miscellaneous, etc.).
                    # By Weight: Not currently implemented.
                    # By Group: Not currently implemented.
               o Sort order "By Weight" configuration: Not
                 currently implemented.
               o Sort order "By Group" configuration: Not
                 currently implemented.
               o Groups configuration: Not currently implemented.
                    # Add: Not currently implemented.
                    # Delete: Not currently implemented.
                    # Modify: Not currently implemented.
               o Position admin menu: The Administration menu can
                 be displayed in the center or on the left or
                 right side of the page. Select the placement of
                 the Administration by selecting from the
                 drop-down list.
                    # Left: Display the Administration menu on
                      the left side of the screen.
                    # Center: Display the Administration menu in
                      the center of the screen. Not currently
                      implemented.
                    # Right: Display the Administration menu on
                      the right side of the screen.
               o Display "Help" link: Not currently implemented.
               o Click "Submit" to save changes.
          + Configure Overviews
               o Disable Module Overviews: By default, Xaraya
                 displays an overview panel when you click on any
                 module in the Administration menu. This overview
                 panel contains useful information about the
                 module, but after you've read it several times,
                 you may wish to turn it off. CHECK this box to
                 skip the module overview. UNCHECK the box to
                 display module overviews.
               o Click "Submit" to save changes.
     _________________________________________________________

5.4. Xaraya Cache System
     _________________________________________________________

5.4.1. Blocklayout Template Caching

   This will describe the template caching built into
   Blocklayout.
     _________________________________________________________

5.4.2. XarCacheManager Module

   This will describe the optional xarcachemanager module.
     _________________________________________________________

Chapter 6. Categories in Xaraya

   Articles are placed into Publication Types which can contain
   Categories. Categories are an easy way to provide hierarchical
   categorization for all information on your site. You could use
   one or more common Categories across different Publication
   Types, or use specific Categories for each type of article, or
   any combination that you prefer for your site.

   Before specifying which Publication Types will be using what
   Categories, create the categorization you want via the
   Categories Administration Menu. To get you started, a default
   set of categories was defined for articles when Xaraya was
   installed. You can adapt the existing categories to your
   specific needs, of course, or remove them altogether.

   Once you have a set of categories you would like to use for
   your articles, go to Admin->Articles->Modify config, and
   specify the number of categories that can be used for each
   Publication Type, and select the 'base categories' to be used.

   A 'base category' is any starting point somewhere in your tree
   of categories, below which you will have the actual list (or
   sub-tree) of categories people can choose from when they
   submit or view articles.

   For example, you could have a 'base category' called Topics,
   with a list of different topics relevant to your site below
   it, and another 'base category' called Cities, with a list of
   cities or places for which you would provide regional news.
   One topic might be 'Good Restaurants', and one category might
   'Brussels', so people would be able to browse through any
   articles about good restaurants in Brussels, for instance.
     _________________________________________________________

6.1. Editing and Creating Categories

   In this section, we explore how to edit pre-configured
   categories and create new categories. Categories are displayed
   to the site administrator in a "category tree", a listing that
   shows categories and sub-categories in an easy-to-understand
   format.

   Admin->Categories->Modify config:

     * If you wish to display categories in a Windows
       Explorer-like tree view, click "Yes". Displaying
       categories in this way requires a JavaScript-enabled
       browser. If you use this display method, the icons in
       Admin->Categories->View Categories have the following
       meaning:
          + The "+" icon to the left of the category name &
            description expands or collapses the tree for the
            category.
          + The "X" icon to the right of the category name &
            description deletes the category and any
            sub-categories under it. If you wish to delete the
            category and any sub-categories, click "Yes" on the
            confirmation screen.
          + The "pencil" icon to the right of the "X" icon allows
            modification of category properties.
     * Click "Submit" to save changes.
       Figure 6-1. Windows Explorer-like tree
       [categoriestree.jpg]

   Admin->Categories->View Categories:

   This panel displays all the Categories that are pre-configured
   by the Xaraya Base installation. Let's edit an existing
   category, and then add a few new categories from scratch.
     _________________________________________________________

6.1.1. Editing an existing Category

   To edit an existing category, click on the "Modify" link on
   the same line as the Name of the category you wish to edit.
   For this example, click "Modify" on the "Topics" line. This
   edits the top-level category called "Topics".

     * Name: The name of the category. For this example, change
       it to "Topics of Interest".
     * Description: A description of the category that is
       displayed to users. For this example, change it to
       "Interesting topics on this website.".

   The next two options determine the position of the new/edited
   category in the category tree, and specifies if the category
   is a top-level category or a sub-category.

     * In relation to this category: Select an existing category
       from the drop-down list. This existing category serves as
       the reference point for the Position function, below. For
       this example, since we don't want to move this category,
       just leave this field as it is.
     * Position: Determines the placement of the new/edited
       category in conjunction with the "In relation to this
       category" field above. For this example, since we don't
       want to move this category, just leave this field as it
       is.
          + Right before, in the same level: If you want the
            new/edited category to be placed ABOVE the category
            specified in "In relation to this category" and be on
            the same level (for example, if the category selected
            in "In relation to this category" is a top-level
            category, this new/edited category will also be
            top-level), select this option.
          + Right after, in the same level: If you want the
            new/edited category to be placed BELOW the category
            specified in "In relation to this category" and be on
            the same level (for example, if the category selected
            in "In relation to this category" is a top-level
            category, this new/edited category will also be
            top-level), select this option.
          + The first child category: If you want the new/edited
            category to be placed ABOVE the category specified in
            "In relation to this category" and to be a child
            category of the category referenced in "In relation
            to this category", select this option.
          + The last child category: If you want the new/edited
            category to be placed BELOW the category specified in
            "In relation to this category" and to be a child
            category of the category referenced in "In relation
            to this category", select this option.
     * Optional image: From this drop-down list, select the image
       associated with this category. The image format can be any
       popular image file format (JPG, GIF, PNG, etc) and must
       exist in one of two directories:
          + "<xarroot>/modules/categories/xarimages" or
          + "<xarroot>/themes/<theme_name>/modules/categories/ima
            ges" for theme-dependent versions
     * Click "Modify" to save changes.
     _________________________________________________________

6.1.2. Adding a new Category

   To add a new Category, click Admin->Categories->Add Category.
   Complete the fields on the next panel, and click "Add" to
   create the new category. If you are adding a large number of
   categories at one time, you can do so in a batch. Enter the
   number of categories you'd like to create in the "Create in a
   Batch" field and click "Reassign". This will refresh the panel
   with the specified number of category slots. Complete the
   fields and click "Add" to batch-create the categories.
     _________________________________________________________

6.1.2.1. EXAMPLE: Add your own Categories

   For this example, using the methods detailed above (editing or
   adding categories as necessary), create the following
   categories under "Topics of Interest" (to create this
   category, see "Editing an Existing Category", above): News,
   Announcements, System Information, Xaraya, and Internet. Enter
   any text in the Description field. Also, put these new
   categories in alphabetical order under "Topics of Interest"
   either by manipulating the placement using the available
   category positioning tools or by creating them in alphabetical
   order.
     _________________________________________________________

6.2. Categories Conclusion

   Once you have defined your site's Categories, they can be
   assigned to one or more Publication Types. We'll learn how to
   assign Categories to Publication Types, and what that means,
   later in this Guide. First, though, let's look at the modules
   of Xaraya.
     _________________________________________________________

Chapter 7. Modules in Xaraya

   Xaraya allows items to be virtually 'bolted on' to its engine.
   These items, called "modules", add features or functionality
   to Xaraya. Because it is important to understand how modules
   function within Xaraya, in this section we explain how any
   Xaraya module can be installed, configured, deactivated,
   upgraded, and completely removed (deleted!). Any of these
   actions may be taken on any non-core Xaraya module. Xaraya's
   Core modules make up the distribution of Xaraya, and can not
   be deactivated, edited, or removed. The Xaraya Base
   distribution comes with a selection of popular modules
   available for use with your site. The Site Administrator may
   choose additional modules to add to the site. Additional
   official modules and third-party modules for Xaraya may be
   downloaded from the official site at http://www.xaraya.com.
     _________________________________________________________

7.1. Xaraya Modules -- A New Approach

   In other Content Management Systems, if, for example, you had
   a Reviews module and a Gallery module, they exist on the site
   as two separate entities that do not communicate with each
   other. If, for example, you wanted a Gallery that allowed
   users to post Reviews, you had to write your own custom module
   to integrate the two pieces, or duplicate the functionality of
   each module in a new custom module.

   Modules in Xaraya are different than modules in any other
   Content Management System because when they are 'bolted on' to
   the Xaraya engine, they can communicate with any other part of
   Xaraya, including other modules. These communication paths are
   easily built using "hooks" within Xaraya -- without coding --
   by the site administrator.

   In our example, within Xaraya, Review functionality could be
   combined with the Gallery without writing any code at all,
   allowing users to post Reviews of items in the Gallery.
   Further in this Guide, we will explore specific examples of
   how to combine the function of modules within Xaraya.

   SPECIAL NOTE: Xaraya doesn't need an external "Gallery"
   module... Using Publication Types, Xaraya can be configured to
   display nearly any kind of data -- without requiring a special
   module to do so. We'll explore this more later in the Guide.

   This section of the Guide shows how to initialize, activate,
   edit, deactivate, upgrade, and completely remove (delete!)
   modules from your Xaraya site.
     _________________________________________________________

7.2. Module Listing: Display & Navigation

   Admin->Modules->View All: This configuration area of Xaraya
   focuses on the modules of your site.

     * Style: Defines the display of the module list.
          + Plain (fast): Default. Displays an unadorned listing
            of Modules. Options (activate, deactivate, hooks,
            etc.) are listed as clickable text.
          + Icons: Displays a listing of Modules adorned with
            icons. Options (activate, deactivate, hooks, etc.)
            are listed as clickable icons.
          + Compact-A: Displays a listing of modules in a
            compact, two-column "over then down" format. The
            action & status list is displayed at the top of the
            screen. The letter indicators are as follows:
               o [I]nstall
               o [U]pgrade
               o [D]eactivate
               o [A]ctivate
               o [R]emove
               o [M]issing
               o [V]iew Info
               o [H]ooks
               o [C]ore Module
          + Compact-B: Displays a listing of modules in a
            compact, two-column "down then over" format. The
            letter indicators are the same as for "Compact-A"
            display style, above.
     * View: Filters the display to modules of a certain type as
       selected from the drop-down list.
          + All modules: Default. Shows all modules on the
            system.
          + All Installed: Shows only modules that have been
            installed.
          + All Active: Shows only modules that have been
            activated.
          + All Inactive: Shows only modules that have not been
            activated.
          + Not Installed: Shows only modules that have not been
            installed.
          + Missing files: Shows any modules with missing files.
     * Sort by: The sort order for displayed modules.
          + Name [a-z]: Default. Alphabetical ordering of
            modules.
          + Name [z-a]: Reverse alphabetical ordering of modules.
     * Hide: Because we cannot change any Core modules within
       Xaraya, we may choose to hide them from the module list to
       reduce clutter. If the "Hide Core Modules" box is CHECKED,
       Core modules are filtered from the module list and not
       displayed. To hide the Core modules, CHECK "Hide Core
       Modules" and click "Reload". Core modules can be displayed
       by UNCHECKING "Hide Core Modules" and clicking "Reload".
     * Force:
          + Regenerate: When a module is added to or deleted from
            the site's module directory, the system needs to
            'Regenerate' the file structure to recognize the
            change in the module directory. To force the system
            to regenerate the modules list, CHECK "Regenerate"
            and click "Reload". This is necessary only when
            modules have been added to or deleted from the site's
            module directory.
     * Reload: Applies any changes you've made to Style, View,
       Sort by, Hide, or Force and reloads the module listing.
     _________________________________________________________

7.3. Managing Modules

   Below the display & navigation section is the listing of the
   modules on the site. Each module has a variety of information
   displayed next to the name of the module. We explore the
   definition of each piece of information, below.

     * Name: The name of the module. When the module has an
       "Active" status, click the name of the module to go to the
       module's administration screen. If you click the name of
       the module and nothing happens, the module does not have
       an administration screen. The administration screen of
       inactive modules is not available.
     * Version: The version number of the module.
     * Upgrade: If an upgraded version of the module that is
       newer than the installed version is available, this field
       displays notification.
     * Info: Click the "Info" link for information about the
       module, including contact information.
     * Status: Displays the status of the module. Status can be
       one of the following items:
          + Not Installed: The files for this module exist in
            Xaraya's installation, but the module has not been
            installed. Modules that have a status of Not
            Installed cannot be used on the site until they are
            installed.
          + Active: The module has been placed into Xaraya's
            modules directory and has been installed. The module
            is ready for use on the site.
          + Inactive: The module is not available for use on the
            site but the module's database and configuration
            settings have NOT been removed. Click "Activate" to
            make the module available on the site.
          + Missing Files: This module has files missing and will
            likely not function. Remove and reinstall the module
            to correct the problem.
     * Actions:
          + [Core module]: Denotes a core module. Since core
            modules are not configurable, no actions are
            available for this module.
          + Install: Indicates that the module exists in Xaraya's
            module directory but is not yet ready for use. Click
            "Install" to initialize and activate the module,
            which creates any database tables that the module
            needs and prepares the module for use on the site.
          + Deactivate: If you wish to make a module unavailable,
            click "Deactivate". This sets the module to an
            unavailable setting, but does not remove any data or
            database tables.
          + Remove: If you wish to remove the module from your
            site and remove all configuration information and
            database tables associated with the module, click
            "Deactivate" (if necessary) and click "Remove".
            Clicking "Remove" removes all the module's data and
            database tables from the site's database and makes
            the module unavailable to site visitors. The module
            is NOT removed from Xaraya's modules directory.
            Modules must be manually deleted from Xaraya's
            modules directory to completely remove them from the
            site.
          + Activate: If a module has previously been deactivated
            and you wish to re-activate it for use on the site,
            click "Activate".
     _________________________________________________________

7.4. Modules in Xaraya

   In later sections of the Guide, we will explore the individual
   modules that are included with Xaraya. Most modules support
   Dynamic Data. If you have Dynamic Data fields defined for a
   module, you will have additional configuration options beyond
   what is covered in this Guide. There are other modules which
   can provide functionality to extend existing modules. This is
   normally done via hooks, which will be covered next. Not all
   site administrators will use all of these features, so feel
   free to skip around!
     _________________________________________________________

7.5. KNOWLEDGE REVIEW: Manipulating Modules (Adding and Removing
Modules)

   It is easy to add or remove modules at any time after Xaraya
   installation.

     * Adding a new module:
       To add a new module to Xaraya, follow these steps:
         1. Download the new module.
         2. Un-archive the new module into a temporary directory
            (if necessary).
         3. Configure the module (read the module's documentation
            to determine what pre-installation configuration, if
            any, is necessary).
         4. Copy (or upload) the module directory & sub-directory
            from the temporary directory to <xarroot>/modules.
         5. Assign appropriate ownership and permissions (if
            necessary).
         6. As the site administrator, go to Admin->Modules->View
            All. CHECK the Regenerate box at the top right of the
            panel and click the "Reload" button. Xaraya will scan
            the <xarroot>/modules directory and display all
            modules that are available, including the new module.
         7. Click "Install" on the line next to the new module
            you wish to install. The module will be installed.
         8. Perform any post-installation configuration of the
            module (if necessary). If a module has
            post-installation configuration options available,
            you can click on the module name in
            Admin->Modules->View All to go to the module's
            configuration panel. You may also click on the module
            name in the Admin menu on the left of the browser
            window.
     * Removing a module:
       To remove a module from Xaraya, follow these steps:
         1. Identify the module you wish to remove.
         2. As the site administrator, go to Admin->Modules->View
            All.
         3. If the module is active, click "Deactivate" on the
            line with the module to be removed. When a module has
            been deactivated, it is no longer available to users
            but the module data is not removed. If you intend to
            make the module active again in the future but do not
            want the module to be available to users at the
            moment, it is advised to leave the module in a
            deactivated state.
         4. To completely remove the module's data, click
            "Remove". The module's data is removed from the
            database (including configuration settings and stored
            information). Once a module has been "Removed", it is
            necessary to re-install and re-configure the module
            if you intend to use it again.
         5. If you wish to remove the module completely from your
            Xaraya site, delete the module's directory from
            <xarroot>/modules. Consult your webserver's operating
            system documentation for how to accomplish this.
     _________________________________________________________

Chapter 8. Hooks in Xaraya

   An Introduction to Hooks

   Hooks extend the functionality of modules by allowing site
   resources to be re-used in a variety of ways across the site.
   Hooks increase the interoperability and efficiency of Xaraya.
   For example, a site resource is BBCODE (which allows
   bbcode-style formatting to be used in text entry). Rather than
   code BBCODE for articles and re-code it again for comments, we
   can simply "hook" BBCODE functionality into the articles and
   comments modules, as well as any other modules we wish! Xaraya
   provides unparalleled levels of interoperability by truly
   modularizing functions.

   Xaraya provides two different methods to view or edit hooks.

     * Admin->Modules->View All: Click "On/Off" under the Hooks
       heading for the module to view or edit hooks that are
       enabled for the particular module. So, for example, if you
       wanted to view the active hooks for the Articles module,
       click "On/Off" under the Hooks heading for the Articles
       module. You see the modules that are 'hooked' into this
       module, and can add or remove hooks. Be sure to click
       "Save Changes" to save changes.
     * Admin->Modules->Configure Hooks: The simplest way to
       determine the order in which to click items to activate
       hooks is to fill in the blanks of this sentence: "I want
       to enable ____ in ____." So, for example, if you wanted to
       enable comments in articles, you would first click
       comments, then CHECK articles. Be sure to click "Save
       Changes" to save changes.

   These two methods serve the same purpose -- to display hooked
   modules and allow modification of hooks. Work with each of
   them to determine which of the methods suits you best.

     * Admin->Modules->Configure Hooks:
       Using 'hooks' in Xaraya, you can extend the functionality
       of your modules.
       Select the hook module providing the extra functionality
       and then check the box(es) of the module(s) in which you
       would like to enable that functionality (For example,
       select "Comments" and then check "Articles" to enable
       Comments within the Articles module.)
     _________________________________________________________

8.1. KNOWLEDGE REVIEW: Handling Hooks

   OTTO: something here to cover the important points of hooks
   again in an easy to comprehend summarised form
     _________________________________________________________

Chapter 9. Articles in Xaraya

   A Summary of the Articles module needs to go here.
     _________________________________________________________

9.1. Articles Module Overview

   Display articles. Admin->Articles.

   The Articles module is possibly the most often-accessed part
   of a community site, since nearly all of the site's content
   will be placed into Article sub-categories.

     * View Articles
       Click View Articles to view a listing of articles on the
       site by Publication Type. If there are multiple pages of
       articles, navigation links are displayed at the bottom of
       the panel. (The number of articles displayed per page is
       defined in Admin->Articles->Modify config. Click the
       Publication Type and set "Items per page" to the number of
       articles to be displayed. Click "Update Configuration" to
       save changes.)
          + Publication Type: From the listing of available
            Publication Types, click the Publication Type for
            which you would like to display articles. For
            example, to display articles in the Web Links
            Publication Type, click "Web Links".
          + Status: This is a filter that displays articles in
            the selected Publication Type that match one of the
            following options. Following our example above, to
            display Approved articles in the Web Links
            Publication Type, click "Approved".
               o All: Display all articles in the
                 currently-selected Publication Type.
               o Submitted: Display articles in the
                 currently-selected Publication Type that have
                 been submitted for publication.
               o Rejected: Display articles in the
                 currently-selected Publication Type that have
                 been rejected for publication.
               o Approved: Display articles in the
                 currently-selected Publication Type that have
                 been approved for publication.
               o Frontpage: Display articles in the
                 currently-selected Publication Type that have
                 been approved for publication and are displayed
                 on the front page of the module. If this module
                 is the current default starting module (set in
                 Admin->Base->Modify config), then articles with
                 this status will also be displayed on the front
                 page of the site.
               o Browse in: This is a filter that displays
                 articles in the selected Publication Type based
                 on the Category to which the article is
                 assigned. Click the Category next to "Browse in"
                 to display a panel with available Categories.
                 Click a Category to display its articles.
          + New Article: Click New Article to add a new article
            to the site as administrator. In the panel that
            appears, select the Publication Type for the new
            article. Enter the article in the text fields. The
            available text fields may be different between
            Publication Types, but Publication Types will have a
            Categories box at the bottom of the panel. From the
            Categories box, select the Categories to which the
            new article will be assigned. Click "Preview" to
            display the article without saving, and click "Add
            Article" to save changes.
          + List of articles on the site. The bottom of this
            panel displays a listing of articles on the site for
            the currently-selected Publication Type.
               o Title: The title of the article.
               o Publication Date: The article's publication date
                 and time.
               o Status: The status of the article. Status can be
                 "Submitted", "Rejected", "Approved", or
                 "Frontpage". See below for information about
                 these statuses.
               o Checkbox: To change the status of
                 currently-listed articles in a batch, place a
                 CHECK in this box next to each article you wish
                 to add to the batch. From the "Change checked
                 article status to" drop-down list, below, select
                 the status to which the checked articles will be
                 changed. Click "Change Status" to change the
                 status of all checked articles.
               o Options:
                    # View: Click this link to view the article
                      as it is displayed to a user of the site.
                      An "[Edit]" link displayed at the top of
                      the article is shown only to users with
                      appropriate editing privileges.
                    # Edit: Click this link to edit the article.
                      Make changes to the article in the panel
                      and click "Preview" to display the modified
                      article without saving, and click "Update
                      Article" to save changes.
                    # Delete: To delete a specific article, click
                      this link next to the article. Confirm your
                      intention to delete the article on the
                      following panel. If you choose to delete an
                      article, all comments associated with the
                      article are deleted at the same time.
               o Change checked article status to:
                    # Submitted: The article has been submitted
                      to the site, but has not yet been rejected
                      or approved. This article is visible only
                      to the site administrator; it is not
                      visible to users.
                    # Rejected: The article has been submitted to
                      the site, but has not been approved for
                      publication. This article is visible only
                      to the site administrator; it is not
                      visible to users.
                    # Approved: The article has been submitted to
                      the site and has been approved for
                      publication. This article is visible to
                      site visitors and the site administrator.
                      To view this article, navigate to the
                      Publication Type and Category of the
                      article, then click the title of the
                      article to display.
                    # Frontpage: The article has been submitted
                      to the site and has been approved for
                      publication. This article is visible to
                      site visitors and the site administrator.
                      The article is displayed on the front page
                      of the module, and if this module is the
                      default starting module, then it will be on
                      the front page of the site. Articles with
                      this status may also be displayed by
                      navigating to the Publication Type and
                      Category of the article, then clicking the
                      title of the article.
                    # Click "Change Status" to save changes.
     * Add Article
       Click Add Article to add a new article to the site as
       administrator. In the panel that appears, select the
       Publication Type for the new article. Enter the article in
       the text fields. The available text fields may be
       different between Publication Types, but Publication Types
       will have a Categories box at the bottom of the panel.
       From the Categories box, select the Categories to which
       the new article will be assigned. Click "Preview" to
       display the article without saving, and click "Add
       Article" to save changes.
       If you wish to insert a PAGE BREAK in an article, enter
       <!--pagebreak--> in the article text (either the
       Introduction or Body Text) where you'd like the break to
       appear. Xaraya automatically manages the page break.
     * Import Webpages
       If you need to import any existing HTML pages into your
       Xaraya site (for example, if you are converting your site
       from a 'flat' HTML site to a content management system),
       the Import Webpages tool will facilitate the process. Use
       this tool to define existing HTML page(s) to import into
       the Xaraya database structure. The imported pages become
       available as articles in the Publication Type selected
       during import. The Import Webpages tool provides filtering
       and replacement options during import.
          + Base Directory: This is the local directory which is
            recursively searched for pages ending with "HTML" or
            "HTM" (case insensitive). The resulting HTML pages
            are listed in this box. If you change the directory,
            click "Refresh" to reload the listing of available
            files.
          + Available HTML Pages: Highlight the HTML page or
            pages you would like to import in this box. You can
            select multiple individual pages by holding the CTRL
            key down and left-clicking on the desired HTML pages.
            To select a range of pages, left-click the first page
            in the range, hold the SHIFT key down while
            left-clicking the last page in the range. Selected
            pages are highlighted.
          + Publication Type: From this drop-down list, select
            the Publication Type to which the imported HTML page
            will be assigned. Once the Publication Type is
            selected, the panel will refresh, showing additional
            options.
               o Insert Page Title into field: From this
                 drop-down list of fields available in the
                 selected Publication Type, select the field into
                 which the HTML page's title will be inserted.
               o Insert Content into Field: From this drop-down
                 list of fields available in the selected
                 Publication Type, select the field into which
                 the HTML page's content will be inserted.
               o Initial Categories: Select the categories to
                 which the imported article will be assigned. If
                 multiple HTML pages are imported, all will be
                 assigned to the same category.
          + Filter Start of Page: This page indicates material to
            be filtered (removed) from the imported webpage. The
            default regular expression is "#^.*<body[^>]*>#is"
            (no quotes), which removes everything before the HTML
            <body> tag. The original HTML page is not modified.
          + Filer End of Page: The default regular expression is
            "#</body.*$#is" (no quotes), which removes everything
            after the HTML </body> tag. The original HTML page is
            not modified.
          + Find Page Title: The default regular expression is
            "#<title>(.*?)</title>#is" (no quotes), which
            indicates that the page title is between the <title>
            and </title> HTML tags.
          + Replacement Rules: Xaraya will search your source
            HTML page and replace matching search text with
            replacement text. This is useful, for example, if
            you've changed the path to graphic files.
               o Search for: Enter the text to be replaced.
               o Replace with: Enter the text to replace found
                 text.
          + Test Import button: Click this button to perform a
            test import of the HTML page without adding the
            article to the site. Examine the resulting page to
            insure that everything worked as expected.
          + Import Webpages button: When ready to perform the
            import of HTML pages into Xaraya, click this button.
            The HTML pages are imported and the article is added
            to the site. The original HTML pages are not
            modified.
     * Publication Types
       This portion of the panel displays existing Publication
       Types with options to edit or delete.
          + New Publication Type: Click this link to add a new
            Publication Type.
               o New Publication Type
                    # Type: The title of the new Publication
                      Type. This is the "system" name of the
                      Publication Type, and is also the name used
                      when referring to this Publication Type in
                      a Short URL.
                    # Description: A description of the
                      Publication Type. The description is used
                      on the site to denote the Publication Type.
                      The contents of this field are displayed to
                      site visitors.
               o Configuration
                    # Field: The field name for the new
                      Publication Type. This field name is used
                      by themes to denote where pieces of content
                      are displayed within the theme. For
                      example, the field named "title" is
                      displayed through placement of the string
                      "#$title#" within the theme definition.
                    # Label: The label for the new Publication
                      Type. The label serves as a description of
                      the Publication Type, and is displayed to
                      users. Leave the Label field blank if you
                      do not want to use a particular field in
                      your new Publication Type.
                    # Format: From this drop-down list, select
                      the format for the field.
                         @ Static Text:
                         @ Text Box:
                         @ Small Text Area:
                         @ Medium Text Area:
                         @ Large Text Area:
                         @ Username:
                         @ Calendar:
                         @ File Upload:
                         @ Status:
                         @ URL:
                         @ Image:
                         @ HTML Page:
                    # Input: CHECK this box if you would like the
                      field to accept input. If you do not with
                      for the field to accept input, UNCHECK this
                      box.
                    # Type: A reference area displaying the
                      database type for the field.
                    # Click "Create" to save changes.
          + Existing Publication Types
            Existing Publication Types are listed in the bottom
            portion of this panel, with the following information
            & options.
               o Name: The name of the Publication Type.
               o Description: A description of the Publication
                 Type.
               o Options:
                    # Edit:
                    # Delete: To delete a Publication Type, click
                      this link next to the Publication Type to
                      be deleted. Confirm your intention to
                      delete on the next panel. If you delete a
                      Publication Type, all articles contained in
                      the Publication Type are also deleted.
                    # Article Config:
                         @ Global Configuration ('Default'
                           Publication Type only)
                              - Default Publication Type for the
                                Articles "Front Page": From this
                                drop-down list, select the
                                Publication Type to which a
                                "frontpage" alias will be
                                assigned. Generally, "News" is an
                                appropriate Publication Type for
                                this field.
                              - Support Short URLs: This box is
                                the 'master switch' for Short URL
                                support in articles. CHECK this
                                box to enable Short URL support
                                for articles. UNCHECK this box to
                                disable Short URL support for
                                modules. Short URL support may be
                                enabled or disabled for
                                individual Publication Types, so
                                it is possible to have some
                                Publication Types support Short
                                URLs while others do not. In
                                order for Short URL support to
                                function, the 'master switch' for
                                Short URLs must be CHECKED in
                                Admin->Base->Modify config.
                         @ Website Configuration
                              - Use <alias> as alias in Short
                                URLs: CHECK this box to use the
                                Publication Type's type as the
                                Short URL for this Publication
                                Type. The Type is configured when
                                adding a new Publication Type
                                under
                                Admin->Articles->Publication
                                Types. To turn off Short URL
                                support for this specific
                                Publication Type, UNCHECK this
                                box.
                              - Use different page template: You
                                can define custom display
                                templates for each Publication
                                Type. To tell Xaraya to use a
                                different template for a
                                Publication Type, enter the name
                                of the template file in this
                                field. Enter the filename without
                                the ".xt" extension. To use the
                                default page template, leave this
                                field blank. See TEMPLATES IN
                                XARAYA for a thorough discussion
                                of templates.
                         @ Overview Configuration

   Note

   The ($...) indicates the name of the variable used to display
   this feature in site templates. If you wish to enable a
   specific feature to a template, add the name of the variable
   to the template at the location where you want the feature to
   appear.
                              - Default start view: From this
                                drop-down list, select the
                                default behavior of Xaraya when a
                                user clicks on the name of a
                                Publication Type from the user's
                                (not the Administration) main
                                menu.
                                   = Latest items:
                                   = Browse in...: (recommended)
                              - Number of columns ($numcols): The
                                number of columns that will
                                display the data to site
                                visitors. If you would like a
                                traditional, single-column
                                display, enter "1" in this field.
                                If you would like a two-column
                                display, enter "2" in this field,
                                and so on.
                              - Items per page ($number):
                                Determines the maximum number of
                                items to display per page in the
                                overview panel. If you would like
                                to display 25 items per page,
                                enter "25" here. Xaraya provides
                                page navigation links if there
                                are more than this number of
                                items.
                              - Show category links in article
                                summaries ($categories): If
                                CHECKED, category links are
                                displayed in article summaries in
                                the overview panel. If UNCHECKED,
                                category links are not displayed
                                in article summaries.
                              - Show previous/next category
                                ($showprevnext): If CHECKED,
                                previous/next category links are
                                displayed on the overview, which
                                allow a site visitor to move more
                                easily between categories. If
                                UNCHECKED, previous/next category
                                links are not displayed.
                              - Show number of comments
                                ($comments): If CHECKED, the
                                number of comments associated
                                with the article are displayed in
                                the overview panel. If UNCHECKED,
                                the number of comments are not
                                displayed.
                              - Show hit counts ($counter): If
                                CHECKED, the number of hits
                                received by the article are
                                displayed in the overview panel.
                                If UNCHECKED, the article's hits
                                are not displayed.
                              - Show ratings ($rating): If
                                CHECKED, article ratings are
                                displayed on the article overview
                                panel. If UNCHECKED, article
                                ratings are not displayed.
                              - Show links to Publication Types
                                ($showpublinks +
                                includes/publinks.xd): If
                                CHECKED, a link-bar is displayed
                                near the top of the center panel
                                of the site that displays quick
                                links to Publication Types and,
                                in parenthesis, the number of
                                articles within the Publication
                                Type, for example:
                                News Articles (403) - Documents
                                (28) - FAQs (16) - Web Links
                                (310)
                                If UNCHECKED, the links are not
                                displayed.
                              - Show link to archives
                                ($archivelink + $archivelabel):
                                If CHECKED, a link to the site's
                                archives is displayed in the
                                overview. In the default Xaraya
                                theme, this link is at the bottom
                                of the page. The Archives show a
                                listing of the stories published
                                per month. If UNCHECKED, the link
                                to the archives is not displayed.
                              - Show link to article map
                                ($maplink + $maplabel): If
                                CHECKED, a link to the site's
                                article map is displayed in the
                                overview. In the default Xaraya
                                theme, this link is at the bottom
                                of the page. If UNCHECKED, the
                                link to the article map is not
                                displayed.
                              - Call transform hooks in
                                summaries: To display text with
                                the output of any 'transforming'
                                hooks, CHECK this box. For
                                example, if you have hooked
                                BBCODE into ARTICLES and would
                                like the Article summary page
                                (typically Frontpage or Article
                                overview) to show the output of
                                BBCODE, CHECK this box. If you
                                wish to show the raw text,
                                UNCHECK this box.
                         @ Article Display Configuration
                              - Show link to previous/next
                                article in display ($prevart +
                                $nextart): OTTO
                         @ Configuration of Hooked Modules
                           OTTO
                         @ Categories
                              - [New]:
                              - Number of possible categories:
                              - Base category for articles (#):
                              - Click "Update Configuration" to
                                save changes.
     * Modify config:
       This panel allows modification of configuration options
       for this module.
     _________________________________________________________

9.1.1. EXAMPLE: Adding a new Publication Type

   OTTO
     _________________________________________________________

9.1.2. EXAMPLE: Adding a new Publication Type that uses Dynamic Data

   In this advanced example, we will configure a new Publication
   Type for Recipes. We will add the new Publication Type, enable
   Dynamic Data, add Dynamic Data fields to our new Publication
   Type, add appropriate Categories, attach the new Publication
   Type to the new Categories, add Templates for the new
   Publication Type, and finally, add an article (a recipe!) to
   the new Publication Type. This example assumes you are
   starting from a fresh, brand-spanking-new, just-installed
   Xaraya Base installation.

    1. LOG IN AS A XARAYA ADMINISTRATOR: This is done any time
       you wish to have Administrator access to your Xaraya site.
    2. CREATE A NEW PUBLICATION TYPE: This is done for each
       custom Publication Type you create.
       To create the new Publication Type, go to
       Admin->Articles->Publication Types. Click "New". Complete
       the fields as follows:
          + Type: recipes (NOTE: Lower case.)
          + Description: Recipe Collection
          + Field: title
               o Label: Recipe Title
               o Format: Text Box
               o Input: CHECKED
          + Field: summary
               o Label: Description
               o Format: Small Text Area
               o Input: CHECKED
          + Field: bodytext
               o Label: Ingredients
               o Format: Large Text Area
               o Input: CHECKED
          + Field: bodyfile
               o Label: (this field should be blank)
               o Format: (as long as Label, above, is blank and
                 Input, below is UNCHECKED, it does not matter
                 what this field contains)
               o Input: UNCHECKED
          + Field: notes
               o Label: Instructions
               o Format: Large Text Area
               o Input: CHECKED
       Do not modify the last 3 fields (authorid, pubdate, and
       status); leave them as they are. Click "Create" to save
       changes.
    3. ENABLE DYNAMIC DATA FOR ARTICLES/RECIPES: This is done for
       each custom Publication Type using Dynamic Data you
       create, unless Dynamic Data has previously been enabled
       for the module.
       To enable Dynamic Data for a Publication Type, go to
       Admin->Modules->Configure Hooks. We want to enable Dynamic
       Data within Articles, so click "dynamicdata" and CHECK the
       box for Articles and the 'Recipe Collection' sub-category
       under Articles. Click "Save Changes".
    4. ADD DYNAMIC DATA FIELD(S) TO THE NEW PUBLICATION TYPE:
       This is done for each custom Publication Type using
       Dynamic Data you create.
       To add dynamic data field(s) to the new publication type,
       go to Admin->Articles->Publication Types. Find the
       'recipes' Publication Type that we created in CREATE A NEW
       PUBLICATION TYPE, above, and click Article Config next to
       it. Near the bottom of the next screen, you'll see
       "Dynamic Data Fields [modify]". Click "[modify]" and in
       the new window that opens, enter the Dynamic Data as
       follows:
          + Label: photo (NOTE: Lower case.)
               o Property Type: Image
               o Data Source: dynamic_data
               o Status: Active
       Click "Update Properties" to save changes. Close the
       window and return to the previous browser window for the
       rest of the steps.
    5. ADD A NEW CATEGORY (AND OPTIONAL SUB-CATEGORIES) FOR THE
       NEW PUBLICATION TYPE: This is done for each custom
       Publication Type you create.
       To add the new category (and optional sub-categories), go
       to Admin->Categories. Click "Add Category" to add a new
       Category. For this example:
          + Create a new Category called "Recipes Category" by
            following the steps below.
               o Name: Recipes Category
               o Description: This is the recipes category for
                 this site.
               o In relation to this category: Generic1
               o Position: Right before, in the same level
               o Optional image: categoryrecipes_top.jpg
               o Click "Add" to add the new category.
          + Create three sub-categories: "Appetizers & Soups",
            "Breads & Baked Goods", and finally "Desserts". To
            create the "Appetizers & Soups" sub-category, click
            "Add Category" and follow these steps:
               o Name: Appetizers & Soups
               o Description: Soups and Appetizer recipes go
                 here.
               o In relation to this category: Recipes Category
               o Position: The first child category
               o Optional image: categorysoups.jpg
               o Click "Add" to add the new category.
          + To create the next two sub-categories, click "Add
            Category" and follow these steps:
               o Name: Breads & Baked Goods
               o Description: Breads & baked goods recipes go
                 here.
               o In relation to this category: Recipes Category /
                 Appetizers & Soups
               o Position: Right after, in the same level
               o Optional image: categorybaked.jpg
               o Click "Add" to add the new category.
          + Create another sub-category, typing "Desserts" in the
            Name field, "Dessert recipes go here" for the
            Description, and "categorydesserts.jpg" as the image.
    6. ADD THE NEW PUBLICTION TYPE TO A CATAGORY: This is done
       for each custom Publication Type you create.
       To add Publication Types to Categories, go to
       Admin->Articles->Modify config and click on the
       description of the Publication Type we created (in this
       example, it's "Recipe Collection"). Scroll down, and
       you'll see:
       Number of possible categories: 0
       Change the "0" to "1".
       Click "Update Configuration" to save changes.
       After the screen refreshes, scroll to the bottom of the
       center section and select the Category for the new
       Publication Type. In this example, if it's not already
       selected, select "Recipes Category" that we created above.
       Click "Update Configuration" to save changes.
    7. CONFIGURE THE NEW PUBLICATION TYPE: This is done for each
       custom Publication Type you create.
       Still in Admin->Articles->Modify config, click on the
       description of the publication type we just created (in
       this example, it's "Recipe Collection"). Make the
       following changes:
          + Use 'recipes' as alias in short URLs: CHECKED
          + Default start view: Browse in Recipes Category
          + Number of columns ($numcols): 1
          + Items per page ($number): 10
          + Show category links in article summaries
            ($categories): CHECKED
          + Show previous/next category ($showprevnext): CHECKED
          + Show number of comments ($comments): CHECKED
          + Show hit counts ($counter): CHECKED
          + Show ratings ($rating): CHECKED
          + Show links to publication types ($showpublinks +
            includes/publinks.xd): CHECKED
          + Show link to archives ($archivelink + $archivelabel):
            CHECKED
          + Show link to article map ($maplink + $maplabel):
            CHECKED
          + Call transform hooks in summaries: UNCHECKED
          + Show link to previous/next article in display
            ($prevart + $nextart): CHECKED
       NOTE: Items enclosed in parenthesis above are the names of
       the variables used in templates.
       Click "Update Configuration" to save changes.
    8. ADD TEMPLATES FOR THE NEW PUBLICTION TYPE: This can be
       done for each custom Publication Type you create.
       We can create up to three custom display templates to tell
       Xaraya specifically how to display this new Publication
       Type. Example files are included in this tutorial
       distribution. If you do not create a template, Xaraya will
       attempt to display the Publication Type using a default
       template.
       Template files are placed into the
       <webdir>/modules/articles/xartemplates directory, and
       should be called 'user-display-<pubtype>.xd',
       'user-summary-<pubtype>.xd', and (optionally)
       'user-view-<pubtype>.xd', where <pubtype> is the name of
       the Publication Type (in this tutorial, <pubtype> is
       "recipes" as created in step #2 above):
          + user-display-recipes.xd -- this is the main view of
            the data
          + user-summary-recpies.xd -- this is a summary view of
            the data
          + user-view-recipes.xd (optional)
       If you wish to create theme-specific versions of these
       files, rename the files from *.xd to *.xt and place the
       theme-specific version in the
       <webdir>/<themes_dir>/<theme_name>/modules/articles
       directory, creating directories as necessary. It is
       recommended that you begin by examining the example files
       included with this tutorial, or open one of the sample
       templates provided with Xaraya and make changes as
       necessary using your favorite HTML editor. Where ever you
       want to display the fields in the new Publication Type,
       enter "#$fieldname#" (no quotes) in the template. Xaraya
       will replace "#$fieldname#" with the contents of the field
       as stored in the database. In this tutorial, we created
       the following fields, which are available for display in
       the template using the #$fieldname# indicated in
       parenthesis:
          + title (#$title#)
          + summary (#$summary#)
          + bodytext (#$bodytext#)
          + notes (#$notes#)
          + photo (#$photo#)
       The templates included with this tutorial distribution
       expect to find a file called "NoPhoto.gif" in the
       <webdir>/images/recipes/ directory of your website. This
       file is displayed if a Photograph URL is not provided in
       the article submission, and is included with this tutorial
       distribution. Copy NoPhoto.gif to the
       <webdir>/images/recipes/ directory, creating directories
       as necessary.
    9. ADD AN ARTICLE TO THE NEW PUBLICATION TYPE: This is done
       for each custom Publication Type you create.
       Now you can add articles to the new publication type.
       Click Admin->Articles->Add Article and click on the name
       of the new Publication Type (in this example, it's Recipe
       Collection). A sample recipe is included with this
       tutorial (SampleRecipe.txt).
       Enter the Recipe Title, Description, Ingredients,
       Directions, and a URL for the photograph for the recipe.
       Select the appropriate Category for the recipe, and click
       "Preview" to see what the recipe will look like, or click
       "Add Article" to save it.
       On the following page, approve the article by putting a
       CHECK in the STATUS box, and selecting "Approved" from the
       drop-down list at the bottom of the page. Click "Change
       Status" to save changes.
   10. LOGOUT FROM THE ADMINISTRATOR ACCOUNT: It is a wise idea,
       though technically not required, to log out of your
       administrator account at the end of each session. To log
       out of your Xaraya administrator account, click [admin
       logout], which appears at the bottom of the Administration
       menu. Confirm your intention to log out by clicking
       "Logout", or click "Cancel" to abort the logout.
     _________________________________________________________

9.1.3. EXAMPLE: Extending the Gallery Publication Type

   OTTO: Speak with mcortez about adding thumbnails, importing,
   etc.
     _________________________________________________________

Chapter 10. Publication Types

   Xaraya's Articles module can manage 'articles' of different
   types at the same time, for instance news articles, longer
   documents in different sections, frequently asked questions,
   and so on.

   These types are called 'Publication Types', and each type of
   article can utilize a different set of data fields, with a
   different meaning for each data field. For example, the
   'summary' field could be used for an Introduction in News
   articles, for providing some Details about a question in FAQs,
   or not be used at all for Section documents.

   There is a specific menu for management of Publication Types
   which allows you to change the description that appears in
   navigation menus, enable & disable dynamic data fields, or
   change their meaning for a particular type, or create or
   delete publication types according to your needs.

   Each publication type also has its own templates, so that the
   look & feel of each publication type can be customized. Until
   you define templates for the new publication type, Xaraya will
   display items using default templates (and a warning).

   A default set of publication types and templates
   (corresponding to the old News, Sections and FAQs modules of
   PostNuke or PHP-Nuke) is included as part of the installation.

   Want to display recipes on your site? Create a new Publication
   Type, and Xaraya can do that.
     _________________________________________________________

10.1. Introduction to Publication Types

   A good strategy for configuration of Categories is to create a
   top-level Category called <sitename>, and below that group all
   the sub-categories for the site. This "<sitename>" top-level
   category could be considered to be the ROOT CATEGORY, with
   additional Categories placed below the ROOT CATEGORY. For
   example, if the site is "MySite.COM":

   MySite.COM (root category)
   |
   |---World News (sub-category)
   |   |
   |   |---North American News (sub-sub-category)
   |   |   |
   |   |   |---United States News (sub-sub-sub-category)
   |   |       |
   |   |       |---Ohio News (sub-sub-sub-sub-category)
   |   |       |
   |   |       |---Nevada News (sub-sub-sub-sub-category)
   |   |       |
   |   |       |---etc...
   |   |
   |   |---Asian News (sub-sub-category)
   |       |
   |       |---China News (sub-sub-sub-category)
   |       |
   |       |---Japan News (sub-sub-sub-category)
   |       |
   |       |---etc...
   |
   |---Sports News (sub-category)
   |
   |---Music News (sub-category)
   |
   |---Entertainment News (sub-category)
   |
   |---etc...

   PUBLICATION TYPES CAN BE USED ONLY BY ARTICLES. CATEGORIES CAN
   BE USED BY ALL MODULES. A module that cannot fit into a
   Publication Type can still use Categories if they want. Plus
   'Site News' could be a Category; you can put news articles in
   there... But you might ALSO have a 'Software News' Category.

     * Admin->Articles->Publication Types:
          + New: Add a new Publication Type
            NOTE: Articles of this Publication Type will use the
            templates "user-display-[publicationtype].xd" and
            "user-summary-[publicationtype].xd" by default.
            Provide those templates before adding new articles.
               o New PublicationType:
                    # Type:
                    # Description:
               o Configuration:
                 If the Label is empty, the field will not be
                 used.
                    # Field:
                    # Label:
                    # Format:
                         @ Static text:
                         @ Text box:
                         @ Small text area:
                         @ Medium text area:
                         @ Large text area:
                         @ Username:
                         @ Calendar:
                         @ File upload:
                         @ Status:
                         @ URL:
                         @ Image:
                         @ HTML page:
                    # Input:
                    # Type:
                    # Click "Create" to save changes.
          + Edit: Click "Edit" next to a Publication Type you
            wish to modify. On the next panel, you may modify the
            settings (as defined in New, above) for the selected
            Publication Type.
               o Click "Modify" to save changes.
               o Export definition to XML: Click this link to
                 export the definition of the Publication Type.
                 On the next panel, the Publication Type is
                 displayed in XML format.
          + Delete: If you wish to delete an existing Publication
            Type, click "Delete" next to the Publication Type you
            want to delete. Note that all articles associated
            with the selected Publication Type will be deleted if
            the Publication Type is deleted. The next panel asks
            you to confirm your intention to delete the
            Publication Type. Click "Delete" to confirm and the
            Publication Type is deleted.
          + Article config: Click this link to go to the Article
            configuration panel for the selected Publication
            Type.
          + View articles: Click this link to display the
            articles associated with the selected Publication
            Type.
          + Add article: To add an article to a particular
            Publication Type, click this link next to the
            Publication Type to which you wish to add the
            article.
          + Import definition from XML: Importing XML deifintions
            of Publication Types can be done in two ways:
              1. XML-format Publication Type definition files are
                 placed into the <xarroot>/modules/articles
                 directory with appropriate ownership &
                 permissions.
              2. The XML definition is pasted into a text field
                 on the Admin->Articles->Publication
                 Types->Import definition from XML panel.
            If you wish to import a Publication Type in XML
            format, follow these steps:
               o Obtain the XML definition(s) for the Publication
                 Type(s) you wish to import.
               o Go to Admin->Articles->Publication Types and
                 click "Import definition from XML".
               o On the next panel, specify the XML to import.
                    # From the drop-down list of *.xml files in
                      the <xarroot>/modules/articles directory,
                      select the file to import.
                    # Paste the XML-format definition into the
                      large text box.
               o Click "Import" to import the Publication Type.
                 The new Publication Type is added to your site.
     _________________________________________________________

10.1.1. EXAMPLE: New Publication Type: A Simple Guestbook for Xaraya

   A simple Guestbook can be made with the Articles module.
   Follow this example to create your own Guestbook. A sample of
   the finished Guestbook is visible at
   http://www.alyousif.tv/index.php/guestbook.

   Go to Admin->Articles->Publication Types. Click "New
   Publication Type". On the next panel, enter the following:

   FIELD: title LABEL: Entry FORMAT: Medium Text Area INPUT:
   checked TYPE: string FIELD: authorid LABEL: Author FORMAT:
   Username INPUT: checked TYPE: integer FIELD: pubdate LABEL:
   Publication Date FORMAT: Calendar INPUT: checked TYPE: integer

   Here's the template that should be placed in
   <xarroot>/modules/articles/xartemplates/user-summary-guestbook
   .xd:

   <div class="xar-alt" style="margin: 0px 3px 6px 3px;padding: 1
   px;text-align: left;"> <div class="xar-norm" style="padding: 3
   px;">
               <xar:if condition="!empty($categories) and count($
   categories) gt 0">
                   [ <xar:loop name="$categories">
                       #$cjoin# <a href="#$clink#">#$cname#</a>
                   </xar:loop> ]
               </xar:if>



             <div class="xar-accent">
               <xar:mlstring>Posted by</xar:mlstring>:
               <b>#$author#</b>
               <xar:mlstring>on</xar:mlstring>
               <b>#$date#</b>
                       <xar:if condition="!empty($counter)">
                          (#$counter# <xar:mlstring>Reads</xar:ml
   string>)
                       </xar:if>



             </div>
             <br />
             #$title#
             <br />
             <div class="xar-sub" align="right">
               <xar:if condition="!empty($comments)">
                   #$comments#
               </xar:if>
             </div>
   </div>
   </div>
     _________________________________________________________

10.1.2. EXAMPLE: New Publication Type: A Blogger

   This example will guide you through the process of adding a
   Blogger Publication Type to your Xaraya site.

     * WHAT IS A BLOG? WHAT IS BLOGGING?:
       blog n.: [common] Short for "weblog", an on-line web-zine
       or diary (usually with facilities for reader comments and
       discussion threads) made accessible through the World Wide
       Web.
       The term "blog" is widespread and readily forms
       derivatives, of which the best known may be "blogosphere"
       (the hyperlinked totality of all blogs and the culture
       surrounding blogs).
       There are tens of thousands of weblogs ("Blogs") on the
       Internet, many of them updated daily -- some of them many
       times a day. Some Blogs are public diaries while others
       are the authoritative or idiosyncratic musings of experts
       and cranks.
       "Blogging" is the process of turning one's own filter on
       news and the world into something others might want to
       read, link to, and write about themselves.
       Blogging is facilitated by desktop BlogTools --
       word-processor-like tools that are created to encourage
       frequent updates of a blog by providing an easy interface,
       specialized tools, and a moment's readiness -- without the
       need to open your browser.
     * FILES INCLUDED WITH THIS TUTORIAL:
       The following files are included with this tutorial.
       OTTO: Move to FILES INCLUDED WITH THIS GUIDE, above, when
       complete.
     * ACTIVATING NECESSARY MODULES FOR BLOGGING:
       In order to configure our Xaraya site for blogging, it is
       necessary to ensure that certain modules are activated. We
       need to activate at least three (and, optionally, a
       fourth) modules:
          + articles -- storage of the blog entries
          + bloggerapi -- the central axis for blogging in Xaraya
          + categories -- categorization of blogs
          + comments (optional but recommended) -- provides site
            visitors the ability to comment on blog entries
       To activate the modules, log in as Administrator and go to
       Admin->Modules->View All. Some of the modules listed above
       may already be active on your site. If the modules listed
       above are not shown with a Status of "Active", they each
       need to be installed by clicking "Install" on their line.
       Once you have ensured that the modules listed above are
       Active on your site, we can move forward to the next step.
     * CREATING A PUBLICATION TYPE FOR THE BLOG:
       While not required, it is recommended that you create a
       specific Publication Type for your blog in articles
       configuration. Doing so allows us to use the site first
       for blogging only and offers the flexibility of adding
       additional types of content later. If you do not wish to
       create a specific Publication Type for your blog, simply
       use one of the existing Publication Types -- for example,
       "news".
       Go to Admin->Articles->Publication Types. Click "New" to
       begin adding a new Publication Type with the following
       values:
       [pubtype.jpg]
       Click "Create" to save changes.
     * ADD CATEGORIES TO THE NEW PUBLICATION TYPE:
       Go to Admin->Articles->Publication Types. Click "Article
       Config" on the 'blog' line. At the bottom of the panel,
       change Number of possible categories to "1". Click "Update
       Configuration" to save changes.
       When the panel refreshes, select a category for blog
       entries from the 'Base category for articles' drop-down
       list. Click "Update Configuration" to save changes.
     * ACTIVATING HOOKS:
       Go to Admin->Modules->Configure Hooks. Click on
       'categories', then CHECK 'blog'. You could CHECK 'all
       articles' instead of 'blog' if you want categories to be
       enabled for every article Publication Type. For the
       purpose of this tutorial, it doesn't matter which of the
       two options you choose as long as you choose one. Click
       "Save Changes" to save changes.
     * LINK BLOGGERAPI TO THE BLOG PUBLICATION TYPE:
       This step connects the incoming data from your BlogTool to
       the correct Publication Type in Xaraya.
       Click Admin->Bloggerapi->Modify config. On the panel that
       appears, select the Publication Type to which you would
       like to point your Blog entries. Select 'blog : Weblog on
       this site', which is the Publication Type we created in
       CREATING A PUBLICATION TYPE FOR THE BLOG, above, and click
       "Update bloggerapi Configuration" to save changes.
       We're now done with the Xaraya-side configuration of your
       blog. Let's move to the BlogTool configuration.
     * CONFIGURING YOUR BLOGTOOL:
       For Windows we recommend w.bloggar. For other operating
       systems, MozBlog is the recommended tool.
          + Configuring w.bloggar -- http://www.wbloggar.com:
               o Download the latest version of w.bloggar from
                 the site above. Install it on any computer(s)
                 from which you'd like to be able to update your
                 Xaraya site.
               o Start w.bloggar. A small account manager window
                 will open for you to configure the site to which
                 you wish to send the blog entries.
                    # Account: <<New>>
                    # User: Enter the user name of a user on your
                      Xaraya site. Any blog entries made through
                      this BlogTool will be posted as this user.
                    # Password: Enter the corresponding password
                      for the user above.
                    # Click "Okay". You will be asked if you want
                      to create this new account. Click "Yes" and
                      you're taken to the Account Properties
                      screen.
                    # Blog Tool: >>Custom<<
                    # Account Alias: The display name for this
                      account, shown in the drop-down account
                      selection list of this BlogTool. "Xaraya
                      weblog" is a good choice, but you can enter
                      whatever you want here.
                    # Ping Weblogs.com: If you would like a
                      notification sent to weblogs.com each time
                      you use this BlogTool to update your site,
                      check this box.
                    # API SERVER:
                         @ Host: your.xarayaserver.com (note: Do
                           not put "http://"!)
                         @ Page: ws.php?type=xmlrpc
                         @ Port: 80
                         @ HTTPS: UNCHECKED
                         @ Timeout: 30 seconds
                    # Click "OK" to save changes and connect to
                      your Xaraya site.
          + Configuring MozBlog -- http://mozblog.mozdev.org:
     _________________________________________________________

10.1.3. EXAMPLE: New Publication Type: A Recipe Category for Xaraya

   This advanced example shows how to create a new Publication
   Type (called Recipes) in Xaraya using Dynamic Data. We cover
   Dynamic Data in depth later in this Guide.

    1. LOG IN AS A XARAYA ADMINISTRATOR: This is done any time
       you wish to have Administrator access to your Xaraya site.
    2. CREATE A NEW PUBLICATION TYPE: This is done for each
       custom Publication Type you create.
       To create the new Publication Type, go to
       Admin->Articles->Publication Types. Click "New". Complete
       the fields as follows:
          + Type: recipes (NOTE: Lower case.)
          + Description: Recipe Collection
          + Field: title
               o Label: Recipe Title
               o Format: Text Box
               o Input: CHECKED
          + Field: summary
               o Label: Description
               o Format: Small Text Area
               o Input: CHECKED
          + Field: bodytext
               o Label: Ingredients
               o Format: Large Text Area
               o Input: CHECKED
          + Field: bodyfile
               o Label: (this field should be blank)
               o Format: (as long as Label, above, is blank and
                 Input, below is UNCHECKED, it does not matter
                 what this field contains)
               o Input: UNCHECKED
          + Field: notes
               o Label: Instructions
               o Format: Large Text Area
               o Input: CHECKED
          + Do not modify the last 3 fields (authorid, pubdate,
            and status); leave them as they are.
          + Click "Create" to save changes.
    3. ENABLE DYNAMIC DATA FOR ARTICLES/RECIPES: This is done for
       each custom Publication Type using Dynamic Data you
       create, unless Dynamic Data has previously been enabled
       for the module.
       To enable Dynamic Data for a Publication Type, go to
       Admin->Modules->Configure Hooks. We want to enable Dynamic
       Data within Articles, so click "dynamicdata" and CHECK the
       box for Articles and the 'Recipe Collection' sub-category
       under Articles. Click "Save Changes".
    4. ADD DYNAMIC DATA FIELD(S) TO THE NEW PUBLICATION TYPE:
       This is done for each custom Publication Type using
       Dynamic Data you create.
       To add dynamic data field(s) to the new publication type,
       go to Admin->Articles->Publication Types. Find the
       'recipes' Publication Type that we created in CREATE A NEW
       PUBLICATION TYPE, above, and click Article Config next to
       it. Near the bottom of the next screen, you'll see
       "Dynamic Data Fields [modify]". Click "[modify]" and in
       the new window that opens, enter the Dynamic Data as
       follows:
          + Label: photo (NOTE: Lower case.)
          + Property Type: Image
          + Data Source: dynamic_data
          + Status: Active
       Click "Update Properties" to save changes. Close the
       window and return to the previous browser window for the
       rest of the steps.
    5. ADD A NEW CATEGORY (AND OPTIONAL SUB-CATEGORIES) FOR THE
       NEW PUBLICATION TYPE: This is done for each custom
       Publication Type you create.
       To add the new cateory (and optional sub-categories), go
       to Admin->Categories. Click "Add Category" to add a new
       Category. For this example:
       Create a new Category called "Recipes Category" by
       following the steps below:
          + Name: Recipes Category
          + Description: This is the recipes category for this
            site.
          + In relation to this category: Generic1
          + Position: Right before, in the same level
          + Optional image: categoryrecipes_top.jpg
          + Click "Add" to add the new category.
       Create three sub-categories: "Appetizers & Soups", "Breads
       & Baked Goods", and finally "Desserts". To create the
       "Appetizers & Soups" sub-category, click "Add Category"
       and follow these steps:
          + Name: Appetizers & Soups
               o Description: Soups and Appetizer recipes go
                 here.
               o In relation to this category: Recipes Category
               o Position: The first child category
               o Optional image: categorysoups.jpg
               o Click "Add" to add the new category.
       To create the next two sub-categories, click "Add
       Category" and follow these steps:
          + Name: Breads & Baked Goods
               o Description: Breads & baked goods recipes go
                 here.
               o In relation to this category: Recipes Category /
                 Appetizers & Soups
               o Position: Right after, in the same level
               o Optional image: categorybaked.jpg
               o Click "Add" to add the new category.
          + Create another sub-category, typing "Desserts" in the
            Name field, "Dessert recipes go here" for the
            Description, and "categorydesserts.jpg" as the image.
    6. ADD THE NEW PUBLICTION TYPE TO A CATAGORY: This is done
       for each custom Publication Type you create.
       To add Publication Types to Categories, go to
       Admin->Articles->Modify config and click on the
       description of the Publication Type we created (in this
       example, it's "Recipe Collection"). Scroll down, and
       you'll see:
          + Number of possible categories: 0. Change the "0" to
            "1".
          + Click "Update Configuration" to save changes.
       After the screen refreshes, scroll to the bottom of the
       center section and select the Category for the new
       Publication Type. In this example, if it's not already
       selected, select "Recipes Category" that we created above.
       Click "Update Configuration" to save changes.
    7. CONFIGURE THE NEW PUBLICATION TYPE: This is done for each
       custom Publication Type you create.
       Still in Admin->Articles->Modify config, click on the
       description of the publication type we just created (in
       this example, it's "Recipe Collection"). Make the
       following changes (NOTE: Items enclosed in parenthesis
       below are the names of the variables used in templates.):
          + Use 'recipes' as alias in short URLs: CHECKED
          + Default start view: Browse in Recipes Category
          + Number of columns ($numcols): 1
          + Items per page ($number): 10
          + Show category links in article summaries
            ($categories): CHECKED
          + Show previous/next category ($showprevnext): CHECKED
          + Show number of comments ($comments): CHECKED
          + Show hit counts ($counter): CHECKED
          + Show ratings ($rating): CHECKED
          + Show links to publication types ($showpublinks +
            includes/publinks.xd): CHECKED
          + Show link to archives ($archivelink + $archivelabel):
            CHECKED
          + Show link to article map ($maplink + $maplabel):
            CHECKED
          + Call transform hooks in summaries: UNCHECKED
          + Show link to previous/next article in display
            ($prevart + $nextart): CHECKED
          + Click "Update Configuration" to save changes.
    8. ADD TEMPLATES FOR THE NEW PUBLICTION TYPE: This can be
       done for each custom Publication Type you create.
       We can create up to three custom display templates to tell
       Xaraya specifically how to display this new Publication
       Type. Example files are included in this tutorial
       distribution. If you do not create a template, Xaraya will
       attempt to display the Publication Type using a default
       template.
       Template files are placed into the
       <xarroot>/modules/articles/xartemplates directory, and
       should be called 'user-display-<pubtype>.xd',
       'user-summary-<pubtype>.xd', and (optionally)
       'user-view-<pubtype>.xd', where <pubtype> is the name of
       the Publication Type (in this tutorial, <pubtype> is
       "recipes" as created in step #2 above):
          + user-display-recipes.xd -- this is the main view of
            the data
          + user-summary-recpies.xd -- this is a summary view of
            the data
          + user-view-recipes.xd (optional) --
       If you wish to create theme-specific versions of these
       files, rename the files from *.xd to *.xt and place the
       theme-specific version in the
       <xarroot>/<themes_dir>/<theme_name>/modules/articles
       directory, creating directories as necessary.
       It is recommended that you begin by examining the example
       files included with this tutorial, or open one of the
       sample templates provided with Xaraya and make changes as
       necessary using your favorite HTML editor. Where ever you
       want to display the fields in the new Publication Type,
       enter "#$fieldname#" (no quotes) in the template. Xaraya
       will replace "#$fieldname#" with the contents of the field
       as stored in the database. In this tutorial, we created
       the following fields, which are available for display in
       the template using the #$fieldname# indicated in
       parenthesis:
          + title (#$title#)
          + summary (#$summary#)
          + bodytext (#$bodytext#)
          + notes (#$notes#)
          + photo (#$photo#)
       The templates included with this tutorial distribution
       expect to find a file called "NoPhoto.gif" in the
       <xarroot>/images/recipes directory of your website. This
       file is displayed if a Photograph URL is not provided in
       the article submission, and is included with this tutorial
       distribution. Copy NoPhoto.gif to the
       <xarroot>/images/recipes directory, creating directories
       as necessary.
    9. ADD AN ARTICLE TO THE NEW PUBLICATION TYPE: This is done
       for each custom Publication Type you create.
       Now articles can be added to the new publication type.
       Click Admin->Articles->Add Article and click on the name
       of the new Publication Type (in this example, it's Recipe
       Collection). A sample recipe is included with this
       tutorial (SampleRecipe.txt).
       Enter the Recipe Title, Description, Ingredients,
       Directions, and a URL for the photograph for the recipe.
       Select the appropriate Category for the recipe, and click
       "Preview" to see what the recipe will look like, or click
       "Add Article" to save it.
       On the following panel, approve the article by putting a
       CHECK in the STATUS box, and selecting "Approved" from the
       drop-down list at the bottom of the panel. Click "Change
       Status" to save changes.
   10. LOGOUT FROM THE ADMINISTRATOR ACCOUNT
       It is a wise idea, though technically not required, to log
       out of your administrator account at the end of each
       session. To log out of your Xaraya administrator account,
       click [admin logout], which appears at the bottom of the
       Administration menu. Confirm your intention to log out on
       the next panel by clicking "Logout", or click "Cancel" to
       abort the logout.
     _________________________________________________________

10.1.4. KNOWLEDGE REVIEW: Publication Types

   OTTO:
     _________________________________________________________

Chapter 11. Dynamic Data in Xaraya

   Xaraya provides the ability for site administrators to add
   data fields to the site to serve a number of different
   purposes, from extending the basic Xaraya configuration to
   adding completely new features. Using Dynamic Data, fields can
   be added and manipulated on the site. This ability is
   available through Dynamic Data, which can be considered
   'building blocks' for data manipulation on the site.

   With other Content Management Systems products, if you wanted
   to display Recipes on your site, for example, you had to wait
   for a Recipes module to be developed and then hope it met your
   needs. As a Content Management System, Xaraya is capable of
   showing almost any data in almost any way that you desire --
   usually without the need to develop (or wait for) an external
   module. No more waiting for someone else to create a
   guestbook; no more waiting for someone else to develop that
   recipe module; no more waiting for someone to add categories
   to the reviews module; no more waiting for a module to display
   portraits or additional information in user information
   screens. Xaraya gives the site administrator the power to be
   self-sufficient and the flexibility to extend Xaraya --
   without coding. Dynamic Data allows Xaraya's site
   administrators to customize Xaraya specifically for their
   needs.

   Using Dynamic Data, site administrators can add fields to
   Xaraya that customize the site.
     _________________________________________________________

11.1. Introduction to Dynamic Data

   Here's a general overview illustrating how to add dynamic data
   to a Xaraya module:

     * Enable the Dynamic Data HOOK for the module you wish to
       extend
     * Create the Dynamic Data OBJECT
     * OTTO: * Define how the Dynamic Data object is DISPLAYED
     _________________________________________________________

11.1.1. EXAMPLE: Dynamic Data: Adding a Picture to User Info

   For a specific example, we'll add a picture to user's
   information on the site. The user's picture file must be
   accessible via the web; this feature does not allow the
   uploading of picture. Let's walk through the steps to set this
   up...

     * Enable the Dynamic Data HOOK for the module you wish to
       extend
       The first thing to do is to enable the dynamic data hook
       for the module you wish to extend. For this example, we
       wish to extend the roles module. OTTO: How to determine
       WHICH module to enable DD for? To enable Dynamic Data for
       the roles module, follow these steps:
          + Go to Admin->Modules->Configure Hooks
          + Click "dynamicdata"
          + CHECK the box next to 'roles' to enable Dynamic Data
            for the roles module
          + Click "Save Changes"
     * Create the Dynamic Data OBJECT
       Now we need to create the dynamic data object that will
       hold the picture information for the roles module. To do
       this:
          + Go to Admin->Dynamicdata->View Objects
          + Under "Other Modules/Users & Groups", click on "View
            Properties" for the roles module
          + In Label, type "My Picture" (or whatever text you
            want displayed to your users)
          + In Property Type, select "Image" from the drop-down
            list.
          + In status select "Display Only". This will stop it
            showing in the membership list but will still make it
            visible in the user info.
          + Click "Update Properties" to save changes.
       You are returned to a similar-looking screen with your new
       Dynamic Data object displayed. Your Dynamic Data object
       has been added.
     * Adding a picture to your user info
       You'll need a picture that is accessible via the web to
       add a picture to your user info. To add the picture,
       follow these steps:
          + As Administrator, go to Main Menu->Modules->Roles
            (NOTE: Do NOT click Admin->Roles for this option).
          + Click "Your Details".
          + Add the URL of your picture to the "My Picture"
            field. Be sure it begins with "http://" unless the
            picture is on your local webserver.
          + Click "Submit".
     * Viewing the picture
       There are two ways to do this. Once you've added your
       picture's URL click the "show" link next to it in "Your
       Basic Details", or click on the user's name in the
       membership list.
     _________________________________________________________

11.1.2. KNOWLEDGE REVIEW: Dealing with Dynamic Data

   OTTO
     _________________________________________________________

Chapter 12. Roles: Users & Groups

   Roles allow you to manage Users and Groups on your site. Roles
   are representations of Users and the different Groups to which
   they can belong.

   Roles can be members of other Roles, to any degree. You can,
   for instance, use Roles to represent a company's organization
   chart, or the set of classes at a university. A Role can be a
   member of as many other Roles as you like (as long as the
   parents are Groups).

   Roles can be assigned Privileges. By doing so, you define what
   a given Role may or may not do on the site. You can use the
   test function of the Roles module to see what parts of the
   site a Role with a given set of Privileges has access to.

   Roles have inheritance. A Role inherits all the Privileges of
   all of its parents, but can override these inherited
   privileges. If you give a group editing privileges, for
   instance, any other Role that is a member of that Group
   inherits the editing privileges. If you want to restrict the
   privileges of some of the members, simply assign them a
   different set of privileges, and the privileges of the parent
   will be overridden.
     _________________________________________________________

12.1. How to use Roles?

   The Roles on your site are displayed in a tree under
   Admin->Roles->View All Groups. At the top of the tree is a
   Role called Everybody, which represents the "group of all
   groups" on your site. Every User and every Group is a member
   or descendent of the Everybody Role.

   Xaraya comes preconfigured with a minimal set of Roles that
   are loaded when you run the installer. This configuration is
   shown below:

   Everybody
   |
   |---Anonymous
   |
   |---Administrators
   |   |
   |   |---Admin
   |
   |---Users

     * Everybody: The Role containing all other roles. This Role
       has no access privileges.
     * Anonymous: A user that represents ALL unregistered users
       on your site. This Role is initially configured with
       Privileges only to access the front page of the site and
       the login block.
     * Administrators: A group that has administration
       privileges.
     * Admin: A member of Administrators group. This is the Admin
       role you create with the Xaraya installer.
     * Users: A group that normally holds registered users of the
       site. This role is not preconfigured with any privileges.
       Members of this Group will not have access to the site
       until you assign privileges.

   The preconfigured Roles cannot be changed or removed. However,
   you can add members to them. You can also define as many more
   Roles in the tree as you wish in whatever configuration you
   choose.

   Always keep in mind: When you create a role, until you've
   assigned privileges to it, the role will only have the
   privileges it inherited from its parents.

     * Admin->Roles->View All Groups:
       This panel displays a tree-view of all Roles on the site.
       The following options are available for each Role:
          + Admin->Roles->View All Groups->"X" icon: Delete this
            Role. It is not possible to delete a Role that
            contains any users. If you wish to delete a Role,
            first remove all the users from the Role. When there
            are no users assigned to a Role, the Delete icon
            becomes available.
          + Admin->Roles->View All Groups->"Two people" icon:
            Display users assigned to this Role.
               o View All: View all users in this Role.
               o View Inactive: View inactive users in this Role.
               o View Not Validated: View users in this Role who
                 have not yet validated their account.
               o View Active: View only active users in this
                 Role.
            Click the name of a specific user to go to a Modify
            User Role panel where the selected user can be
            edited, or added to (or removed from) a particular
            Role.
            The Show Users screen allows you to delete a specific
            user, view the privileges assigned to a specific
            user, or to test the privileges of a specific user.
            Click the icon for the function you wish to utilize.
            See below for an explanation of these functions.
          + Admin->Roles->View All Groups->"Envelope" icon: Send
            a plain-text email to all members of this Role.
            The following variables are available to be used in
            the Subject or Body of the email (see Site Emails,
            below, for more information on using variables):
               o %%name%% -- Display name for the user on the
                 site
               o %%sitename%% -- Site Name
               o %%siteadmin%% -- Name of the site administrator
               o Subject: Enter the subject of your email message
                 in this field.
               o Message: Enter the body of your email message in
                 this field.
               o Click "Submit" to send email.
          + Admin->Roles->View All Groups->"Arrow pointing down
            at person" icon: Show the Privileges assigned to this
            Role.
            Privileges are displayed in two categories:
               o Inherited Privileges
                    # Name: The name of the privilege
                    # Realm: The realm in which the privilege
                      exists
                    # Module: The specific module affected by the
                      privilege
                    # Component: The module component affected by
                      the privilege
                    # Instance: The instance affected by the
                      privilege
                    # Level: The access level of the privilege
                    # From Group: The group from which the
                      privileges were inherited. Click the
                      privilege name to view it.
               o Assigned Privileges
                    # Name: The name of the privilege
                    # Realm: The realm in which the privilege
                      exists
                    # Module: The specific module affected by the
                      privilege
                    # Component: The module component affected by
                      the privilege
                    # Instance: The instance affected by the
                      privilege
                    # Level: The access level of the privilege
               o If a privilege can be removed, a "Remove" link
                 is displayed in the far right column. Click
                 "Remove" to delete the privilege. Only
                 directly-assigned privileges can be removed from
                 this panel.
            Assign a Privilege to Role <rolename>:
               o Privilege Drop-down list
               o Click "Add" to assign privilege.
          + Admin->Roles->View All Groups->"Arrows swirling
            around person" icon: Test this Role's Privileges
               o Registered Masks for this Module: Select a
                 module from the drop-down list. The screen will
                 update with a list of Masks for the module.
                 Click the mask against which you want to test
                 privileges. The selected user/group is tested
                 against that mask, and if the user/group is
                 permitted to perform the action, a PERMITTED
                 message is displayed. If the user/group is not
                 permitted to perform the action, a NOT PERMITTED
                 message is displayed.
               o Click "Test" to perform test.
     * Admin->Roles->Add Group/User:
          + Display name: The display name for the User/Group.
          + Type: From the drop-down list, choose if you wish to
            add a new User or Group.
          + Member of: From this drop-down list, select the
            default Role for this new User or Group.
       The following fields are required if "Type" (above) is
       "User". If you are adding a Group, these fields are not
       available.
          + User Name: The username of the user to be added.
          + Email: Email address of the user to be added.
          + State: From this drop-down list, select the state for
            the new user's account.
               o Inactive:
               o Not Validated:
               o Active: The user's account is validated and
                 fully activated.
               o Pending:
          + Password: The password for the user to be added.
          + Confirm Password: Confirm the user's password by
            entering it here.
          + Click "Add" to save changes.
     * Admin->Roles->Purge Users:
          + Select Status Type:
            From the drop-down list, select the type of users you
            would like to purge.
               o Inactive: This classification is for users that
                 have been inactive on the site for a specific
                 period of time. If you wish to purge users of
                 this status type, select this value from the
                 drop-down list. OTTO: Where is inactive timeout
                 set?
               o Not Validated: This classification is for users
                 that have registered an account but have not
                 validated their account. If you wish to purge
                 users of this status type, select this value
                 from the drop-down list.
               o Pending:
          + Click "Submit" to perform purge.
     * Admin->Roles->Modify config:
          + Page Layout:
               o Number of Users to View Per Page to "25"
               o Enabled Short URLs: CHECKED
               o Show Terms of Service: CHECKED
               o Show Privacy Policy: CHECKED
          + User Registration Options:
               o Allow Registration: CHECKED
               o Minimum age to be a user: "13"
               o Allow users to choose their own password when
                 registering: CHECKED
               o Minimum length for password: "5"
               o Send notice to admin when new user registers:
                 CHECKED
               o Require explicit administrator approval before
                 activating new user: CHECKED
               o Require validation of new user: CHECKED
               o Show dynamic properties on registration (if
                 enabled): CHECKED
               o Send welcome email on successful registration of
                 user: CHECKED
               o Default group for new users: From the drop-down
                 list, select the default group to which new
                 users will be assigned after successfully
                 registering (and, if enabled, validating) their
                 account.
          + Filtering Options:
               o Disallowed user names: Enter usernames that are
                 forbidden for use on the site.
               o Disallowed email addresses: Enter email
                 addresses that are forbidden for use on the
                 site.
               o Disallowed IP addresses: Enter IP addresses that
                 are forbidden for use on the site.
       Click "Update Users Configuration" to save changes.
     _________________________________________________________

12.1.1. Site Emails

   The site can automatically send email messages to users at
   various stages of user registration. Emails can be sent for to
   confirm a new user, welcome a confirmed user to the site,
   remind a registered user of their password, or to re-validate
   a user who has changed email addresses.

   The next few options allow customization of the site emails.

   The following variables can be included in the email (either
   subject or body) and are replaced in the text with specific
   information:

     * %%username%% -- User's username on the site
     * %%name%% -- Display name for the user on the site
     * %%sitename%% -- Site Name
     * %%siteadmin%% -- Name of the site administrator
     * %%password%% -- User's password

   Additionally, if you have configured Dynamic Data for the
   Roles module, available Dynamic Date objects are listed as
   variables.

     * Admin->Roles->Confirmation Email:
       This email is sent to users to complete their registration
       by clicking a link in the email.
       The confirmation email is plain text. Edit the subject and
       body as necessary, and click "Submit new confirmation
       email" to save changes.
       The following variables are available in this message body
       or subject:
          + %%link%%: The link on which the the user must click
            to complete registration
          + %%ipaddr%%: The IP address of the person registering
          + %%name%%: Name given by user during registration
          + %%valcode%%: Validation code to activate the user's
            account
     * Admin->Roles->Welcome Email:
       This email is sent to users to welcome them to the site.
       The welcome email is plain text. Edit the subject and body
       as necessary, and click "Submit new welcome email" to save
       changes.
     * Admin->Roles->Reminder Email:
       This email is sent to users who indicate that they have
       lost their password.
       The reminder email is plain text or HTML depending on your
       settings in Admin->Mail->Modify config. Edit the subject
       and body as necessary, and click "Submit" to save changes.
     * Admin->Roles->Validation Email:
       This email is sent to users when they re-validate their
       account (for example, change email address).
       The validation email is sent as plain text or HTML
       depending on your settings in Admin->Mail->Modify config.
       Edit the subject and body as necessary, and click "Submit"
       to save changes.
     _________________________________________________________

12.1.2. KNOWLEDGE REVIEW: Reviewing Roles

   OTTO: Add a new Category and limit it so only Joe and Jane can
   see it but Bob can't.
     _________________________________________________________

Chapter 13. Privileges: Building Blocks for Site Access

   Through the use of privileges and roles, Xaraya provides very
   fine-grained access control for site users on either a Group
   or individual User level. Many of the concepts behind user
   roles and privileges are based in Object Oriented Programming.

   Privileges are individual access levels (example: Allow
   Comments on Articles; example: Do not allow access to
   administration options) that can be used as building blocks
   and collected together into Compound Privileges.

   Any combination of Individual Privileges and Compound
   Privileges can be placed into Site Roles. Site Roles are built
   from existing Individual Privileges or Compound Privileges.
   Privileges are made from Access Levels. Access Levels are the
   basis for the access control system in Xaraya. Users are
   placed into Roles and have permission to do whatever the
   Privileges associated with that Role permit them to do on the
   site.
     _________________________________________________________

13.1. How to use Privileges

13.1.1. Terminology

   Because Xaraya's Roles & Privileges are considerably different
   from user rights features in other Content Management Systems,
   let's first define some terminology that will be used in this
   section of the Guide.

     * Role: A uniquely-named set of one or more users. A Role
       can correspond to a User or Group of users.
     * Privilege: An object that can grant or deny a particular
       kind of access to a module component. For example, the
       ability to view the Login Block is a privilege, the
       ability to edit an Article is a privilege, and the ability
       to post a comment is a privilege.
     * Module: A functional unit of a Xaraya site -- a module of
       the Xaraya system (articles, polls, messages, ratings,
       quotes, headlines, etc).
     * Component: A group of resources that can be protected with
       the security system. Components are defined by the modules
       in which they reside. Components can be VISUALLY DISCRETE
       resources, such as blocks or web pages, or they can be
       FUNCTIONALITY resources, such as the ability to add or
       edit items. Components can be defined in any way the
       module developer wishes, for example, "adding an article",
       "viewing a link", "displaying a menu", etc, could all be
       designed as components by the module author. Some
       components coincide with concepts known outside the
       security system, such as blocks, but this is not
       necessarily the case.
     * Instance: A specific instance of a component. For example,
       the login block on the front page of a Xaraya site is an
       instance of the Block component in the Roles module.
       Another example of a 'Component' and an 'Instance': the
       Component might be menus in a module while the Instance
       would be "menu number 7". Think of Components as classes
       of Privilege objects and Instances as specific examples of
       those objects.
     * Mask: A special kind of privilege used to check other
       privileges. Each mask protects one or more components.
       When a mask is encountered, it is checked against the
       user's privileges to see whether access to the component
       in question is permitted.
     * Access level: The type of access granted by a privilege or
       required by a mask. An access level is the right to access
       a resource. Security levels in Xaraya go from 0 (no
       access) to 800 (admin or full access).
     * Realms: Realms are a way of creating different security
       views of the same Xaraya site. They are an "extra
       dimension" used to make finely-grained security schemes.

   EXAMPLE: If you would like anonymous users to be able to view
   items on your website (but be unable to post comments), add
   the following privilege:

     * Admin->Privileges->Add Privilege:
          + Click "with rights" radio button -- the panel will
            reload with additional options
          + Name: ViewTopics
          + Member of: CasualAccess (If you DO NOT select an
            existing privilege of which the new privilege is a
            member, the new privilege will appear in the top
            level. If you select a Member from the drop-down
            list, the privilege appears in TWO places:
              1. Top level
              2. Under the privilege selected from the drop-down
                 list
            This configuration is in place so the privilege may
            be re-used. It also prevents the privilege from being
            "lost".)
          + Realm: All
          + Module: Articles
          + Component: All
          + Level: Set to "Read"
          + Click "Add"
     _________________________________________________________

13.1.2. Explanation of privilege levels

   OTTO verify with John Cox or Dracos

     * None: User has no access to this item.
     * Overview: User can see the SUMMARY of an article, or be
       shown a link but not the article/link itself.
     * Read: User has READ ONLY access to this item.
     * Comment: User can POST COMMENTS about this item.
     * Moderate: Used for functions that require moderation, such
       as Comments, or in Forums. An example is granting a user
       moderation abilities within a message board but nowhere
       else on the site.
     * Edit: "Edit" is a permission for users that may not be
       permitted to Add, but are allowed to Edit. Example: An
       Article Administrator that is permitted to edit stories,
       but is not permitted to post Articles.
     * Add: "Add" grants permission to either add or approve
       content.
     * Delete: "Delete" is the opposite of "Add". You are
       granting someone the ability to remove content.
     * Admin: User has ADMINISTRATOR ACCESS to this item.
     _________________________________________________________

13.1.3. Container Types

     * Empty: It's possible to create a Privilege which has no
       access rights itself, but is just a container for others.
       Selecting EMPTY can to create a 'master container' for
       other Privileges. ADVANCED: It is possible for a 'master
       container' to contain access rights. We'll explore that
       more later. OTTO
     * With Rights: This Privilege, unlike an Empty Privilege,
       has access rights.
     _________________________________________________________

13.1.4. EXAMPLE: Read-access for Anonymous users

   To grant Anonymous users read access to the site, add the
   following privilege:

     * Go to Admin->Privileges.
     * Click "CasualAccess".
     * Under the Privilege drop-down list below Add Privilege To
       'CasualAccess', select "ReadAccess"
     * Click "Add" to save changes.

   Unregistered and Anonymous users now have read access to the
   site.
     _________________________________________________________

13.1.5. Allow Registered Users to modify their account

   To allow Registered users to change their theme, post
   comments, and submit articles, add the following privilege:

     * Go to Admin->Privileges->Add Privilege
     * Admin->Privileges->View Privileges->View Topics:
       If you would like anonymous users to be able to post
       comments, change the "Level" field to "Comment" and click
       "Update" to save changes.
     _________________________________________________________

Chapter 14. Xaraya Authentication Modules

   This section describes some the Xaraya authentication system
   works and some of the plugins available for it.
     _________________________________________________________

14.1. AuthSystem Module
     _________________________________________________________

14.1.1. Authsystem Module

   Xaraya default authentication module.

   This module does not have an administration panel.
     _________________________________________________________

14.2. AuthLDAP Module
     _________________________________________________________

14.2.1. Authldap Module

   Xaraya LDAP authentication module. Admin->Authldap.

   This module provides LDAP authentication services for Xaraya.

     * Modify config:
       This panel allows modification of configuration options
       for this module.
          + LDAP Server Name or IP: Enter the complete server
            name or IP address for the LDAP server.
          + LDAP Server Port Number: Enter the port number for
            the LDAP server.
          + Anonymously Bind to Server:
          + LDAP bind DN:
          + LDAP UserID Field Name:
          + Search User DN:
          + LDAP Admin ID:
          + LDAP Admin Password:
          + Add LDAP User to Xaraya Database on Login: If a user
            exists in LDAP but does not have a login account for
            Xaraya the user will be unable to login. By CHECKING
            this option and entering the attribute values, a user
            that has account information in LDAP will be
            automatically added to the Xaraya database and
            permitted to login. If you do not wish to add LDAP
            users automatically to Xaraya's database, UNCHECK
            this option.
          + LDAP Username Attribute Name:
          + LDAP Email Attribute Name:
          + Default Group: DDL
          + Click "Submit" to save changes.
     _________________________________________________________

14.3. AuthInvision Module
     _________________________________________________________

14.3.1. AuthInvision Module

   Xaraya/Invision Board authentication module.
   Admin->Authinvision.

   When this module is activated and configured and a user logs
   into your site, Xaraya looks at the Invision Power Board (IPB)
   database for the user's registration information. If the
   user's information is in IPB's database, the user is
   authenticated and their registration information is copied
   into Xaraya's database if it doesn't already exist.

   Before starting, make sure that you've got your IPB forums set
   up and configured. The set up and configuration of IPB forums
   is beyond the scope of this document. Before the AuthInvision
   module can be activated, you have to manipulate a file and a
   database entry so that everything is properly configured.

     * Copy the <xarroot>/modules/roles/xartemplates/login.xd
       file to
       <xarroot>/themes/<theme_name>/modules/roles/xartemplates/l
       ogin.xt (creating directories as needed) and edit the
       links in
       <xarroot>/themes/<theme_name>/modules/roles/xartemplates/l
       ogin.xt to point to your IPB registration page (usually
       http://www.yoursite.com/forum/index.php?act=Reg&Code=00,
       depending on where your forum is installed).
     * Using phpMyAdmin, go into your Xaraya database and edit
       the xar_config_vars table and change the
       Site.User.AuthenticationModules value to
       a:1:{r0;s:12:"authinvision";}. That is all that should be
       in that value; no more, no less. Be careful with this
       command; if you get it wrong, you will break your site.

   Now install & activate the module and you're all set!
     _________________________________________________________

14.4. AuthSSO Module
     _________________________________________________________

14.4.1. AuthSSO Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

Chapter 15. Managing Content in Xaraya

   OTTO: explain managing content with Xaraya
     _________________________________________________________

15.1. Polls Module
     _________________________________________________________

15.1.1. Polls Module

   Conduct polls. Admin->Polls.

   Polls allow you to gather information from your site visitors
   using a 'voting booth' method. Xaraya supports an unlimited
   number of different polls, and polls optionally support
   selection of multiple options (for example, for surveys like
   'Which of these items do you own?').

     * New Poll: To create a new Poll for the site, click "New
       Poll". The next panel offers the following options.
          + Poll title: Enter the name of the poll in this field,
            which is displayed to site visitors.
          + Poll type: If you want your users to be able to
            select only one option, choose "Single vote" (for
            example, "Ringo"). If you want your users to be able
            to select multiple options (for example, "John" and
            "Paul"), choose "Multiple vote".
          + Private: CHECK this box to make this poll private.
            UNCHECK this box to make the poll public, which means
            any site visitor with privileges can view and vote in
            this poll.
          + Poll options: Enter each available poll option, one
            option per line. Move from field to field using the
            TAB key.
          + Click "Create Poll" to save changes.
     * List Polls:
          + Title: The title of the poll.
          + Actions:
               o Edit Options: To add, modify, or delete options
                 for the selected Poll, click the "Edit options"
                 link.
                    # Option: The poll option.
                    # Order: To move a poll option up or down,
                      click the corresponding arrow next to it.
                    # Actions:
                         @ Modify: To modify a poll option, click
                           the "Modify" link next to the option
                           to be modified. Make any modifications
                           and click "Modify Option" to save
                           changes.
                         @ Delete: To delete a poll option, click
                           the "Delete" link next to the option
                           to be deleted. Confirm your intention
                           to delete the poll option by clicking
                           "Delete Option" on the next panel. The
                           poll option is removed.
                    # New option: Click "New Option" to add a new
                      poll option to an existing poll. Enter the
                      option text to be displayed to site
                      visitors, and click "Create Option" to save
                      changes.
               o Close: Closes the poll so no more votes can be
                 submitted.
               o Modify: The modify option allows the title,
                 type, privacy setting, and options to be changed
                 on an existing poll. Click "Modify Poll" to save
                 changes.
               o Reset: Click this option to reset the polling
                 data for an exsiting poll. Confirm your
                 intention on the next panel. If you click "Reset
                 Poll", any existing votes are removed for the
                 selected Poll.
               o Delete: Deletes the poll and all responses from
                 the site. Click "Delete Poll" to confirm your
                 intention to delete the poll.
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Scale of result bar: OTTO
          + Number of options for new polls: Sets the default
            number of options available when a new poll is
            created. If you only ask "Yes" or "No" polls, it is
            safe to set this to "2" options. Only the poll
            options that you use are displayed to site visitors.
            No matter the value in this setting, new options can
            be added to polls easily. A suggested setting for
            this field is "10".
          + Number of polls per list page: This setting defines
            the number of polls to display per page. To display
            20 polls per page, enter "20" in this field.
          + Activate comments in polls?: CHECK this box to permit
            comments on polls. The Comments module must be
            installed for this option to function.
          + Use images for graph display: From this drop-down
            list, select if you would like to use images for poll
            results graphs.
               o Never: Select this option to NEVER display
                 images in the poll results graph.
               o Blocks only: Select this option to display
                 images in the poll results graph only when the
                 poll is displayed within a block.
               o Module space only: Select this option to display
                 images in the poll results graph only within the
                 Polls module, but not in blocks. For example,
                 selecting this option displays images in the
                 poll results graph only when a site visitor
                 clicks the Polls module.
               o Always: Always display images for the poll
                 results graph.
          + Allow users to vote (per poll): From this drop-down
            list, select the frequency with which a site visitor
            is permitted to vote in a poll.
               o Once: The site visitor is permitted to vote in a
                 poll only once.
               o Once per day: The site visitor is permitted to
                 vote in a poll once per day.
               o Once per week: The site visitor is permitted to
                 vote in a poll once per week.
               o Once per month: The site visitor is permitted to
                 vote in a poll once per month.
          + Allow users to see results before voting: CHECK this
            box to allow site visitors to view poll results, even
            if they have not yet voted in a poll. UNCHECK this
            box to hide poll results until a user has voted in a
            specific poll.
     * Click "Submit" to save changes.
     _________________________________________________________

15.1.1.1. EXAMPLE: Creating a Poll

   To create a Poll, follow these steps:

     * Go to Admin->Polls->New Poll.
          + In Poll Title, type "Who is your favorite Beatle?"
          + Select SINGLE in Poll Type, since we want our site
            visitors to select only ONE Beatle. If you wanted to
            allow them to select multiple options, set this field
            to Multiple vote. For this example, set it to Single
            vote.
          + Leave Private UNCHECKED.
          + Options: Add the following options, moving from field
            to field by pressing the TAB key.
               o John
               o Paul
               o George
               o Ringo
     * Click "Create Poll" to create the poll.
     _________________________________________________________

15.2. XarBB Module
     _________________________________________________________

15.2.1. XarBB Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

15.3. Headlines Module
     _________________________________________________________

15.3.1. Headlines Module

   Generates a list of RSS news feeds. Admin->Headlines.

   RSS is a Web content syndication format. Using RSS, your site
   can 'pull' content in the form of headlines from selected
   websites and display that content on your site. If a user of
   your site is interested in reading the article, they can click
   a link to be taken to the other site. The Headlines modules
   facilitates this process.

   Your site can be syndicated assuming that you have configured
   Admin->Bloggerapi. The link for syndication of your site is
   "www.yoursite.com/index.php?module=articles&func=view&theme=rs
   s".

     * Add: In this section of the Headlines module, we specify
       the news feeds that we want to syndicate.
          + List of available feeds: Click this link to open a
            new browser window with http://www.syndic8.com. Click
            "Feeds" at the top of the Syndic8 site to display a
            list of available feeds, or enter search criteria and
            search for feeds. Once you have found a feed you wish
            to syndicate, copy the Feed URL from Syndic8 into
            Xaraya's URL field, below.
          + URL: Once you know the URL for the news feed you wish
            to syndicate, enter the complete URL (including
            "http://") in this space.
          + Click "Create Headline" to save changes. The news
            feed is added to the site's Headlines list.
     * View: This link allows you to view news feeds which you
       are syndicating, and to edit or delete them.
          + URL: The complete URL for the news feed, including
            "http://".
          + Order: Defines the order in which syndicated news
            feeds are displayed in the module. News feeds are
            displayed in ascending numeric order by order number.
            From 0 to 999, you may assign an order number to your
            news feeds to arrange them in your preferred order.
            These numbers do not need to be consecutive; it is
            perfectly acceptable to number your news feeds by 5's
            or 10's as you see fit. If you do not assign order
            numbers, sites are displayed in the order in which
            they were added.
          + Options:
               o Edit: Permits modification of a news feed.
                    # URL: Enter the complete URL (including
                      "http://") for the news feed.
                    # Alternate Title: To override the title of
                      the feed that is provided by the feed,
                      enter the title of the feed in this field.
                      Leave this field blank to use the
                      feed-supplied title information.
                    # Alternate Description: To override the
                      description of the feed that is provided by
                      the feed, enter the description of the feed
                      in this field. Leave this field blank to
                      use the feed-supplied description
                      information.
                    # Order: Modify the order number of the news
                      feed in this field. Enter a number, from
                      0-999, in this field.
                    # Click "Modify Headline" to save changes.
               o Delete: To delete a news feed from your site,
                 click this link next to the feed to be deleted.
                 You will be asked to confirm your intention to
                 delete, and the feed will be deleted from your
                 site.
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Items per page: In this field, enter the number of
            headlines to display per page. For example, to
            display 20 headlines per page, enter "20" in this
            field.
          + Click "Update Headlines Configuration" to save
            changes.
     _________________________________________________________

15.4. Addressbook Module
     _________________________________________________________

15.4.1. Addressbook Module

   Modules Distribution, Xaraya address book module.
   Admin->Addressbook.

   The Addressbook module provides a configurable address book
   for your site. Entries in the address book can be made private
   (viewable only by the person who entered the item) or public
   (viewable by all users with access to this module).

     * Modify config:
       This panel allows modification of configuration options
       for this module.
          + Access level:
               o Grant Rights for an unregistered user:
               o Grant Rights for a registered user:
                    # View: To give unregistered/registered users
                      VIEW access to the address book, CHECK this
                      box. To prohibit unregistered/registered
                      users from VIEWING the address book,
                      UNCHECK this box.
                    # Create: To allow unregistered/registered
                      users to CREATE entries in the address
                      book, CHECK this box. To prohibit
                      unregistered/registered users from CREATING
                      entries in the address book, UNCHECK this
                      box.
                    # Edit/Delete: To allow
                      unregistered/registered users EDIT/DELETE
                      access to the address book, CHECK this box.
                      To prohibit unregistered/registered users
                      from EDITING/DELETING items from the
                      address book, UNCHECK this box.
          + Other settings:
               o Title of this Address book: In this field, enter
                 the name of the address book as it will be
                 displayed to users.
               o Default sort order / List View: Select two
                 columns of your choice. This setting affects not
                 only the sort order but also the display of
                 columns in the list view. Users may select
                 between the Default and Alternate sort orders.
               o Alternate sort order / List View: Select two
                 columns of your choice. This setting affects not
                 only the sort order but also the display of
                 columns in the list view. Users may select
                 between the Default and Alternate sort orders.
               o Name display in list view and sort order for
                 name information: This setting determines the
                 sort order and display of names in the list
                 view. You can change the default Â«Last Name,
                 First NameÂ» to Â«First Name Last NameÂ».
               o Special character (Umlauts) replacement for sort
                 columns: Names and companies are stored in
                 special sort columns for correct sorting when
                 special characters (such as Umlauts) are used.
                 This Admin setting allows you to set up the
                 character replacement to correct the sort for
                 each language.
               o Personal address book mode: The Address Book
                 module may be used as a Global address book
                 (UNCHECKED (default)) or a Personal address book
                 (CHECKED). As a Global address book (UNCHECKED)
                 all users with appropriate access may view
                 records that are NOT marked Private. As a
                 Personal address book (CHECKED) users may only
                 view entries they have created and unregistered
                 users may not view or create any entries.
               o Do you want to use a prefix field?: Prefix/Title
                 (Mr., Mrs., etc.) values can be set in
                 Admin->Addressbook->Name Prefixes panel and are
                 optionally selected via a drop-down list when
                 creating/editing an entry. This field is hidden
                 (UNCHECKED) by default. If you wish to use a
                 prefix field, CHECK this box.
               o Do you want to use images/logos?: Administrators
                 will see a selection box of all files in the
                 <xarroot>/modules/Addressbook/xarimages and can
                 assign an image to a record. The image is shown
                 in the upper right corner of the detail page.
                 Currently, all pictures must be manually
                 uploaded into the
                 <xarroot>/modules/Addressbook/xarimages
                 directory. This field is hidden (UNCHECKED) by
                 default. If you wish to use images/logos, CHECK
                 this box.
               o Disable the menu: If you wish to use the
                 Addressbook module as a simple contact list, you
                 can disable the menu completely. You can also
                 disable it for guests only. Note, Administrators
                 always see the full menu, regardless of this
                 setting. Select from the drop-down list.
                    # Enabled for all: Everyone can see the menu.
                    # Disabled for all: No one can see the menu.
                      Administrators always see the full menu.
                    # Disabled only for guests: The menu is
                      disabled for unregistered users, but
                      displayed to registered users.
               o Disable the second line of the main menu:
                 Disables the display of the second menu line
                 only. Users have access to the categories, sort
                 order, and the search field, but not to Private
                 records, A-Z / Complete list view switch, and
                 the Add New Record link.
               o Show zip before city: If you would like to
                 display the postal/zip code before the city,
                 CHECK this box. Otherwise, UNCHECK this box.
               o Records viewed per page: How many Addresses
                 would you like to display per page? Enter that
                 value into this field, for example, "25".
               o Hide the Copyright and Version Note: If you wish
                 to hide the version number and copyright notice
                 of this module, CHECK this box. To display the
                 version number and copyright notice of this
                 module, UNCHECK this box.
          + Custom labels:
               o Custom tab (if empty, no custom fields are
                 displayed): Name of the Custom Fields tab and
                 the headline for custom fields in the detail
                 panel. Leave blank if you do not use custom
                 fields.
               o Width of TEXTAREA fields: The width of the
                 TEXTAREA field can change depending on the
                 settings of your theme. Sometimes this results
                 in a very bad layout for your form. You can set
                 the HTML COLS of a TEXTAREA field in this box.
                 Valid size ranges from 4 to 100.
               o Format for date entries: Select the format for
                 date entry and display.
                    # MM.DD.YYYY: Displays September 14, 1971 as
                      "09.14.1971".
                    # DD.MM.YYYY: Displays September 14, 1971 as
                      "14.09.1971".
               o Format for numeric values: Select the format for
                 numeric entry and display, either "9,999.99" or
                 "9.999,99".
          + Administrative Messages
            Administrative messages are sent whenever Addressbook
            catches an error that forces the user to start over.
               o Send messages to Site Admin if error
                 encountered?: This option enables error messages
                 to be emailed directly to the site administrator
                 email account. UNCHECK to disable this feature.
               o Different email address if not the default Site
                 Admin: Choose an alternate email address if the
                 Site Administrator does not wish to receive
                 error notifications from Addressbook.
               o Send error reports to Addressbook developer?:
                 Recommended for quality assurance purposes. Only
                 the contents of the error message are sent. This
                 option sends an email to the Addressbook
                 developers with the error message, date & time
                 of occurrence, and the fully qualified host name
                 of the server running the Addressbook module. NO
                 OTHER INFORMATION IS SENT. This information is
                 used solely for the purpose of fixing issues
                 encountered in the Addressbook module. UNCHECK
                 to disable this feature.
               o Click "Commit Changes" to save changes.
     * Categories:
       Your Addressbook entries can be assigned to a single
       category for organizational purposes. Example categories:
       "Business", "Personal", etc. You may add as many
       categories as necessary. The category is assigned to an
       entry by selecting it from the drop-down listing during
       entry creation or editing.
          + Category: Enter the name of the category you wish to
            add.
          + Delete: To delete an existing category, CHECK the box
            on the line with the category to be deleted.

            Note

   When you click "Commit Changes" to delete an existing
   category, you are NOT asked for confirmation before deletion.
          + Click "Commit Changes" to save changes.
     * Contact labels:
       Contact labels allow specification of different contact
       methods for an entry in the address book. Example contact
       labels: Phone, Mobile, Pager, Fax, E-Mail, Web, Other. You
       may add as many contact labels as necessary. The contact
       labels are available as drop-down lists when
       adding/editing a contact.
          + Label: Enter the name for the contact label you wish
            to add.
          + Delete: To delete an existing contact label, CHECK
            the box on the line with the contact label to be
            deleted.

            Note

   When you click "Commit Changes" to delete an existing contact
   label, you are NOT asked for confirmation before deletion.
          + Click "Commit Changes" to save changes.
     * Name Prefixes:
       Honorary titles, or name prefixes, such as "Mr.", "Sir",
       "Mrs.", "Professor", or "Dr." can be specified in these
       fields. You may add as many name prefixes as necessary.
       You must have CHECKED "Do you wish to use a prefix field?"
       in Admin->Addressbook->Modify config for this field to be
       displayed during creation/editing of a contact.
          + Prefix: Enter the prefix in this field.
          + Delete: To delete an existing prefix, CHECK the box
            on the line with the prefix to be deleted.

            Note

   When you click "Commit Changes" to delete an existing prefix,
   you are NOT asked for confirmation before deletion.
          + Click "Commit Changes" to save changes.
     * Custom Fields:
       If you wish to add custom fields for your contacts, do so
       using this panel.
          + Custom label: Enter the display text for the custom
            label in this field.
          + Data type: From the drop-down list, select the data
            type for the new custom field. A special data type,
            "Horizontal Rule", simply draws a horizontal line and
            does not accept data entry.
          + Delete: To delete an existing custom data type, CHECK
            the box on the line with the custom field to be
            deleted.

            Note

   When you click "Commit Changes" to delete an existing custom
   field, you are NOT asked for confirmation before deletion.
          + Order: Set the order in which the custom fields are
            displayed by clicking the UP arrow to move a field up
            in the order. Click the DOWN arrow to move a field
            down in the order.
          + Click "Commit Changes" to save changes.
     * Admin Docs: Click this link to view administration
       documentation for this module.
     _________________________________________________________

15.5. Contact Module
     _________________________________________________________

15.5.1. Contact Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

15.6. Newsletter Module
     _________________________________________________________

15.6.1. Newsletter Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

15.7. Newsgroups Module
     _________________________________________________________

15.7.1. Newsgroups Module

   Read and post to NNTP. Admin->Newsgroups.

   The NewsGroups module provides the basic functionality to read
   and post to NNTP.

     * Modify config:
          + News server: Enter the name of the news server from
            which you wish to pull news. For example,
            "news.xaraya.com".
          + Port: Enter the port on the news server through which
            news will flow. Generally "119".
          + Topics per page: Enter the number of topics to
            display per page. If, for example, you wish to
            display 50 topics per page, enter "50" in this field.
          + Click "Update Configuration" to save changes.
     _________________________________________________________

15.8. Uploads Module
     _________________________________________________________

15.8.1. Uploads Module

   Upload handler module for Xaraya. Admin->Uploads.

   Using the Uploads module, the Site Administrator may permit
   uploads in a protected fashion. For example, if the Site
   Administrator configures Uploads in a certain way (see
   examples, below), users can submit images along with article
   submissions. These user-sent images can be displayed within
   articles.

     * View uploads:
          + View All:
          + Waiting for approval:
     * Upload file:
          + Browse:
          + Click "Submit Query" to save changes.
     * Import files:
     * Modify config:
          + Primary configuration:
               o Uploads directory: This must be the full path to
                 a folder on your server, including ending slash.
               o Maximum Upload Size (in bytes): This number may
                 be ignored if it is greater than your PHP
                 maximum upload size.
               o Allowed File Extensions: This list should be
                 semicolon (;) delimited. Do not use dots (.)
                 unless it is a multi-part extension like tar.gz.
                 Do not put a semicolon on the end unless you
                 wish to accept uploads without extensions.
               o Confirm Deletes/Rejects: Specifies if
                 confirmation must be provided before files are
                 deleted. Check YES to turn on confirmation.
                 Check NO to turn off confirmation.
               o Click "Submit Query" to save changes.
          + Images configuration:
               o Maximum Image Width (in pixels):
               o Maximum Image Height (in pixels):
               o Thumbnails:
                    # Kept with original file:
                    # Kept in thumbnail folder:
                    # None:
               o Thumbnail path: In this field, enter the local
                 path where (optionally, depending on the setting
                 of "Thumbnails", above) thumbnails are stored,
                 including the trailing slash. The directory must
                 be writable by PHP.
               o NetPBM path: Enter the path to the NetPBM
                 installation, including the trailing slash (for
                 example, /usr/local/bin/). If this field is
                 populated, the Uploads module will use NetPBM to
                 generate thumbnails. If this field is not
                 populated (or the NetPBM files cannot be found),
                 the Uploads module will use PHP's GD interface
                 which requires PHP to be compiled with support
                 for GD 1.8+. See Admin->Base->System for
                 information.
          + Import configuration:
               o Import directory: Enter the local path where
                 you've placed files that you wish to import via
                 Admin->Uploads->Import. This must be the full
                 path to the folder on the server, including
                 trailing slash.
               o Obfuscate/Secure imported files: Check YES to
                 obfuscate the imported files. Check NO and the
                 files will not be obfuscated.
          + Click "Submit Query" to save changes.
     _________________________________________________________

15.8.1.1. EXAMPLE: Adding Image Uploads to a Publication Type

   To allow users to upload images to the site and include the
   uploaded images in articles, we must complete several steps.
   These steps are listed below.

     * Create a directory where uploaded images will be stored.
       Default is "<xarroot>/var/uploads", but the directory can
       be anywhere you'd like.
     * Change the permissions on the UPLOAD directory to
       world-readable & world-writable. On Linux systems, this is
       done by "chmod 777 <path_to_upload_dir>".
     * Install the Uploads module. Go to Admin->Modules->View
       All. CHECK "Regenerate" and click the "Reload" button to
       refresh the page. Click "Install" next to the Uploads
       module if necessary.
     * Go to Admin->Uploads->Modify Config.
          + In the "Uploads Directory" field, enter the full path
            to the uploaded images folder on your server,
            including ending slash.
          + Ensure that you're satisfied with the permitted
            extensions in the Allowed File Extensions field. For
            example, "gif;jpg;png;zip;tar.gz;tgz".
          + Edit the other settings in this panel to your
            preferences.
          + Click "Submit Query" to save changes.
     * We want to enable Uploads in Articles Publication Type, so
       we must hook the Uploads module to the Publication Type(s)
       of the Articles module. Go to Admin->Articles->Publication
       Types. Select the Publication Type to which you would like
       to hook Uploads and click "Article Config" next to it.
          + If you do not see "Dynamic Data Fields [modify]" at
            the bottom of the panel, you need to enable Dynamic
            Data for the Articles module before you can continue.
            To enable Dynamic Data for the Articles module, do
            the following:
               o Go to Admin->Modules->View All. Locate the
                 Articles module in the panel. Click "On/Off"
                 under Hooks next to the Articles module.
               o On the panel that appears, place a CHECK in the
                 box next to Uploads to enable Uploads in
                 Articles. You can select either ALL Publication
                 Types in Articles (by CHECKing the "All" column)
                 or select specific Publication Type(s) by
                 CHECKing their individual boxes.
               o Click "Save Changes" to save changes.
               o Go back to Admin->Articles->Publication Types.
                 Select the Publication Type to which you would
                 like to hook Uploads and click "Article Config"
                 next to it.
          + If you see "Dynamic Data Fields [modify]" at the
            bottom of the panel, click "[modify]". A new browser
            window will open. In this new window we define the
            Dynamic Data field that will hold the uploaded image
            filename.
               o Enter text to be displayed to the user in the
                 "Label" field. For example, "Image".
               o From the Property Type drop-down list, select
                 "File Upload".
               o The remaining fields should be set as follows:
                    # Default is blank.
                    # Data source is set to "dynamic_data".
                    # Validation is blank.
                    # Status is Active.
               o Click "Update Properties" to save changes. The
                 new Dynamic Data field is added to the
                 Publication Type.
     * Go to Admin->Articles->Add Article. Select a Publication
       Type for which you have enabled Upload hooks. You should
       see at the bottom of the page the new Image field.
     _________________________________________________________

15.9. Calendar Module
     _________________________________________________________

15.9.1. Calendar Module

   Calendar module. Admin->Calendar.

   OTTO
     _________________________________________________________

15.10. Messages Module
     _________________________________________________________

15.10.1. Messages Module

   Xaraya Messages module. Admin->Messages.

     * Modify config: This panel allows modification of
       configuration options for this module.
          + Configure Module
               o Short URL Support: If you wish to enable Short
                 URL support for this module, CHECK this box. If
                 you do not wish to enable Short URL support for
                 this module, UNCHECK this box.
               o Click "Modify" to save changes.
     _________________________________________________________

Chapter 16. Transforming Content in Xaraya

   OTTO: explain content management and transforms usage with
   Xaraya
     _________________________________________________________

16.1. Autolinks Module
     _________________________________________________________

16.1.1. Autolinks Module

   TRANSFORM. Automatically link key words. Admin->Autolinks.

   Autolinks is a feature that, when installed, generates web
   links related to text content on-the-fly. If you have
   Autolinks turned on & configured properly, "Beatles" defined
   as a Keyword, and "http://www.beatles.com" as the auto-link
   URL, Autolinks in Xaraya can automatically replace occurrences
   of "Beatles" within your articles with "<a
   href="http://www.beatles.com">Beatles</a>".

   When the Autolinks module is installed, the option to hook
   Autolinks into particular modules appears in
   Admin->Modules->Configure Hooks. Hook Autolinks into the
   modules you wish (such as Articles, Comments, Ephemerids,
   Messages, and XarBB). See the section on Hooks for information
   about hooking modules together.

   There are five 'levels' of use for the Autolinks module on
   your site.

    1. Beginner: Create Autolinks based on previously-defined
       Autolink Types without using Dynamic Data. If you just
       want to create Autolinks, this is the simplest level. The
       default Autolink Types & templates are reasonably
       comprehensive.
    2. Intermediate #1: Using Dynamic Data to allow over-ride of
       global settings for individual links (for example, named
       targets for links, etc).
    3. Intermediate #2: Using dynamic data to access optional
       features of the standard templates (features such as an
       alternative icon in the 'external' link type).
    4. Advanced #1: Adding new Autolink Types and creating
       templates for the new types.
    5. Advanced #2: Using regular expression (regex) matching.

   Let's examine the options available within Autolinks.

     * View Links
       To view, edit, or delete Autolinks, click
       Admin->Autolinks->View Links. On the next panel, the
       following options are displayed. Autolinks in your
       database are displayed sorted by Name.
          + Type: Displays the Autolink Type. Click the Autolink
            Type text to go to the Modify Autolink Type panel.
          + Name: Displays the name of the Autolink. Names are
            unique across all Autolinks on a site. Click the Name
            text to go to the Modify Autolink panel.
          + Matching key: Xaraya searches content items for this
            text. If matching text is located, it is replaced
            with an autolink. If the Autolink has the "Match as
            regular expression" field CHECKED, the matching key
            is considered to be a regular expression (regex) and,
            so that you can tell it's a regex, is displayed on
            the listing as emphasised (which may be italics or
            other text formatting based on the theme).
          + URL: The URL to which this autolink points.
          + Options:
               o Disable: If you wish to disable an Autolink but
                 not delete it from the Autolinks database, click
                 "Disable". The Autolink will not appear as a
                 link when matching text is found. To enable an
                 Autolink, click "Enable".
               o Edit: If you wish to edit an Autolink, click on
                 the "Edit" link for that Autolink. A panel is
                 displayed allowing you to edit all the
                 information about the selected Autolink.
                    # Type: Displays the Autolink Type. If you
                      wish to move an existing Autolink to a
                      different Autolink Type, select the "Move"
                      command under Admin->Autolinks->View
                      Links->Options.
                         @ Edit: If you wish to edit the Autolink
                           Type, click this link to go to the
                           Modify Autolink Type panel.
                    # Security
                         @ Name: Type the name of the Autolink as
                           it will be displayed in the Autolink
                           administration panels of the site.
                           Names are unique across all Autolinks
                           on a site. The name field exists
                           because the Keyword may be a regular
                           expression (see below) instead of a
                           simple name.
                         @ Enabled: If this box is CHECKED, the
                           Autolink.is enabled and will be
                           displayed if a matching key is found
                           content. If this field is UNCHECKED,
                           the Autolink is not displayed if a
                           matching key is found in content. The
                           "Example" field is displayed
                           regardless of the setting of this
                           field. Toggling this field will
                           recompile the autolink from the
                           template.
                    # Matching
                         @ Matching key: Xaraya searches content
                           items for this text, which must be
                           enclosed by white space, tags, or
                           punctuation. The punctuation
                           characters are defined in
                           Admin->Autolinks->Modify config. If
                           matching text is located, it is
                           replaced with the autolink.
                         @ Match as regular expression: This is
                           an advanced option within Xaraya.
                           CHECK this box to cause the Autolink
                           to be evaluated as a regular
                           expression instead of a string.
                           UNCHECK this box (default) to evaluate
                           the Autolink as a string. A regular
                           expression (frequently abbreviated to
                           "regex") is a way for a site
                           administrator to express how Xaraya
                           should look for a specified pattern in
                           Autolink text and then what to do when
                           each pattern match is found. For
                           example, a regular expression could
                           tell a program to search for all text
                           lines that contain the word "Windows
                           95" and then to print out each line in
                           which a match is found or substitute
                           another text sequence (for example,
                           just "Windows") where any match
                           occurs.
                           Regular expression matching is very
                           powerful in that a single regular
                           expression will match more than just
                           one word. For example, you may want to
                           match "Windows 98", "Windows 95", and
                           "Windows 9X" as a single autolink with
                           the same URL. Another reason for using
                           a regex is to split the matched string
                           into sub-strings. For example, you may
                           wish to match the text <article:aid>
                           (e.g., "<article:123>") and replace it
                           with a link. The template would need
                           to know just the "123" portion. The
                           regex can split the matched string
                           into the required parts, allowing the
                           seperate components to be passed to
                           the template.
                    # Replacing
                      Everything in this section depends on the
                      template. This section describes the
                      'standard' template; other templates may do
                      something completely different with these
                      fields. The sample templates included with
                      Autolinks will adhere to the standards
                      described below.
                         @ Title: Enter the title of the Autolink
                           in this field. The title is displayed
                           to site visitors as a tool-tip.
                         @ URL: Enter the complete URL for the
                           Autolink in this field. For external
                           sites, always include "http://" at the
                           beginning of the link. For local
                           links, just the path to the page is
                           sufficient (remember that you can use
                           Short URLs if they are enabled).
                         @ Comment: An optional comment on the
                           Autolink. The Comment field is not
                           currently used in any of the default
                           Autolink templates, however, it is
                           passed to the template in case someone
                           wants to use it.
                    # Other
                      Sample text to test link: In this field,
                      enter sample text to test the link. The
                      sample text (and resulting links) are
                      displayed on the Admin->Autolinks->View
                      Links panel. In Admin->Autolinks->Modify
                      config, you can specify how the sample text
                      will be displayed (sample, result, both, or
                      none).
                         @ Sample: (displayed in
                           Admin->Autolinks->View Links)
                         @ Result: (displayed in
                           Admin->Autolinks->View Links)
               o Click "Modify Autolink" to save changes.
               o Move:
                    # Move to Autolink Type:
                    # Click "Move" to save changes.
               o Delete: To delete an Autolink, click on the
                 "Delete" link for that Autolink. A panel will be
                 displayed asking you to confirm your request to
                 delete the Autolink. If you wish to delete the
                 Autolink, click "Confirm"; otherwise click
                 "Cancel deletion of Autolink" and the link will
                 not be removed.
     * Add Link
       To add a new Autolink, click this link. On the next panel,
       the following options are displayed.
          + Autolink Type: From this drop-down list, select the
            Autolink Type from the previously-defined Autolink
            Types.
          + Name: Enter the title of the site in the Name field
            (for example, "The Beatles Site"). If the name is
            left blank on the first panel, the value is taken
            from the matching key field. This is the name that
            will be displayed as a tool-tip and in the listing of
            all Autolinks.
          + Matching key: Enter the keyword or regex in the
            Matching key field. This is the text that will be
            matched in an article (for example, "beatles").

            Note

   Capitalization is not important in the Key (link) Word field.
          + URL: Enter the complete URL for the site in the URL
            field (for example, "http://www.beatles.com"). For
            external sites, always include "http://" at the
            beginning of the link. For local links, just the path
            to the page is sufficient (remember that you can use
            Short URLs if they are enabled).
            If the URL is located on your web site, enter the
            path to the file or the complete URL. For example, if
            the file is on your site, enter "music.html" and
            Autolinks will automatically prepend the
            "http://www.yoursite.com", resulting in an Autolink
            of "http://www.yoursite.com/music.html". To be more
            specific, you could also enter
            "http://www.yoursite.com/music.html" instead of just
            "music.html".
          + Comments: Use the Comments field to enter optional
            free-form alphanumeric comments about the link. The
            Comment field is not currently used in any of the
            default Autolink templates, however, it is passed to
            the template in case someone wants to use it.
          + Click "Create" to save changes. You are displayed a
            second panel where there may be additional fields to
            be populated, including any dynamic data fields
            defined for the Autolink Type. Creation of a new
            Autolink must be two-stage because dynamic data
            fields presented will depend on the chosen Autolink
            Type.
     * View Types
       To view, modify, or delete existing Autolink Types, click
       this link. On the next panel, the following options are
       displayed.
          + Name: The name of the Autolink Type as it is
            displayed in the Admin->Autolinks panel. Must be
            unique.
          + Template: Enter the name of the template file for
            this Autolink Type (link-{name}.xd). If you enter
            "underlined" in this field, Xaraya looks for a file
            called "link-underlined.xd". The file must exist with
            appropriate permissions and ownership in one of two
            locations on the site:
               o <xarroot>/modules/autolinks/xartemplates/ for a
                 site-wide template
                 or
               o <xarroot>/<themes_dir>/<theme_name>/modules/auto
                 links/ for a theme-specific template
          + Method: Either "Static" or "Dynamic", based upon the
            Execute Template Dynamically setting. It is useful to
            understand the difference between these two methods.
               o Static: A Method of Static will execute the
                 template the moment that "Modify" or "Save" is
                 clicked. The results are then stored away and
                 used to replace linked text.
               o Dynamic: A Method of Dynamic does not execute
                 the template when "Modify" or "Save" is clicked.
                 Instead, Dynamic will execute the template when
                 matching text is found. If the same matching
                 text appears ten times in a page, a Dynamic type
                 is executed ten times. There are two main
                 reasons why you might use the Dynamic Method:
                   1. The template performs some kind of lookup
                      to get additional details related to what
                      has just been matched, so that details can
                      be displayed that are not known at the time
                      the autolink is created (an article title,
                      for example).
                   2. You may have different autolink templates
                      in different themes and want to use the
                      appropriate template for the theme. This
                      will execute the theme template based on
                      the theme being viewed by the site visitor.
                      By contrast, a Static Method will 'freeze'
                      the template based on the theme the site
                      administrator is using at that time.
          + Description: Description of the Autolink Type. This
            is displayed within Admin->Autolinks as a bit of
            information for the site administrator.
          + Options: To edit or delete an existing Autolink Type,
            click the appropriate link next to the Autolink Type
            to edit or delete. If you choose to delete an
            Autolink Type, you are asked to confirm your choice
            on the next panel. If the Autolink Type contains
            autolinks, you are asked to confirm the intention to
            delete these Autolinks as well. Autolinks that are
            not assigned to an Autolink Type are not permitted.
     * Add Type
       Autolink Types are a group of similar-style or
       similar-functionality links based on a shared template for
       formatting, and sharing the same dynamic data properties
       if dynamic data is enabled. To add a new Autolink Type,
       click this link. This panel is also displayed when
       Modifying an Autolink Type. On the next panel, the
       following options are displayed.
          + Name: Type the name of the Autolink Type in this
            field.
          + Template name: Enter the name of the template file
            for this Autolink Type (link-{name}.xd). If you enter
            "underlined" in this field, Xaraya looks for a file
            called "link-underlined.xd". The file must exist with
            appropriate permissions and ownership in one of two
            locations on the site:
               o <xarroot>/modules/autolinks/xartemplates/ for a
                 site-wide template
                 or
               o <xarroot>/<themes_dir>/<theme_name>/modules/auto
                 links/ for a theme-specific template
          + Execute Template Dynamically: For default Autolinks
            operation (non-regular expression), leave this box
            UNCHECKED. To execute the template dynamically, CHECK
            this box.
          + Description: Description of the Autolink Type. This
            is displayed within Admin->Autolinks.
          + Click "Create" to save changes.
     * Modify config
       This section allows configuration of how Autolinks appear
       on your site.
          + Matching Rule Options
               o Punctuation characters: This list defines
                 characters that are allowed to border a linked
                 word. For example, if you want to match the word
                 "site" but not in the word "my-site", do not
                 define "-" as an allowed punctuation character.
               o Match non-breaking space entity as white space:
                 "&nbsp;" is an entity that represents ' ', while
                 ' ' is just a space. To match "$nbsp;" to a
                 space, CHECK this box. It is generally
                 recommended that this option be CHECKED unless
                 you have a specific reason to uncheck it. For
                 example, if this box is CHECKED, a link that
                 matches "my site" will also match "my&nbsp;site"
                 as well as "my site" and "my &nbsp; site". All
                 of these links will display the same if the
                 field is CHECKED, but you may not wish to match
                 non-breaking spaces. White space in non-matching
                 regular expressions is treated as white space,
                 regardless of what type or how long it is.
          + Action Options
               o Limit on number of times each link is used in a
                 piece of text: Enter the number of times in a
                 particular article that matching text will be
                 converted to an Autolink. For example, if you
                 would like a matching piece of text to be
                 converted to an Autolink twice in a single
                 article and subsequent matches would not be
                 converted, enter "2" in this field. To convert
                 ALL matching text within a particular article to
                 Autolinks, leave this field blank.
               o Autolink decoration (style will override class):
                 From the drop-down list, select the type of
                 decoration displayed for autolinks. This field
                 may be depreciated at some point, but it is
                 currently implemented for legacy reasons. The
                 definitions below are used on the default
                 templates. It is possible to over-ride these
                 settings in a link by using a dynamic data
                 property field called "style".
                    # Default: The default decoration style as
                      defined in the site's theme will be used.
                    # None: The autolink is displayed without any
                      decoration.
                    # Underline: The autolink text is underlined.
                    # Overline: The autolink text is overlined
                      (the opposite of underlining).
                    # Both: Both Underline & Overline decorations
                      are used to display the autolink.
               o Open links in new window: CHECK this box if you
                 would like Autolinks to open in a new window.
                 UNCHECK it to open Autolinks in the current
                 browser window. It is possible to over-ride this
                 setting in a link by using a dynamic data
                 property field called "target", where your own
                 targets may be defined.
               o Show template errors inline (errors shown in
                 content): Use this while debugging. If a link
                 does not execute the template properly, then it
                 will generate an error message. CHECKING this
                 field will show the error message as a tool-tip
                 over the matched text (the text showing as an
                 error class). UNCHECKING this field will leave
                 words that link to an erroneous template intact
                 - unmatched. The error message does not look
                 good on a site, so it should be UNCHECKED once
                 debugging is complete.
               o Template base name (affects all templates used):
                 Don't touch this unless you want to see what
                 template errors look like. Seemed like a good
                 option so an admin can switch between different
                 sets of links without changing theme.
          + Admin Options
               o Items per page: How many Autolinks would you
                 like to display per page? Enter that value into
                 this field, for example, "25".
               o Show sample links in list:
                    # None:
                    # Results only:
                    # Sample only:
                    # Sample and Results:
     * Click "Create Autolink" to add the Autolink to the
       database.
     _________________________________________________________

16.1.1.1. EXAMPLE: Adding AutoLinks to a Publication Type

   Adding AutoLinks to a Publication Type is very easy. There are
   two different methods for accomplishing this task, and we will
   cover them both in this example. Be sure you have some
   Autolinks defined (go to Admin->Autolinks->Add and add a few)
   and an article that contains Autolink text so you can see the
   results of your work.

     * Method 1. Go to Admin->Modules->View All. Next to the
       Articles line in the panel, click "On/Off" under the Hooks
       heading. On the next panel that appears, CHECK to enable
       Autolinks in specific Publication Type(s), or CHECK the
       ALL box to enable Autolinks in all Publication Types.
       Click "Save Changes" to save changes. You have just
       enabled Autolinks to Publication Type(s)!
     * Method 2. Go to Admin->Modules->Configure Hooks. In the
       next panel, click Autolinks. CHECK the specific
       Publication Types in which you wish to enable Autolinks,
       or CHECK the ALL ARTICLES box to enable Autolinks in all
       Publication Types. Click "Save Changes" to save changes.
       You have just enabled Autolinks to Publication Type(s)!
     _________________________________________________________

16.2. BBCode Module
     _________________________________________________________

16.2.1. BBCode Module

   Enables BBCode formatting.

   This module does not have an administration panel.

   Enables BBCode formatting markup tags in text fields on the
   site. When BBCode is activated for a module, that module will
   allow entry & display of BBCode tags. BBCode is a markup
   language that allows, among other options, making text bold by
   enclosing it in "[b]" and "[/b]" markups (for example,
   "[b]Bold Text[/b]").

   When this module has been hooked to another module (for
   example, if you enable BBCode in Articles), an editor page
   will display BBCode formatting quick-buttons. If text in a
   text field is highlighted, it can be transformed by clicking
   one of the BBCode quick-buttons. For example, if text was
   highlighted in a text area and the "I" (italics) BBCode
   quick-button was clicked, the italics tags would be added
   before and after the highlighted text.
     _________________________________________________________

16.2.1.1. EXAMPLE: Adding BBCode / BBClick to a Publication Type

   To add BBCode formatting capability or BBClick transformation
   to a Publication Type, follow these steps:

     * Go to Admin->Modules->Configure Hooks.
     * Click BBCode to select it as the module providing extra
       functionality. The panel will refresh, and you will see a
       list of modules to which the BBCode module can be hooked.
     * CHECK the module(s) in which you would like to enable
       BBCode formatting. For our example, CHECK "all articles"
       and "comments". Click "Save Changes" to save changes.

   Go to Admin->Articles->Add Article. Click the "News Articles"
   Publication Type. On the resulting panel, the BBCode Form
   Controls are displayed above the Category selector box. Using
   these controls, or by manually entering BBCode formatting
   markup, BBCode can be used in articles.

   To add BBClick capability, just go through the steps again
   substituting BBClick for BBCode.
     _________________________________________________________

16.3. BBClick Module
     _________________________________________________________

16.3.1. BBClick Module

   Make clickable hooks out of text. Automatically transforms
   URLs entered into text fields into clickable links.

   This module does not have an administration panel.
     _________________________________________________________

16.4. Censor Module
     _________________________________________________________

16.4.1. Censor Module

   Censor objectionable words. Admin->Censor.

   This module allows a site administrator to automatically
   filter -- or 'censor' -- objectionable words or phrases from
   the site.

     * Add Censored Word
       Add items to the list of objectionable words to be
       filtered by clicking Admin->Censor->Add.
          + Keyword: Enter the keyword/phrase (the objectionable
            word/phrase) to be filtered in this field.
          + Click "Create Censor" to save changes.
     * View
       View items on the list of objectionable words/phrases by
       clicking Admin->Censor->View.
          + Key word: Each objectionable word/phrase is listed
            alphabetically.
          + Options: For each word/phrase, the following options
            are available.
               o Edit: Permits modification of an objectionable
                 word/phrase. Click "Modify Censor" to save
                 changes.
               o Delete: Permits deletion of an objectionable
                 word/phrase. Confirm your intention to delete
                 the item on the next panel.
     * Modify config
       This panel allows modification of configuration options
       for this module.
          + Replace censored word with: If the Censor module
            finds objectionable text, it will be replaced with
            the text entered in this field. For example, "****"
            will replace any objectionable word/phrase with
            "****".
          + Items per page: How many objectionable items would
            you like to have displayed per page. Enter that value
            in this field. For example, "20".
          + Click "Submit" to save changes.
     _________________________________________________________

16.5. Comments Module
     _________________________________________________________

16.5.1. Comments Module

   Allows users to post comments in any module that uses hooks.
   Admin->Comments.

     * Overview: Displays the overview panel for this module.
       This panel contains information about the module and how
       to use it.
     * View Statistics: This panel displays statistics about all
       comments on the site. From this panel the administrator
       can see the total number of comments and where the
       comments are located. Additional actions allow deletion of
       comments, either selective or complete.
          + Module name: The name of the module containing
            comments. Click the module name to go to that
            module's statistics panel containing figures for each
            of that module's pages that have comments associated
            with them. From that panel, you can delete all
            comments associated with a particular page.
          + Module pages: Displays a count of the pages within a
            particular module which contain comments.
          + Total comments: Displays a count of total comments.
          + Inactive comments: Displays a count of inactive
            comments.
          + Action:
               o Delete: By clicking "Delete" you can delete all
                 comments associated with a particular module. To
                 delete all comments associated with a particular
                 module, click "Delete" and confirm your
                 intention to delete on the following panel.
               o Delete All: Click this link to delete ALL
                 comments associated with ALL modules. On the
                 following panel, confirm your intention to
                 delete all comments from all modules.
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Default rendering depth:
               o 1...9: From this drop-down list, select the
                 default rendering depth for comments on the
                 site. This setting determines how many levels of
                 comments are displayed. For example, if you set
                 it to "2", Xaraya will show the top 2 levels of
                 comments and a setting of "9" will show up to 9
                 levels of nested comments. It is unlikely that
                 you'll experience 9 nested levels of comments.
                 An example of 9 nested comments is a reply to a
                 reply to a reply to a reply to a reply to a
                 reply to a reply to a reply to a reply!
                 If a message's comments go beyond the default
                 rendering depth, a message is displayed
                 notifying the user that the particular message
                 has additional comments that are not displayed,
                 and that the user can click the message to
                 display all the comments. Suggested setting is
                 "9".
          + Default rendering style:
               o Nested: Comments are displayed with child
                 comments 'nested' (indented slightly) underneath
                 their parent comments. This is a recommended
                 setting, as it is easy to visually track
                 comments and sub-comments. Comments are
                 displayed expanded.
               o Flat: Comments are displayed with child comments
                 in the same level (no indentation) as their
                 parents. Comments are displayed expanded.
               o Threaded: Threaded view displays comments in a
                 tree-like structure with the parent comment at
                 the top with child comments below. The threaded
                 view is similar to the default view in many mail
                 readers, along with cute threaded images.
                 Comments are displayed collapsed.
               o No comments: Do not display comments. If a user
                 turns off comments while reading comments (not
                 in user preferences but on an actual page with
                 comments) the only way to turn them back on at
                 the moment is by going to user preferences.
          + Default sorting mode: Defines the default sorting
            mode for comments. Registered users can change their
            sort order if they wish. Default sorting mode relies
            on Default sorting order, below, to determine if the
            items are displayed in ascending or descending order.
               o Author: Sort comments by the author's username.
               o Date: Sort comments by the date/time of the
                 comment.
               o Thread: Sort comments into threads.
               o Title: Sort comments by the title of the
                 comment.
          + Default sorting order: Defines the sorting order for
            comments. Registered users can change their sort
            order if they wish. Default sorting order relies on
            Default sorting mode, above, to determine if the mode
            for sorting.
               o Ascending: Display oldest-to-newest /
                 alphabetical order.
               o Descending: Display newest-to-oldest / reverse
                 alphabetical order.
          + Allow registered users to post anonymously?: If
            CHECKED, an option is provided whereby a registered
            user can post a comment anonymously. The user name is
            always displayed to the site administrator.
          + Click "Update Configuration" to save changes.
     _________________________________________________________

16.6. Changelog Module
     _________________________________________________________

16.6.1. Changelog Module

   Tracks changes to module items. Admin->Changelog.

   The DocBook for this Guide is being developed.

     * Modify config:
       This panel allows modification of configuration options
       for this module.
          + Fields (comma-separated list):
          + Click "Update Change Log Configuration" to save
            changes.
     _________________________________________________________

16.7. Hitcount Module
     _________________________________________________________

16.7.1. Hitcount Module

   Count displays of module items. Admin->Hitcount.

   The Hitcount module is a utility module that counts the number
   of hits on items on the site.

     * View Statistics:
          + Module name: Click on a module name to go to that
            module's statistics page containing figures for each
            of that module's items that have hit counts
            associated with them.
            If you click the name of a module, the next panel
            displays a listing of items (and, if you've CHECKED
            "Show the item title in statistics" in
            Admin->Hitcount->Modify config, the title of the
            item).
            Click "Total hits" to sort the list by hits.
            Click "Delete" to delete the hit counts associated
            with a particular module or item. Note that the
            module and module contents are not deleted by this
            function. On the next panel you are asked to confirm
            your intention to delete. Once you confirm, the hit
            counts are deleted for the item.
          + Module items: The total number of items associated
            with the module.
          + Total hits: The total hits for all items within the
            module.
          + Grand total: The grand total of each column.
          + Action:
               o Delete: By clicking Delete you can delete the
                 hit counts associated with a particular module
                 or item. Note that the module and module
                 contents are not deleted by this function. On
                 the next panel you are asked to confirm your
                 intention to delete. Once you confirm, the hit
                 counts are deleted for the item.
               o Delete All: By clicking Delete All you can
                 delete all hit counts. Note that module and
                 module contents are not deleted by this
                 function. On the next panel you are asked to
                 confirm your intention to delete. Once you
                 confirm, the hit counts are deleted for all
                 items.
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Count Administrator Hits: If you would like for the
            Administrator's hits to increment the counter, CHECK
            this box. If you do not wish for the Administrator's
            hits to increment the counter, UNCHECK this box.
          + Number of top items shown to users: In this field,
            select the number of top items to display to site
            visitors. For example, if you wish to display the top
            10 items, enter "10" in this field.
          + Number of items shown in statistics: In this field,
            enter the number of items shown per page in the
            administrator's statistics view
            (Admin->Hitcount->View Statistics-><category_name>).
            If you wish to display 50 items per page, enter "50"
            in this field.
          + Show the item title in statistics: CHECK this box to
            display the item title in Admin->Hitcount->View
            Statistics-><category_name>. If this box is
            UNCHECKED, only the item number (and not the title)
            is displayed in the statistics view.
          + Click "Update Users Configuration" to save changes.
     _________________________________________________________

16.8. Keywords Module
     _________________________________________________________

16.8.1. Keywords Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

16.9. Pubsub Module
     _________________________________________________________

16.9.1. PubSub Module

   Allow users to subscribe to updates to site items.
   Admin->Pubsub.

     * View All:
          + Module name:
          + Category:
          + Subscribers:
          + Action:
     _________________________________________________________

16.10. Ratings Module
     _________________________________________________________

16.10.1. Ratings Module

   Rate Xaraya items. Admin->Ratings.

   The ratings module allows users to submit their rating of site
   content. There is a default configuration set, followed by a
   specific configuration set for any modules to which the
   Ratings module is hooked. It is recommended that you select
   one rating style for your whole site to avoid confusion.

     * View Statistics:
          + Module Name:
          + Module Items:
          + Total Ratings:
          + Action:
               o Delete: By clicking "Delete" you can delete all
                 ratings associated with a particular module.
                 Clicking on a module's name takes you to that
                 module's statistics panel which contains the
                 figures for each of that module's items that
                 have ratings associated with them. From there
                 you can delete all ratings associated with a
                 particular item.
               o Delete All:
          + Grand Total:
     * Modify config:
          + Default configuration
               o Rating Style: Select the rating style from the
                 drop-down list.
                    # Percentage: The user enters a value from
                      "0" to "100" to indicate their satisfaction
                      with the content. The rating is displayed
                      as a percentage out of 100.
                    # Number out of five: Users select a value
                      from "0" through "5" from the drop-down
                      list to indicate their satisfaction with
                      the content. "5" is the most satisfied, "0"
                      is the least. The rating is displayed as a
                      number out of five.
                    # Stars out of five: Users select a value
                      from "0" through "5" from the drop-down
                      list to indicate their satisfaction with
                      the content. "5" is the most satisfied, "0"
                      is the least. The rating is displayed as
                      stars out of five.
                    # Number out of ten: Users select a value
                      from "0" through "10" from the drop-down
                      list to indicate their satisfaction with
                      the content. "10" is the most satisfied,
                      "0" is the least. The rating is displayed
                      as a number out of ten.
                    # Stars out of ten: Users select a value from
                      "0" through "10" from the drop-down list to
                      indicate their satisfaction with the
                      content. "10" is the most satisfied, "0" is
                      the least. The rating is displayed as stars
                      out of ten.
               o Security Level: Select the security level for
                 ratings from the drop-down list.
                    # Low: Users can submit a rating multiple
                      times.
                    # Medium: Users can submit a rating once per
                      day.
                    # High: Users must be logged in and can only
                      submit a rating once.
          + Configuration for hooked modules: A specific Rating
            Style and Security Level may be configured
            independently for each hooked module. Hooked modules
            are listed below Default Configuration, and the
            Rating Style and Security Levels function in the same
            way as in Default configuration, above.
     _________________________________________________________

16.10.1.1. EXAMPLE: Adding Ratings to a Publication Type

   OTTO
     _________________________________________________________

16.11. Search Module
     _________________________________________________________

16.11.1. Search Module

   Search for data on a Xaraya site. No administration panel.

   The Search module provides site visitors full-site text search
   capability. The searches may be limited by Author, Publication
   Type, and Category. The search phrase is entered into the
   "Search for:" box and the "Search" button is pressed, the
   search is executed and a clickable list of results is
   displayed.
     _________________________________________________________

16.12. Subitems Module
     _________________________________________________________

16.12.1. Subitems Module

   Dynamic data subitems. Admin->Subitems.

   The documentation for this part of the Guide is being
   developed.

     * Add link:
          + Dynamicdata ObjectId:
          + Hook-Module Name:
          + Hook-Module Itemtype:
          + Hook-Module Template:
          + Click "Create New DDSubobjectlink" to save changes.
     * View links:
          + Module:
          + ItemType:
          + ObjectID:
          + Template:
          + Actions:
               o Edit:
               o Delete:
     * Modify config:
          + Enable Short URLs?: CHECK this box to enable Short
            URLs for this module. UNCHECK this box to disable
            Short URLs for this module. Short URL support must be
            enabled in Admin->Base->Modify config for Short URLs
            to function.
          + Check "Update Configuration" to save changes.
     _________________________________________________________

16.13. Smilies Module
     _________________________________________________________

16.13.1. Smilies Module

   Transform smilies to images. Admin->Smilies.

   The Smilies module transforms text that uses smilies code into
   graphical images.

     * Add:
          + Smiley Code: The text entered by a site visitor to
            generate the smiley.
          + Smiley Icon Path: The path to the smiley image file.
          + Smiley Emotion: Text describing the emotion conveyed
            via the smiley. Used as mouseover text if a user
            hovers over the smiley.
          + Click "Create Smiley" to save changes.
     * View:
          + Smiley Code: The text entered by a site visitor to
            generate the smiley.
          + Smiley Icon: The smiley itself.
          + Smiley Icon Path: The path to the smiley image file.
          + Smiley Emotion: Text describing the emotion conveyed
            via the smiley.
          + Options:
               o Edit: Click the "Edit" link next to the smiley
                 you wish to edit. Make any required changes and
                 click "Modify Smiley" to save changes.
               o Delete: Click "Delete" next to the smiley you
                 wish to delete. On the next panel, confirm your
                 intention to delete and the smiley is deleted.
     _________________________________________________________

16.13.1.1. EXAMPLE: Adding Smilies to a Publication Type

   OTTO: To be written.
     _________________________________________________________

16.14. Workflow Module
     _________________________________________________________

16.14.1. Workflow Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

16.15. Wiki Module
     _________________________________________________________

16.15.1. Wiki Module

   Allow Wiki formatting in Xaraya items. No administration
   panel.

   This module does not have an administration panel.
     _________________________________________________________

16.16. XLink Module
     _________________________________________________________

16.16.1. Xlink Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

16.17. XarLinkMe Module
     _________________________________________________________

16.17.1. XarLinkMe Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

16.18. XSLT Module
     _________________________________________________________

16.18.1. XSLT Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

16.19. Figlet Module
     _________________________________________________________

16.19.1. Figlet Module

   Transform text to ASCII art. Admin->Figlet.

   This is an EXTREMELY important module for Xaraya. Perhaps the
   single most important module, because no other Xaraya module
   allows a user to enter plain old text and convert it to nice,
   useless ASCII art. Just kidding. This is a fun module, nothing
   more.

     * Modify config: This panel allows modification of
       configuration options for this module.
          + Available fonts: This drop-down list is simply a
            DISPLAY of fonts that are available for the Figlet
            module. Fonts must exist in the
            <xarroot>/modules/figlet/xarfonts directory with
            appropriate ownership and permissions, and any new
            fonts you wish to install go into that directory.
            Note that Figlet uses FLF-format font files. Check
            http://www.figlet.org for information on fonts for
            use with Figlet.
          + Click "Submit" to save changes.
     _________________________________________________________

16.20. MyBookmarks Module
     _________________________________________________________

16.20.1. MyBookMarks Module

   MyBookmarks allows sharing of your favorite URLs.
   Admin->Mybookmarks.

   The MyBookmarks module gives your users a way to add their
   favorite bookmarks to a sitewide database. The Bookmarks block
   with each user's personal bookmarks, will be displayed on
   thier Roles My Account page. The Random Bookmarks block will
   pull a random link from the master database of all user's
   bookmarks.

     * Overview: Provides a general overview of the module.
     * Main page: OTTO
     * View bookmarks: From this panel, you can view all
       bookmarks on the site. You have options for maintaining
       the bookmarks and adding new ones from this panel.
          + ID: The ID number of the bookmark.
          + Username: The username of the user who added the
            bookmark. Click the username to view User
            Information.
          + Link name: The name of the bookmark as entered by the
            user who added it.
          + URL: The URL for the bookmark as entered by the user
            who added it. Click the URL to visit the page.
          + Options:
               o View: Displays another view of the bookmark
                 entry in the site's database, but does not view
                 the actual bookmarked page.
               o Modify: Click this link to modify the link name
                 and/or URL. From this panel, you may view the
                 profile of the user who added the bookmark.
                 Click "[ check ]" to open the URL in a new
                 window. Modify the values as necessary, then
                 click "Modify" to save changes, "Preview" to
                 preview the changes without saving, or "Cancel"
                 to abort the modification without saving.
               o Delete: Click "Delete" to delete an existing
                 bookmark.

                 Note

   You are not asked to confirm your intention to delete an item
   when clicking this link.
               o New: Click "New" to add a new bookmark to the
                 site. On the following panel, enter the Link
                 Name & URL for the link you wish to add. Click
                 "Create" to save changes, "Preview" to preview
                 the database entry without saving, or "Cancel"
                 to abort the addition without saving.
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Configure Module
               o Short URL support:
               o Click "Modify" to save changes, or "Cancel" to
                 cancel changes.
          + Bookmark configuration
               o Modules per page:
               o Click "Modify" to save changes, or "Cancel" to
                 cancel changes.
     _________________________________________________________

16.21. Overlib Module
     _________________________________________________________

16.21.1. Overlib Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

Chapter 17. Maintaining Your Xaraya Site

   This section deals the day-to-day operation of a Xaraya site.
   It is under development.

   OTTO: Does Xaraya have a best practices for routine maintence?

   In general, Xaraya runs without any need for pre-emptive or
   recurring maintenance. However, some features could benefit
   from some attention to keep your site running smoothly. This
   section contains a few things that could be done on a regular
   basis.

     * Example backup script
       Although many webmasters have copies of their website on
       their local workstations, they often neglect to make a
       copy of their database. A backup of both website and
       database needs to be done regularly to protect against
       catastrophic data-loss situations. Included below is a
       useful script for backing up the web site's database and
       files.
       # xaraya-bu.sh | 1.12
       #==============+ by Drew Vogel (drew@xaraya.com)
       # This script will:
       #       * Backup files from the <webdir> (recursive) into
       a file in the
       #         root directory called webdir.tar.gz
       #       * Perform a dump of the Xaraya database into a fil
       e
       #         called Xaraya.sql in the root directory,
       #       * Archive all backup up files into one archive,
       #       * Copy the archive to a specified location, and
       #       * Clean up all its temp files.
       #
       # Define some variables
       #
       # In BACKUP_TABS, put a list of database table names, sepa
       rated by a space,
       # that you would like to backup from MySQL.
       BACKUP_TABS="Xaraya"
       #
       # MYSQL_USER is your MySQL administrator username.
       #
       MYSQL_USER=username
       #
       # MYSQL_PASSWORD is your MySQL administrator password.
       #
       MYSQL_PASSWORD=password
       #
       # DATE stores the format of the filename. In this case, it
        results in a XAR prefix with
       # a date string, like: XAR-23Oct2002.
       #
       DATE=$(date +XAR-%d%b%Y)
       #
       # Change the two lines below to the directory you want to
       backup.
       #
       cd /var/www/html
       #
       # The script itself
       #
       echo "Backing up /var/www/html/ directory to archive webdi
       r.tar.gz..."
       tar -cpzvf ~/webdir.tar.gz *
       echo "...done."
       cd ~/
               for TAB in $BACKUP_TABS;do
                       echo "Creating dump of $TAB database..."
                       mysqldump -u $MYSQL_USER -p$MYSQL_PASSWORD
        -B $TAB -c -a --add-drop-table >~/$TAB.sql
                       echo "...done."
               done
       echo "Adding the files to archive $DATE.tar.gz..."
       cd ~/
       #
       # Edit the line below to include the tablenames from the d
       atabase.
       #
       tar -czvf $DATE.tar.gz Xaraya.sql
       echo "...done."
       #
       # Edit the line below to specify the destination directory
       .
       #
       echo "Copying $DATE.tar.gz archive to /var/www..."
       cd ~/
       #
       # Edit the line below to specify the destination directory
       .
       #
       cp $DATE.tar.gz /var/www/
       chmod 770 /var/www/$DATE.tar.gz
       #
       # Edit the line below to specify the destination directory
       .
       #
       echo "...done."
       echo "Cleaning up..."
       cd ~/
               for TAB in $BACKUP_TABS;do
                       echo "CLEAN UP: Deleting $TAB..."
                       /bin/rm $TAB.sql
                       echo "...done."
               done
       rm webdir.tar.gz
       rm $DATE.tar.gz
       ls -l /var/www/$DATE.tar.gz
       echo "...done."
       echo "Xaraya backup complete!"
     _________________________________________________________

17.1. Logging

   Logging your site can often help with tracking down problems
   and odd behaviour.

   To enable basic logging on your Xaraya site edit
   var/config.system.php and make sure the following lines exist
   and are not commented out: (the filename can be changed as
   appropriate)

   $systemConfiguration['Log.LogLevel'] = 'DEBUG';
   $systemConfiguration['Log.LoggerName'] = 'simple';
   $systemConfiguration['Log.LoggerArgs'] = array('fileName' =>
   'var/logs/log.txt');

   Changing the 'simple' to 'dummy' will disable the logger.

   [ marcel to add content here on other loggers ]
     _________________________________________________________

17.2. Sitetools Module
     _________________________________________________________

17.2.1. SiteTools Module

   Set of tools for site and database maintenance. This module
   allows you to flush (delete) cache files in either of all of
   your Template, RSS or adodb cache directories.
   Admin->Sitetools.

   The Site Tools Module provides a set of utilities to assist in
   managing cache files, and databases for your site, from within
   Xaraya. As time progresses, other site utilities may be added
   to this module, so you should check for an upgrade in
   Admin->Modules listings when installing new versions of Xaraya
   or this module.

     * Optimize database:
       This utility allows you to optimize your database. Tables
       are listed with optimization status, and the amount of
       space saved through an optimization. At this time only
       MySQL databases are supported, but we expect this will be
       expanded to other database types with time, as well as the
       ability to choose from one or more databases.
       Click "Optimize Now!" to optimize your database.
       Optimization totals are displayed on the next panel when
       optimization has completed.
     * Backup database:
       Before this option can be used, a Backup Path must be
       configured in Admin->Sitetools->Modify config. The path
       must exist and be world-writable. The backup database
       utility allows you to create one of four different types
       of database backups:
          + Full backup with complete inserts
          + Full backup with standard inserts (a smaller file)
          + Partial backup: all tables are listed with their
            number of records and you can choose the tables to
            backup.
          + Structure only: only the structure of your database
            will be backed up. No content.
       In all options, you can choose to create a compressed gz
       file, or text sql file. The gz option will only be
       effective if your server has gz option available.
       At this time only MySQL databases are supported, but we
       expect this will be expanded to other database types with
       time, as well as the ability to choose from one or more
       databases.

   Note

   Do not leave your backup file on the server in a web browsable
   directory. Remember to move it to a secure directory, or
   delete the file when you have saved it to your local computer.
     * Clear Cache files:
       This option allows you to flush (delete) cache files in
       any/all of your Template, RSS, or ADODB cache directories.
       To select the caches to be flushed, CHECK the box. If a
       box is left UNCHECKED, the cache files for that directory
       will not be removed. Click "Confirm deletion" to perform
       the deletion of cache files.
     * Browse Cache files:
       This option allows you to list and browse all cache files
       in your Template cache directory, with the corresponding
       template file listed. By clicking on a listed file you can
       browse the contents which are displayed with line
       numbering. This is useful when debugging new templates, or
       isolating problems with existing templates.
     * Modify config:
          + Cache file options: Set paths to your template, RSS,
            and ADODB caches. These should not be changed unless
            you physically configure new directories for cache
            files. Unless you did this through the Multisite
            Module, you would have to make changes to the Xaraya
            code for this.
          + Backup Options: You must enter the path to the
            directory where your backup files will be created.
            The default is the <xarroot>/var/uploads directory as
            this is writeable (chmod 777). If you change this,
            make sure your backup directory exists and is
            writeable.
          + Use timestamps in backup files: By checking this, a
            time stamp will be written into the name of any
            backup files that are created.
          + Columns for display: For partial backups, all tables
            are displayed for selection and inclusion into the
            backup. This option allows you to change the number
            of columns used for display.
          + Click "Update Configuration" to save changes.
     _________________________________________________________

17.3. HTML Module
     _________________________________________________________

17.3.1. HTML Module

   Configure the allowed HTML for your site. Admin->Html.

   This table displays the HTML tags that Xaraya will accept in
   content submissions, either from users or from Administrators.
   All content entry areas accept HTML tags based on the
   specifications in this table. To modify the settings, click
   Admin->Html->Set Allowed. Specify if the tag is 'Not Allowed',
   'Allowed', or 'Allow Parameters'.

     * Not allowed: The HTML tag is never allowed and will be
       ignored in the post.
     * Allowed: The HTML tag is allowed without any parameters.
       This is useful for on-or-off text-formatting tags (for
       example, <b> and </b> for BOLD, <i> and </i> for ITALICS,
       etc.).
     * Allow parameters: The HTML tag is allowed with parameters.
       An example of a tag with parameters is <font type="Arial"
       color="#FF0000">.

   If you would like to add an HTML tag that is not in the table,
   click Admin->Html->Add and enter the HTML tag into the text
   box. It is not necessary to enclose the tag in "<" and ">".
   Click "Create HTML Tag" to save changes. The new tag is
   inserted into the HTML tag list as "Not allowed". Edit the
   setting as necessary.

   To delete an HTML tag from the table, click "Delete" next to
   the tag. Confirm your intention to delete the tag by clicking
   "Submit", or click "Cancel deletion of HTML Tag" to abort
   deletion.

   Click "Submit" to save changes.
     _________________________________________________________

17.4. Mail Module
     _________________________________________________________

17.4.1. Mail Module

   Mail handling utility module. Admin->Mail.

   The Mail module controls how your Xaraya system sends mail to
   users or groups of users. This module is a utility module that
   takes information from other modules installed on your Xaraya
   system and formats mail messages for them. This module allows
   you to use SMTP, SendMail, or the normal PHP Mail functions to
   send mail to site visitors.

     * Modify config: This panel allows modification of
       configuration options for this module.
          + Modify Mail Configuration
               o Admin Name: Enter the name of the site
                 administrator here. For example, "Joe Admin".
               o Admin Email: Enter the site administrator's
                 complete email address in this field.
               o Add different reply-to: If CHECKED, email
                 messages from the site are sent with a different
                 Reply-To Name & Address. Two additional fields
                 become available:
                    # Reply To Name: Enter the name that replaces
                      the Admin Name, above.
                    # Reply To Email: Enter the email address
                      that replaces the Admin Email, above.
               o Send HTML Emails?: If CHECKED, HTML formatted
                 emails will be sent, and two additional fields
                 become available after clicking the "Update Mail
                 Configuration" button.
                    # HTML Email Header: In this field, enter the
                      complete HTML header for emails sent from
                      this site.
                    # HTML Email Footer: In this field, enter the
                      complete HTML footer for emails sent from
                      this site.
               o Default Word Wrap Size: Set the word-wrap size
                 for emails sent from this site in this field.
                 For example, set to "78".
               o Default Priority to send messages: From the
                 drop-down list, select the default priority for
                 messages that are sent from the site. Some email
                 readers handle messages with higher priorities
                 in different ways, marking them with a flag or
                 playing a sound, for example.
                    # High: Send email messages from the site
                      marked as high priority.
                    # Normal: Send email messages from the site
                      marked as high priority. This is the
                      recommendation, and the default.
                    # Low: Send email messages from the site
                      marked as low priority.
               o Default method to send mail: From the drop-down
                 list, select the default method to be used for
                 sending messages from the site. Use the email
                 sub-system on the site, or select Mail to use
                 PHP's built-in mail handling system.
                    # SMTP: Use SMTP to send email from the site.
                    # Sendmail: Use Sendmail to send email from
                      the site.
                    # Mail: Use PHP's mail functions to send
                      email from the site.
                    # QMail: Use QMail to send email from the
                      site.
          + Filtering Options
               o Strings for search: You can specify custom
                 strings of text that will be replaced in site
                 emails. Enter each string on a single line. Do
                 not separate with commas or other punctuation.
                 Suggested format is "%%string%%" (without
                 quotes) to ensure that no conflict exists.
               o Strings for replacement: Enter each string on a
                 single line in the same order as the search
                 (above). Do not separate with comma, etc.
          + Click "Update Mail Configuration" to save changes.
     _________________________________________________________

17.5. Sniffer Module
     _________________________________________________________

17.5.1. Sniffer Module

   Used for browser detection. No administration panel.

   This module does not have an administration panel.
     _________________________________________________________

17.6. Stats Module
     _________________________________________________________

17.6.1. Stats Module

   Site statistics. Admin->Stats.

   The Statistics module collects data about visitors to your
   website. To use the Stats module, install the module, set the
   configuration options as you would like, and the Stats module
   begins to collect data.

     * Modify config: This panel allows modification of
       configuration options for this module.
          + Count Administrator Hits: If you wish for the hits
            made by the site administrator to increment the
            statistics, CHECK this box. If you do not wish for
            hits made by the site administrator to increment the
            stats, UNCHECK this box.
          + Click "Update Users Configuration" to save changes.
     _________________________________________________________

17.7. Referer Module
     _________________________________________________________

17.7.1. Referer Module

   Referer Tracking. Statistics extension. Admin->Referer.

   This panel shows who has been linking to your site and how
   they are locating your site. It provides an interesting look
   at how your site is being accessed from the internet.

     * View:
          + URL: Displays the URL from which your site is linked,
            or "Bookmark" if the requests originate from a user's
            bookmark file.
          + Frequency: The number of unique requests from the
            particular URL.
          + Delete Referers: Click this link to clear the listing
            of referers. You are asked to confirm your intention
            to delete and, if you confirm, the existing referers
            are cleared.
     * Modify config:
          + Items per page: In this field, specify the number of
            referers to display per page. For example, if you
            wish to display 100 referers, enter "100" in this
            field. Click "Submit" to save changes.
     _________________________________________________________

17.8. Opentracker Module
     _________________________________________________________

17.8.1. OpenTracker Module

   Xaraya wrapper around phpOpenTracker statistics tracking
   system (http://www.phpopentracker.de). No administration
   panel.

   This module does not contain any administrator-modifiable
   settings, so has no administration panel.
     _________________________________________________________

Chapter 18. Using Web Services with Xaraya

   OTTO: explain webservices usage with Xaraya
     _________________________________________________________

18.1. MetaWeblogApi Module
     _________________________________________________________

18.1.1. MetaWebLogAPI Module

   Metaweblog API implementation. No administration panel.

   This module does not have any configurable options.
     _________________________________________________________

18.2. BloggerApi Module
     _________________________________________________________

18.2.1. BloggerAPI Module

   Blogger API implementation for Xaraya. Admin->Bloggerapi.

     * Modify config:
       This panel allows modification of configuration options
       for this module.
          + Blogger API publication type: From the drop-down
            list, select the Publiction Type for which BloggerAPI
            is activated, or "None" if you do not wish to
            activate BloggerAPI.
               o None: Not configured: If you do not wish to use
                 BloggerAPI, select this option.
               o <publication type>: From the drop-down list,
                 select the Publiction Type for which BloggerAPI
                 is activated.
               o Click "Update bloggerapi Configuration" to save
                 changes.
     _________________________________________________________

18.3. Soapserver Module
     _________________________________________________________

18.3.1. SOAPserver Module

   SOAP server implementation for Xaraya. Admin->Soapserver.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

18.4. XMLRPCServer Module
     _________________________________________________________

18.4.1. XMLRPCserver Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

18.5. XMLRPCSystemApi Module
     _________________________________________________________

18.5.1. XMLRPCsystemAPI Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

18.6. XMLRPCValidatorApi Module
     _________________________________________________________

18.6.1. XMLRPCvalidator Module

   Xaraya module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

18.7. Trackback Module
     _________________________________________________________

18.7.1. TrackBack Module

   (Modules distribution): Implements the Trackback specification
   for Xaraya. No administration panel.

   This module does not have an administration panel.
     _________________________________________________________

18.8. Ping Module
     _________________________________________________________

18.8.1. Ping Module

   Xaraya ping module.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

Chapter 19. Miscellaneous Xaraya Modules

   This section describes some Xaraya modules that don't really
   fit anywhere else so they are grouped together here.
     _________________________________________________________

19.1. Translations Module
     _________________________________________________________

19.1.1. Translations Module

   Translation handling for Xaraya. Admin->Translations.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

19.2. Window Module
     _________________________________________________________

19.2.1. Window Module

   Incorporate external sites or stand-alone apps. Admin->Window.

   The Window module is a port of the popular PostWrap module
   (for PostNuke) to Xaraya. It lets you display stand-alone
   external web pages from within your Xaraya site.

     * The Window module uses the center block to display
       external page(s).
     * Pages correspond to URLs. You can display pages off your
       local server, or from the Internet.
     * You can define a number of different options for your
       external page(s), among them the height and width of the
       display, whether only registered users may see them, and
       so on.
     * You can display as many pages as you like, each with its
       own settings.

   The following options are available under Admin->Window:

     * General settings: These are the general, default settings
       for the URLs that are entered in this module. Specific
       overrides are available for URLs; see "URL-specific
       settings", below.
          + Display off-site pages:
          + Use buffering of output before sending:
          + Allow input from browser address bar:
          + Compare URL against URL security in database:
          + Only for registered users:
          + Add link for "Open in new window":
          + Use fixed title:
          + Auto-resize window:
          + Height of viewing window (in pixels). Only if
            Auto-resize window, above, is set to NO, in which
            case this field specifies the height of the content
            window.
          + Width of viewing window (in pixels or percent). If
            you're entering a percent, enter it with the "%"
            symbol, for example, "75%".
          + Click "Save changes" to save changes.
     * URL-specific settings: The site administrator can
       configure options on a URL-by-URL basis in this panel.
          + Existing URLs: View, edit, or delete existing URL
            records in this section of the panel.
               o URL address: The complete URL (including
                 "http://") for the site.
               o Alias: The alias for the site as displayed to
                 site visitors.
               o Options:
                    # Edit: To edit a specific URL, click "Edit"
                      next to it.
                    # Delete:
          + New URL: Add a new URL to the module & set options.
               o URL address field: The complete URL (including
                 "http://") for the site you wish to add. For
                 example, "http://www.bluesnews.com".
               o Alias field: The alias for the site as displayed
                 to site visitors. For example, "BluesNews".
               o Only for registered users:
               o Add link for "Open in new window":
               o Use fixed title:
               o Auto-resize window:
               o Height of viewing window (in pixels). Only if
                 Auto-resize window, above, is set to NO, in
                 which case this field specifies the height of
                 the content window.
               o Width of viewing window (in pixels or percent).
                 If you're entering a percent, enter it with the
                 "%" symbol, for example, "75%".
               o Click "Add" to save changes.

   Once URLs are populated in the Window module, you may open
   them in your site by linking to
   "http://www.mysite.com/index.php?module=window&page=<your
   page>". For example,
   "http://www.yoursite.com/index.php?module=window&page=http://w
   ww.bluesnews.com". or
   "http://www.yoursite.com/index.php?module=window&page=BluesNew
   s".
     _________________________________________________________

19.3. BKView Module
     _________________________________________________________

19.3.1. BKView Module

   BitKeeper repository viewer. Admin->Bkview.

   This module permits viewing of a BitKeeper repository. If you
   use BitKeeper, this module will be useful for viewing items.
   If you do not use BitKeeper, this module will be of little
   use.

     * View repositories:
     * Add repository:
          + Repository name: Enter the name of the repository as
            you want it displayed on the site.
          + Path: Enter the complete path to the BitKeeper
            repository.
          + Click "Add repository" to save changes.
     _________________________________________________________

19.4. Facilities Module
     _________________________________________________________

19.4.1. Facilities Module

   Facility management module. Admin->Facilities.

   The DocBook for this Guide is being developed.

     * Modify config: This panel allows modification of
       configuration options for this module.
          + Number of facilities to display per page:
          + Show top menu:
          + Configuration of hooked modules
          + Click "Update config" to save changes.
     _________________________________________________________

19.5. Multisites Module
     _________________________________________________________

19.5.1. Multisites Module

   Basic installation of a multisite Xaraya. Admin->Multisites.

   The documentation for this part of the Guide is being
   developed.

     * Add Site: Configure the Master Site from
       Admin->Multisites->Master config.
       You can then add new sites through the menu option
       Admin->Multisites->Add Sites.
     * View Sites:
     * Admin config:
          + Number of site listings per page: In this field,
            enter the number of site listings to display per
            page. For example, if you wish to display 10 site
            listings per page, enter "10" in this box.
          + Click "Update Admin Configuraration" to save changes.
     * Master config: This panel allows modification of
       configuration options for this module.
          + Server config: Multisites can use one of 2 possible
            variables either HTTP_HOST or SERVER_NAME. One or the
            other may not always work on your system, depending
            on the way the server is configured.
               o HTTP_HOST:
               o SERVER_NAME:
          + File Paths & Domain Types
               o Default Master Data Directory Path:
               o Domain & subdomain extensions: The common
                 extensions are .com, .net, and .org. If, for
                 example, you use a subdomain or domain such as
                 www.domain.biz as a site, you will need to add
                 the .biz extension to the list.
                 If you want to use domain extensions to
                 discriminate your sites (for example, mysite.com
                 is a different site than mysite.net), make sure
                 the text box is blank.
          + Click "Set multisite configuration" to save changes.
     _________________________________________________________

19.6. Recommend Module
     _________________________________________________________

19.6.1. Recommend Module

   Send a link for this site to a friend. Admin->Recommend.

   The documentation for this part of the Guide is being
   developed.
     _________________________________________________________

19.7. Example Module
     _________________________________________________________

19.7.1. Example Module

   Example for new modules. Admin->Example.

     * Add Item:
          + Add Item:
          + Example name:
          + Example number:
          + Click "Add Example" to save changes.
     * View items:
          + Example Name:
          + Example Number:
          + Example Options:
     * Modify config: This panel allows modification of
       configuration options for this module.
          + Display example items in bold?:
          + Example items per page?:
          + Enable Short URLs?:
          + Click "Update Configuration" to save changes.
     _________________________________________________________

19.8. Dyn_Example Module
     _________________________________________________________

19.8.1. Dyn_Example Module

   Xaraya module.

   The DocBook for this Guide is being developed.
     _________________________________________________________

Chapter 20. Conclusion

   Thank you for reading the Official Xaraya Installation and
   Getting Started Guide!

   I sincerely hope that this Guide has increased your
   understanding of how Xaraya functions, and that it has helped
   you to install and configure your own Xaraya site. Writing
   this Guide has been largely a solo effort that I undertook
   gladly. It is my pleasure to be able to give something back to
   the Xaraya community; the community has provided a product
   with which it has been a great pleasure to work.

   I am very interested in hearing your comments and suggestions
   about this Guide. Please get in touch with me using one of the
   methods below:

   <drew@xaraya.com>

   http://www.drewvogel.com

   Happy Xaraya-ing!

   -drew vogel
     _________________________________________________________

Appendix A. Xaraya License

   Xaraya is licensed and distributed under the GNU General
   Public License. The text of the GNU General Public License is
   below. GNU GENERAL PUBLIC LICENSE Version 2, June 1991

   Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59
   Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is
   permitted to copy and distribute verbatim copies of this
   license document, but changing it is not allowed.

   The licenses for most software are designed to take away your
   freedom to share and change it. By contrast, the GNU General
   Public License is intended to guarantee your freedom to share
   and change free software--to make sure the software is free
   for all its users. This General Public License applies to most
   of the Free Software Foundation's software and to any other
   program whose authors commit to using it. (Some other Free
   Software Foundation software is covered by the GNU Library
   General Public License instead.) You can apply it to your
   programs, too.

   When we speak of free software, we are referring to freedom,
   not price. Our General Public Licenses are designed to make
   sure that you have the freedom to distribute copies of free
   software (and charge for this service if you wish), that you
   receive source code or can get it if you want it, that you can
   change the software or use pieces of it in new free programs;
   and that you know you can do these things.

   To protect your rights, we need to make restrictions that
   forbid anyone to deny you these rights or to ask you to
   surrender the rights. These restrictions translate to certain
   responsibilities for you if you distribute copies of the
   software, or if you modify it.

   For example, if you distribute copies of such a program,
   whether gratis or for a fee, you must give the recipients all
   the rights that you have. You must make sure that they, too,
   receive or can get the source code. And you must show them
   these terms so they know their rights.

   We protect your rights with two steps: (1) copyright the
   software, and (2) offer you this license which gives you legal
   permission to copy, distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make
   certain that everyone understands that there is no warranty
   for this free software. If the software is modified by someone
   else and passed on, we want its recipients to know that what
   they have is not the original, so that any problems introduced
   by others will not reflect on the original authors'
   reputations.

   Finally, any free program is threatened constantly by software
   patents. We wish to avoid the danger that redistributors of a
   free program will individually obtain patent licenses, in
   effect making the program proprietary. To prevent this, we
   have made it clear that any patent must be licensed for
   everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
   modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND
   CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

   0. This License applies to any program or other work which
   contains a notice placed by the copyright holder saying it may
   be distributed under the terms of this General Public License.
   The "Program", below, refers to any such program or work, and
   a "work based on the Program" means either the Program or any
   derivative work under copyright law: that is to say, a work
   containing the Program or a portion of it, either verbatim or
   with modifications and/or translated into another language.
   (Hereinafter, translation is included without limitation in
   the term "modification".) Each licensee is addressed as "you".

   Activities other than copying, distribution and modification
   are not covered by this License; they are outside its scope.
   The act of running the Program is not restricted, and the
   output from the Program is covered only if its contents
   constitute a work based on the Program (independent of having
   been made by running the Program). Whether that is true
   depends on what the Program does.

    1. You may copy and distribute verbatim copies of the
       Program's source code as you receive it, in any medium,
       provided that you conspicuously and appropriately publish
       on each copy an appropriate copyright notice and
       disclaimer of warranty; keep intact all the notices that
       refer to this License and to the absence of any warranty;
       and give any other recipients of the Program a copy of
       this License along with the Program.
       You may charge a fee for the physical act of transferring
       a copy, and you may at your option offer warranty
       protection in exchange for a fee.
    2. You may modify your copy or copies of the Program or any
       portion of it, thus forming a work based on the Program,
       and copy and distribute such modifications or work under
       the terms of Section 1 above, provided that you also meet
       all of these conditions:
          + You must cause the modified files to carry prominent
            notices stating that you changed the files and the
            date of any change.
          + You must cause any work that you distribute or
            publish, that in whole or in part contains or is
            derived from the Program or any part thereof, to be
            licensed as a whole at no charge to all third parties
            under the terms of this License.
          + If the modified program normally reads commands
            interactively when run, you must cause it, when
            started running for such interactive use in the most
            ordinary way, to print or display an announcement
            including an appropriate copyright notice and a
            notice that there is no warranty (or else, saying
            that you provide a warranty) and that users may
            redistribute the program under these conditions, and
            telling the user how to view a copy of this License.
            (Exception: if the Program itself is interactive but
            does not normally print such an announcement, your
            work based on the Program is not required to print an
            announcement.)
       These requirements apply to the modified work as a whole.
       If identifiable sections of that work are not derived from
       the Program, and can be reasonably considered independent
       and separate works in themselves, then this License, and
       its terms, do not apply to those sections when you
       distribute them as separate works. But when you distribute
       the same sections as part of a whole which is a work based
       on the Program, the distribution of the whole must be on
       the terms of this License, whose permissions for other
       licensees extend to the entire whole, and thus to each and
       every part regardless of who wrote it.
       Thus, it is not the intent of this section to claim rights
       or contest your rights to work written entirely by you;
       rather, the intent is to exercise the right to control the
       distribution of derivative or collective works based on
       the Program.
       In addition, mere aggregation of another work not based on
       the Program with the Program (or with a work based on the
       Program) on a volume of a storage or distribution medium
       does not bring the other work under the scope of this
       License.
    3. You may copy and distribute the Program (or a work based
       on it, under Section 2) in object code or executable form
       under the terms of Sections 1 and 2 above provided that
       you also do one of the following:
          + Accompany it with the complete corresponding
            machine-readable source code, which must be
            distributed under the terms of Sections 1 and 2 above
            on a medium customarily used for software
            interchange; or,
          + Accompany it with a written offer, valid for at least
            three years, to give any third party, for a charge no
            more than your cost of physically performing source
            distribution, a complete machine-readable copy of the
            corresponding source code, to be distributed under
            the terms of Sections 1 and 2 above on a medium
            customarily used for software interchange; or,
          + Accompany it with the information you received as to
            the offer to distribute corresponding source code.
            (This alternative is allowed only for noncommercial
            distribution and only if you received the program in
            object code or executable form with such an offer, in
            accord with Subsection b above.)
       The source code for a work means the preferred form of the
       work for making modifications to it. For an executable
       work, complete source code means all the source code for
       all modules it contains, plus any associated interface
       definition files, plus the scripts used to control
       compilation and installation of the executable. However,
       as a special exception, the source code distributed need
       not include anything that is normally distributed (in
       either source or binary form) with the major components
       (compiler, kernel, and so on) of the operating system on
       which the executable runs, unless that component itself
       accompanies the executable.
       If distribution of executable or object code is made by
       offering access to copy from a designated place, then
       offering equivalent access to copy the source code from
       the same place counts as distribution of the source code,
       even though third parties are not compelled to copy the
       source along with the object code.
    4. You may not copy, modify, sublicense, or distribute the
       Program except as expressly provided under this License.
       Any attempt otherwise to copy, modify, sublicense or
       distribute the Program is void, and will automatically
       terminate your rights under this License. However, parties
       who have received copies, or rights, from you under this
       License will not have their licenses terminated so long as
       such parties remain in full compliance.
    5. You are not required to accept this License, since you
       have not signed it. However, nothing else grants you
       permission to modify or distribute the Program or its
       derivative works. These actions are prohibited by law if
       you do not accept this License. Therefore, by modifying or
       distributing the Program (or any work based on the
       Program), you indicate your acceptance of this License to
       do so, and all its terms and conditions for copying,
       distributing or modifying the Program or works based on
       it.
    6. Each time you redistribute the Program (or any work based
       on the Program), the recipient automatically receives a
       license from the original licensor to copy, distribute or
       modify the Program subject to these terms and conditions.
       You may not impose any further restrictions on the
       recipients' exercise of the rights granted herein. You are
       not responsible for enforcing compliance by third parties
       to this License.
    7. If, as a consequence of a court judgment or allegation of
       patent infringement or for any other reason (not limited
       to patent issues), conditions are imposed on you (whether
       by court order, agreement or otherwise) that contradict
       the conditions of this License, they do not excuse you
       from the conditions of this License. If you cannot
       distribute so as to satisfy simultaneously your
       obligations under this License and any other pertinent
       obligations, then as a consequence you may not distribute
       the Program at all. For example, if a patent license would
       not permit royalty-free redistribution of the Program by
       all those who receive copies directly or indirectly
       through you, then the only way you could satisfy both it
       and this License would be to refrain entirely from
       distribution of the Program.
       If any portion of this section is held invalid or
       unenforceable under any particular circumstance, the
       balance of the section is intended to apply and the
       section as a whole is intended to apply in other
       circumstances.
       It is not the purpose of this section to induce you to
       infringe any patents or other property right claims or to
       contest validity of any such claims; this section has the
       sole purpose of protecting the integrity of the free
       software distribution system, which is implemented by
       public license practices. Many people have made generous
       contributions to the wide range of software distributed
       through that system in reliance on consistent application
       of that system; it is up to the author/donor to decide if
       he or she is willing to distribute software through any
       other system and a licensee cannot impose that choice.
       This section is intended to make thoroughly clear what is
       believed to be a consequence of the rest of this License.
    8. If the distribution and/or use of the Program is
       restricted in certain countries either by patents or by
       copyrighted interfaces, the original copyright holder who
       places the Program under this License may add an explicit
       geographical distribution limitation excluding those
       countries, so that distribution is permitted only in or
       among countries not thus excluded. In such case, this
       License incorporates the limitation as if written in the
       body of this License.
    9. The Free Software Foundation may publish revised and/or
       new versions of the General Public License from time to
       time. Such new versions will be similar in spirit to the
       present version, but may differ in detail to address new
       problems or concerns.
       Each version is given a distinguishing version number. If
       the Program specifies a version number of this License
       which applies to it and "any later version", you have the
       option of following the terms and conditions either of
       that version or of any later version published by the Free
       Software Foundation. If the Program does not specify a
       version number of this License, you may choose any version
       ever published by the Free Software Foundation.
   10. If you wish to incorporate parts of the Program into other
       free programs whose distribution conditions are different,
       write to the author to ask for permission. For software
       which is copyrighted by the Free Software Foundation,
       write to the Free Software Foundation; we sometimes make
       exceptions for this. Our decision will be guided by the
       two goals of preserving the free status of all derivatives
       of our free software and of promoting the sharing and
       reuse of software generally.
   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS
       NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
       APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING
       THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
       PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
       EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
       PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM
       PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
       SERVICING, REPAIR OR CORRECTION.
   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO
       IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
       WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS
       PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING
       ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
       ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
       (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
       PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
       OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS
       BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
     _________________________________________________________

Appendix B. Creating the Xaraya database via phpMyAdmin

   If Xaraya successfully created your database, skip to
   "Administrator Account Creation". If Xaraya cannot create the
   database for you, you should use phpMyAdmin to create an empty
   database called "Xaraya" and configure access permissions.
   This can be a two-step process:

     * Using phpMyAdmin, create a user in the database if
       necessary
       If you already have a database username & password, skip
       this step. To create a database user <db-user> with
       password <db-user-password>, follow these steps in
       phpMyAdmin:
          + Click "Privileges".
          + Click "Add new User" and complete the fields.
               o User name: Use text field: Type the name for the
                 user in the text field. This is the same value
                 as <db-user>, above.
               o Host: If the database is running on the same
                 server as the website (this is the most common
                 scenario), select "Local" from the drop-down
                 list.
               o Password: Use text field: Type the password for
                 this user in the text field. This is the same
                 value as <db-user-password>, above.
               o Re-type the password to verify.
               o Click "Go" to save changes.
     * Using phpMyAdmin, create the empty Xaraya database (called
       "Xaraya")
       In phpMyAdmin, follow these steps to create the database
       that Xaraya will use:
          + Create a new database called "Xaraya".
          + Click the "Home" link near the top left of the
            phpMyAdmin page.
          + Click "Databases".
          + Next to the line for Xaraya, click "Check
            Privileges".
          + Next to <db-user>, click "Edit".
          + Check all in "Edit Privileges" and click "Go".
          + Click the "Home" link near the top left of the
            phpMyAdmin page.
          + Click "Reload MySQL".

   Once the empty "Xaraya" database has been created, re-run the
   Xaraya installer and UNCHECK "Create the database" under
   Database Settings Collection.
     _________________________________________________________

Appendix C. Enabling Short URL support in Apache

C.1. Short URLs in Apache 1.x

   Short URLs work without modifying your Apache 1.x
   configuration.
     _________________________________________________________

C.2. Short URLs in Apache 2.x

   If you are running Apache 2.x on your webserver and wish to
   support Short URLs, you must add the directive: AcceptPathInfo
   On to your httpd.conf file (usually /etc/httpd/conf/httpd.conf
   on RedHat systems). Restart Apache once the change has been
   saved ("apachectl graceful" on RedHat systems). See the
   documentation on the Apache website for more information about
   adding this directive.
     _________________________________________________________

Appendix D. Creating a Xaraya Theme

   For the original article, see
   http://www.mahmood.tv/index.php/docs/20

   I gave http://www.computerpoint.tv a make-over in less than a
   couple of hours, and that included installing Xaraya,
   importing the previous PostNuke 0.723 data AND creating the
   theme! Themes with BlockLayout are extremely easy. I am sure I
   haven't even scratched the surface or capabilities of the
   BlockLayout templating engine, but I got it done, and here's
   how:

    1. Copy the Xaraya_Classic theme into whatever name you like
       your new theme to be, let's say 'MacyGray':
       # cd <xarroot>/themes # cp -R Xaraya_Classic MacyGray
    2. Reserve an ID on Xaraya.com and note the ID you've chosen.
       Edit the <xarroot>/<themes_dir>/MacyGray/xartheme.php file
       and enter your Theme ID there. While in that file, change
       all other information that needs to change like the theme
       name, directory etc. In vi I do:
       :g/Xaraya_Classic/s//MacyGray/g
       that will replace all occurances of 'Xaraya_Classic' with
       'MacyGray'
       To do the same for all other files in
       <xarroot>/<themes_dir>/MacyGray, do a grep to see where
       'Xaraya_Classic' occurs then change that as I've done
       above in vi or whatever editor you use:
       # cd themes/MacyGray # grep -R Xaraya_Classic *
       This will spew all occurances of Xaraya_Classic in all the
       files in the directory and the subdirectories, then go to
       each file and do a replace as above.
    3. Now that you have the basic framework for MacyGray, it is
       time to get creative!
       Use your HTML editor to load
       <xarroot>/<themes_dir>/MacyGray/default.xt.
       Load up <xarroot>/<themes_dir>/MacyGray/style.css file to
       ensure that you're working on the complete theme and to
       avoid surprises! There is a LOT of information and control
       in the style.css file and you can change just about
       anything in the theme by changing values in the style.css
       file. It is also here that you would change the page
       background color, fonts to use, font attributes, etc.
       Again your HTML editor should give you a way to change
       things in the stylesheet in a graphical environment.
       Place graphics and other elements. Basically, create your
       theme here then save the files.
    4. Check that your HTML editor didn't change the graphic
       paths, make sure that your graphics are in
       "<xarroot>/<themes_dir>/MacyGray/images/" directory,
       rather than "file:///".
    5. Everything saved, make sure that the permissions on the
       files and directories are set appropriately.
    6. Go to the Admin->Themes->View Themes. CHECK "Regenerate"
       and click "Reload". Then initialize and activate your new
       theme.
    7. Go to Admin->Themes->Modify config and set your new theme
       as the default.

   ...et voila! Now you have a new theme for Xaraya!

   For variables and tags to use (if you need more that is, you
   could check the BlockLayout RFC on Xaraya.com)
     _________________________________________________________

Appendix E. Converting from PostNuke to Xaraya

   Conversion of an existing PostNuke site to Xaraya is easy. A
   conversion script facilitates the conversion process for
   PostNuke versions . The import script will not import PostNuke
   items if there is no specific script that handles that part of
   the data. During conversion, PostNuke data is converted and
   stored in the new Xaraya tables. The original PostNuke data is
   not modified in any way.

   To convert from PostNuke to Xaraya, follow the steps below.

    1. Backup existing PN database to a file, just to be safe.
       For example:
          + "mysqldump -u <username> -p -B <PostNuke_dbase_name>
            -c -a --add-drop-table >PNbackup.sql"
    2. If you have many articles (more than 250 or so) on your
       PostNuke site, it may be necessary to increase PHP's
       max_execution_time to prevent timeouts when converting and
       importing data. If max_execution_time is too low, PHP may
       'time out' before the articles can be imported
       successfully.
          + To adjust the max_execution_time, edit /etc/php.ini
            and set max_execution_time to 120, making a note of
            the previous value. Save the file and exit the
            editor. Restart your webserver so the changes are
            implemented ("apachectl restart", for example).
    3. From the Xaraya Base distribution, install a Xaraya
       Community site. In the Database Name field of Xaraya's
       installer, specify the name of your existing PostNuke
       database (case-sensitive). Specify a different prefix for
       Xaraya's tables ("xar" is recommended) than was used for
       PostNuke.
    4. Install the POLLS module in Xaraya. If you skip this step,
       the importer will present an error when it tries to import
       any polls that exist on your PostNuke site.
    5. Copy the import_pn*.php files from the Xaraya Base
       distribution's "/tests/import/postnuke" directory to your
       <xarroot> directory. Give the <xarroot>/import_pn*.php
       files appropriate system permissions and ownership so they
       can be accessed via the web. For example:
          + "cp /test/import/postnuke/import_pn*.php <xarroot>"
          + "cd <xarroot>"
          + "chown -R web:apache import_pn*.php"
          + "chmod -R 770 import_pn*.php"
    6. From a browser, go to
       http://www.yourwebsite.com/<xarroot>/import_pn.php. Follow
       the on-screen steps to import each area of the PostNuke
       site into Xaraya.
    7. After the conversion is complete, delete the
       import_pn*.php files from your <xarroot> directory.
       Leaving these files can present a security risk.
    8. Edit /etc/php.ini and set max_execution_time back to the
       previous value. Save and exit the editor. Restart your
       webserver so the changes are implemented ("apachectl
       restart", for example).
    9. If you no longer intend to run PostNuke, the PostNuke
       tables can be deleted from the database using the command
       line or phpMyAdmin.

   After conversion, the PostNuke tables in the database may be
   deleted, if desired.
     _________________________________________________________

Appendix F. Installing & Configuring Red Hat 9.0 to run Xaraya

   NOTE: Though we install them, this appendix does NOT include
   information on configuring email services (Sendmail, Postfix,
   Squirrelmail, SpamAssassin, etc.). Configuration of this type
   is beyond the scope of this document.

   To install RED HAT LINUX 9.0 to run Xaraya, follow these
   steps.

   CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION *
   CAUTION *

   ==============================================================
   ===============

   This procedure will COMPLETELY ERASE HARD DRIVES INSTALLED ON
   THIS SYSTEM. Be sure there is no important data on the drives;
   EVERYTHING WILL BE LOST.

   Use these instructions at your own risk.

   ==============================================================
   ===============

   CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION *
   CAUTION *

     * Get the RED HAT 9.0 installation CDs.
     * Boot the system from the RED HAT 9.0 installation CD.
       Launch the Red Hat Installer.
     * Perform the (optional) media check to test your
       installation CDs. This is strongly recommended the first
       time you install from a particular CD set, to make sure
       that it does not contain any errors. Select "OK" to
       perform the media check. Once you have checked each CD set
       once, it is generally not necessary to check it again and
       you may "Skip" this step.
     * WELCOME TO RED HAT LINUX: Click "Next" at the Welcome
       screen.
     * LANGUAGE SELECTION: Select the language to use during
       installation. Click "Next".
     * KEYBOARD CONFIGURATION: Select your Keyboard
       Configuration. Click "Next".
     * MOUSE CONFIGURATION: Select your Mouse Configuration.
       Click "Next".
     * INSTALLATION TYPE: If there is already a Linux operating
       system installed on this machine, select "Perform a new
       Red Hat Linux installation" and click "Next". Select
       "SERVER". Click "Next".
     * DISK PARTITIONING SETUP: Select "Automatically Partition"
       and click "Next".
     * AUTOMATIC PARTITIONING: Select "Remove ALL partitions on
       this system". Click "Next".
       A warning window gives you the opportunity to change your
       mind. If you are certain that you want to remove all
       partitions on this system, click "Yes". If you do not want
       to remove all partitions on this system, click "No".
       CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION
       * CAUTION *
       ==========================================================
       ===================
       Selecting "Yes" will erase EVERYTHING on this system.
       ==========================================================
       ===================
       CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION
       * CAUTION *
     * DISK SETUP: You can review the changes that Red Hat will
       make to your computer's hard drive partitions here. Click
       "Next" to continue.
     * BOOT LOADER CONFIGURATION: Leave set to defaults unless
       you wish to change the settings. Click "Next".
     * NETWORK CONFIGURATION: Leave set to defaults unless you
       wish to change the settings. Click "Next".
     * FIREWALL CONFIGURATION: Select Medium (or High) Security,
       CHECK your network device (usually "eth0") as a Trusted
       device, CHECK WWW (HTTP), FTP, SSH, DHCP, and MAIL (SMTP).
       Do NOT check Telnet unless you have a specific need to
       support it. Click "Next".
     * ADDITIONAL LANGUAGE SUPPORT: If you wish for your Red Hat
       installation to support multiple languages, select them
       from the listing under Additional Languages. Click "Next".
     * TIME ZONE SELECTION: Select your Time zone. Click "Next".
     * SET ROOT PASSWORD: Enter the root user's password twice.
       Remember this password -- it is the key to administrator
       access to this server. Click "Next". Be patient -- the
       installer will read package information for a while, then
       display the next step.
     * PACKAGE GROUP SELECTION:
       The only items that should be CHECKED for this
       installation are as follows. UNCHECK any other package
       sets. If you need to install additional features (such as
       Printing Support), you may do so.
       Check:
          + X Window System
          + GNOME Desktop Environment
          + Graphical Internet
          + Text Based Internet -- click "Details" In addition to
            those items already checked,
               o Check epic
               o Check lynx
               o Check ncftp
               o Check pine
          + Server Configuration Tools
          + Web Server -- click "Details" In addition to those
            items already checked,
               o Check mod_auth_mysql
               o Check mod_auth_pgsql
               o Check php-mysql
               o Check php-odbc
               o Check php-pgsql
          + Mail Server -- click "Details". This appendix does
            NOT include information on configuring email services
            (Sendmail, Postfix, Squirrelmail, SpamAssassin,
            etc.). This configuration is beyond the scope of this
            document. In addition to those items already checked,
               o Check postfix
               o Check spamassassin
               o Check squirrelmail
          + SQL Database Server -- click "Details"
            In addition to those items already checked,
               o Check mysql-server
          + Administration Tools
          + System Tools
       Click "Next".
     * As configured above, the installation is approximately
       1235 megabytes.
       CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION
       * CAUTION *
       ==========================================================
       ===================
       Continuing through the next step will DESTROY ANY DATA on
       the system.
       ==========================================================
       ===================
       CAUTION * CAUTION * CAUTION * CAUTION * CAUTION * CAUTION
       * CAUTION *
     * ABOUT TO INSTALL: Click "Next" to begin the installation.
     * INSTALLING PACKAGES: The system will install from the Red
       Hat CDs. Insert installation CDs them as you are prompted
       for them, and click "OK" to continue installation when
       each CD has been inserted.
     * BOOT DISKETTE CREATION: After installation completes, the
       installer will offer to make a boot floppy. If your system
       has a floppy drive, it is highly recommended that you
       create a boot floppy. Select "Yes" to create a boot
       floppy. You need a floppy disk -- it will be completely
       erased. Select "No" to skip the creation of a boot floppy.
     * GRAPHICAL INTERFACE (X) CONFIGURATION: The Red Hat
       installer will attempt to detect your video card and
       monitor type. Click "Next" to move through these
       configuration options.
     * CUSTOMIZE GRAPHICS CONFIGURATION: Select your Color Depth
       and Screen Resolution from the drop-down lists.
       IMPORTANT: At the bottom of this screen, set "Please
       choose your login type" to TEXT. We select "Text" because
       the text mode login requires fewer system resources. Click
       ""Next"" to continue.
     * You see "Congratulations, the installation is complete".
       Remove all media -- the CD and the boot floppy. Click
       "Exit" to exit the installer and reboot into your new Red
       Hat 9.0 server.
     * When the system reboots, log in as root with the password
       you selected above. In the root directory, you should see
       a file called "anaconda-ks.cfg". This is a record of the
       installation that was just performed. It is recommended
       that you keep this file somewhere safe -- the boot floppy
       is a good suggestion. Insert the floppy disk, making sure
       it is write-enabled.
          + Type "mount /mnt/floppy".
          + Type "cp anaconda-ks.cfg /mnt/floppy/ks.cfg".
          + Type "umount /mnt/floppy".
       When the floppy drive's activity light goes out, remove
       the floppy disk, write-protect it, and keep it in a safe
       place, preferrably away from this server since the file we
       just copied contains password information. You should also
       delete the anaconda-ks.cfg file from your server ("rm
       anaconda-ks.cfg"). If you ever wish to perform this exact
       installation again, you can do so by booting from the boot
       CD, inserting the floppy with ks.cfg on it, and typing
       "linux ks=floppy".
     * Still logged in as root, type "setup" at the command line.
       Use the cursor keys to move the lightbar down to "System
       services". Press ENTER. Scroll down and press the SPACEBAR
       next to "httpd" (web server), "mysqld" (MySQL database
       server), and "squid" (WWW proxy cache). Press TAB to move
       the lightbar to OK, then press ENTER. Press TAB two times
       to move the lightbar to Quit, and press ENTER to leave
       Setup.
     * Type "reboot" at the command line to reboot your server.
       When the server reboots, the items we selected above will
       automatically launch during boot.
     * UP2DATE:
          + When the system has rebooted, make sure that the
            server is connected to the internet. Then, log in as
            root and type "up2date". Because Red Hat is a
            constantly evolving product, there are new releases
            of component software on a frequent basis. The
            Up2Date program keeps your system updated by
            communicating with Red Hat Network. If necessary,
            edit the settings that are displayed, however,
            generally, the defaults are acceptable. Press ENTER
            to save and exit, or press "q" to quit without
            saving.
          + From the command line, type "rpm --import
            /usr/share/rhn/RPM-GPG-KEY" to import your Red Hat
            Network information into your installation.
          + From the command line, type "up2date" again. Read the
            information and click "Next" twice. If you are an
            existing Red Hat Network user, enter your username,
            password, and email address in the fields. If you are
            not an existing Red Hat Network user, choose a
            username and password and enter them and your email
            address in the fields. Use TAB to move forward
            through the fields and SHIFT-TAB to move backward.
            Using TAB, move the lightbar to "Next" and press
            ENTER to continue.
          + Read the next screen, and click "Next" to continue.
            Red Hat will build a package list and ask if it can
            send information about your installed packages. It is
            suggested that you allow this information to be sent.
            Click "Next" to continue, and click "Next" again to
            send the system profile to Red Hat Network. Click
            "Finish" when the profile has been sent.
          + From the command line, type "up2date -l" to see a
            listing of packages available for updating. There may
            be a lot of packages, so it is recommended that you
            type "up2date -l >update.txt" to save the list of
            files to "update.txt". View the list by typing "more
            update.txt". Each item on the list indicates a
            package that has been updated since the creation of
            the CDs from which you installed.
          + To tell Red Hat to update packages, type the
            following at the command line: "up2date <packagename>
            <packagename> ...". You can put several packages on
            one line. Press ENTER and up2date will download,
            verify, and install the packages you specified. If an
            updated kernel (the core of the Linux operating
            system) is available and you wish to update your
            kernel, type "up2date -f kernel" to force the update
            of the kernel.
          + Once your system is completely up-to-date, type
            "reboot" to reboot your server.
     * IFCONFIG: From the command line, type "ifconfig" to see
       the internet protocol (IP) address for this system. Make a
       note of the IP address.
     * phpMyAdmin: Download the latest stable version of
       phpMyAdmin (in tar.gz/PHP files format) from
       http://phpmyadmin.sourceforge.net to a temporary
       directory. From the command line, type "cd /tmp", then
       "lynx http://phpmyadmin.sourceforge.net" to connect to the
       site then select the latest version of phpMyAdmin for
       download. Press ENTER on the file. Select a download
       mirror and press ENTER. Press "d" to begin the download.
       When it completes, click on "Save to disk", and press
       ENTER to retain the default filename. Press "q" and "y"es
       to exit Lynx.
       To extract the archive, type "tar -xzvf
       <phpmyadmin>.tar.gz" (replace <phpmyadmin> with the name
       and version of phpMyAdmin that you just downloaded). When
       the extraction is complete, type "cd <phpmyadmin-dir>"
       (replace <phpmyadmin-dir> with the name of the directory
       where phpMyAdmin was extracted). Type "pico
       config.inc.php". This is the main configuration file for
       phpMyAdmin.
       There are four places we need to edit. Change the values
       for host, user, password and authentication mode to fit
       your environment. "Host" means the MySQL server and is
       usually "localhost". Also insert the correct value for
       $cfg['PmaAbsoluteUri']. Save the file and exit the editor.
       Now we need to copy phpMyAdmin directory to the <webdir>.
       From within the <phpmyadmin-dir>, type "mkdir
       <webdir>/phpmyadmin", then type "cp *
       <webdir>/phpmyadmin".
       It is recommended that you protect the directory in which
       you installed phpMyAdmin. Read phpMyAdmin's
       Documentation.html file in the phpMyAdmin directory for
       more information on doing so. phpMyAdmin is now ready for
       use.

   * MySQL: MySQL is the database that drives Xaraya. In order to
   configure MySQL for use, we must accomplish two things: Set a
   root password for the database, and create a database user &
   password.

     * Set a root password for the database: When Red Hat
       installs MySQL, it is not password protected, making it
       vulnerable. To assign a password of "yourpass" for the
       root user, enter the following at the command line:
          + "mysqladmin -u root password yourpass"
     * Create a database user: We must create a database user
       that Xaraya will use to access the database. We'll use
       phpMyAdmin for this. To launch Red Hat's Desktop, type
       "startx" at the command line. When the desktop appears,
       click the icon at the lower left of your screen that looks
       like a globe with a computer mouse coiled around it to
       launch Mozilla browser.
          + From within the broswer, visit the directory where
            you installed phpMyAdmin. In this example, it should
            be "http://localhost/phpmyadmin".
          + Click Privileges->Add a new User
          + Enter the following information:
               o User Name: Enter the name for the database user,
                 for example, "dbuser".
               o Host: Enter the host where the database resides.
                 Since we're hosting the database on the same
                 site as the webserver, select "Local" from the
                 drop-down list.
               o Password: Enter the password for the database
                 user.
               o Re-type: Enter the same password again, to
                 verify.
          + Under Global Privileges, CHECK all the items in each
            column.
          + Click "Go" to save changes.
          + VERY IMPORTANT: Click the "Home" link under the
            phpMyAdmin logo in the top-left corner of your
            screen, then click "Reload MySQL".
     * To exit the Red Hat Desktop, click the Red Hat icon in the
       lower left corner of the screen and select "Log out".
       Click "Log Out" and "OK" in the confirmation window, and
       you are returned to the command line.
     * Sendmail: Sendmail is the email agent on your server.
       Check with your service provider for tips on configuring
       Sendmail.
     * Postfix: Postfix is another email agent on your server.
       Check with your service provider for tips on configuring
       Postfix.
     * SpamAssassin: SpamAssassin is a mail filter to identify
       spam. Check with your service provider for tips on
       configuring SpamAssassin.
     * SquirrelMail: SquirrelMail is a webmail package. Check
       with your service provider for tips on configuring
       SquirrelMail.

   Your system is now ready for the installation of Xaraya.
     _________________________________________________________

Appendix G. Standards Compliance

   XHTML, RSS, CSS, and W3C accessibility standards.
