The Official PostNuke Installation & The Official PostNuke Installation & Getting Started Guide: Revision 9939

39 / Preview
by Drew Vogel

Getting Started Guide Copyright © 2002 by Drew Vogel. All rights reserved.

This edition was built on Wednesday, November 13 2002 :: 12:15:32 PM EST.

Revision 9939 / Preview The Official PostNuke Installation and Getting Started Guide was written by Drew Vogel.
You may not distribute, modify, or translate this Guide without the prior consent of Drew Vogel (<drew@drewvogel.com>). The only approved
use is review, comment, and personal use.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, Draft v1.0, 8 June 1999 or
later (the latest version is available at http://www.opencontent.org/openpub).
Distribution and/or sale of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.
Distribution and/or sale of the work or derivative of the work in any standard (paper) book or printed form is prohibited unless prior permission is
obtained from the copyright holder.

Drew Vogel
Dedication
This Guide is dedicated to Wendy, the keeper of my heart and the delight of my eyes.

4
Table of Contents Blocks...............................................................................................................................................59
Comments ........................................................................................................................................66
1. Important Note Regarding This Version Of The Guide ....................................................................9 Downloads........................................................................................................................................67
2. Credits...................................................................................................................................................11 Downloads -> Download Configuration.................................................................................72
Ephemerids.......................................................................................................................................72
3. Most Current Versions ........................................................................................................................13
FAQ ..................................................................................................................................................73
4. Who Should Use This Guide...............................................................................................................15 Groups ..............................................................................................................................................74
5. An Overview of Content Management Systems (CMS) ...................................................................17 HTTP Referers .................................................................................................................................74
6. An Overview of PostNuke ...................................................................................................................19 HTTP Referers -> HTTP Referers Configuration ..................................................................74
7. Benefits of PostNuke ............................................................................................................................21 Languages ........................................................................................................................................75
Languages -> Languages Configuration.................................................................................75
8. System Requirements ..........................................................................................................................23
Mail Users ........................................................................................................................................75
Hardware Requirements...................................................................................................................23 Quotes ..............................................................................................................................................76
Software Requirements ....................................................................................................................23 Reviews ............................................................................................................................................76
Software Recommendations.............................................................................................................23 Sections ............................................................................................................................................78
Tools You Can Use...........................................................................................................................24 Submit News ....................................................................................................................................79
9. Assumptions & Conventions...............................................................................................................25 Surveys .............................................................................................................................................80
10. New Installation .................................................................................................................................27 Topics ...............................................................................................................................................81
Step-by-step: First-time installation of PostNuke ............................................................................27 Topics -> Topics Configuration ..............................................................................................82
Top List ............................................................................................................................................82
11. Upgrade Installation..........................................................................................................................33
User Administration .........................................................................................................................83
Step-by-step: Upgrading PostNuke..................................................................................................33
User Administration -> User Configuration ...........................................................................83
12. Testing The Installation/Upgrade.....................................................................................................37 User Administration -> Dynamic User Data ..........................................................................83
13. A Lesson in PostNuke Terminology .................................................................................................39 Web Links ........................................................................................................................................85
14. Basic Website Configuration.............................................................................................................41 Web Links -> Web Links Configuration.................................................................................87
Basic Site Setup ...............................................................................................................................41 17. Groups & Permissions.......................................................................................................................91
Footer Messages...............................................................................................................................45 Overview of the Permissions System...............................................................................................91
Backend Configuration.....................................................................................................................45 Default PostNuke Permissions Explained........................................................................................92
Security Options...............................................................................................................................46 Advanced Group Permissions ..........................................................................................................92
Run On An Intranet..........................................................................................................................46 User Permissions..............................................................................................................................93
HTML Options.................................................................................................................................47 Setting up and configuring Groups ..................................................................................................93
15. Understanding Modules ....................................................................................................................49 Permission Levels ............................................................................................................................94
16. Advanced Website Configuration & Use .........................................................................................51 An example of Group Permissions ..................................................................................................95
An example of User Permissions .....................................................................................................95
Add Story .........................................................................................................................................51
Permissions FAQ..............................................................................................................................95
Admin Messages ..............................................................................................................................53
Permissions for Newbies..................................................................................................................97
AutoLinks.........................................................................................................................................55
Permission Samples................................................................................................................99
Banners.............................................................................................................................................56
Banners -> Banner Reporting.................................................................................................58
Banners -> Banners Configuration .........................................................................................59

v vi
18. Conclusion ........................................................................................................................................107
19. APPENDIX A: Create the MySQL database that PostNuke will use.........................................109
20. APPENDIX B: Create the MySQL username and password that PostNuke will use...............111
21. APPENDIX C: Configure the webserver.......................................................................................113
22. APPENDIX D: Configure PHP ......................................................................................................115
23. APPENDIX E: Enable GZIP compression in php.ini ..................................................................117
24. APPENDIX F: Getting development versions of PostNuke using the CVS server at
developer.hostnuke.com ...............................................................................................................119

vii viii
 Chapter 1. Important Note Regarding This Version Of The Guide

Chapter 1. Important Note Regarding This

Version Of The Guide
This version of the Official PostNuke Installation and Getting Started Guide is the most current, up-to-
date revision, and is presented for review and comment. Since revision 9900, the Guide is CONTENT
COMPLETE and ready for PEER REVIEW/REVISION and EDITING. There will be a spelling and
grammar pass made through the Guide once the content has been reviewed.
I am very interested in your review of and comment on the Guide as it stands at this point. If you notice
anything that is spelled incorrectly, is incomplete, could be explained better, or is just plain WRONG,
please let me know at <drew@drewvogel.com>.
The plan for the future of the Guide is as follows:

• Complete the content -- DONE!

• Peer Review/Revision & Editing -- IN PROCESS
• Port the Guide to DocBook format -- IN PROCESS
• Create a variety of output types (PDF, HTML, help, online help, text, etc)

Once the Guide is through the peer review & editing process, it will be released with fewer restrictions.
It will also be made more presentable using DocBook instead of being displayed in this ugly monospace
font. Currently, I am interested only in your comments about the CONTENT, not the PRESENTATION.
When the Guide is finished, translation will be permitted and encouraged. If you are interested in trans-
lating this Guide, please contact Drew Vogel (<drew@drewvogel.com>).

9 10
 Chapter 2. Credits

Chapter 2. Credits
PostNuke was written by the PostNuke Team. PostNuke is, as with many successful open-source projects,
a huge collaborative effort spanning many diverse talents from across the globe. Without their vision, this
document would not exist. The complete credits file can be found in the html/docs folder of the PostNuke
distribution.
Thank you to the PostNuke Team for declaring this to be the "Official" guide.
The Official PostNuke Installation and Getting Started Guide was written by Drew Vogel. Additional
sections compiled by Drew Vogel from wiki sources on http://docs.postnuke.com. Thanks to the
authors, reviewers, contributors, Wesley Blue, Chris Godfrey, Søren Grauslund, Murilo Pinto, Richard
Cave, Peter Lunn, Terry Garrett, Pedro Innecco, Steven Johnson, Craig Saunders, Curtis Nelson, and Des
Dougan. Additional material by Dean Peters (<dean@deanpeters.com>, http://www.deanpeters.
com), used with permission. Special thanks to Gregor Rothfuss for many things.

11 12
 Chapter 3. Most Current Versions

Chapter 3. Most Current Versions

The most current version of PostNuke is always available at http://www.postnuke.com.
The most current version of this Guide is always available at http://www.drewvogel.com, in the Down-
loads section under PostNuke Documentation.
PostNuke, and this Guide, are works in progress. Every effort will be made to keep this document up-to-
date with the current release of PostNuke.

13 14
 Chapter 4. Who Should Use This Guide

Chapter 4. Who Should Use This Guide

This Guide is for PostNuke installers, or those individuals interested in PostNuke installation and config-
uration issues.
This Guide is intended to be read from start to finish. Certain sections may be skipped as directed (for
example, if you’re upgrading, you do not need to read the first-time installation instructions). However,
reading this entire Guide from start to finish will provide the maximum educational benefit.

15 16
 Chapter 5. An Overview of Content Management Systems (CMS)

Chapter 5. An Overview of Content has been designed as an ENGINE, and is capable of far more than simply posting news, stories, docu-
mentation, etc. The ENGINE of PostNuke essentially handles web site configuration, presentation, and
Management Systems (CMS) user management. Additional ’bells and whistles’ chosen by the administrator can be virtually ’bolted’
on to the PostNuke engine. Some may use PostNuke for something entirely different than the "news site"
configuration we will be discussing in this manual. Many PostNuke sites are configured as a company
A Content Management System (CMS), in general, allows you to "dynamically" handle content (primarily Intranet application -- a single point-of-entry for all their internal processes (i.e., project approvals, time
text at this point in development, but images also to some degree -- as well as other media such as MP3’s). tracking, billing, file storage, etc.). PostNuke’s only limitation is the imagination of the administrator. In
To illustrate this, compare a CMS with more traditional "static" HTML pages. With static pages, each time fact, one of the PostNuke developers is giving serious consideration to writing a text-based game (ala
you want to change or update something on your site, you have to download, edit the page, and upload it Infocom) as a module that relies upon PostNuke’s engine -- without a "news" focus at all!
back to the server. Only you, and the people who have your access codes, can update the site.
With a dynamic CMS like PostNuke, you only have to upload the site during the initial installation of
the CMS. If you want to add an article, you just go to your site with a web browser (from any computer
connected to the Internet), and click on ’Add Story’, ’Submit News’, (or whatever this function is called
on your site). A box appears, and you either type or cut/paste the story into the box, then click on the
Submit button.
At this point, the story may not appear immediately on the site, since CMS’s can be configured so that
any visitor can submit a story but a manager must approve the story before it is made available. The site
manager, or one of a group of editors that are responsible for maintaining the site, will be sent an e-mail
announcing that someone has submitted a story for approval. They will then go to the site, log in with
their administrator name & password and decide if the story should be deleted or approved & posted. This
occurs with just a few easy mouse-clicks.
Once the story is approved, it will appear near the top of the page along with a small image which indicates
the Topic associated with that story. All the other stories move down on the page to make room for the
new story.
To summarize: with ordinary, static web pages, you have to do a lot of HTML editing and uploading each
time you want to change something on your site. With a CMS, you can forget all this, and just change
your site by surfing to it and clicking on the links for updating your site (so if you know how to surf the
net, you can maintain your site; very little other work is necessary!).
The above scenario describes only one of the most basic functions of a CMS. It’s all you really need to
know to maintain a basic site. But there are hundreds of different functions available in an advanced CMS
like PostNuke. Fortunately, it’s fairly easy to figure out the main functions, ignoring the rest until you
wish to use them. But this is the second advantage of using a CMS instead of ordinary HTML pages: the
advanced functionality allows your users to search your site, post on forums, leave user information which
is easily manageable -- in short, anything that can be done with advanced database management. There
are over 100 different ’modules’ available for PostNuke, each with its own specific functionality, and new
modules are being added every week.
If you think all of this sounds good, you’ll absolutely love this... In the description above, we have only
scratched the surface of what PostNuke can offer! In fact, speaking technically for a moment, PostNuke

17 18
 Chapter 6. An Overview of PostNuke

Chapter 6. An Overview of PostNuke

PostNuke is an Open Source multi-lingual Content Management System (CMS) written in PHP
and licensed under the GNU General Public License. PostNuke software dynamically manages
website content submitted through browsers. PostNuke has been rated as "IBM Server Proven"
by IBM (http://www8.software.ibm.com/solutions/isv/igssg.nsf/list/bycompanyname/862569E
D0005977186256B4900774EA4?OpenDocument (http://www8.software.ibm.com/solutions/
isv/igssg.nsf/list/bycompanyname/862569ED0005977186256B4900774EA4?OpenDocument))
and is currently the only Open Source CMS to have attained this status.
PostNuke allows administrators to work dynamically within a structured environment to rapidly deliver
diverse content including articles, links, news, job boards, frequently asked questions, resume listings,
dynamic headlines, weather, file download areas, and much more. PostNuke reduces web site development
costs by introducing sophisticated administration tools & services which separate form, function, content,
and design.
Utilizing the ADODB database abstraction layer (http://php.weblogs.com/ADODB), PostNuke con-
nects to many different database management systems (DBMSs) (including MySQL, SQL, PostGRESQL,
among others) providing convenience and flexibility for internet/intranet implementations of any size. De-
signed from the ground up to be modular, EXPANDABILITY is a key feature of PostNuke. Modules can
be ’bolted’ into the web site with very little configuration, making it a snap to add new features.
The PostNuke development community is world-wide, active, and dynamic. With over 120 active devel-
opers spanning five continents and more than thirty-five languages, PostNuke’s development draws from
the best & brightest of the open source development community.

19 20
 Chapter 7. Benefits of PostNuke

Chapter 7. Benefits of PostNuke

Some major benefits & features of PostNuke are:

• Site structure, design, editing, and the submission of site content can be separated for easy administra-
tion of material;
• Sites are scalable, so many people can contribute to a PostNuke site/community;
• PostNuke is the first CMS to be rated as "IBM Server Proven
(http://www8.software.ibm.com/solutions/isv/igssg.nsf/list/
bycompanyname/862569ED0005977186256B4900774EA4?OpenDocument)";
• Sites are flexible, there are great default features included in PostNuke and these can be easily altered,
extended, or modified;
• Site development is Open Source (collaberative code) allowing robust, modular, consistent, security-
and standards-aware feature-rich software with a number of support options;
• Completely Database-Driven Site Engine (ADODB Compliant
(http://php.weblogs.com/ADODB));
• Extendable Through The Use of Third Party Modules;
• Powerful Security Module for Multi-level User/Administrator Logins;
• Fully Editable and Manageable News, Links, Downloads, FAQ, and Services Sections;
• Customizable Layouts - (coming soon);
• Dynamic Forum/Poll/Voting Booth for On-The-Spot Results;
• News Feed Manager - Access to over 1,000 news feeds;
• Banner Ad Manager - Sell Advertising on your site;
• Site Statistics indicates Browser & Operating System, Top News and Articles;
• Distribute workload using the Users/Administrators Manager;
• Easy Install on any Unix including Linux, FreeBSD, MacOSX, Solaris, AIX, SCO, and most Windows
operating systems including Win98/NT/2000/XP.

21 22
 Chapter 8. System Requirements

Chapter 8. System Requirements Software Recommendations

Some additional software packages will speed up your web site or offer enhanced features. You may wish
The following sections detail the hardware and software requirements for running PostNuke. More infor- to install these packages.
mation about configuring the software packages can be found in the Appendix. * It is very strongly recommended that a properly configured & working email subsystem (for example,
SendMail, QMail, ProcMail, etc) is installed on your server. Most hosted sites will provide this subsystem.
It is beyond the scope of this document to cover the installation and configuration of this software.
Hardware Requirements
* phpMyAdmin (http://phpmyadmin.sourceforge.net) -- recommended only if the site will be us-
The hardware requirements for PostNuke are essentially driven by the software that you wish to run on ing the MySQL database system -- phpMyAdmin is a cross-platform free utility that can manage an entire
the computer. If your computer is capable of running PHP, MySQL, and the webserver (Apache / IIS / MySQL server, but also a single database. Many users may not have root (administrator) access to their
etc.), then it can certainly run PostNuke. More generous hardware configurations, additional memory, and database. If that is the case, you will need to create the database using an online tool such as phpMyAdmin.
increased storage space will improve the performance and capabilities of the system.
* Enabling GZIP compression within PHP is an easy way to add some speed to your site.
* Internet connection: An internet connection is very highly recommended, but it is not required -- Post-
* PHP Accelerator (http://www.php-accelerator.co.uk) -- PHP Accelerator is free, able to deliver
Nuke will run quite happily on a standalone computer.
performance gains and load average reduction to rival or exceed the very best alternatives, and is the
* Storage: The absolute minimum storage space for an installation of PostNuke is approximately 8 intelligent choice of script caching solutions for PHP based sites.
megabytes. However, this amount of storage leaves almost no room for expansion. It is therefore rec-
ommended that PostNuke is allocated at LEAST 25 megabytes of storage space.
Tools You Can Use
Software Requirements Make sure that you have the following applications handy. You will need them to facilitate your in-
stallation. If you need to download any of these programs, check http://www.download.com or
Before you can run PostNuke, it first needs to be installed or upgraded from a previous version. Before http://www.tucows.com (http://www.download.com).
PostNuke can be installed, there are other pieces of software that must be installed and functioning on
your system, and additional pieces of software that you may wish to install. In this section, we discuss the • An FTP program
different pieces of software that are the minimum requirements for running PostNuke.
• A Telnet program that also supports SSH
* Supported operating systems include: Unix, Linux, FreeBSD, MacOSX, Solaris, AIX,
Win98/NT/2000/XP, Sun Cobalt OS (RAQ4) • An ASCII text editor

* A functioning webserver (Apache or IIS, among others). See Appendix A for information about config- • A compression tool (TAR, ZIP, etc.)
uring the webserver. * FoxServ (http://www.foxserv.net) -- FoxServ is an extremely handy tool for first-time PostNuke
* A working installation of PHP (version 4.0.1pl2 or higher) compiled with MySQL support. PHP is the users to get Apache / MySQL / PHP / Perl up and running quickly, particularly for Windows servers.
language in which PostNuke is written. Without PHP support, the web server would not be able to parse * Apache Toolbox (http://www.apachetoolbox.com) -- Apache Toolbox is a fully customizable and
the PHP files and your site would not work. See Appendix B for information about configuring PHP. menu driven script for Linux that will install Apache / MySQL / PHP / PERL, and much more. Everything
* A working database management system (MySQL 3.23 or higher, SQL, or PostGRESQL, among oth- is compiled from source. It checks for RPMs that might cause problems and uses wget to automatically
ers). download the source if it’s missing. This is an advanced tool for Linux.
* PHPTriad (http://sourceforge.net/projects/phptriad) -- PHPTriad installs a complete work-
ing PHP/MySQL server environment on Windows platforms (9x/NT). Installs PHP, Perl, MySQL,
Apache, and PHPMyAdmin.

23 24
 Chapter 9. Assumptions & Conventions

Chapter 9. Assumptions & Conventions

This Guide is the one-stop resource for PostNuke, no matter what OS platform runs it. Examples are given
for both Windows and *NIX systems whenever possible.
For the purposes of this documentation, the following assumptions are made:
* You are running a Red Hat-compatible Linux distribution (other *NIX-type installations will work as
well) (http://www.redhat.com).
* You are running Apache (http://www.apache.org).
* You are running MySQL (http://www.mysql.com).
* You are running PHP (at least version 4.0.1pl2) (http://www.php.net).
* Your web directory (where your web pages are located) is "/var/www/html". We call this the Documen-
tRoot.
* Your URL is "http://www.yoursite.com".

25 26
 Chapter 10. New Installation

Chapter 10. New Installation pixels wide by 80 pixels tall to fit into most pre-made themes. However, if you
are satisfied with how a larger graphic looks, you may use a logo graphic that
ignores these size recommendations. This graphic file is displayed at the top
If you are new to the world of PostNuke or CMSs, WELCOME! You are about to embark upon a very of the page within some themes, and at the top of every page that is printed
exciting journey. Grab a big cup of coffee, sit back, and let’s get this installed and configured! from your site.
Ensure that your system has the required software (and, optionally, the recommended software) installed
and working before attempting installation of PostNuke. The graphic file must be located in the /images/ directory of your web site or
within the theme’s /images/ directory. The graphic file can be in PNG, GIF, or
JPG format. The canonical location will be determined in a future release.
Step-by-step: First-time installation of PostNuke
* Set the following permissions on these files located in your web directory:
- "chmod 666 config.php" (Windows: Remove the read-only file attribute
• Print this document and keep it handy during the installation. with "attrib -r config.php". If using NTFS, be certain that the proper NTFS
• Create the database that PostNuke will use. See Appendix 1 for assistance with this step. permissions are set.)

• Create the database username and password that PostNuke will use. See Appendix 2 for assistance with
- "chmod 666 config-old.php" (Windows: Remove the read-only file
this step.
attribute with "attrib -r config-old.php". If using NTFS, be certain that the
• Obtain the latest PostNuke release from http://www.postnuke.com in either ZIP or TAR.GZ format. proper NTFS permissions are set.)
Download the release to a temporary directory. Under *NIX, TAR.GZ is the preferred format since the
files will possess the correct user privileges. * Point your browser to the installation file (for example,
• Using your compression program, VIEW the distribution file to make sure it will expand the files into http://www.yoursite.com/install.php).
the correct subdirectory path.
* Follow the prompts to create databases, tables, and configuration options.
• Extract the PostNuke archive into a temporary directory. Move the /html and /sql directories into your - Select your language from the drop-down list. Click "Set Language" to
DocumentRoot (as specified by Apache) (for example, /var/www/html), preserving paths (for example, continue.
"tar -xzvf $lt;PostNuke-archive.tar.gz$gt;", "mv -R html /var/www/", "mv
-R sql /var/www/"). - Read the license. Click "Next" to agree with the license terms and
-or- continue installation. If you do not agree with the license terms, abort the
installation.
• Upload the extracted PostNuke files into your web directory, preserving paths.
- CHMOD Check: PostNuke checks to make sure that critical files are
* If you plan to offer multiple languages, download and install the appropriate appropriately writable in the web directory. If no errors are reported, click
language packs. English is included in the distribution by default. Language "Continue". If there are errors reported, correct them and click "Re-check" to
packs and installation instructions can be found on SourceForge’s PostNuke perform the CHMOD check again.
page: http://sourceforge.net/projects/post-nuke under "Files".
- Database configuration
* If you have a logo graphic for your site, upload it to the images directory - Database Host: Enter the name of the host system where the
(for example, /var/www/html/images). You may name the file anything you want. database files will be stored. This is the <dbhost> that was defined in
If you do not yet have a logo, you may skip this step and the default PostNuke Appendix A. If your database is on your local machine, this entry will usually
logo will be displayed. Generally, the dimensions of this file should be 220 be "localhost".

27 28
 Chapter 10. New Installation Chapter 10. New Installation

- Database Username: Enter the database username that will be If you receive an error such as "Unable to make database", then you do not have
used to add, edit, and delete records from the database. This is the <dbuser> root access to the database and will need to create the database in another way
that was defined in Appendix B. before the installation can continue. See Appendix A for assistance with
creating the database.
- Database Password: Enter the database password for the user
defined above. This is the <dbpass> that was defined in Appendix B. Once the database has been created, installation can continue and the tables
will be created. Click "Continue" to move to the next step.
- Database Name: Enter the name of the database to be created.
This is the <dbname> that was defined in Appendix A. Entry example: "postnuke". You can now set up an Administrator account. If you skip this step, the login
for the Administrator account will be username: "Admin" and password:
- Table Prefix (for Table Sharing): If you wish to prefix the "Password" (case sensitive). However, it is very strongly advised that you set
table names, enter the prefix here. For most users that are not sharing tables, up an Administrator account now.
the recommended entry is "nuke".
- Admin Login: Enter the login name of the Administrator here. The name
- Database Type: Select the database type from this drop-down that is entered is displayed as a user on the site. Pick an appropriate name.
list. Entry example: "MySQL" Entry examples: "siteadmin" or "joesmith".

- Site is for intranet or other local (non-internet) use: Check - Admin Name: Enter the full name of the Administrator here. Entry
this box if this site is intended for intranet or other local (non-internet) example: "Joe Smith".
use.
- Admin Password: Enter the password for the Administrator here.
Click "Continue" to move to the next step.
- Admin Password (verify): Enter the password for the Administrator
You are presented a review of the database configuration selections that you again here to verify that the correct password is saved.
just made. If they are incorrect, click "Change Info" to modify the selections.
If the settings are correct, click "New Installation" to begin the installation. - Admin Email: Enter the full email address for the Administrator here.
Entry example: "admin@yoursite.com".
- If you were able to create the database as directed in Appendix A, leave
"Create the database" box UNCHECKED and click "Start". - Admin URL: Enter the URL for the Administrator here, including
"http://". Usually, the URL will be the site that the Administrator is
- If you did not create the database as directed in Appendix A, and have root administrating. Entry example: "http://www.yoursite.com".
access to the database, check the "Create the database" box and click "Start".
IMPORTANT NOTE: Write down the Administrator name & password. You will need
- If you do not have root access, you must create the database manually and the them later.
installation script will automatically add the tables. See Appendix A for
assistance with creating the database. Click "Set Login" to save this information. You will be notified that the
update was successful. Click "Finish" to continue.
- If you are not sure if you have root access or not, check the "Create the
database" box and click on "Start" to try it. Click "Go to your PostNuke site" to enter your PostNuke site for the first

29 30
 Chapter 10. New Installation Chapter 10. New Installation

time. Skip down to "TESTING THE INSTALLATION/UPGRADE", below.

31 32
 Chapter 11. Upgrade Installation

Chapter 11. Upgrade Installation IMPORTANT NOTE: If you do not move ALL previous-version PostNuke files from these directories, it
will prevent your web site from functioning properly.

If you have a previously installed version of PostNuke, or if you were running PHPNuke or MyPHPNuke,
and wish to switch to PostNuke, you can use the Upgrade features of the installation to migrate your older • Extract the PostNuke archive into a temporary directory. Move the /html and /sql directories into your
system into the new PostNuke system. DocumentRoot (as specified by Apache) (for example, /var/www/html), preserving paths (for exam-
Previous versions of PostNuke (versions 0.50, 0.60, 0.62, 0.63, 0.64, and 0.7x) can be automatically up- ple, "tar -xzvf <PostNuke-archive.tar.gz>", "mv -R html /var/www/", "mv -R
graded to the latest version of PostNuke using the upgrade function. Additionally, upgrades from MyPH- sql /var/www/").
PNuke (versions 1.87 and 1.88) and PHPNuke (versions 4.40, 5.20, 5.30, 5.31, and 5.40) to the latest -or-
version of PostNuke are supported by the upgrade process. Upgrades from PHPNuke 5.5 and later will be
available in a future PostNuke release. • Upload the extracted PostNuke files into your web directory, preserving paths.
Through the upgrade process, user accounts are preserved, as are the settings for Articles, Blocks, Com- • If you wish for your site to offer multiple languages, download and install appropriate language packs.
ments, Downloads, Headlines, and Reviews. Features that are specific to other CMS software (for exam- English is included in the distribution by default. Language packs and installation instructions can be
ple, article ratings in PHPNuke) are not converted and will be removed from the PostNuke database. Some found on SourceForge’s PostNuke page: http://sourceforge.net/projects/post-nuke under
modules and blocks may need to be upgraded to newer versions before they will function with PostNuke. "Files".
• From your previous-version backup, copy "config.php" and "config-old.php" to your web directory (for
example, under *NIX, type "cp /var/nukebackup/config.php /var/www/html/", "cp
Step-by-step: Upgrading PostNuke
/var/nukebackup/config-old.php /var/www/html").
• Additionally, copy "config.php" into the web directory with the name "pn7config.php"
• Print this document and keep it handy during the installation. (for example, under *NIX, type "cp /var/nukebackup/config.php
• Obtain the latest PostNuke release from http://www.postnuke.com in either ZIP or TAR.GZ format. /var/www/html/pn7config.php").
Download the release to a temporary directory. Under *NIX, TAR.GZ is the preferred format since the • Set the permissions on these files located in your web directory:
files will possess the correct user privileges.
• "chmod 666 config.php" (Windows: Remove the read-only file attribute with "attrib -r
• Using your compression program, VIEW the distribution file to make sure it will expand the files into config.php". If using NTFS, be certain that the proper NTFS permissions are set.)
the correct subdirectory path.
• "chmod 666 config-old.php" (Windows: Remove the read-only file attribute with "attrib
• Completely back up your entire web directory (for example, /var/www/html). -r config-old.php". If using NTFS, be certain that the proper NTFS permissions are set.)
• Do a dump of your web site’s database using "mysqldump" (or equivalent utility). Try the • "chmod 666 pn7config.php" (Windows: Remove the read-only file attribute with "attrib
following:"mysqldump -u <db_administrator_name> -p --opt <old_db_name> -r pn7config.php". If using NTFS, be certain that the proper NTFS permissions are set.)
> DBbackup_10Apr02.sql".
You will be prompted for your administrator password and the contents of the database called
"old_db_name" will be saved as "DBbackup_10Apr02.sql" in the current directory. • Point your browser to the installation file (for example, http://www.yoursite.com/install.php).
• Follow the prompts to modify databases, tables, and configuration options.

• Move all previous-version PostNuke files & directories from your web directory and sub-directories into • Select your language from the drop-down list. Click "Set Language" to continue.
another location. Be especially careful to move everything from the /includes and /modules directories. • Read the license. Click "Next" to agree with the license terms and continue installation. If you do not
It is not necessary to move NON-PostNuke files from the web directory or sub-directories (for example, agree with the license terms, abort the installation.
under *NIX, type "mv -R /var/www/html/* /var/nukebackup").

33 34
 Chapter 11. Upgrade Installation Chapter 11. Upgrade Installation

• CHMOD Check: PostNuke checks to make sure that critical files are appropriately writable in the • If you have a logo graphic for your site, upload it to the images directory (for example,
web directory. If no errors are reported, click "Continue". If there are errors reported, correct them /var/www/html/images). You may name the file anything you want. If you do not yet have a logo,
and click "Re-check" to perform the CHMOD check again. you may skip this step and the default PostNuke logo will be displayed. Generally, the dimensions of
• Database configuration this file should be 220 pixels wide by 80 pixels tall to fit into most pre-made themes. However, if you
are satisfied with how a larger graphic looks, you may use a logo graphic that ignores these size recom-
• Database Host: Enter the name of the host system where the database files are stored. If your mendations. This graphic file is displayed at the top of the page within some themes, and at the top of
database is on your local machine, this entry will be "localhost". every page that is printed from your site.
• Database Username: Enter the database username that will be used to add, edit, and delete files The graphic file must be located in the /images/ directory of your web site or within the theme’s /im-
from the database. ages/ directory. The graphic file can be in PNG, GIF, or JPG format. The canonical location will be
• Database Password: Enter the database password for the user defined above. determined in a future release.
• Database Name: Enter the name of the database to be upgraded. Entry example: "postnuke".
• Table Prefix (for Table Sharing): If you wish to prefix the table names, enter the prefix here. For Click "Go to your PostNuke site" to enter your PostNuke site for the first time. Skip down to "Testing The
most users that are not sharing tables, the recommended entry is "nuke". Installation/Upgrade", below.
• Database Type: Select the database type from this drop-down list. Entry example: "MySQL" Once the upgrade has been tested to work, you may begin to migrate your NON-PostNuke files from the
backup directory back into the web directory. You may now delete your previous-version backup files (for
• Site is for intranet or other local (non-internet) use: Check this box if this site is intended for
example, from /var/nukebackup)
intranet or other local (non-internet) use.

Click "Continue" to move to the next step.

You are presented a review of the database configuration selections that you just made. If they are incor-
rect, click "Change Info" to modify the selections. If the settings are correct, select "Upgrade" to upgrade
from a previous version of PostNuke, or if you are migrating from PHPNuke or MyPHPNuke.
The next screen is where you select the CMS from which you are upgrading.

• Click "PHP-Nuke" to upgrade an existing PHP-Nuke install.

• To continue, click the version of PHP-Nuke you wish to upgrade. Follow the prompts.

• Click "PostNuke" to upgrade an existing PostNuke install.

• To continue, click the version of PostNuke you wish to upgrade. Follow the prompts.

• Click "MyPHPNuke" to upgrade an existing MyPHPNuke install.

• To continue, click the version of MyPHPNuke you wish to upgrade. Follow the prompts.

35 36
 Chapter 12. Testing The Installation/Upgrade

Chapter 12. Testing The Installation/Upgrade

Before we can declare the installation/upgrade a success and begin configuring your site, we need to test
its basic functionality. The first way to test it is to click the "Go to your PostNuke site" and see if PostNuke
comes up.
If you do not see a PostNuke page, something went wrong. The first thing to check is that no "index.html"
file exists in your web directory. If there is such a file, rename it (or delete it) to prevent it from overriding
the "index.php" file. Also, if you performed an upgrade to PostNuke, you may need to clear the cookies
in your browser, and then restart your browser.
If you get a message that says something like: "Warning: Access denied for user: ’root@localhost’ (Using
password: YES) in newinstall.php on line 36 Unable to make database", then your database username
and/or password is incorrectly defined.
You may wish to visit the PostNuke live support site located at
http://www.postnuke.com/modules.php?op=modload&name=IRC_Chat&file=index
(http://www.postnuke.com/modules.php?op=modload&name=IRC_Chat&file=index) for more
assistance with this and other installation problems. Before accessing this page, it is necessary to register
for a free account on http://www.postnuke.com.
If you see a PostNuke page, then the installation/upgrade was a success. You should now do the following:

• Delete the entire install directory from the DocumentRoot (for example, /var/www/html/install). It is a
security risk to leave it on the website.
• Delete the install.php file from the DocumentRoot (for example, /var/www/html/install.php). It is a
security risk to leave it on the website.
We can move forward into configuration, after a quick lesson in terminology.

37 38
 Chapter 13. A Lesson in PostNuke Terminology

Chapter 13. A Lesson in PostNuke Terminology • GROUPS: Categories of site users with different levels of site privileges to add, modify, approve, or
view elements of the site or content. For example: Admins, Editors, Users, Unregistered visitors.

Before we move forward into Basic Website Configuration, it is important to explain several concepts and • PERMISSIONS: Working in conjunction with GROUPS, PERMISSIONS determine what a user is
some terminology. Please take the time to read and understand this section. permitted to do on the site.
• THEMES are preconfigured modules that change the look & feel of site elements such as fonts, colors,
• BBCODE: OTTO graphics, and other design features (they are essentially the same as ’templates’ or ’skins’).
• BLOCKS: The different types of information displayed on the site. For example: News Articles, Polls, • WIKI ENCODING: Wiki Encoding is an alternative to HTML code for display within articles and text
and Links are different types of Blocks. on the site. A reference to the Wiki Text Formatting Rules is at: http://phpwiki.sourceforge.
net/phpwiki/TextFormattingRules. PostNuke does NOT provide a full-blown Wiki implementa-
• CATEGORY: With Categories, a page can be displayed (much like the main page of the website) on
tion. If you seek a full Wiki, check http://phpwiki.sourceforge.net/phpwiki/PhpWiki.
the site containing only the Articles that fit into that Category. An example of Categories illustrates it
very well:
• Category Youth
• Topic news
• Topic announcements

• Category Adults
• Topic news
• Topic announcements

• Category Seniors
• Topic news
• Topic announcements

For example, when you go to the category ’Youth’, you have a whole sub-site dedicated to Youth. When
you go to the category ’Adults’, you have a whole sub-site dedicate to Adults, etc.

• COMMENTS: User-added material beneath an element. For example: A comment on an Article.

• MODULES: Functional elements (mini-applications) that are designed to be virtually ’bolted on’ to a
Postnuke site. For example: A calendar or forum.
• TOPICS: Categories of content. News is categorized by Topic, for example, Music and Cooking.

39 40
 Chapter 14. Basic Website Configuration

Chapter 14. Basic Website Configuration 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"
In order to configure your site, you will need to log in as the Administrator. We set up an Administra-
tor username & password during first-time installation, above. Upgrading users will use their existing For additional information on Meta Keywords, please visit Web Developer-META Tag Resources
Administrator username & password. (http://www.webdeveloper.com/html/html_metatag_res.html) or The META Tag Builder
(http://vancouver-webpages.com/META).
Point your browser to your site (http://www.yoursite.com) and log in by entering the Administrator name
and password in the "User’s Login" and "Password" fields. Click "Login" to log in. You will see a new
menu listing called "Administration" on the Main Menu. Click the Administration link to go to your site’s • Dynamic Meta Keywords: In addition to defining your own keywords for your site, you can choose to
administration tools, and click Settings. have meta keywords generated dynamically. When this option is enabled, meta keywords are generated
Within the Settings section of configuration, you can ’personalize’ PostNuke site to your tastes. dynamically whenever the full text of an article is being displayed. All the words in the article are used
as meta keywords. Enabling this function (setting it to "Yes") has a small performance cost.
• Site Start Date: This simple field displays the site start date. Entry is free-form alphanumeric text. The
Basic Site Setup contents of this field is displayed on Statistics pages, and other areas within the site.
Entry example: "June 25, 2001"
• Site Name: This is your site’s name. Something like "PostNuke Central", "Game Central",
"DrewVogel.COM", or "Top 20 Hits of All Time".
• Administrator E-Mail: This field is the email address where all administrative emails will be sent. This
• Site Logo: This field names a graphic file that is the logo for your site. The file named in this field is the person who is responsible for maintaining the major parts of the site. Enter the complete email
must exist in your /var/www/html/images directory. An example of what might be entered in this field: address. NOTE: If you do not have an installed & working email subsystem on your webserver, it is not
"logo.gif". necessary to enter anything into this field.
• Site Slogan: This field allows the administrator to define an optional slogan for the site. This slogan is Entry example: "admin@yoursite.com"
displayed at the top of the page under the site name in some themes, and in the title bar of the browser
by default.
• Default Theme for your Site: From the drop-down list, select the name of the default theme you would
If the Site Name is defined as "Game Central" and the Site Slogan is defined as "It’s All
like users to see when they access your site. When users register for access to your system, they may
About the Games!", the browser title bar would be:
have the option to change the theme that they see when accessing the site. A user’s theme settings are
Game Central :: It’s All About the Games! for THEIR account only; other users of the system will see the default theme as specified here unless
the user has selected a different theme.

• Meta Keywords: One of the challenges when running a web site is letting external search engines know • Allow users to override theme?: This setting indicates if you would like your users to be able to select
that your site exists. Meta Keywords define words that categorize your site. Many search engines send from any additional themes that you may have installed, or if you would like to force the default theme
out robots (also called spiders) to search the Web for content. When you define Meta Keywords for (above) for all users. Entry example: "Yes" (allows users to select their own theme).
your site though this configuration option, you make it easier for the search-engine robots to categorize IMPORTANT NOTE: If you allow users to override their theme setting but later change this setting to
your site, and your site will be categorized more appropriately since you are defining the options. Enter "No" (do not allow users to select their own theme), you will need to manually edit the preferences of
words & phrases, separated by commas, that describe the focus of your web site. Capitalization is not each user that has switched themes on your site. Edit the user’s preferences to point to your system’s
important in this field. Many search engines limit the number of keywords that you can use. Therefore, DEFAULT theme otherwise the user will be ’locked’ out of your system. For example, if you disable
you should choose your words carefully and use no more than 10-15 keywords that best describe your or remove a theme, or remove the ability for the user to change themes, and your user has previously
site’s content. specified a theme that you have deleted or are no longer allowing, the user will see a blank white page
when they try to access your site. Edit that user’s preferences and select the DEFAULT theme you

41 42
 Chapter 14. Basic Website Configuration Chapter 14. Basic Website Configuration

specified, above. Be sure to save your changes. For more assistance with this problem, please visit IRC Entry example: "For referrers from this domain only" (recommended setting).
Support.

• Enable funny error messages in error.php: APACHE ONLY -- DOES NOT WORK WITH IIS. If your
• Display Right Blocks in Articles?: When a user selects a story to read, this function determines if a page/module reference isn’t found, your visitors are presented with a helpful page of instructions. To
Right Block is displayed next to the story. This Right Block includes "Related links" and other features. enable this error-handling feature, add the following line into a .htaccess file located in your web’s root
"Related Links" are links that PostNuke determines to be related to the specific news article, either directory (for example, /var/www/html):
because the two articles are in the same topic, or because they are by the same author. Set to "No" if
--- CUT HERE ---
you do not wish for the Right Block to be displayed.
ErrorDocument 404 http://www.yoursite.com/error.php?op=404
• Locale time format: This determines the format for time and date display on the site -- 12 hour or 24
hour, date format, etc. Most US residents will use "en_US". --- CUT HERE ---

• Timezone Offset: Set for the timezone that your SERVER is in. Example: My server is hosted in the If you enable "Funny error messages", users will additionally see some Java-scripted nonsense ala
Eastern US timezone, so I set the Timezone Offset in the Administration panel to that timezone (GMT Hitchhikers Guide to the Galaxy, the only purpose of which is to entertain the visitors, rather than to
-5:00 hours). A user on my site might be located on the West Coast of the United States which is 3 inform. Entry example: "Yes" (displays funny error message and helpful error page), or "No" (display
timezones away. Now when that user sets his preferences in his user options, the time will be displayed only the helpful error page)
to that user in his timezone instead of the timezone of my server. An example of this feature can be found at: http://www.postnuke.com/error.php?error=404 or
• Start Page: The module to which index.php is pointing... Essentially, the module you wish to have http://www.drewvogel.com/error.php?error=404.
displayed as the "front page" to your site -- the very first thing that users see when they visit your site. An alternate way to configure error.php handling, if you have httpd.conf access, is to edit your Apache
Select from the drop-down list of modules. The most common setting is "News" as the default Start httpd.conf (usually in /etc/httpd/conf) to specify the error handler. For example:
Page.
--- CUT HERE ---
• Number of articles on Admin menu: Indicates the number of articles you wish to have displayed in the ErrorDocument 401 /error.php?error=401
Administration menu. This setting is useful because stories can be edited easily from the Administration ErrorDocument 403 /error.php?error=403
menu. Select a number from the drop-down list. Example: 20 ErrorDocument 404 /error.php?error=404
ErrorDocument 500 /error.php?error=500
• Stories # on Home Page: This determines the number of news items that are displayed on the home
page. A smaller number in this box makes your pages load faster, while a larger number shows more --- CUT HERE ---
items to the user at a time. Entry example: 20
Note that you need to restart your Apache session (for example, "httpd restart") in order for the
• Graphics in Administration menu?: This Yes or No switch determines if icon graphics should be dis- configuration changes to be reflected in your running site.
played in the Administration menu. Selecting "Yes" will display the graphics, while "No" will not
display them.
• Initial group for users: In this field, you type the name of the Group that new users to your site are
• Send Error reports by: PostNuke has the ability to alert the Administrator if it detects that a user is
automatically assigned. Groups and Permissions are discussed in detail further in this manual. For the
requesting a non-existent page. This setting determines how that notification takes place.
default PostNuke Permissions system, the appropriate entry is "users".
• "Don’t send error reports": Disable this feature.
** PLEASE NOTE: THIS FIELD WILL BE REMOVED FROM FUTURE VERSIONS OF POSTNUKE.
• "For referrers from this domain only": Send an error report to the site administrator CONFIGURE THE DEFAULT LANGUAGE FROM ADMINISTRATION -> LANGUAGES -> LAN-
only when the broken link is from this site. GUAGES CONFIGURATION. **
• "For all referrers": Send an error report to the site administrator when the broken link is on
this site or other sites. "For all referrers" can be used to check that sites that are linking to your site
are linking to valid pages -- this is especially useful after an upgrade.

43 44
 Chapter 14. Basic Website Configuration Chapter 14. Basic Website Configuration

• Select the language for your site: This is the default language for use on your site. If you have Multi- • Backend title: This is a one-line description of the page containing your news headlines. Specify some-
Lingual options enabled (see Administration -> Languages -> Languages Configuration, further in this thing other than your site name in this field, since the site name (as defined in Site Name, above) is
manual) and additional language packs installed, your users may be able to display the site in a different automatically displayed. Text in the Backend Title field can show up on the link back to your site or
language. Language packs can be found on SourceForge’s PostNuke page: http://sourceforge. may be displayed to identify the source from which this RSS file comes. For example, "The best
net/projects/post-nuke under "Files". Entry example: "[eng] English" in news & reviews!"
• Backend language: From the drop-down list, select the language for the RSS feed from your site.
If another site wishes to syndicate your news and requests the URL for your RSS feed, answer them with
Footer Messages http://www.yoursite.com/backend.php.
NOTE: By default, the RSS feed is available. To turn it off, rename or delete the backend.php file.
• Footer line: The ’footer’ is displayed at the bottom (the ’foot’) of each and every page on your site. This
OTTO: CLARIFY. To test that your RSS feed is functioning, open it in your browser, which will show
is an excellent place to give credit, state copyright, or put links that you wish to appear everywhere on
it to you in XML layout. You can also go to http://publish.curry.com/rss and http://www.wc.
your site.
cc.va.us/services/news to see sample output from your RSS file.
Entry example:
To include a RSS feed from another site, create an RSS Block. (See the section "Advanced Website
--- CUT HERE --- Configuration -> Blocks" elsewhere in this guide.)
"<center><a href="http://www.postnuke.com" target="blank"><img For more information about RSS, see http://www.webreference.com/authoring/languages/
src="images/powered/postnuke.butn.gif" border="0" Alt="web site powered by xml/rss/intro/ and http://blogspace.com/rss. A simple step-by-step tutorial on the components
PostNuke" hspace="10"></a> <a href="http://php.weblogs.com/ADODB" of an RSS feed is at http://www.jamsterdam.com/rss092.
target="blank"><img src="images/powered/adodb2.gif" Alt="ADODB database
library" border="0" hspace="10"></a><a href="http://www.php.net"
target="blank"><img src="images/powered/php2.gif" Alt="PHP Scripting Language"
border="0" hspace="10"></a><br><br><font size="1">All logos and trademarks in
Security Options
this site are property of their respective owners. Comments are property of
their posters, everything else © This Site.<p>This web site was made with <a • Security level: Set the overall security level for your system. This function determines how long the
href="http://www.postnuke.com">PostNuke</a>, a web portal system written in user’s session will persist. Options:
PHP. PostNuke is Free Software released under the <a
• High (users must log on each time they return to the site)
href="http://www.gnu.org">GNU/GPL license</a>.</center></font>"
• Medium (users stay logged on for a set number of days)
--- CUT HERE ---
• Low (users stay logged in forever)
Most websites will choose "Medium" as their security level as it represents the best balance between
security and convenience for the user.
Backend Configuration
Other sites can list your site’s headlines (with links) in their web pages. These sites use what is often • For Medium security, users stay logged in for: If Security level is set to Medium, this list specifies how
called an RSS feed, which is essentially an XML file laid out according to one of the RSS specifications. many days will pass before a user’s session will expire. Entry example: 3 days
This section of configuration allows you to set some specifics about how the RSS file is generated for your • Users become inactive after not using the system for: If PostNuke detects that a user’s session has been
site. You may link to news items on other websites by defining an RSS Block, which is explained in detail idle for a certain period of time, it will expire the session. This setting determines how long PostNuke
in the section Advanced Website Configuration -> Blocks, further on in this Guide. will wait before expiring the session due to inactivity. Entry example: 20 minutes

45 46
 Chapter 14. Basic Website Configuration Chapter 14. Basic Website Configuration

Run On An Intranet not use multiple languages on your web site, or if your language does not require multi-byte support,
you should set this to "No".

• Intranet: Intranet should only be set to "Yes" if you cannot access PostNuke with a fully-qualified host Click "Save Changes" when your modifications are complete. Your settings will be saved.
name (for example, http://www.yoursite.com). Setting Intranet to "Yes" removes a number of security This ends Basic Website Configuration. Before we can move forward into Advanced Website Configura-
levels from PostNuke. It is NOT recommended to run in this mode unless you are behind a firewall and tion, it is important to explain several concepts and some terminology. Please take the time to read and
users are not permitted to access the site from outside the firewall. Entry example: "No" understand the next section, UNDERSTANDING MODULES.
Another option for Intranet use without the need to set Intranet to "Yes" is as follows: Administrators
can simulate a domain name by adding the IP address of the site and the desired domain name of the
site to a HOSTS file (usually /etc/hosts for *NIX, under C:\WINDIR\system32\drivers\etc for Windows
NT/2000/XP).
IMPORTANT NOTE: Under Windows, be certain to modify the ’hosts’ file and NOT ’lmhosts’. ’lmhosts’
is for NetBIOS names.
For example, a HOSTS file entry might look like:

192.26.128.3 triton triton.tatooine.com

This means that typing http://triton or http://triton.tatooine.com would be pointed to 192.26.128.3. Hence,
the site can be loaded on an Intranet without the need to downgrade security.

HTML Options

• HTML tags allowed in posts: This table determines the HTML coding that PostNuke will accept in
submissions, either from users or from Administrators. All content entry areas will accept the HTML
codes specified below. Specify if the tag is ’Not Allowed’, ’Allowed’, or ’Allowed with 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 text-formatting tags
(for example, <b> and </b> for BOLD).
• Allowed with parameters: The HTML tag is allowed with parameters. An example of a tag with
parameters is <font type="Arial" color="#FF0000">.

• Translate embedded HTML entities into real characters: "Embedded HTML entities" usually begin with
"&#", and pertain mostly to multi-byte languages such as Korean or other Asian languages. If you do

47 48
 Chapter 15. Understanding Modules

Chapter 15. Understanding Modules the module is inaccessible to users. NOTE: Deactivate does NOT delete the physical module files (in
modules/) and/or any specific module variables created during initialization.

PostNuke allows items to be virtually ’bolted on’ to its engine. These items, called "modules", add fea- To remove a module’s functionality, go to the Administration menu’s Module link, select "Regenerate",
tures or functionality to PostNuke. Because it is extremely important to understand how modules function and click "Deactivate" next to the module to be removed. This turns the module off but keeps the module
within PostNuke, we will explain how any PostNuke module can be initialized, activated, edited, deacti- variables and database tables intact. This is all you need to do to make the module inaccessible to your
vated, upgraded, and completely removed (deleted!). Any of these actions may be taken on any PostNuke users, unless you wish to completely remove (uninstall) the module from your site. Completely remove
module. modules by deleting their sub-directories from your modules/ directory.

The PostNuke distribution comes with a selection of popular modules already configured for use with
• UPGRADE: This function will integrate new tables, module variables, and user variables when you
your system. The Administrator may choose which modules to use on the site, and disable or even com-
move from one version of a module to a newer version of a module. Note that you must Activate again
pletely remove (delete!) those that will not be used on the site. Additional modules for PostNuke may be
after Upgrading a module.
downloaded from the official module site at http://mods.postnuke.com/index.php.
• REMOVE: Completely remove (delete!) this module from your system. The module must first be de-
From the Administration menu, click "Modules".
activated before it can be removed. Clicking "Remove" will delete the modules’s database tables and
module variables from your web site, but the physical files of the module (in modules/<modulename>)
• List: Display a listing of all modules on your site, sorted by Module name. are NOT deleted.
• Regenerate: Regenerate the module listing. When a new module is added to or deleted from the mod- If you wish to completely remove a specific module, click "Remove" to remove the module from your site.
ules/ directory, the system needs to ’Regenerate’ the file structure to recognize the change in the mod- The only way to delete the physical files of the module is to remove the directory yourself (for example,
ules/ directory. However, there is no problem if you click "Regenerate" every time you wish to view the "rm modules/<modulename>). If you wish to utilize the module’s functionality again in the future, you
modules listing, to make sure that you’re working with the most up-to-date list. will need to re-initialize and re-activate the module.
After the listing has been regenerated any new modules are displayed in the modules listing (sorted by IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to "Remove" a deactivated
Module name), and you are given the option to Initialize and then Activate them. module! Be certain that you wish to delete the module before clicking the "Remove" button.

• INITIALIZE: Calls a function which creates any necessary tables and module variables that the
module requires. Modules must be Initialized before any other action can be done on them.
• ACTIVATE: Informs PostNuke that the module is initialized and should be activated. Modules must
first be Initialized before they can be Activated so tables and module variables are properly initialized.

To activate a specific module, from your site’s Administration menu, select "Modules" then "Regenerate".
From the list that appears, select the module that you wish to activate. Click "Initialize" to initialize the
module, and then click on "Activate" to turn the module on. Set the permissions (explained later in this
document), and the module is ready for use.

• EDIT: Allows the Administrator to change settings for a particular module. The module Name, Descrip-
tion, AutoLinks (on/off) (if AutoLinks are enabled, elsewhere), Ratings (on/off), and Wiki Encoding
(on/off) may be configured on a module-by-module basis.
• DEACTIVATE: This function tells PostNuke that the services that this module offers are to be taken
offline (deactivated). A module must first be Activated before it can be Deactivated. Once deactivated,

49 50
 Chapter 16. Advanced Website Configuration & Use

Chapter 16. Advanced Website Configuration & • Click "Save" to save the new Category.
• Go to the Administration page (click on "Go to admin section")
Use Click "Add Story", and the new Category will be available from the Category drop-down list.

Once the basic configuration of your website is complete and you have a good understanding of how
Modules can add functionality to PostNuke, and how to use them, it is time to move into Advanced • Publish on homepage?: Should this story be published on the homepage? The majority of Administra-
Website Configuration. Not all Administrators will use all these features, so feel free to skip around! tors will leave this field set at the default of "Yes". If the Category field (above) is set to the default
of "Articles", this field does nothing. If the Category field (above) is set to something OTHER than
"Articles", set this field to "Yes" to cause the Article to be displayed on the home page. Set to "No" if
Add Story the Article will only be available within the Category.
• Allow comments?: Click "Yes" to allow users to post comments on this story. Click "No" to prohibit
Whenever you wish to post new information to your website, go to the Administration menu and click
users from posting comments on this story. If set to "Yes", a link called "comments?" will appear at the
"Add Story". You will be taken to the Add Story screen, where you can write (or cut & paste) the story
bottom of the story. Once comments have been posted for a particular story, the link title will change to
you wish to add.
indicate the number of comments for the story.

• Title: The title of the story as it will be displayed to the user. Free-form alphanumeric text. Entry • Language: From the drop-down list, select the language for this story, or "All" to indicate that this story
example: "Cooking Basics". is shown to users regardless of the user’s language settings. The default setting of "All" is a good choice
unless you have specific reason to change it.
• Topic: From the drop-down list, select the Topic for your story. Topics allow you to divide your content
into logical groupings, and they are discussed in detail in the Topics section, below. • Story text: Enter the text of the story in this field. Permitted HTML is allowed (as defined in Admin-
istration -> Settings -> HTML Options) in this field. Text entered here will be displayed on the front
** BE AWARE THAT STARTING IN VERSION 0.713, THE NEXT TWO OPTIONS, ’CATEGORIES’ &
page of the site. Story text is used for the summary of the story, or to display one (or more) introductory
’PUBLISH ON HOMEPAGE’, ARE INCOMPLETELY IMPLEMENTED AND WILL CHANGE DRA-
paragraphs on the homepage. Extended text is where the details of the story are communicated.
MATICALLY IN FUTURE VERSIONS OF POSTNUKE. **
• Extended text: Enter extended text of the story in this field. Permitted HTML is allowed (as defined
in Administration -> Settings -> HTML Options) in this field. Text entered in this field will NOT be
• Category: From the drop-down list, select the Category for this story. Most Administrators will be able displayed on the front page of the site; it is displayed only when the user clicks "Read More" at the
to leave this field set at the default of "Articles". The default category, "Articles", is the ’master’ cate- bottom of the story.
gory, and cannot be edited or deleted. To use Categories functionality, first define additional Categories
• Notes: Permitted HTML is allowed (as defined in Administration -> Settings -> HTML Options) in this
for the site.
field. Enter notes for the story in this field. Text entered in this field will be displayed in italicized text
To add a new Category to the site, follow these steps: on the front page of the site at the bottom of the story. The Notes field is useful in a variety of ways.
For example, the site Administrator can re-visit the article and add extra information for emphasis.
• From the Administration menu, click on "Add Story". • Do you want to program this story?: If you want to delay the publication of this story until a specific
• From the Add Story screen, click "Add" next to Categories. time or date, click "Yes" and define the time or date when the story will be published in the following
fields. Note that you may not program a story in the past. If you wish to post the story immediately,
• Enter the name for the new Category. For example, "Cooking with Drew".
leave this field set to the default of "No".
• From the drop-down list, select the theme (from your currently installed themes) in which to display
• Time: Enter the hour (in 24-hour format) and minute (in 5-minute intervals) that this story should be
this Category.
posted. For example, hour: "13", minute: "35".
** NOT CURRENTLY FUNCTIONING **
• Day: Enter the day of the month that this story should be posted. For example, "4".

51 52
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Month: Enter the month that this story should be posted. For example, "7". Admin Messages
• Year: Enter the year that this story should be posted. For example, "2010". The Administration Messages module allows the Administrator to display site messages to users. Differ-
In the examples above, the story would be programmed to be posted on July 4, 2010 at 1:35pm. ent messages can be displayed to users based on the user’s status on the system. For example, display
a message to unregistered users encouraging them to register, or show a message to registered users in-
forming them of new features that are available to them. You may have as many Administration Messages
• Preview story: The default for the drop-down list is to Preview the story. Choose Preview to show defined as you wish.
the complete story as it will be displayed to users. Click "OK" to preview the story. Check spelling,
If you have Administrative Messages defined, they are listed at the top of the screen with the option to Edit
grammar, and URLs.
or Delete the message. Click "Edit" to edit the message. Make any changes that you wish, then click "Save
• Post story: When you are satisfied that the story is correct, select "Post story" from the drop-down list. Changes" to save. Click "Delete" to delete an Administration Message. Click "Yes" to confirm deletion or
Click "OK" to post the story and make it immediately available to users. click "No" to abort deletion of the Administrative Message.
TIP: If you wish to present a series of articles (Part 1, Part 2, Part 3...) and link them all together to allow To add an Administrative Message, fill in the fields below.
users to read the second article after finishing the first (etc.), follow these steps.
• Title: Enter the title of the message as it will be displayed to users. Free-form alphanumeric text.
• Write your first article. Note the Article ID.
• Content: Enter the body of the message here. Free-form alphanumeric text. All HTML tags defined in
(To determine an article’s Article ID, locate the Article on the main page of the site and "hover" the Administration -> Settings are permitted in this box.
mouse over the Article title. In the browser’s status bar, you will see the URL for the link, for example:
• Language: From the drop-down list, select the language for which this Message will be displayed,
http://www.yoursite.com/modules.php?op=modload&name=News&file=article&sid=112. Look near
or "All" to have the Message shown to all users of the site, regardless of their language setting. In
the end of the line for "sid=##", where "##" is the Article ID. In this example, your Article ID is
this way, you could create English language Administrative Messages that are displayed only to your
"112".)
English users.
• Active?: To make this Message active and displayed to the users, click "Yes". If you do not wish
• Write the second article. Note the Article ID. For this example, we will assume that the second article to display the Message, but do not wish to delete it, click "No" and the Message will be marked as
has an Article ID of "126". Inactive.
• Edit the first Article and add the following to the bottom of the article: • Who can view this?: From this drop-down list, select the type of users to whom this message should be
<span style="text-align:center">lt;a displayed.
href="modules.php?op=modload&name=News&file=article&sid=126">::Part • All visitors: This Message will be displayed to ALL users of the site. This is the best way to get a
2::</a></span> message to all of your users (these messages will be displayed to anonymous and registered users, as
well as to Administrators).

• Edit the second Article and add the following to the bottom of the article: • Registered users only: This Message will be displayed only to those users who have registered and
are currently logged on the site (these Messages will not be displayed to anonymous users). As an
<span style="text-align:center"><a example, configure a message to thank the user for registering on the site.
href="modules.php?op=modload&name=News&file=article&sid=112">::Back to
Part 1::</a></span> • Anonymous users only: This Message will be displayed only to those users who are not logged
into the site (these Messages will not be displayed to registered users). As an example, configure a
Message encouraging non-registered users to apply for an account on the site.
Follow these steps to add additional Articles in your series. • Administrators only: This Message will be displayed only to those users with Administrative per-
missions on the site.

53 54
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

click on the "Edit" link for that AutoLink. A page will be displayed where you can edit all the informa-
tion about that particular link. Click "Update AutoLink" to save your changes.
Click "Add Message" to save the message.
To delete an AutoLink, click on the "Delete" link for that AutoLink. A page 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.
AutoLinks
AutoLinks is a feature that, when Activated, generates web links related to the content on-the-fly in mod-
ules (for example, News or Sections) from text within the module (text in the article). By default, Au- • Modify AutoLinks Configuration: This section allows configuration of how AutoLinks appear on your
toLinks is not active and must be activated through Administration -> Modules. site.

For example, if you have AutoLinks turned on, "Beatles" defined as a Keyword, and • Only link each item once in each piece of text: If this option is checked, then only the FIRST occur-
"http://www.beatles.com" as the auto-link URL, PostNuke will automatically replace occurrences of rence of a matching Key (link) Word in the article will be changed into an AutoLink. If this option
"Beatles" within your articles with "<a href="http://www.beatles.com">Beatles</a>". is unchecked, ALL occurrences of matching Key (link) Words in the article will be changed into
AutoLinks.
When AutoLinks are Activated, the option to Activate/Deactivate AutoLinks for particular modules will
appear when editing modules (from Administration -> Modules -> List -> <module name>). Activate Au- For example, if your news article had the text:
toLinks for the modules you wish, such as News. AutoLinks has a slight performance cost when activated. "The Beatles are a band. The Beatles played music, and the Beatles were very good"
Once AutoLinks have been activated, an AutoLinks link will appear in your Administration screen with ...and this function was CHECKED, it would become:
the following options.
"The <a href="http://www.beatles.com">Beatles</a> are a band. The Beatles played music, and the
Beatles were very good".
• Add AutoLink: Enter the keyword in the Key (link) Word field. This is the text that will be matched in
an article (for example, "beatles"). However, if the function was UNCHECKED, the text of the article would be changed to:

NOTE: Capitalization is not important in the Key (link) Word field. "The <a href="http://www.beatles.com">Beatles</a> are a band. The <a
href="http://www.beatles.com">Beatles</a> played music, and the <a
Enter the title of the site in the Title field (for example, "The Beatles Site"). This is the name that will
href="http://www.beatles.com">Beatles</a> were very good".
be displayed as a mouse-over and in the listing of all AutoLinks.
Enter the complete URL for the site in the URL field (for example, "http://www.beatles.com"). Make
sure to enter "http://" at the beginning of the link if the site is external to your site; otherwise it will not • Remove decoration from AutoLinks: If you want your AutoLinks to be underlined in your news
function as expected. article, UNCHECK this option. If you do not want your AutoLinks underlined, CHECK this option.

If the URL is located on your web site, you can enter the path to the file or the complete URL. For exam-
ple, if the file is on your site, you can enter "music.html" and AutoLinks will automatically prepend the TO ADD AUTOLINKS TO A SPECIFIC MODULE: Select the module(s) that you wish to use AutoLinks
"http://www.yoursite.com", resulting in an AutoLink of "http://www.yoursite.com/music.html". You and "Edit" them. For example, Administrators may want the News module to feature AutoLinks. Go to
could also enter "http://www.yoursite.com/music.html". Administration -> Modules -> Regenerate. Select "Edit" next to the News module. From the page that is
Finally, use the Comments field to enter optional free-form alphanumeric comments about the link. displayed, check the box next to "Activate AutoLinks for this module" and click "Commit Changes" to
Comments are visable only to the site Administrator. save your changes. Repeat for any other modules that you wish to use AutoLinks.

Click "Create AutoLink" to add the autolink to the database. Click "Update AutoLinks Configuration" to save changes.

• View AutoLinks: To view, edit, or delete AutoLinks, click the "View AutoLinks" link. All the Au-
toLinks in your database will be displayed sorted by Key (link) Word. If you wish to edit an AutoLink,

55 56
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

Banners Click "Add Client" to save your changes. Your Clients may log in to check their Banner statistics by
pointing their browser to "http://www.yoursite.com/banners.php?op=login".
Many websites rely on banner advertisement to generate revenue for the webmaster. PostNuke has features
built in that provide banner display, reporting, and management. Administrators will find it easy to add, IMPORTANT NOTE: This account is NOT a standard PostNuke user account. When the Client logs in,
edit, or delete client & banner information in this section. they will be shown the statistics for the banners they have running on the site, but they will not be logged
into the site as a user.
Standard banner sizes, as determined by IAB Ad Standards (http://www.iab.net/iab_banner_
standards/bannersizes.html), are defined as: The statistics that the Client will be shown are as follows:

• 468 x 60 (Full Banner) • Banner ID: The ID number for the banner on the site.

• 234 x 60 (Half Banner) • Impressions Made: The number of times that the banner has been displayed to users.

• 120 x 90 (Button 1) • Impressions Total: This field shows the total number of impressions that the Client purchased, or "0" if
the Client has unlimited impressions.
• 120 x 60 (Button 2)
• Impressions Left: If the Client purchased a certain number of impressions, this field shows how many
• 88 x 31 (Micro Bar)
of those impressions remain.
• 160 x 600 (Wide Skyscraper)
• Clicks: How many times the banner has been clicked from the site.
• 120 x 600 (Skyscraper)
• % Clicks: The percentage of Impressions Made that the Clicks comprise.
• 125 x 125 (Square Button)
• Functions:
• 180 x 50 (Rectangle)
• Email Stats: Emails the statistics to the email address configured in "Contact e-mail", above.
• 120 x 240 (Vertical Banner)
• Change URL: The Client may elect to change the URL where the banner will direct users that click
• 300 x 250 (Medium Rectangle) on it. The Client will make the changes and click "Change" to change the URL.
• 250 x 250 (Square Pop-up)

• Add a new client: In order to place a banner on your site, you first need to create a Client associated • Add a new banner: Once the client has been created, you may configure the banner to be displayed.
with the banner.
• Client name: Select the name of the client from this drop-down list.
• Client name: Enter the name of the client, for example: "Red Hat Linux".
• Purchased impressions: If the client has purchased a specific number of impressions, enter the num-
• Contact name: Enter the full name of the contact, for example: "John Doe". ber in this field. For example, if they purchased 1000 impressions, enter "1000". For unlimited im-
• Contact e-mail: Enter the complete email of the contact, for example: "jdoe@somewhere.com". pressions, enter "0".

• Client login: Enter the username of the client here, for example: "johndoe". • Image URL: This is the full URL or path to the banner image. The image can reside on
your own site, or the site of your client (or anywhere else, for that matter). For example,
• Client password: Enter the client’s password. "http://www.yoursite.com/images/banners/banner1.gif".
• Extra Information: Extra information is free-form alphanumeric text that you can use to record in- • Click URL: When a user views the banner and wishes to visit the site, this field tells PostNuke where
formation about the client, such as phone numbers, contact information, etc. It visible only to the to send the user. Enter the full URL of the link to visit. For example, "http://www.othersite.com".
Administrator from within the Banners module.

Click "Add Banner" to save your changes.

57 58
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

Banners -> Banner Reporting • New block: To add a new Block to your website, click "New Block". Fill out the fields on the screen
that appears. Each field is discussed below.
Once you have any Banners defined, a report will be displayed any time you enter Administration ->
Banners. This report shows the current Active Banners, the Banners that are Finished (have used all their • Title: In this field, enter the title that will be displayed for the new Block. Entry example: "Adminis-
purchased impressions), and a listing of Advertising Clients. tration Menu".
• Block: From this drop-down list, select the Block type. There are several options for Block type pro-
• Current active Banners: This section of the report shows how many impressions the Banner has gen- vided by PostNuke, and additional Block types will be added as modules are ’bolted on’ to PostNuke,
erated, the number of impressions remaining (if the client purchased a number of impressions), the though not every module will add Block types.
number & percentage of Clicks on the Banner that your site has generated, the Client name, and op-
Each Block type has different configuration options (displayed after you click "Commit" on this
tions to Edit or Delete the Banner.
screen) that will be covered in this section. No Block may have content that is greater than 64K in
• Finished banners: This section of the report shows Banners that have used all their purchased impres- size, and ALL Block types have the following configuration options in common:
sions, along with numbers & percentages of clicks, the dates that the banner was active, and options to
Edit or Delete the Banner. • Title: The title of the Block as it will be displayed on the site.
• Advertising clients: This section of the report shows Client & contact information, how many active • Position: From this drop-down list, select where the Block should be displayed on the page, either
Banners the client has on your site, and options to Edit or Delete the Client. left, right, or centre. The ORDER of the Blocks can be modified from Administration -> Blocks
-> View Blocks.
• Language: Select the language for which this Block will be displayed from the drop-down list. In
Banners -> Banners Configuration
this way, you could create English language blocks that are displayed only to your English users.
Select "All" to cause the Block to be displayed in all languages.
• Activate banners in your site: Set to "Yes" if you wish to display banners on your site. This is a ’master
• Refresh time for block: If the Block pulls information from outside sources, this setting defines
switch’. Even if you have banner clients defined in the Banners module, the banners will not be dis-
how frequently the Block will poll for updates. Entry example: "Half an hour".
played if this switch is set to "No". Banner placement on the page is a function of your particular theme.
Entry example: "Yes". The text in parenthesis after the Block type is the module/name combination used by PostNuke to
specify the Block type.
• Your IP to not count the hits: In order to keep from "padding" the hits to your site, you may enter your
IP number to exclude hits from the count. If you are running your own server enter "127.0.0.1". If your
site is hosted elsewhere, enter your external IP (assigned by your ISP). • Core/Today’s Big Story: (Core/big): Today’s Big Story displays the most popular (the most
viewed) story for the day.
• Core/Button Link Block: (Core/button):
** CORE/BUTTON FUNCTIONALITY WILL BE REMOVED FROM POSTNUKE AND THERE-
Blocks FORE ARE NOT DOCUMENTED HERE. USE CORE/HTML INSTEAD. **
Within PostNuke, Blocks act as building blocks to construct your site. Blocks are provided by the core
PostNuke engine, or virtually ’bolted on’ by modules. Core PostNuke blocks provide basic system func-
• Core/Categories Menu: (Core/category): Displays a list of Categories as defined in the Admin-
tionality, while modules provide enhanced functionality or new features. Using Blocks, the Administrator
istration -> News module. Shows either all defined Categories, or only the Categories for the
can customize the look of the site by adding, removing, or changing the position of Blocks.
currently selected language, depending on the setting for Multilingual options in Administration
Go to Administration -> Blocks to add, edit, view, or delete Blocks from your website. The Blocks display -> Language -> Language Configuration.
is sorted by Position.

59 60
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Core/Ephemerids: (Core/ephem): If you have Ephemerids defined for your site, this Block instructs • Core/Livesupport: (Core/phplive): If you don’t have an account with LivePeople.info
PostNuke to display Ephemerids in this Block. There are no additional configuration options for (http://www.livepeople.info) yet, you may want to sign up now. It’s free for PostNuke users only!
this Block type. • Your LivePeople company name:
• Core/HTML: (Core/html): This is a general Block for displaying HTML. All HTML tags defined • Your LivePeople user ID:
in Administration -> Settings are permitted in this box.
• Content: Enter the HTML content that you wish to display in this field. Only HTML that is • Core/PHP Script: (Core/php): Executes a PHP script within the site. Meant to include small
below 64K in size will function in this block. blocks of PHP code, like a Stock Ticker from http://www.hotscripts.com or similar.
IMPORTANT NOTES: Do not run scripts that access databases in this block. Only PHP scripts
• Core/User’s Login: (Core/login): that are below 64K in size will function in this block.

• Core/Generic menu: (Core/menu):

• Content: Cut and paste the entire PHP script you wish to execute into this field. A very simple
• Menu format: This setting determines if the menu will be displayed as a listing or if the menu example of a script that might be inserted here is:
items are selected from a drop-down list.
"passthru("/usr/games/fortune -s");"
• Display: Specify if specific elements should be displayed within this Block.
(This is for *NIX and assumes that the random ’fortune’ program is in the /usr/games direc-
• Modules: tory.)
• Waiting content: If configured as an Administration menu, you can enable this field to have IMPORTANT NOTE: Putting "" tags at the beginning & end of code entered in the Content
an indicator that shows if there is waiting content (stories, etc) on the site. field will cause a parse error to be generated when the page is displayed.

• Content:
• Title: • Core/Display poll: (Core/poll): Display a Poll in this Block. You may configure if the Current
• URL: Poll or a specific Poll is to be displayed.

• Description (optional): • Poll to Display: Choose the Poll to be displayed.

• Delete: • Current: Select this to have the current poll displayed.

• Insert Blank After: • Specific: From the drop-down list, select the specific Poll you wish to have displayed.

• Core/Online: (Core/online): Displays a listing of who is online on the site. There are no additional • Core/Story Related Links: (Core/related): This Block displays the latest article with the same
configuration options for this Block type. Topic as the story being displayed. The Block functions only when you display an Article; it is
not useful on the front page of a site. Only the most recent Story in the Topic is shown.
• Core/Past Articles: (Core/past): Displays a clickable listing of the past Articles on the site. The
number of stories displayed depends on the setting in the user’s Your Account -> Homepage -> RSS is a Web content syndication format. Using RSS, your site can ’pull’ content in the form
Number of stories field, or if that is not set, on Settings -> Number of articles on homepage. If the of headlines from other websites and display that content on your site. If a user of your site is
user wishes to read any of these Articles, click on the Article name to display the full Article. interested in reading the article, they can click a link to be taken to the other site.

• Core/RSS Extra: (Core/rss2): RSS is a Web content syndication format.

61 62
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• RSS File URL: • Category: If a Category is selected in this drop-down list, only Stories from that Category
• Select "Custom" to define your own RSS newsfeed or select from previously defined RSS will be displayed in the Block. ** NOT CURRENTLY FUNCTIONAL **
newsfeeds from the drop-down list. • Maximum number of stories to display:

• Core/Plain Text: (Core/text): This Block type simply displays the text contents of the Content
field. All HTML tags defined in Administration -> Settings are permitted in this box.
Unfortunately, there are multiple versions of RSS feeds available, and the only way to determine
which of these two Blocks will work with your particular RSS feed is by trial-and-error. If you • Content: Enter the text you wish to display in this field.
enter a known-good RSS link into one of these two Block types and it doesn’t work, try the other
Block type.
• Core/Languages: (Core/thelang): Displays a language selection Block. Depending on the con-
• Core/RSS Newsfeed: (Core/rss): RSS is a Web content syndication format. figuration option selected in Administration -> Languages -> Languages Configuration, this
Block will display either a drop-down list or flag graphics to allow the user to select their de-
• RSS File URL: fault language for the site.
• List of available feeds: (www.syndic8.com) • Core/Topics Menu: (Core/topic): Displays all active Topics on the website and the date of the
last addition to the Topic. Click the Topic name to see articles in that Topic, with a link at the
top of the page to show ALL articles in that Topic.
• Maximum number of articles shown:
• Core/User’s Custom Box: (Core/user): This is a box that your users can edit to display items
• Display site image:
that are important to them. It is displayed only to the individual user. All HTML tags defined in
• Display site search: Administration -> Settings are permitted in this box, so users could put customized links, etc.,
• Display article descriptions: here. Users can edit their Custom Box through Your Account -> Change Homepage.

• Use alternate display style: • Core/Latest Web Links: (Core/weblinks): This Block displays the latest Web Links that have
been added to the site.
• Module Name: (usually "Web_Links")
• Core/Search Box: (Core/search): Displays a Search box. In PostNuke 0.713, the Search is lim-
ited to searching ONLY News articles. However, in a future release, this will be a full site • Total links: Specify how many links to display in this Block. Defaults to "10". If you wish to
search. display the 25 most recent Web Links, enter "25" here.

• Core/SMS: (Core/sms): ** NOT CURRENTLY FUNCTIONAL ** Uses Short Message Service

(SMS) to send messages to mobile electronic devices. This is not useful in the United States. • Admin Messages/Show admin messages: (Admin_Messages/messages): Displays the messages
• Core/Story Titles: (Core/stories): Displays titles of News stories. Click the title to read the arti- that the Administrator has defined in Administration -> Admin Messages.
cle. • Quotes/Random Quote: (Quotes/quote): Displays a random Quote from the quotes defined in
• Display all stories (or) Administration -> Quotes.

• Display front-page stories (or) • Wiki/WIKI: (Wiki/wiki): Text block allowing Wiki encoding. Wiki Encoding is an alternative to
HTML code for display within articles and text on the site. A reference to the Wiki Text Format-
• Display non-front-page stories: ting Rules is at: http://phpwiki.sourceforge.net/phpwiki/TextFormattingRules.
• Topic: If a Topic is selected in this drop-down list, only Stories from that Topic will be • Content: Enter Wiki-formatted text in this field.
displayed in the Block.

63 64
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Template/Show first example items (alphabetical): (Template/first): • Deactivate:

• Number of example items to display: • Edit: Using this function, you can edit the settings for each Block.
• Title: Change the displayed title of this Block in this field.
• Position: From this drop-down list, select if the Block should be displayed on the left, right,
or center of the page.

For our example, select "Core/Generic menu" from the drop-down list. • Language: Select the language for this Block from the drop-down list.
• Refresh time for block: If the Block pulls information from outside sources, this setting de-
• Position: You can specify where on your website the Block will be displayed. This setting determines fines how frequently the Block will check for updates. Entry example: "Half an hour".
if the Block will be displayed on the left, right, or center of your website. Later, you can change the
display order of the blocks by clicking "View blocks" and changing the order using the arrows.
• Left: This Block will be displayed on the left side.
Click "Commit" to save your changes.
• Right: This Block will be displayed on the right side.
• Centre: This Block will be displayed in the center. • Delete:
For our example, select "Left" as the position for the block.
• Show active/all blocks: This is a toggle switch that selects between showing ALL blocks and only
those blocks that are ACTIVE on your site.
• Language: From this drop-down list, select the default language for this Block. Entry example: "En- To remove the Reminder block that says "Please remember to remove the following files from
glish".
your PostNuke directory...", follow these steps:
Click "Commit" to save your changes. The new Block will be created, and it will be displayed on the
website. • Log in as Administrator with your Administrator username and password.
• Click on the "Administration" link on the Main Menu.
• View blocks: Displays blocks in Position order. • Click on the "Blocks" link.
• Order: Click the arrow pointing UP to move this Block UP in the display order. Click the arrow • Click "View Blocks".
pointing DOWN to move this Block DOWN in the display order.
• Find "Reminder" on the listing that appears, and click "Delete" under Options for that block.
• Position:
• Click "Confirm" to verify that you wish to delete that block.
• Title:
• Module:
• Name:
• Language:
• State: Active/Inactive
• Options:
• Activate:

65 66
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

Comments Downloads
Comments allow users to interact with your website. When a user reads a News article on your site, if they Your website can offer files for users to download. These downloads may be broken into categories and
feel that they have something to add to the article -- a point of clarification, a correction, or anything else sub-categories to make it easier for users to locate just the files in which they are interested. This section
-- they may post a comment with that information. These comments are stored in the web site database, of configuration is where you specify options relating to Downloads. By default, Downloads is not active
and are displayed at the bottom of the page whenever the article is read. and must be activated through Administration -> Modules.
This configuration option for Comments determines how user comments on News articles will be handled For the purpose of this documentation, we will assume that you wish to set up one main category called
by PostNuke. "Music", with one sub-category called "MP3 Files".
IMPORTANT NOTE: Comments are enabled by default for the Reviews module, and are not affected by
the settings in this section. • Clean download votes: PostNuke allows users to vote on Downloads. This function resets the votes.
• Broken downloads reports (#): If a user feels that a download points to a bad link, they can click "Report
• Type of moderation: This setting determines the type of moderation you want for Comments on your broken link" on the file to send a message to the Administrator to report that problem. When you go to
site. Moderation may be necessary because sometimes users will post inappropriate or off-topic infor- Administration -> Downloads, you will be shown the number of Broken Download reports.
mation in their comments. Be aware that excessive moderation can kill a community. Moderators have Click "Broken downloads reports" to view the listing of reported Broken Downloads. From that menu,
the ability to edit or remove comments from your site. Select the type of moderation you want from select "Edit" to be taken to the file’s properties, which can be edited to correct a problem (click "Modify"
the options. The site Administrator always has full moderation rights over all comments, no matter the to save any changes). Click "Ignore" to Ignore the Broken Download report (for example, if the file is
setting below. good) and to remove any additional Broken Download reports for that particular file. Click "Delete"
• "Moderation by Admin": This is the most common configuration for a site run by one person. The to delete the download link from your database (for example, if the file IS broken) and any additional
site Administrator has full moderation rights over all comments, and they may delete inappropriate Broken Download reports for that particular file.
comments as they see fit. IMPORTANT NOTE: There is no CONFIRMATION when you click to "Delete" a broken download! Be
• "Moderation by users": With this option set, your registered, logged-in users have full moderation certain that you wish to delete the file from the database before clicking the "Delete" button.
rights over all comments, and they may delete inappropriate comments as they see fit. This is useful
in a "community" web site.
• Download modification requests (#): Download modification requests may be submitted when a user
• "No moderation": No moderation at all. Only the site Administrator has full moderation rights over wishes to inform you that the Download on your site is out-of-date (a newer version exists, for example).
all comments. If there are Download modification requests, the number of requests (#) will be displayed. Click the
Download Modification Request link. All the requests will be displayed. Select "Edit" to be taken to the
file’s properties, which can be edited to correct a problem (click "Modify" to save any changes). Click
• Allow Anonymous to post?: This setting determines if Anonymous users may post comments. If set to
"Ignore" to Ignore the Broken Download report (for example, if the file is good) and to remove any
"Yes", all users may post comments. If set to "No", only registered, logged-in users may post comments.
additional Broken Download reports for that particular file. Click "Delete" to delete the download link
Entry example: "No"
from your database (for example, if the file IS broken) and any additional Broken Download reports for
• Comments limit in bytes: This determines the total size, in bytes, of a posted comment. This setting that particular file.
is here to prevent users from "flooding" your system with random text to try and cause errors in your
IMPORTANT NOTE: There is no CONFIRMATION when you click to "Delete" a broken download! Be
database. The default setting is a very good choice -- 4096. This allows for a fairly sizable comment,
certain that you wish to delete the file from the database before clicking the "Delete" button.
but does not endanger the system.
• Anonymous default name: The default name for non-registered users on your site as displayed in the
Comments. Entry example: "Anonymous". • Validate downloads: This function can assist in determining which files in your downloads section are
no longer valid. Click "Validate downloads" to be taken to a screen with several options. Click "Check
Click "Submit" to save your changes.
ALL Downloads" to have PostNuke automatically check each and every download on your site. Please

67 68
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

note that this function may take several moments to finish, especially if you have lots of downloadable • File link: Enter the *complete* web link to download this file. Entry example:
files. If you wish to validate only a category (and its sub-categories) of downloads, click the name of "http://www.yoursite.com/files/music/jazz/dukeellington.mp3". Make sure that the file to be linked
the category that you wish to validate. If you wish to validate only a sub-category, click the name of the exists before adding the download link.
sub-category that you wish to validate. • Category: Select the category for this file from the drop-down list. Entry example: "Music / MP3
When the validation is complete, a screen with results will be displayed. If the files were found and the Files / Jazz Tunes".
download is determined to be a valid link, "OK" will be displayed in the Status column. • Description: Enter up to 255 characters of free-form alphanumeric text to describe this file.
If there was a problem with particular file(s), "Failed!" will be displayed in the Status column. You are • Author’s name: (optional) Enter the name of the author (or person that provided the file) in this field.
offered options for files with errors. Select "Delete" to remove the file listing from the database. Select
"Edit" to be taken to the file’s properties for editing. Click "Modify" to save any changes, or "Delete" • Author’s e-mail: (optional) Enter the author’s (or person that provided the file) email address in this
to remove the file listing from the database. field.
• Filesize: (optional) Specify the size of the file (in bytes) here. PostNuke cannot automatically deter-
mine the size of the file.
• Add main category: This function adds a main category to your download listing, for example, "Music".
• Version: (optional) If this is a specific version of the file, you can enter that version information here.
• Name: Enter the name of the category as you would like it displayed to your users, free-form al-
phanumeric text. Entry example: "Music". • Homepage: (optional) Homepage for the file.

• Description: A short (255 characters) free-form alphanumeric text description of this main category. • Hits: (optional) Number of hits that this file has received on your web site. If blank, the counter starts
Entry example: "Music files, tools, and utilities". at 0.

Click "Add" to save your changes and create the main category. Click "Add URL" to save your changes.

• Add Sub-category: You can create sub-categories (and sub-sub-categories, etc.) using this function. • Modify category: If you wish to change the name or description of a category, or delete it altogether,
select the category from the drop-down list and click "Modify". The category is displayed and you can
• Name: Enter the name of the sub-category you wish to create in free-form alphanumeric text. Entry
edit the information. Click "Save Changes" to save your changes. If you modify the name of a category,
example: "MP3 Files".
that change is automatically applied to any sub-categories (etc.) under that category. For example, if
• In: This determines the parent category in which you wish to create the sub-category. For example, you changed "Music" to "Songs", then "MP3 Files" and "Jazz Tunes" would be updated to reside under
to create the "MP3 Files" as a sub-category of Music, select "Music" from this drop-down list. the "Songs / MP3 Files / Jazz Tunes" structure.
It is possible to create sub-sub-categories (etc.) by selecting the Main Category / Sub-Category (etc.) If you wish to delete a category or sub-category, you can select it from the drop-down list and then
from the drop-down list. For example, if you wish to add a sub-sub-category called "Jazz Tunes" to click "Delete" on the next page. You are asked to confirm your desire to delete the category. If you
the "MP3 Files" sub-category (which is a sub-category of "Music"), you would simply add another click "Yes", the category AND ALL SUB-CATEGORIES below it, are deleted. For example, if you
sub-category called "Jazz Tunes" and select In: "Music / MP3 Files" from the drop-down list. chose "Songs" and then clicked "Delete" and said "Yes" to the confirmation, the "MP3 Files" and "Jazz
Click "Add" to save your changes and create your sub-category. Tunes" sub-categories & pointers to the files would be deleted as well.
IMPORTANT NOTE: Deleting categories/sub-categories from the website DOES NOT delete the actual
files from your system. For example, if you deleted the "Songs" category (or any of the sub-categories),
• Add a new download: Now that we’ve got the download categories configured, we can begin to add the file "dukeellington.mp3" would NOT be deleted.
files for the users to download from the system.
• Program name: Enter the title of the file as you would like it to appear in the download listing.
Free-form alphanumeric text. Entry example: "Smooth Jazz from Duke Ellington" • Modify a download: To modify a download, enter its "Download ID" in this field and click the "Modify"
button. To determine a download’s Download ID, locate the Download entry that you wish to edit and

69 70
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

"hover" the mouse over the title. In the browser’s status bar, you will see the URL for the link, for IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to "Delete" an Editorial!
example: Be certain that you wish to delete the Editorial before clicking the "Delete" button.
http://www.yoursite.com/modules.php?op=modload&name=Downloads&file=index&req=getit&lid=52. Below the Add Editorial block is a display of the Comments and Votes that this download has received.
Look near the end of the line for "lid=##", where "##" is the Download ID. In this example, your Comments and votes may be deleted by clicking the "X" in the Delete column.
Download ID is "52".
IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to delete a Comment or
You may then modify any of the following fields. a Vote! Be certain that you wish to delete the Comment or Vote before clicking the "X" button.

• Program name
• File link
Downloads -> Download Configuration
• Check: Click "Check" to verify the location of the file.
• Let Anonymous users post new downloads?: If you wish to allow unregistered or not-logged-in users of
• Description your site post new downloads, set this to "Yes". If you wish to restrict posting of new downloads only to
registered/logged-in users, set this to "No". It is recommended that only registered users are permitted
• Author’s name to post new downloads. Entry example: "No".
• Author’s e-mail Click "Submit" to save your changes.
• Filesize
• Version
• Homepage
Visit: Click "Visit" to visit the homepage for the file. NOTE: This link opens in the current browser
•
Ephemerids
window.
Ephemerids is a small "Today In History"-type module. Once Ephermids are defined, they can be dis-
played on the site by placing an Ephemerid Block.
• Hits
• Category • To add a new Ephemerid, enter the day, the month, the year, and a description of the Ephemerid in the
fields below.
Click "Add" to save the changes.
• Day: Enter the day of the month in this field. For example, "18".
• Month: Enter the month in this field. For example, "6".
• Add editorial: If you wish to add an Editorial for the download, you may do so in this function. If an
Editorial already exists for this download it will be displayed; you can edit the title or the text. Once an • Year: Enter the year in this field. For example, "1942".
editorial is added, there is an icon next to the name of the file indicating that an Editorial exists, and a • Language: From the drop-down list, select the language for which this Ephemerid will be displayed.
text link to the Editorial appears at the bottom of the file info. In this way, you could create English language ephemerids that are displayed only to your English
• Editorial title: Enter the title of the Editorial here. Free-form alphanumeric text. users. Select "All" to cause the ephemerid to be displayed in all languages. For example, "All".
• Editorial text: Enter the body of the Editorial here. Free-form alphanumeric text. • Ephemerid description: Enter the description of the ephemerid in this field. For example: "Paul
McCartney born in Liverpool England!".
Click "Add" or "Modify" to perform that action. Click "Delete" to delete an existing Editorial.
Click "OK" to save your changes.

71 72
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

the bottom of the page to Add a new question. Type the question and answer in the fields, and click
• To Edit or Delete an Ephemerid: To edit or delete an Ephemerid from your collection, locate it on the "Save" to add the question/answer to the Frequently Asked Questions.
listing of Ephemerids and click "Edit" to edit the Ephemerid to your satisfaction, and then click "Save
Changes" to save. Click "Delete" to delete the Ephemerid. • Add a FAQ Category: To use FAQs, first add one or more FAQ Categories. These can be whatever you
IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to "Delete" an like, but should reflect a certain product or section on your site. Simply type a FAQ Category name and
Ephemerid! Be certain that you wish to delete the Ephemerid before clicking the "Delete" button. click "Save".
• Category: Enter the name of the FAQ Category as it will be displayed to users. Free-form alphanumeric
text.
• Language: From the drop-down list, select the language for which this FAQ Category will be displayed,
FAQ or "All" to have the FAQ Category shown to all users of the site, regardless of their language setting.

Frequently Asked Questions (FAQs) are an excellent source of information for your visitors. Using very • Parent: If you wish to create a sub-category, simply select the parent FAQ Category from this drop-down
well-written FAQs that cover the most common questions of your visitors will keep you from getting list, or leave it at the default setting of "New top category" to add a new parent FAQ Category.
inundated with support emails.
Questions can be submitted by users by visiting the FAQ link on the Main Menu. When the user clicks
"Ask a question", they are taken to a screen to enter their email address and type their question. From Groups
the drop-down list, users select the FAQ Category for their question from the drop-down list, or "Unsure"
Groups are discussed in detail later in the documentation.
to post a general question. The user clicks "Submit Question" to send their question. When there are
questions waiting to be answered, the Administrator is notified by an entry in the Waiting Content section.
As Administrator, go to Administration -> FAQ to access the following functions of this module.
HTTP Referers
• View unanswered questions: Click "View unanswered questions" to be shown a listing of questions that This page will show you who has been linking to your site and how they are locating your site. It provides
have been submitted but have not yet been answered. The Administrator may "Answer" or "Delete" the an interesting look at how your site is being accessed from the internet.
question. If the Administrator wishes to answer the question, click "Answer" and type the reply to the
question, and edit the FAQ Category from the drop-down list (if necessary). Click "Save" to add the • Frequency: The number of unique requests from the particular URL.
question & answer to the Frequently Asked Questions. Click "Delete" to delete the question. Answer • URL: Displays the URL from which your site is linked, or "Bookmark" if the requests originate from a
"Yes" to confirm deletion, or "No" to abort deletion of the message. user’s bookmarks.
If FAQ Categories exist, they are displayed at the top of the FAQ module screen with the option to • Percent: The percentage of your overall hits from this URL.
"Delete" the FAQ Category, "Edit" the FAQ Category title & language settings, or edit the "Content" of
that FAQ Category. • Delete Referers: When you wish to reset the log of HTTP Referers, click this link. The log of HTTP
Referers will be reset.
• Delete: Delete this FAQ Category, all questions & answers in this FAQ Category, and any sub- IMPORTANT NOTE: There is no CONFIRMATION screen when you click "Delete".
categories of this FAQ Category. Answer "Yes" to confirm deletion, or "No" to abort deletion of
the FAQ Category.
• Total: Grand total of HTTP referers.
• Edit: Edit the Title and Language settings for the FAQ Category. Click "Save" to save changes.
• Content: Add/Edit/Delete the content of this FAQ Category. If there are questions within the FAQ
Category, they are displayed with the option to "Edit" or "Delete" the question. There is a form at

73 74
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

HTTP Referers -> HTTP Referers Configuration • Mail user: From the drop-down listing of all registered users on the site, choose the user to whom you
wish to send email. If you wish to mail to all registered users, click the "Mail all registered users" box.
• Activate HTTP referers?: This is the "master switch" for this function. Set it to "Yes" to enable HTTP • From: Enter the email address from which this email is being sent.
Referer logging, or to "No" to disable HTTP Referer logging. Entry example: "Yes". • Reply-to-address: If you wish for replies to go to a different email address than the "From" email, enter
• How many referers as a maximum?: Because the HTTP Referer list gets large quite quickly on a busy the reply-to address here.
site, you should set a maximum to prevent your database table from becoming bloated. Configure the • Subject: Enter the subject for your email. Free-form alphanumeric text.
maximum number of referers through this function. Once the limit is reached, older entries are trimmed
away as new entries are received. Entry example: "3000". • Message: Enter the body of your email in this field. Free-form alphanumeric text.

Click "Submit" to save your changes. Click "Send mail" to send the message.

Quotes
You may define quotes that will be displayed in random order on the website. Enter the Quote as you wish
Languages it to appear in the Quote Text field, and, optionally, add the Author of the quote in the Author field. Click
** IMPORTANT NOTE: THIS MODULE IS INTENDED FOR LANGUAGE TRANSLATORS; IT IS NOT "Submit" to save the quote.
DOCUMENTED IN THE GUIDE. HOWEVER, PLEASE GO THROUGH Languages -> Languages Con- To edit or delete Quotes, click "Modify Quotes". All quotes on the system will be displayed with the
figuration TO SET THOSE OPTIONS. ** option to Edit or Delete the quote. You may search for Quotes by keyword by using the Search box at
the top of the screen. Enter the keyword(s) to search for within Quotes and click "Submit" to perform
the search. Matching results will be displayed for Editing or Deletion. Edit the quote and click "Submit"
Languages -> Languages Configuration to save the changes. Click "Delete" to delete a particular quote. A confirmation screen will be displayed
before deleting the quote.
• Select the language for your site: This is the "master switch" that configures your site’s default language.
Entry example: "English"
• Activate ML: This is a "master switch" for enabling/disabling Multi-Lingual (ML) support on your site Reviews
to support multiple languages. If your site is single-language only, you can safely set this to "No". Entry
PostNuke allows you to have Reviews on the site. This page is where they are maintained.
example: "Yes"
• Activate User Flags: Do you wish to display language flag graphics to enable users to more easily • Title: Enter the Title for the Reviews page in this field. Free-form alphanumeric text. Entry example:
select their language? The flag graphics are stored, by default, in images/flags. Entry example: "Yes" "We Need Your Reviews!".
(recommended to be set to "Yes" if Activate ML (above) is also set to "Yes")
• Reviews page description: Enter heading text that will appear at the top of the Reviews
page. For example, "This section is for reviews of events, restaurants, movies, concerts,
books, CDs, DVDs, articles, clothing, computer games, board games, shops, theatre events,
local & regional attractions, sporting events, etc., etc., etc.... If you attended a great event
Mail Users lately -- or have eaten at a terrible restaurant -- or visited a decent museum, please <a
Mail Users allows the Administrator of the site to email a specific user or all registered users. href="modules.php?op=modload&name=Reviews&file=index&req=write_review">write a
review</a> and share your opinion with us!".
Click "Save Changes" to store the settings.

75 76
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

It is possible to display an image with the Review. This image should be 150 x 150 in size, and stored in Please make sure that the information entered is 100% valid and uses proper grammar and capitalization.
modules/Reviews/images. Enter the name of the image in this field. For example, "whitealbum.gif". For instance, please do not enter your text in ALL CAPS, as it will be rejected.
If there are Reviews awaiting validation, they will appear below the Reviews Page Description. Click "Cancel" to abort the Review. Click "Preview" to see a display of how your Review will appear
when it is added to the Reviews listing. If everything is to your satisfaction, click "Yes" to add the Review.
The Reviews that are awaiting validation will be displayed. The Administrator can edit the Date, Review
To edit the Review, click the "No" link. Since you are logged in as Administrator, the Review will be
Title, Language, Review Text, Reviewer, Reviewer E-mail, Score, and Image.
added immediately.
Click "Add Review" to approve the Review and add it to the Reviews listing. Click "Delete" to delete the
review.
IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to "Delete" a Review. Be Sections
certain that you wish to delete the Review before clicking the "Delete" button.
Sections are provided as an area of your website for content that does not change very often.
To Add a Review, follow these steps:
From the Administration menu, click "Sections".
• From Administration -> Reviews, click "Click here to write a review". You will be taken to the Review
screen. • Editing Active Sections: If the site has any previously-defined Active Sections, they will be listed at the
top of the page. Click the Section name to edit the properties of the Section. At the top of the page, the
Near the top of the screen (under the alphanumeric listing of Reviews), there is a link called "Write a
graphic for the Section will be shown. Under that is a drop-down list from which you can select any
review".
article within the Section for editing. Click "Go" to edit the article.
Edit the Section Name (up to 40 characters of non-HTML alphanumeric text) or the Section Image (the
• Click "Write a review". On the next screen, complete the fields for your Review. Enter information graphic file must be in the images/sections/ directory) from this page.
according to the on-screen specifications.
Click "Save Changes" to save any modifications. Click "Delete" to delete the Section and ALL articles
• Product title: Enter the name for the Review here. For example, "Star Wars Episode I Review". in the Section. From the confirmation screen, click "Yes" to delete the Section and ALL articles in that
• Language: From the drop-down list, select the language for which this Review will be displayed, or Section. Click "No" to abort deletion.
"All" to have the Review shown to all users of the site, regardless of their language setting. In this way,
you could create English language Reviews that are displayed only to your English users.
• Adding a new article to a Section: To add an article into Sections, follow the steps below.
• Review: Enter the body of the Review in this block. All HTML tags defined in Administration ->
• Enter the title of the Article in the "Title" field.
Settings are permitted in this box. If you want your Review to span multiple pages you can write ""
where you want the page break. • Select the Section into which the article should be added. Do not select any Section to save the article
for publishing at a later time.
• Your Name: Enter the name of the author of this Review. Required.
To publish an article that has been previously saved, "Edit" the article from the listing of articles at
• Your e-mail: Enter the complete email address of the author of this Review. Required.
the bottom of the Administration -> Sections page.
• Score: Assign a numerical score for the item being reviewed. Required.
• Related Link: If the item being reviewed has an official website, enter that URL here. Make sure your
• From the drop-down list, select the language for which this article will be displayed, or "All" to have
URL starts with "http://". Optional.
the article shown to all users of the site, regardless of their language setting. In this way, you could
• Link title: Enter a Title for the URL Link. Required if you have a Related Link (above), otherwise not create English language articles that are displayed only to your English users.
required.
• Enter the body of the article in the "Content" field. Free-form alphanumeric text. All HTML tags
• Image filename: Name of the image of the item being reviewed. The graphic file should be no larger defined in Administration -> Settings are permitted in this box.
than 150 x 150 in size, and must be located in modules/Reviews/images/. Optional.

77 78
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

To cause the article to span multiple pages, add " " where the page break is to be inserted. The article • E-mail message: Enter the body of the email. Free-form text. Entry example: "There was a
will be displayed with navigation controls if multiple pages are defined. new submission to the web site. Please log in as Administrator and
review this submission".

Click "Add new Article" to save the new article to Sections. The article is immediately available. • E-mail account (from): Enter the complete email address from which this notification email will be
sent. Entry example: "admin@yoursite.com".

• Editing/viewing/deleting recent articles in Sections: A listing of recent articles in Sections is displayed

near the bottom of the page. From left to right, the listing indicates: Surveys
• the name of the article
** IMPORTANT NOTE: THE SURVEY MODULE WILL BE RELEASED AFTER 0.714. ’SURVEYS’
• the language setting for the article WILL REPLACE ’POLLS’. **
• the Section in which the article is listed Surveys allow you to gather information from your users using a ’voting booth’ method. PostNuke sup-
• Edit/Delete options. ports an unlimited number of different surveys, and surveys optionally support selection of multiple op-
tions (for example, for surveys like ’Which of these items do you own?’).
Click "Edit" to edit the article (click "Save Changes" to save any modifications), or "Delete" to delete
the article. Click "Delete" to delete the article. From the confirmation screen, click "Yes" to delete the
• New Survey: Before Surveys will be displayed on your website, you must create them. To create a
article. Click "No" to abort deletion.
Survey, click "New Survey". There is no limit to the number of different surveys you may have on your
site.
• Add a new Section: At the bottom of the page, a new Section can be created. Type the Section Name, • Title: Enter the title of the Survey in this field. Entry example: "Who is your favorite Bea-
for example: "Articles I Have Written". Enter the name of the optional graphic file associated with this tle?".
Section in the Section Image field. The graphic must be located in the images/sections/ directory.
• Type: Select the type of survey you wish to create. If you want your users to be able to select only one
Click "Add Section" and the new Section will be created. option, choose "Select one of the options" (for example, "John") from the drop-down
list. If you want your users to be able to select multiple options (for example, "John" and "Paul"),
choose "Select multiple options" from the drop-down list.
Submit News • Initial options: Enter the different options, or answers, in these fields, one entry per line. For example,
you might enter:
PostNuke provides a mechanism by which the system administrator can be notified via email when a new
article is submitted to the site. Within this section, you define the particulars of that contact. "George"
"John"
• Notify of new submissions by email?: Enter Yes or No. "Yes" will send an email when new submissions
"Paul"
are received. "No" will not send an email. NOTE: If you do not have an installed & working email
subsystem on your webserver, the rest of the configuration options in Submit News are not necessary. "Ringo"
• E-mail to send the message: Specify a complete email address in this field. The notification email will
be sent to this address. Entry example: "user@yoursite.com". Click "Create Survey" to create the new survey with the options you specified above.
• E-mail subject: Enter the subject line for the email. Free-form text. Entry example: "NEW Submis-
sion at the web site!"
• View Surveys: If you wish to review, edit, or delete the surveys on your site, you may do so with this
function. Click "View Surveys" to be shown a listing of all surveys on your site.

79 80
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Name: The name of the Survey as displayed on your site. cians". This permits the user to focus on the topic of their choice, so that, for example, a musician doesn’t
• Type: The Survey’s type, either "Select one of the options" or "Select multiple options". have to know what’s going on in the kitchen.

• State: "Open" means that the survey is available and accepting new votes, "Closed" means that the • Current Active Topics: This section displays the icons and names of the currently defined Topics avail-
survey is no longer accepting new votes.
able on your site. To edit a Topic, click the icon of the topic you wish to edit to be taken to the Edit
• Total Votes: The total number of votes that the Survey has received. Topic screen.
• Survey Options: Click this link to edit the options available for a Survey. • Edit Topic: You may Add, Edit, or Delete topic information from this screen.
• Order: Specify the display order for the option item. Click the UP arrow to move the option up in IMPORTANT NOTE: If you DELETE the Topic, ALL the News articles and comments under the Topic
the order; click the DOWN arrow to move the option down in the order. will be deleted as well. However, the topic icon will NOT be deleted from images/topics -- that must be
done manually.
• Option name: This is the word or phrase in each option, and is what the user sees as selection
choices in this Survey.
• Option votes: How many votes each option has received. • Add a new topic: To add a new topic, fill out the following fields and click "Add topic".
• Options: Select "Edit" to edit the option, or "Delete" to delete the option. • Topic name: This is the database name of the topic. It is not displayed to users, and has a limit of 20
• Edit: Modify the Option name in this field. Click "Create option" to save the changes. characters and NO spaces are allowed (example: "cooking").

• Delete: Click "Delete" to delete the option. A confirmation screen will be displayed. If you wish • Topic text: This is free-form alphanumeric text describing the topic, with a limit of 40 characters
to delete the option, click "Confirm" to delete it; otherwise, click "Cancel deletion". (example: "Kitchen Happenings").
• Topic image: This is the name and extension of the graphic image to be used to designate this topic.
Keep it small -- usually 40x40 or 60x60, however, there is no system limitation on the size. The file
• New Option: To add an additional option selection for the Survey, click "New Option". Enter the must be in images/topics (example: "cooking.gif").
Option name in the field and click "Create option" to save the changes. You may wish to re-order
the options after adding a new field.

Topics -> Topics Configuration

• Close: Click "Close" to mark this Survey as "Closed", and to prevent any new votes from being cast
in this Survey. Be aware that once a Survey is closed, there is no way to Open it again. IMPORTANT
NOTE: There is no confirmation after clicking "Close". • Topics images path: This field specifies the location of the topic image files. Entry example: "im-
ages/topics".
• Edit: Allows editing of the Survey Title and Survey Type. Click "Update Survey" to save the changes.
• Number of topics icons displayed per row: This field determines how many topics are displayed in a
• Delete: Click "Delete" to delete the Survey and all its responses. A confirmation screen will be
row, both on the Topics Administration screen (that Admins see) and the Topics screen (that users see).
displayed. If you wish to delete the Survey, click "Confirm" to delete it; otherwise, click "Cancel
Select the size that works best for your site. Entry example: "5".
deletion".

Top List
Topics PostNuke provides a function that will display the most popular Stories, Comments, Sections, Submitters,
Topics allow you to divide your content into logical groupings. For example, if your site caters to Cooks Polls, Authors, Reviews, and Files.
and Musicians, it would be logical that there would be a topic called "Cooks" and a topic called "Musi-

81 82
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Number of items on top page: If you wish to display the top 25 most popular items, enter "25" in this User Administration -> Dynamic User Data
field. If you wish to display the top 10 most popular items, enter "10" in this field. Entry example: "10".
** IMPORTANT NOTE: THE DYNAMIC USER DATA MODULE IS BEING REWRITTEN. THIS SEC-
TION OF THE GUIDE IS, THEREFORE, INCOMPLETE. **
After a user registers for an account on your web site, they may edit their personal profile by selecting
User Administration "Your Account" -> "Change Your Info". The Dynamic User Data Administration screen allows the Ad-
Within this module, you may edit or delete an existing user, add a new user, or modify user configuration ministrator to specify which of the pre-configured fields to display, which of the pre-configured fields to
options, including Dynamic User Data. hide, and to optionally add custom fields requesting additional user information.

• Edit a user: Enter the complete username of the user you wish to edit, select "Modify", and click "OK". • Dynamic User Data: Click this link to be shown a listing of the current User Data that is requested from
You will be shown the user’s information and allowed to change it as you wish. Click "Save changes" your users when they visit "Your Account" -> "Change Your Info". This listing is shown in the order
to save any changes you make. that it is displayed to users, with Inactive fields at the top.
• Delete a user: Enter the complete username of the user you wish to delete, select "Delete", and click • Active: If this field is Active (displayed to and allowing input from users), there will be a green icon
"OK". You will be asked, "Are you sure you want to delete user <username>?". Click "Yes" to delete in this field. If the field is Inactive, the icon will be red. Click the icon to toggle the state of the field.
the user, or "No" to abort this function. • Field Label: Displays the label and text for each field. The label is on the left side of the column, and
• Add a new user: To add a new user, fill out the Username, E-mail, and Password fields for the user and might be "_UREALNAME", for example. The Field Label must be unique. The text is on the right
click "Add user". The user account will be created. side, and might be "Real name", for example.
• Weight: Specify the display order for the Field. Click the UP arrow to move the Field up in the order;
click the DOWN arrow to move the Field down in the order.
User Administration -> User Configuration
• Data Type: "Core", "Core Required", "String", "Text", "Float", or "Integer".
Within this section, you can configure options that affect every user of your site.
• Length: "N/A" or the string length defined for this Field.
• Minimum age: You can specify a minimum age to access your site. Enter the age in years in this field, • Delete: "N/A" or "Delete". "Core" and "Core Required" Fields are not deletable and can only be
or "0" to disable age-checking. Entry example: "13" made Inactive if you wish for them not to appear to users. Before a Field can be deleted, it must
• User menu images path: This is the path where icon graphics for the user menu are stored. Entry first be made Inactive (see above). If the Field is deletable, click "Delete" to remove it. You will be
example: "images/menu". presented with a confirmation screen. Click "Yes" to delete the Field and all its data, or click "No" to
skip deletion.
• Graphics in the user page: Click "Yes" to have icon graphics displayed in the user’s menu (accessed
when the user visits their account options). Click "No" to have no icons displayed, or "Yes" to display
the icons. Entry example: "Yes" • Add Fields: Administrators may add custom User Data fields through this function. Your users will
• Minimum users password length: Specify the minimum length for user passwords. The longer the pass- be prompted for these custom fields (as well as any enabled standard fields) when they visit the "Your
word, the more secure. Choose a good balance between security and user convenience. Entry example: Account" -> "Change Your Info" page on the website.
"5" • Field Label: Enter the Field Label here. The Field Label must correspond to an entry in the language
Click "Submit" to save your changes. definition file (language/<current language>/global.php). For example, if you wanted to add a field
requesting a user’s eye color, you would first edit the language/<current language>/global.php file
and add the following line:
--- CUT HERE ---
define(’_EYECOLOR’,’Your Eye Color’);

83 84
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

--- CUT HERE ---

Once the file has been edited and saved, enter "_EYECOLOR" in this Field Label. • Add a New Link: If you wish to administratively add web links, you may do so using this function.
Simply type the title of the page (for example, "Official PostNuke Homepage"), the complete page URL
(including "http://") (for example: "http://www.postnuke.com"), the category in which the page should
• Data Type: Determine the data type for entries in this field. appear on your site (for example, "Computers / CMS"), a free-form alphanumeric text description of the
• String: site (for example: "All things PostNuke!"), and finally, the username and email address of the submitter.
Click "Add this URL" to add the new link. When logged in as the Administrator, the submission is
• Text:
added to the database immediately. If not logged in as the Administrator, links must be approved before
• Float: they will be posted.
• Integer: • Modify a Link: To modify a link, enter its "Link ID" in this field and click the "Modify" button. To
determine a link’s Link ID, locate the Web Link entry that you wish to edit and "hover" the mouse
over the link title. In the browser’s status bar, you will see the URL for the link, for example:
• Length: Enter the length of the string for STRINGS ONLY. This determines how many characters http://www.yoursite.com/modules.php?op=modload&name=Web_Links&file=index&req=visit&lid=59.
a user is allocated for response. For example, if you wanted the user to be able to enter only one Look at the end of the line for "lid=##", where "##" is the Link ID. In this example, your Link ID is
character, enter "1" in this field. The maximum length is 1254. "59".
You may modify any of the following fields. Click "Modify" to save your changes, or "Delete" to delete
the Web Link. You must confirm the deletion before anything will be deleted.

• Page title: Title of the web page link, for example: "DrewVogel.COM".
Web Links
• Page URL: This is the FULL URL of the web site. Be sure to include "http://" at the beginning of the
Web Links allow your users to submit, view, and comment on other websites. Web Links can be config- URL. For example: "http://www.drewvogel.com"
ured into categories (for example: "Computers") and sub-categories (for example, "Computers / Games",
• Visit: Click "Visit" to open the referenced web site in a new browser window. (This is an excellent
"Computers / Audio", or "Computers / CMS"). Users can search for results or post comments about web-
way to ’preview’ a site before approving it.)
sites within this module.
• Description: Free-form alphanumeric text description of the web site to which this link points.
• Add a Category: To add a new category to your Web Links, enter the name of the category (for example, • Name: Name of the link submitter. Free-form alphanumeric text.
"Computers"), enter a description (for example, "Everything you need to know about computers!"), and
• E-mail: Complete e-mail address of the link submitter.
click "Add".
• Hits: This is the number of hits (or visits) that this site has received from your site.
To add a sub-category, follow the same steps but select the parent category in the drop-down list to the
right of the name. • Category: Select from the drop-down list of previously-defined categories (see "Add a Category",
above).
Click "Modify" to save your changes. Click "Delete" to delete this link.
• Modify a Category: To modify a category, select it from the drop-down list and click "Modify". The
category will be displayed to allow editing of the name or description. Make your changes and click IMPORTANT NOTE: There is no CONFIRMATION SCREEN when you click to "Delete" a Web Link!
"Submit changes". If you wish to delete a category, click "Delete". You will be offered a confirmation Be certain that you wish to delete the Web Link before clicking the "Delete" button.
screen before anything is deleted.
IMPORTANT NOTE: When you "Delete" a Category, ALL sub-categories AND WebLinks in that Cate-
gory (and sub-categories) will be deleted.

85 86
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Add/modify editorial: At the bottom of the Modify Link page, you are offered the option to write (or • How many unregistered user votes per 1 registered user vote: To place more value on the opinions of
modify if an editorial exists) an editorial of the referenced web site. Once the editorial has been written, registered users, you can define an entry in this field that specifies how many UNregistered user votes
an "Editorial" link appears next to the Web Links listing for the web site. are equal to one registered user vote. An entry of "10" means that every 10 unregistered user votes are
equal to one registered user vote. Entry example: "10".
For example:
• How many outside user votes per 1 registered user vote: To place more value on the opinions of reg-
Drew’s Recipe File
istered users, you can define an entry in this field that specifies how may Outside user votes are equal
Description: Recipes that Drew likes! Frequently updated. to one registered user vote. An entry of "10" means that every 10 Outside user votes are equal to one
Added on: 24-Oct-2001 Hits: 52 Rating: 9.1 (21 Votes) registered user vote. Entry example: "10".

Rate this site | Report broken link | Details | Editorial • Let detailed vote summary decimal out to n places: This entry allows you to specify if the detailed vote
summery should display decimal points, and if so, how many. If you want only whole numbers, enter
Editorial title: Enter the name of the editorial here. Free-form alphanumeric text.
"0" in this field. Enter "2" to carry the decimal points out two places. Entry example: "2"
Editorial text: Enter the body of the editorial here. Free-form alphanumeric text.
• 1 to show top links as a percentage (else # of links): "Top Links" is defined as the best rated links (or
Click "Add" or "Modify" to perform the action and save the editorial. downloads). "Popular" is defined as the most visited (or downloaded) items. If you set this field to "1",
your Top items are displayed as: "Top Links: Top 25% - 50% - 75% - 100%" (the percentages are links
that show that percentage of the items). If set to a number (for example, "10"), Top Links will show that
• Links Awaiting Validation: If your users submit web links, the links are held unaccessible to other users many top items (for example, "Top 10 Links"). Entry example: "1".
until the Administrator can review and post it.
• Top links - either # of links or percentage to show (percentage as whole number. #/100):
• 1 to show most popular links as a percentage (else # of links): "Top Links" is defined as the best rated
Web Links -> Web Links Configuration links (or downloads). "Popular" is defined as the most visited (or downloaded) items. If you set this
** IMPORTANT NOTE: WEB LINKS ARE BEING REWRITTEN FOR FUTURE VERSIONS OF POST- field to "1", your Popular items are displayed as: "Most Popular: Top 25% - 50% - 75% - 100%"
NUKE. THIS SECTION OF THE GUIDE IS, THEREFORE, INCOMPLETE. ** (the percentages are links that show that percentage of the items). If set to a number (for example,
"10"), Popular links will show that many popular items (for example, "10 Most Popular Links"). Entry
• Links per page: How many links to display per page listing. Set this number to balance convenience example: "1".
and load on your web site. If your listing of links spans multiple pages, navigation tools appear at the • Most popular: either # of links or percentage to show (percentage as whole number. #/100): Entry
bottom of the listing. Example entry: "25" example: "25"
• Number of days Anonymous users need to wait to vote on a link: If you wish, you can configure Web • Show featured link box on links main page: Entry example: "Yes"
Links so that Anonymous users may not vote on links for a certain period of time. That period of time
• Number votes needed to make the "Top 10" list: This field defines the minimum number of votes that a
is specified in this field. Enter "0" in this field to allow Anonymous users to vote on links as soon as the
link must receive to be qualified for the "Top 10" list on your site. Entry example: "5"
link is available. Entry example: "1" day.
• Block unregistered users from suggesting link changes: Set to "Yes" to block Anonymous users from
• Number of days outside users need to wait to vote on a link: If you wish, you can configure Web Links
requesting modification of the link description and other link information . If set to "No", Anonymous
so that Outside users may not vote on links for a certain period of time. Outside users are defined as
users may request modification of the link description and other link information. Entry example: "No"
users who cast votes via PostNuke’s "remote vote" service: Owners of links (or downloads) can put a
rating form or text/button link in their sites to allow their visitors to cast a vote on your site. Enter "0" • Hits to be ’Popular’: Set this field to a number equal to how many visits a site must have from your site
in this field to allow Outside users to vote on links as soon as the link is available. Entry example: "1 to be considered ’popular’. Entry example: "500"
day". • Number of links as ’New’: Within this field, you define how many web links are to be defined as "new"
• Allow Webmasters to put vote links on their site: Entry example: "Yes" at a time. If you wish to display 10 links as "new", enter "10" in this field.

87 88
 Chapter 16. Advanced Website Configuration & Use Chapter 16. Advanced Website Configuration & Use

• Number of links as ’Best’: Within this field, you define how many web links are to be defined as "best"
at a time. If you wish to display 25 links as "best", enter "25" in this field.
• Links in search results: This field defines how many links are displayed in Search results. If there are
more than this number of links, the user will be shown a link to display all matching results. Entry
example: "10"
• Let Anonymous users post new links?: Should Anonymous users be allowed to post new links? If you
wish to allow Anonymous users to post new links, set this field to "Yes". If you do not wish to allow
Anonymous users to post new links, set this field to "No". Entry example: "Yes"

89 90
 Chapter 17. Groups & Permissions

Chapter 17. Groups & Permissions • Advanced Corporate web site: Anonymous (Guests), Registered Users, Customers, Customers Eligible
for Support, Admin

It is easy to forget that websites have more than "visitors". As the line between design & programming • Corporate Intranet: Anonymous (Guests), Registered Users, Admin, Store Associates, Marketing Dept.,
for the web continues to blur, we must think of "websites" more like "software". Webmasters offer an Finance Dept., etc.
interface to their product. Each "visitor" is actually a "user" of the product. When we think of them as
"users" instead of "visitors", the relationship becomes a bit more personal. As we encourage the users to
become "registered users", that personal relationship builds. Default PostNuke Permissions Explained
For most site administrators, PostNuke’s default Permissions System will be sufficient right "out of the Your site has visitors -- Anonymous (tier zero) or Registered users (tier one) -- who read the news and
box" with no additional configuration. The default Permissions System provides two ’tiers’ of access to Admins (tier two) who post the news. New users are automatically placed into the "users" group when
the site, and a special unregistered visitors (Anonymous) group (which, for this document, is referred to they register for the system, though this is definable within PostNuke’s configuration options by going to
as "Tier 0", because it’s not really an access group per se, as much as it is the ABSENCE of membership Administration -> Settings -> Initial group for users and typing the name of the group to which new users
in other access groups). should be assigned.
The unregistered visitors group is defined as visitors to your site that have not registered for an account. Therefore, if we examine the "tiers" of Permissions in the default PostNuke configuration, we see:
This Anonymous group does not appear in the Group administration, but the Anonymous group always
exists within any Permissions configuration. This group can be given its own set of permissions -- from no
• Tier 0: Anonymous -- Visitors who have NOT registered for an account on the site
access at all to full Administrator access. The unregistered users group is distinct from the "users" group,
which is defined in the default distribution as users who have registered for an account on your system. As • Tier 1: "Users" -- Users who have registered for an account on the site
an example of the difference between the "anonymous" and "users" groups, PostNuke, by default, does • Tier 2: "Admins" -- Administrative control of the site
not allow Anonymous users to vote on Polls while members of the "users" group are permitted to vote in
The PostNuke Group system allows users to be placed into any number of groups, which are used to
Polls.
control access to and administrative functions on the site. If a user is a member of two or more Groups,
the Groups are evaluated in the order the Groups are listed in Administration -> Permissions.
Overview of the Permissions System The mapping between users and groups is many-to-many relationship -- multiple users can be in a single
Group, and each user can be in any number of Groups.
A "two-tier" permissions system (such as PostNuke’s default Permissions) is fine & well if you are running
a simple news site.
However, PostNuke’s Permissions system allows far greater flexibility. By allowing or denying access
Advanced Group Permissions
to certain areas of the site, the Permissions system allows very fine management of access to content.
For example, PostNuke may be configured in such a way that non-registered users do not have access to Advanced administrators may wish to customize the Permissions system to take advantage of the fine-
certain areas -- forums, reviews, polls, etc -- on the site until they register. This control extends all the way grained access control that PostNuke provides.
to particular News Article -- you could, if you wish, configure PostNuke to NOT allow a certain user to In most cases this is accomplished by assigning users to Groups. All members of a particular Group will
view a specific News Article. have the same level of access across the site. Create as many Groups as complexity of the site requires.
Examples of Permissions Tiers: An example of an advanced Group setup might be:

• Simple News Site: Anonymous (Guests), Registered Users, Admin (this is the default permissions • GROUP: Anonymous: Unregistered users who are visiting the site. Privileges: Read only access to
system in the PostNuke distribution) most areas of the site, Home Page, and certain items (for example: Become a Member, Classified ads,
• Advanced News Site: Anonymous (Guests), Registered Users, Subscribed Users, Admin Contact us, etc.). This Group is restricted from commenting on Articles and participating in Polls.
• Corporate web site: Anonymous (Guests), Registered Users, Customers, Admin

91 92
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

• GROUP: Registered: Users who have completed the registration form on the site. Privileges: Read and • Creating Groups: To create a Group, select the ’Add A New Group’ option. Type the name of the new
write access to most areas of the site. They can comment on Articles and participate in Polls. This group, and click the ’New Group’ button. The group will be created.
Group of users is restricted from editing other users’ posts. • Adding a User to a Group: To add a user to a Group, select the Group name, and click the ’Add a user
• GROUP: Members: Users who have agreed to pay for the use of the site. They have read and write to this Group’ link. You will be shown a drop-down list of users who are not currently members of this
access to all areas of the site and some special additional areas like a specific database, a job posting Group. Choose the user to add to this Group and select the ’Confirm’ button to add that user to the
area, a special picture gallery, a members’ chat forum, etc. Group.
• GROUP: Sub-Admin: Has the ability to add, edit, or delete content from pieces of the site, but not the • Removing a User from a Group: To remove a user from a Group, select the Group name. A list of users
whole site. who are currently part of that Group is shown. To remove a user select the ’Delete’ link next to the
• GROUP: Admin: Full access to all areas and the ability to add, edit, and delete content. user’s name.
• Renaming a Group: To rename a Group, select the Group name and click the ’Modify Group’ link.
Rename the Group as desired, and then click ’Rename group’ to save the changes.
User Permissions • Deleting a Group: To delete a Group, select the ’Delete’ link next to the Group that you wish to delete.
A confirmation page will be displayed. Select "Yes" to permanently delete this Group, or "No" to abort
In some special cases you may wish to grant an individual user special privileges. This can be accom-
Group deletion.
plished by using User Permissions. An example is when a specific user has agreed to moderate or manage
an area of the site. To that individual user you grant the same access level as an Administrator, but limit that IMPORTANT NOTE: The user accounts of members of a particular Group are NOT deleted when you
Administrative access to a specific area of the site. User Permissions override Group Permissions. User delete a Group.
Permissions should be used only in special cases where the existing Group Permissions are insufficient.

Setting up and configuring Groups Permission Levels

Each user can be placed in a definable Group and the entire group can be given a permission set. If you
are upgrading from an older version of PostNuke, PHPNuke, or myPHPNuke, you will have new Groups • None: No access to this function. The function will not appear as an option for the user.
defined for each of the author permissions that you had previously defined. These groups are set up during
the upgrade, but you will need to manually configure their permissions. • Overview: Allows OVERVIEW access to this function. The function appears as an option for the user,
but they may not post comments.
IMPORTANT NOTE: It is critically important that the ORDER of the Groups is correct. Permissions are
applied in order, from the top down. The system stops looking for permissions when it finds the first Group • Read: Allows READ-ONLY access to this function. The function appears as an option for the user.
that matches, so if one line gives everyone access to everything, a later line will NOT be able to take that • Comment: Allows COMMENT access to this function. The user can read and post comments within
access away. Be very careful. this function.
If a user is a member of 2 or more Groups, the Groups are evaluated in the order they are listed in • Moderate: Used for functions that require moderation, such as Comments, or in Forums. An example
Administration -> Permissions. is a user having moderation abilities within a message board but nowhere else on the site.
Example: The user is put into two Groups: "GroupA" and "GroupB". GroupA has explicit access to a • Edit: "Edit" is a permission for users that may not be permitted to Add, but are allowed to Edit. Example:
particular feature. GroupB explicitly does NOT have access to that feature. Since GroupA is evaluated An Article Administrator that is permitted to edit stories, but is not permitted to post Articles.
first, the user will have access to that particular feature.
• Add: "Add" grants permission to either add or approve content.
From Administration -> Groups:
• Delete: "Delete" is the opposite of "Add". You are granting someone the ability to remove content.
• Admin: Allows ADMIN access to this function. The user has Administrator access to this function.

93 94
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

An example of Group Permissions Permissions FAQ

The following is an example of a Group Permissions model as used on http://www.drewvogel.com.
The line numbers, shown below, are for this Guide only (they do not appear in PostNuke), and are ex- • Q1. What is the permissions system for?
plained below.
A: The permissions system is designed to allow site administrators to protect their site content and
Group Component Instance Perm. level restrict operations to their desired level of detail.
------------------------------------------------------------------------ For more information on the permissions system, check out the online help within PostNuke. Log in
1. Admins Menublock:: Administration::*. Admin as Administrator, go to Permissions, and click "View Group Permissions" or "View User Permissions".
2. Admins .* .* Admin On the screen that is displayed, several of the text items are ’clickable’... Click them to open windows
3. All groups Menublock:: Administration::*. None that provide additional explanation.
4. Users .* .* Comment
5. Unregistered Menublock:: Main Menu:(Andromeda| None
Logout|Forums|Submit • Q2. I don’t like it! I prefer the way it worked before.
News|Members List| A: The permissions system is set up initially to work in a style very similar to the old PostNuke. To
Messages): make a user an Administrator of a site, go to Administration -> Groups and add that user to the ’Admins’
6. Unregistered .* .* Read Group.

• Line 1: Grant all members of Group "Admins" a Permission level of "Admin" for all Instances matching • Q3. Why are there so many warnings in the permissions manual about getting the permissions right?
a Menublock called "Administration". Administrators have full access to the Administration menu. A: It is critically important that you configure permissions properly. Failing to do so can open up the
• Line 2: Grant all members of Group "Admins" a Permission level of "Admin" for all Instances of site to allow anyone to update, add, or even DELETE content on the site. However, provided that you
EVERYTHING on the site -- this grants all Admins unlimited access for everything on the site. read these instructions carefully and do not change the default permissions unless you are absolutely
sure of what you are doing, this should not happen.
• Line 3: Remove access to Menublock "Administration" for members of "All groups". This disables
access to Administration functions from ALL users, unless specifically allowed by a special user or
group permission. Line 1, above, is an example of a special group permission. • Q4. Why can’t users access the Polls unless they log in? or Why can’t users comment on Stories unless
• Line 4: Allow all members of Group "Users" (registered users) access to "Comment" on everything on they log in?
the site. A: The permissions system is set up initially to only allow Unregistered users to have generic read-level
• Line 5: Remove access (set to "None") to specific items "Andromeda|Logout|Forums|Submit access. To allow unregistered users to comment on items, look in the group permissions setup for a line
News|Members List|Messages" from the "Main Menu" of "Unregistered" users. that looks like this:

• Line 6: Allow all "Unregistered" users access to "Read" everything on the site. Unregistered .* .* Read

As you can see, Permissions are evaluated by PostNuke from the top first, moving down through the ...and edit it so that it says:
permissions. Unregistered .* .* Comment
Be sure to save any changes.

An example of User Permissions

• Q5. Why do I need that ’.*’ on the end of my permissions?
UNDER CONSTRUCTION
A: You don’t. Since PostNuke .710, ’Foo:’ is the same as ’Foo:.*’.

95 96
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

The most obvious use of this is in the first entry for the group permissions, which is Permissions for Newbies
Admins .* .* Admin After looking around I noticed a lot of you are trying to do what I have done... Create a sub-administrator
...which says ’Admins are allowed to administer anything’ for certain parts of the site by creating a Sub-Admin group. Below is some information that may assist in
configuring your permissions.
For details on allowing different types of content, check out the online manual pages for the Permissions
system. For example, assume that you have a group of people you wish to place into a sub-administrator group.
Here is a step-by-step example of creating this group and giving them permission to approve stories
(articles) for the site.
• Q6. How do I add a sub-admin to my site that has access to certain features, plus have the Administration
menu accessible to them? • Go to the Administration menu and click "Groups".
A: We’re going to need two sets of permissions, one to actually edit a story, and one to allow the • Create a Group with a descriptive name (for example, "subadmins").
Administration link to show up in the ’main menu.’
• Add the users that you want in the "subadmin" Group (examples: John Doe, Jane Doe).
The following permissions would allow this to happen (do not include the square brackets):
Now that you have created the Group, you must grant the Group permission to do what you want them to
Admins .*.* Admin Edit Delete do. In this example, we wish to allow them to be able to approve an Article for the site:
SubAdmin [(Stories::)|(Modulename::)|(Modulename::)] .* Admin
SubAdmin Menublock:: Main Menu:Administration: Read • Go to Administration -> Permissions.
All groups Menublock:: Main Menu:Administration: None
• Click "New Group Permissions" to create a new set of permissions.
Replacing ’Modulename’, above, with an actual module name would give your sub-admin access to
those modules as well. • Select the "subadmins" group.

Remember NOT to include the square brackets! • Under "Component", type "Stories::".
• Under "Instance", type ".*".

• Q7. How do I force users to enter login name and password at the homepage? • Under "Permission Level", select "Admin" from the drop-down list.

A: We must first allow Unregistered users to see the Login block (we have to allow them to login!), by • Click on "New Permission" to save your changes.
adding: Graphically this is:
Unregistered Loginblock:: .* Read
Function Setting Notes
We then change the default permission to not allow Unregistered users to read anything, thus -----------------------------------------
Unregistered .* .* Read Group subadmins Setting the permissions for Group subadmins
Component Stories:: Using the Stories Module
...becomes... Instance .* The permission level applies to everything in this
Unregistered .* .* None component
Permission Admin Highest level of access
Be certain to add the lines in the order as specified or else it will not function as expected.
Remember this is going to give anyone in your Subadmins Group TOTAL control over the Stories module.
Most of you have the first permission set as ADMIN ADMIN. Move this newly-created group directly
below Admins to ensure that another permission does not override it.
For example:

97 98
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

Group Component Instance Permissions Level To make it so that a member of group ’Users’ can no longer submit news yet another group, ’Submitters’
---------------------------------------------------- (where Users are added to this group at the discretion of the admin) can Submit News.
subadmins Stories:: .* Admin Let’s break this issue down. There are four steps to this situation.
Users .* .* Read

...would allow subadmins group Admin permissions since those members in subadmins are also in the • Change USERS group to DISALLOW users in this group to Submit News.
group Users, but the subadmins permission is above the Users permission. • Change SUBMITTERS group to ALLOW users in this group to Submit News.

Group Component Instance Permissions Level • Add user(s) to the new SUBMITTERS group.
---------------------------------------------------- • Get the ORDER of the permissions correct.
Users .* .* Read
Now that we understand the steps, it is rather straightforward to implement what you want.
subadmins Stories:: .* Admin
1. Assuming that we have the following permissions structure set up:
...this, however, would be useless since the permissions were already defined as Comment level for the
Users before they were defined as Admin for subadmins. Everyone in Users and subadmins would have Sequence Group Component Instance Permissions
the same access. level
================================================================================
=
Permission Samples Admins Menublock:: Administration::*. Admin
Let’s say I have a link to a feature called ANDROMEDA and I don’t want a user called "JoeSmith" to see Admins .* .* Admin
it. I will select "JoeSmith" as the User and remove that user’s ability to view it. To every other user the All groups Menublock:: Administration::*. None
menu would look like this: Users .* .* Comment
Unregistered Menublock:: Main Menu:(Andromeda|Logout None
Home
|Forums|Games|Submit News
Your Account |Members List|Messages):
ANDROMEDA Unregistered Polls:: .* Comment
Unregistered .* .* Read
News
...however, by adding the following to the permissions system... ...we can DISALLOW Submit News by adding the following line (marked with "=-=-=-" above and below
the added line):
User JoeSmith
Component Menublock:: Sequence Group Component Instance Permissions
level
Instance Main Menu:ANDROMEDA: ================================================================================
Permission None =
Admins Menublock:: Administration::*. Admin
...that user’s menu now looks like this:
Admins .* .* Admin
Home All groups Menublock:: Administration::*. None
Your Account =-=-=-
Users Menublock:: Main Menu:(Submit News): None # THIS IS
News THE ADDED LINE!
=-=-=-

99 100
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

Users .* .* Comment
Unregistered Menublock:: Main Menu:(Andromeda|Logout None Let user called "James" see the "Administration" link. Add a User permission
|Forums|Games|Submit News for the specific user:
|Members List|Messages):
Unregistered Polls:: .* Comment User/Group James
Unregistered .* .* Read Component Menublock::
Instance Main Menu:Administration:
The added line sets to "None" the ability for the Users group to see the Main Menu item "Submit News". Permission Read
If your main menu is called something other than "Main Menu", or your submit news link is called
something other than "Submit News", change the instance text. If you renamed the "Administration" link to "Control", you would have to change
2. We create a Group called "Submitters". Go to Administration -> Groups -> Add New Group. Type the the permission to:
name of the new group (I used "Submitters") and click the "New Group" button.
User/Group James
3. When the Groups page re-appears, click the name of the new group ("Submitters"), then click "Add a
Component Menublock::
user to group" to add user(s) to this new Group.
Instance Main Menu:Control:
4. Finally, go back to Administration->Permissions for step four which pulls it all together. Add line that Permission Read
is marked with "=-=-=-" above and below.
----------------------------------------------------------------------------
Sequence Group Component Instance Permissions
level If you would like to make certain Articles available only to specified groups,
================================================================================ you may do so by grouping the Articles under a specific category and declaring
= the permission as follows:
Admins Menublock:: Administration::*. Admin
Admins .* .* Admin User/Group Unregistered
All groups Menublock:: Administration::*. None Component Stories::
=-=-=- Instance :<Category Name>:
Submitters .* .* Comment # THIS Permission None
IS THE ADDED LINE!
=-=-=- ...where "<Category Name>" is the name of the Category where the Articles were
Users Menublock:: Main Menu:(Submit News): None grouped.
Users .* .* Comment
Unregistered Menublock:: Main Menu:(Andromeda|Logout None ----------------------------------------------------------------------------
|Forums|Games|Submit News
|Members List|Messages): Adding Downloads Permissions to filter unregistered access.
Unregistered Polls:: .* Comment
Unregistered .* .* Read Here are the complete steps to do this :
* Locate the line 80 from modules/Downloads/lang/eng/global.php file.
The added line gives specific permission to anyone in group "Submitters" to be able to use the Submit
News function.
* Change the define to the following:
---------------------------------------------------------------------------- define(’_DOWNLOADSACCESSNOAUTH’, ’You must be a registered member to access

101 102
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

downloads’); To allow Anonymous users to vote in Polls:

* Go to Permissions Administration then Add a new group permissions as shown User/Group Unregistered
below: Component Polls::
Groups: Unregistered Instance .*
Component: Downloads:: Permission Comment
Instance: .*
Permissions Level: None ----------------------------------------------------------------------------

* Place the permission hierarchically just BEFORE default unregistered Member from group "users" can add stories (this will add a link to Add Stories
permission as shown below: in the menu of group "users"):
Group: Unregistered
Component: .* User/Group users
Instance: .* Component Stories::
Permission level: Read Instance .*
Permission Add
----------------------------------------------------------------------------
----------------------------------------------------------------------------
Restrict Articles submitted by a specified author ("uid 2" in this case) from
being seen by Anonymous users: Create a section available to certain members only. In this example, we first
created a group named "Paid Members" before doing the following:
User/Group Unregistered
Component Stories:: Group: Paid Users
Instance 2:: Component: Sections::Section
Permission None Instance: .*::1 (1 is the section ID)
Permissions level: Read
----------------------------------------------------------------------------
Group: All Groups
Restrict a specific article ("sid 50" in this case) from being read by a Component: Sections::Section
specific user ("Paul" in this case): Instance: .*::1 (1 is the section ID)
Permissions Level: None
User/Group Paul
Component Stories:: Make sure that the first definition is above the second one and you’ve got a
Instance ::50 section for paid members only.
Permission None
----------------------------------------------------------------------------
(interesting uses!)
Members from group "users" can add Polls (this will add a link to Add Polls in
---------------------------------------------------------------------------- the menu of group "users"):

103 104
 Chapter 17. Groups & Permissions Chapter 17. Groups & Permissions

User/Group users
Component Polls::
Instance .*
Permission Add

-----------------------------------------------------------------------------

105 106
 Chapter 18. Conclusion

Chapter 18. Conclusion

Thank you for reading the Official PostNuke Installation and Getting Started Guide!
I hope that this Guide has increased your understanding of how PostNuke functions, and that it has helped
you to install and configure your own PostNuke 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 PostNuke 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 at:
<drew@drewvogel.com>
http://www.drewvogel.com
Happy PostNuking!
-drew vogel

107 108
 Chapter 19. APPENDIX A: Create the MySQL database that PostNuke will use

Chapter 19. APPENDIX A: Create the MySQL

database that PostNuke will use
If you have root access to the database, a command such as:
"mysqladmin -u root -p create <dbname>"
...will create the database. Replace "<dbname>" with the name of the database to create, for example,
"rogue".
If you do not have root access to the database, you will need to create the database in another way before
installation can continue.
Please consider using a tool such as phpMyAdmin (http://phpwizard.net/projects/phpMyAdmin)
to automate the database creation process. To create the database using phpMyAdmin, type the name of
the new database (for example, "rogue") and click "Create". The database will be created.

109 110
 Chapter 20. APPENDIX B: Create the MySQL username and password that PostNuke will use

Chapter 20. APPENDIX B: Create the MySQL • - Set "Database" to the name of your PostNuke database <dbname>.
• - Click "Check All" under Privileges.
username and password that PostNuke will use • - Click the "Go" link below Privileges.

Follow these steps to set up the database username and password:

• The user will be given full access to the PostNuke database, but nothing else.
• "mysql -u root -p"
You will be prompted to enter the root database password. When the MySQL monitor prompt appears,
type in the following:
"GRANT ALL PRIVILEGES ON <dbname>.* TO <dbuser>@<dbhost> IDENTIFIED BY
’<dbpass>’ WITH GRANT OPTION;"

• <dbname>: The name of the database that PostNuke will use. Example: "rogue".
• <dbuser>: The username that PostNuke will use to access the database. Example: "web".
• <dbpass>: The password for <dbuser>.
• <dbhost>: The hostname where <dbname> resides. Most users will use "localhost".
Press RETURN. If the process was a success, it will be reported as "Query OK, 0 rows affected (0.05 sec)".
If you do not have root access to the database, a database username and password can be created using ph-
pMyAdmin (http://phpwizard.net/projects/phpMyAdmin). To create a database username and password,
follow these steps:

• Log in to phpMyAdmin.
• Click "Users".
• Under the section entitled "Add a new user", follow these steps:
• - Set "Host" to "localhost" (or the host defined in <dbhost>.
• - Set "Username" to <dbuser>.
• - Set "Password" to <dbpass>, and re-type it to verify the password.
• - ALL Privileges should be BLANK (unchecked).
• - Click the "Go" link below Privileges.

• The user will be created. Next, follow the steps below to grant privileges to the user we just created.
• - Click "Grants" next to the user that we just created.

111 112
 Chapter 21. APPENDIX C: Configure the webserver

Chapter 21. APPENDIX C: Configure the

webserver
You need to ensure that your webserver is configured to recognize PHP files. You may need to add the
following to your Apache httpd.conf file (usually in /etc/httpd/conf for *NIX, or C:\Program Files\Apache
Group\Apache\conf for Windows) to define the search order for files. It is recommended that "index.html"
(or "default.htm" for Windows) be the first entry, followed by "index.php". If you edit your Apache con-
figuration, you must restart Apache for the changes to be incorporated (for example, "httpd restart").
--- CUT HERE ---
#
# DirectoryIndex: Name of the file or files to use as a pre-written HTML
# directory index. Separate multiple entries with spaces.
#
<IfModule mod_dir.c>
DirectoryIndex index.html index.php index.php3 index.pl index.htm
</IfModule>
--- CUT HERE ---
For Windows IIS and Personal Webserver, there are several ways to configure PHP support. Please consult
the ’install.txt’ file that comes with the PHP distribution.

113 114
 Chapter 22. APPENDIX D: Configure PHP

Chapter 22. APPENDIX D: Configure PHP

You need to ensure that your site has a working installation of PHP (version 4.0.1pl2 or higher) compiled
with MySQL support. PHP is the language in which PostNuke is developed. Without PHP support, the
web server would not be able to parse the PHP files and your site would not work.
To determine which version of PHP you’ve got installed, or if it is installed at all, create a file called
"test.php" in your web directory. The file should contain the following:
--- CUT HERE ---

--- CUT HERE ---

Point your browser to this page (for example, http://www.yoursite.com/test.php). The version of PHP will
be displayed at the top of the page. If it is earlier than 4.0.1pl2, you MUST upgrade or PostNuke will not
function. More recent versions of PHP have significant security and functionality enhancements.
PHP also requires that a few settings exist in php.ini (usually /etc/php.ini for *NIX, or
C:\Windows\PHP.ini for Windows). These settings are usually correct within php.ini by default, but
please check to make sure your php.ini has the following entries to ensure proper operation:
--- CUT HERE ---

include_path=’.’
magic_quotes_gpc = Off
register_globals = On
short_open_tag = On
session.auto_start = 0
debugger.enabled = False

--- CUT HERE ---

The following line in php.ini must be commented out or deleted, if it exists, or PostNuke will not function.

session.save_handler = php

PLEASE NOTE: If you make any changes to your php.ini file, it is necessary to restart your webserver
so that the changes are incorporated into the system. Restart your webserver from the command line (for
example, "httpd restart"), or restart your computer.

115 116
 Chapter 23. APPENDIX E: Enable GZIP compression in php.ini

Chapter 23. APPENDIX E: Enable GZIP

compression in php.ini
Within php.ini (usually /etc/php.ini), add the following lines to activate GZIP compression (*NIX ONLY
-- DOES NOT WORK ON WINDOWS SERVERS):
--- CUT HERE ---

# GZIP COMPRESSION
#
output_handler = ob_gzhandler

--- CUT HERE ---

117 118
 Chapter 24. APPENDIX F: Getting development versions of PostNuke using the CVS server at
developer.hostnuke.com

Chapter 24. APPENDIX F: Getting development NOTE: It is strongly recommend that you use the latest stable version of
versions of PostNuke using the CVS server at TortiseCVS to checkout from developer.hostnuke.com. With the newest (unstable)
development versions of TortoiseCVS, inconsistencies in performance can occur,

developer.hostnuke.com depending on your Windows environment.

2. Checkout with WinCVS

This section will describe two methods to checkout code from the
CVS-respository on developer.hostnuke.com. The methods are: Get WinCVS for your Windows or Macintosh. You also need a SSH-client
1. Checkout with TortoiseCVS and the Python 2.2xx-version.
2. Checkout with WinCVS
The next step is to set up the WinCVS Admin->Preferences settings:
1. Checkout with TortoiseCVS
The WinCVS Admin->Preferences settings are:
TortoiseCVS works with Windows 95, 98, ME, NT, 2000 and XP, is very authentication: ssh
similar to WinCVS. For an anonymous CVS-checkout, you do not need a developer path: /home/cvsroot
account. host address: cvs.hostnuke.com
username: anonymous
a. Get TortoiseCVS (latest stable version is recommended).
Install TortiseCVS on your machine. Also install an ssh-ftp-client, for Select "Show CVS console (open TTY)"
example, from Ftp-Client. See the Tutorial for the PN-module-checkout.
See also the WinCVS -- Daily Use Guide and the quick reference guides
b. Create a folder for checking out PostNuke and right-click on on developer.hostnuke.com. For questions and further information see the latest
it. In the content menu choose CVS -> Preferences -> Quirky and set Network information on developer.hostnuke.com.
Compression to "0 - None". Then, right click again on the folder created for
checking out PostNuke and select CVS Checkout and enter the following
information:

- Module tab
Protocol - Internet (secure shell)
Server - cvs.hostnuke.com
Repository Directory - /home/cvsroot
User name - anonymous
Module - postnuke_official

- Revision tab
Get tag/branch: - PostNuke_71

c. When checking out a DOS-window will open. Type ’anonymous’

as password. (if checking out as registered developer, provide your
username/password).

119 120