END USER'S SECTION
ADMINISTRATOR'S SECTION
QUICK START NOTES FOR END USERS
Editing pages is very simple and is covered in this section. End Users can ignore the other sections in this document.
Once you login, (for example, at http://yourdomain.com/pm/standard) the Top Menu will display a set of 2 default 'pages' -- 'Index' and 'News' with links to 'Edit' or 'View Include Files'. If you see these links, it means that your web administrator still has to change the data structure of your PageMod system.
If your administrator has changed the data structure of your installation, then you may not see 'Index' or 'News' -- instead you'll see links representing pages that are specific to your system.
Each 'page link' represents an html page. In some cases the html page may be treated as a regular html page that you can access from the web. In other cases, the pages are treated as 'include files' -- that is, they're included in other html pages. Consult your web administrator about your specific system.
Click 'Edit' to edit a page:
As an end user, your primary activity is to 'edit' the data contained in the fields that are displayed when you click on the edit button. You can change the data and also (in the case of image fields) upload images.
After changing the data in the fields, and/or specifying images to upload, then simply hit 'Save'. The Save function will:
Note: You can edit the pages as often as you like -- each time you hit 'Save', the final pages are generated.
That's it! You're done. End Users can ignore the other sections in this document.
These install directions assume that you have access to the SHELL prompt of your server, either via ssh or telnet. If you don't have that access, you'll have to unzip the files on your desktop and upload each directory by hand. The critical issue is that certain directories and files must be 'world writeable' so that the web server can write to them. For a list of those directories, consult the section below -- File And Directory Permissions.
1. Unzip the distribution file (pagemod.tar.gz)
in your web server's *home* directory (not your web document root)
(Your home directory is *above* your web document root.)
by typing:
gunzip pagemod.tar.gz
pagemod.tar.gz contains two .tar files and one readme file:
- pagemod_non_web.tar
- pagemod_web.tar
- readme.pagemod.install.txt
2. Again, in your *home* directory, 'untar' the file
'pagemod_non_web.tar (the *non_web* file)
by typing:
tar xvpf pagemod_non_web.tar
This will create the 'pagemod' directory where the primary
script files will be installed.
3. Copy the file 'pagemod_web.tar' to your 'web document root',
typically 'www' or 'html' (where your top index.html page is)
by typing:
cp pagemod_web.tar ./www
(or ./your_web_document_root_name)
then change to that directory by typing:
cd ./www
and then type:
'tar xvpf pagemod_web.tar'
This will create a 'pm' directory where your generated
pages and images will be stored.
4. Edit the file 'index.cgi' in the
pm/standard directory and change the path names for the
following variables (shown here with fake dirs):
- $preferences_dir = '/your.home.directory/pagemod';
- $web_doc_root = '/your.home.directory/www';
(where the 'www' is the name of your web document root)
(substitute the correct name)
5. Your login url will be http://yourdomain.com/pm/standard
The default username is 'admin'.
The default password is 'admin2000'.
(Change them!)
The password file is:
pagemod/users/standard/.pagemod.cnf
6. Once you login at the standard url, you'll see the
regular user menu *plus* the 'admin' menu, which
you can use to create other users.
NOTE! If you want to turn OFF the admin menu,
(for example in a 'simple installation')
then edit the pagemod_site.pl file and change the
variable $show_admin_menu to 'no'.
NOTE! The file pm/standard/index.cgi also has
3 variables that control menu display:
- $show_modify_structure = 'no';
- $show_regenerate_pages = 'no';
- $show_select_templates = 'no';
If they're set to 'no' then the respective menus
will only show in the admin menu. Otherwise, they'll
display in the normal users menu if they're set to 'yes'.
However, if they're set to 'no' and you also have
$show_admin_menu set to 'no', then they won't show up
at all.
7. Consult the documentation!
8. You're done.
PageMod files are stored in two directory trees:
- homedirectory/pagemod
- homedirectory/www/pm
... where 'homedirectory' is the site's 'home directory' e.g: /home/username and 'www' is the site's 'web document root', usually either 'www' or 'HMTL'.
The script files, templates, user data files, etc. are stored under homedirectory/pagemod. The generated pages, uploaded images and login script (and pagemod system graphics) are stored under homedirectory/www/pm.
FILE
AND DIRECTORY PERMISSIONS (for manual installs)
Certain files and directories must be set to be 'world writeable', that is '777'
(rwx-rwx-rwx) for directories and '666' (rw--rw--rw) for files or '755' (rwx-r-x-r-x)
for some 'executable' files. This is so the web server can 'write' to the files
and directories.
DIRECTORIES Set to drwxrwxrwx (777)
In Your Home Directory:
- DIR (777): pagemod/users
- DIR (777): pagemod/users/standard
- DIR (777): pagemod/users/standard/backup
- DIR (777): pagemod/users/standard/page_templates
- DIR (777): pagemod/users/standard/sessions
- DIR (777): pagemod/shared_templates/basic
- DIR (777): pagemod/shared_templates/special
In Your Web Document Root Directory:
- DIR (777): pm
- DIR (777): pm/standard/pages
- DIR (777): pm/standard/pages/images
FILES Set to -rwxr-xr-x (755) (Executable)
In Your Home Directory:
- FILE (755): pagemod/bin/libformat.so
- FILE (755): pagemod/bin/nconvert
In Your Web Document Root Directory:
- FILE (755): pm/standard/index.cgi
FILES Set to -rw-rw-rw- (666)
In Your Home Directory:
- FILE (666): pagemod/users/standard/pagemod.data.pl
- FILE (666): pagemod/users/standard/page_template_dir.pl
Note: ALL TEMPLATE FILES must be set to 666. (The files here
are default installation files.)
- FILE (666): pagemod/users/standard/page_templates/index.main.template.html
- FILE (666): pagemod/users/standard/page_templates/index.popup_text.template.html
- FILE (666): pagemod/users/standard/page_templates/news.whats_new.template.html
- FILE (666): pagemod/shared_templates/basic/index.main.template.html
- FILE (666): pagemod/shared_templates/basic/index.popup_text.template.html
- FILE (666): pagemod/shared_templates/basic/news.whats_new.template.html
- FILE (666): pagemod/shared_templates/special/index.main.template.html
- FILE (666): pagemod/shared_templates/special/index.popup_text.template.html
- FILE (666): pagemod/shared_templates/special/news.whats_new.template.html
In Your Web Document Root Directory:
Note: Strictly speaking, the PAGES files don't have to be set to 666, since
they're generated by the web server. However, if YOU upload them, you have to
set them to 666 so that the server can write to them. (The files here are default
installation files.)
- FILE (666): pm/standard/pages/index.html
- FILE (666): pm/standard/pages/index.popup_text.html
- FILE (666): pm/standard/pages/news.whats_new.html
- FILE (666): pm/standard/pages/images/index.main.1.courting.jpg
- FILE (666): pm/standard/pages/images/index.main.2.true_love.jpg
- FILE (666): pm/standard/pages/images/tn_index.main.1.courting.jpg
- FILE (666): pm/standard/pages/images/tn_index.main.2.true_love.jpg
Please look at the file 'pagemod/pagemod_site.pl' for setup variables and definitions. Each variable has notes next to it, explaining its purpose. Generally speaking, you don't have to edit anything. These are 'global' variables that will be used by all installed users within that pagemod tree.
The mandatory
'setup file' is the 'index.cgi' file in the
pm/standard directory. Variables in this file allow you to change the behavior
of the program for each user in the pagemod tree.
LOGGING IN
You login at the url: /pm/standard (or some other username after the 'pm' directory).
The program requires a username
and password, which is stored in the file 'pagemod/users/standard/.pagemod.cnf'.
You may change the username and password by editing that file.
NOTE: *MANY* FTP programs do NOT display filenames that begin with a dot (.)
unless you request it. This is for security. You may have to set an option on
your ftp program to display 'hidden' files.
Once you log in, your password is encrypted and half of it is stored in the
'sessions' directory. The other half is encrypted and stored in a hidden field
called a session id, in your web browsers screen. The encryption method is a
handrolled XOR encryption. See the file http://worldcommunity.com/opensource/futuresql/security.txt
for details on this method.
OVERVIEW
PageMod is a "a web page text and image modification system".
It is designed to be a simple tool that allows a web administrator to update
"sections" of text and images within individual web pages without having to
edit the web page itself.
Assume that a web page called
"index.html" has 2 sections that need constant updating, such as "News" and
"Schedule".
First, place "server side include" commands in the index.html file, like this:
<!--#include virtual="/pm/standard/pages/index.news.html" -->
.... some html text ....
<!--#include virtual="/pm/standard/pages/index.schedule.html" -->
The server side include commands point to small "SSL include files", html files
that ** DO NOT ** contain <html> headers and footers. Instead, they simply
contain the html text and/or images that you would like to appear in the spots
where you placed the ssl commands.
The "naming convention" of the SSL files is based on the "Perl Data Hash" (see
below).
The "/pm/standard/pages" directory is defined in the setup files: "index.cgi"
and "pagemod_site.pl" (along with many other variables).
Generated Files:
The SSL files are *NOT*
created by the web designer -- instead, they're automatically generated by the
program, by "meshing" values from a data file with "tags" that reside in html
templates.
The HTML templates *are* created by the designer, and look exactly like the
SSL files except for one critical thing:
They contain ":!:tags:!:" (with the :!: delimiters) that get replaced with data
values when the script is run. (See below for more information.)
Using the above example of the "index.html" file, two (2) html template files
would have to be created by the web developer, with these names:
- index.news.template.html
- index.schedule.template.html
Note that the template file names are identical to the final SSL files *except*
for the word "template" at the end of the main part of the filename.
The template filenames (and then the generated SSL files) are structured based
on this syntax:
<page_name><section_name>template.html as in:
index.news.template.html or
index.news.html
Each template has one or more ":!:tags:!:"
inside it. The names of the tags can be anything that the web developer desires,
with the notes listed below.
TAG
NAME RULES
1. Tag Names are Case Sensitive.
2. Tag Names shouldn't have any spaces - keep them 'alpha_numeric' as well as
underlines or dashes.
Give the few rules presented here,
and with the exception of the Image Upload tags and Link Url tags, tag names
can be anything you want! All tag data fields are presented as text_box
fields except for the Image and Link fields. The program is completely blind
to the meaning of a particular tag -- it doesn't regard them at all, except
for the above two exceptions.
NOTE!! Periods in Section Names and Tag Names are Illegal *except* in the case
mentioned below (SORTING). (They're always illegal in the :!:tags:!: placed
in the template files.)
Special TAG: Image Upload Fields
3. If the tag name starts with the
word 'graphic' it will be treated as an 'image upload' field.
4. If you need more than ONE graphic file in a section, use the suffix '_1'
or '_2', etc. The '_1' syntax is mandatory if you have more than one graphic.
Special TAG: Link Url Fields
5. If the tag starts with the phrase
'link_url', it will be treated as an 'href link' in the system display (not
the generated pages -- you have place the href code by hand -- see below). It
will also be presented for editing in a single line field.
Note that the tags for the link url and the link title are in two tags -- thus
the developer must place the hrefs around the link tags -- but this allows greater
flexibility. E.g: <a href=":!:link_url:!:">:!:link_title:!:</a>
For example, the content of a template might look like this:
*** start of template ***
<p><font face="Arial, Helvetica, sans-serif" size="+1">
<b><font color="red">:!:headline:!:</font></b></font></p>
<img src=":!:graphic_1:!:"><br>
<p>:!:text:!:</p>
<a href=":!:link_url:!:">:!:link_title:!:</a>
*** end of template ***
Because the
program only "sees" the :!:tags:!:, you can include any legal html
or Javascript you like, including tables or even parts of tables in the template
files.
THE STRUCTURE
OF THE PERL DATA FILE
The tags mentioned above are replaced with data.
The data is stored in ONE file, called "pagemod.data.pl". This file is a real
live Perl script file that stores data in a format known as a "hash of hashes"
(basically a tree like structure).
It can be edited with a text editor, but it MUST adhere to the data structure
syntax and conventions contained in the sample file.
As a backup, the pagemod directory contains a 'plain vanilla' data file called
'pagemod.data.sample.pl' that you can use at any time as a reference.
NOTE! Because the data file is a Perl 'hash' file, it is extremely exacting.
Thus, if you edit it by hand, please make sure that you include all the necessary
{ } bracket pairs and please place commas (,) after each entry.
Although the program sometimes saves the data file without commas after the
last entries in a set, it is a better practice when editing and moving things
around by hand to place commas after every entry.
NOTE: Most users will want to use
the Modify Structure of Pages button on the Top Menu instead of trying
to edit the data file by hand. See the Administration Menu section.
The data file "structure" must MATCH the html template file names, as follows:
Using the index.news.template.html
file as an example:
- the section in the filename called 'index'
matches the final html page -- thus, it represents the 'page'
key in the data structure.
- the section in the filename called 'news'
represents a 'section' in the page (index.html).
Thus, the data file would contain a 'branch' like this:
SAMPLE OF DATA HASH
1. The first key is the PAGE NAME
(e.g. 'index')
2. The second key in is the SECTION NAME in the page.
3. The third set of keys/values are the TAG NAMES and TAG VALUES for each SECTION.
'index' => {
'01.news' => {
'01.headline' => 'headline value',
'02.graphic_1' => 'index.news.1.filename.jpg',
'03.graphic_2' => 'index.news.2.filename.jpg',
'04.text' => 'text value',
'05.link_url' => 'link url value',
'06.link_title'=> 'link title value',
},
},
INCLUDING
HTML ELEMENTS IN FIELD VALUES
You can store a set of popdown menu or scrolling list values in a field, or
any other html 'element'. For example, in your template you might have a tag:
:!:scrolling_list:!:
Then, in your field, you'd have:
<select name="fieldname" multiple size="2">
<option value="value1">Value1 Title
<option value="value2">Value2 Title
<option value="value3">Value3 Title
<option value="value4">Value4 Title
</select>
The program is "blind" to values in the fields, so you can include any type
of html code you like. If you use things like scrolling lists, you may want
to include the tag <!-- NO_BR_CHANGES --> in your data field content.
See below.
No Line Breaks Tag -- <!-- NO_BR_CHANGES -->
By default, all hard returns in
text box fields are replaced with <br> tags. If you add the comment
<!-- NO_BR_CHANGES --> anywhere in a text field, it will not add the <br>
tags.
This is useful for text fields that contain html elements, such as a popdown menu.
SORTING THE DISPLAY OF SECTIONS AND TAG FIELDS
If you wish to SORT the editing
display of sections and tags **IN THE DATA FILE**, then 'prepend' the section
names and tag names with NUMBERS and/or LETTERS that sort according to ASCII
rules. You MUST place a PERIOD (.) after the prefix.
Note that the "PREFIX." will be stripped off when the sections and tags are
displayed -- thus **DON'T** use the number prefixes in the tags placed in the
templates.
- NOTE!! Do NOT use SORT ORDER PREFIXES in the PAGE NAME keys.
ONLY use them in the SECTION_NAME keys and the TAG_NAME keys.
- NOTE: Sorting is done based on normal ascii conventions. You may use any variety
of prefixes -- the program 'cuts' the prefix off at the DOT (.)
- NOTE: Don't use a period (.) anywhere else in the page, section or tag names.
Only use a period as a sorting delimiter, per above.
"Include File" Method v. Standard HTML Pages
Some designers like to have the PageMod system treat the generated files mentioned above as regular web pages, not 'include' files. This can be done by simply linking to one of the generated pages as if it was a regular web page.
In addition, the PageMod system allows one to modify a set of variables in the pagemod_site.pl file that will generate a regular index.html page, thus allowing one to use PageMod for an entire web system. These variables are:
$top_page_or_include = 'top_page';
# set to 'top_page' or 'include'
$top_page_key_name = 'index';
# the name of the top page (not including the .html)
$top_page_section_key = 'main';
# if a section key of the above value exists
# within the top_page_key_name (above)
# then this key data will be written as 'index.html'
Multiple User Mode & Single User Mode
PageMod is set up to allow one user to have his or her own set of web pages, based on the username/directory called 'standard'. If that's all someone wants, it doesn't make sense to even display the 'Administration Menu', which is turned on by editing the 'pagemod_site.pl' file and setting the variable $show_admin_menu to 'yes'.
However, PageMod can also be used for multiple users, who all login at the pm/username url (e.g. pm/standard or pm/johnsmith). When used in this mode, all the users have their data stored under the two PageMod directory trees:
- homedirectory/pagemod
- homedirectory/www/pm
A web hosting provider can then
alias a user's pages directory to their domain web document root, e.g.
homedirectory/www/pm/johnsmith/pages could be aliases so that johnsmith.com
would show the files in the pages directory.
See the Administration Menu section about adding a new user. The display of menu items for each user is controlled by variables in their 'index.cgi' file, which is stored in their login directory, e.g: homedirectory/www/pm/johnsmith/.
Also see the Administration Menu
about PageMod's ability to share 'templates' among different users, and even
change templates on the fly.
THE
TOP MENU
The pages listed on the top menu are created on the fly based on the data hash
KEYS.
From the top menu, you can EDIT a page's sections, or VIEW the generated include
files for that page.
As an End-User, from the Top Menu you can:
See the section 'Administration Menu & Functions' for an explanation of each function.
If you're logging in via the 'standard' directory, you can access an Administration Menu, which is on the lower half of the Top Menu. If you set $show_admin_menu to 'no' in the file 'pagemod_site.pl', you won't see the Admin Menu.
If you DO see the Admin Menu, it will display all of the functions available, including the Top Menu functions that have been set to 'no' in 'index.cgi'.
ADMINISTRATION
MENU & FUNCTIONS
Some of these functions may not appear on the Top Menu, based on variables set in the index.cgi file or the pagemod_site.pl file.
EDITING
THE DATA FILE BY HAND - COMMAS ISSUE
See the section on 'Administration Menu and Functions - Modify Structure of
Pages' -- you don't have to edit the data file by hand. It's safer not to do
so. One reason to edit it by hand is if you want to change a tag or section.
The Modify Structure section only allows you to Add or Delete items.
However, you can edit the
data file by hand -- but one gotcha is that Perl saves the data file
without commas at the end of each section. It's legal to use commas at the section
ends, but Perl doesn't include them by default, because the ends are the only
place where you can omit commas.
If you copy and paste sections, or move sections around, you have to be careful
to make sure that commas are included everywhere (except the end where they're
not required -- however, I include them in the ends, to guard against errors
if I move a section). If you edit the data file and upload it and then get a
system error, it's most likely a comma problem.
THE
EDIT SCREEN
The sections and tags listed on the edit screen are created on the fly based
on the data hash KEYS.
Thus, if you change the KEYS (the 'left' side values), the display on the web
will change.
NOTE!!! Make sure that if you change the keys, you also change the TEMPLATE
NAMES!!!
Use the BROWSE buttons to find the graphic files on your machine. Note that
certain characters are NOT allowed in the file names:
- spaces
- " (double quotes)
- ` (back ticks)
- * (asterisks)
After editing, hit the SAVE key and your files will be uploaded, and your data
saved.
UPLOADED IMAGES ARE GIVEN
UNIQUE FILENAMES
Note that the graphic filename VALUES (e.g: 'index.news.1.filename.jpg') are
given prefixes based on the page and section and whether or not the tags have
a '_1' or '_2' (etc) in the tag names. That is, the original *uploaded* filename
might be 'filename.jpg' -- but the program changes the name after the upload,
so that it ensures that the filename is unique and not in conflict with a file
of the same name that belongs to another section or page. Thus, the ending filename
becomes 'index.news.1.filename.jpg'.
THUMBNAILS
OF UPLOADED IMAGES
The program utilizes a thumbnail program ('nconvert' by default) to create thumbnails
of the uploaded images. The thumbnails are used for the administrative display
of the images while editing the data -- they are NOT used in the final tag replacement.
I do this because some of the uploaded images could be very large and would
clog the edit screen.
There is a value in the setup file called:
$large_image_size
If it is set to '0', then the images will have thumbnails made of them, but
the main images will not be 'sized down'.
If the above variable is set to something other than '0', such as '300', then
the main images will be sized down to '300' (for example) pixels wide.
Note that nconvert is available
from http://www.xnview.com and is free for
non-commercial use.
DIRECTORY AND
FILE DESCRIPTIONS
The script runs by a 'stub file', that is, a small file within the web document
tree. The default name is:
/www/pm/index.cgi (this must be set to 755, or rwx-r-x-r-x)
where the 'admin' directory is in the 'www' or 'html' web document root. In
turn, this script calls the main pagemod script file 'pagemod_main.cgi' in the
pagemod directory.
Here's a detailed list of files with File/Dir Permissions and
Descriptions:
drwxr-xr-x pagemod - main pagemod dir outside the web tree pagemod: drwxr-xr-x bin - utility directory drwxr-xr-x shared_templates - shared template dir drwxrwxrwx users - user's dir -rw-r--r-- admin_menu.html - template for admin menu -rw-r--r-- error.html - template for error messages -rw-r--r-- forbid.index.html - template for Forbidden Index pages -rw-r--r-- index.template.cgi - template for index.cgi files -rw-r--r-- login.template.html - template for logging in -rw-r--r-- message.html - template for messages -rw-r--r-- pagemod.data.sample.pl - sample data file -rw-r--r-- pagemod_main.cgi - main script file -rw-r--r-- pagemod.manual.html - pagemod manual -rw-r--r-- pagemod_site.pl - setup file for pagemod -rw-r--r-- pagemod.template.cnf - template for username/password file -rw-r--r-- t1.html - template for basic screen display pagemod/bin: -rwxr-xr-x libformat.so - library for thumbnail program -rwxr-xr-x nconvert - thumbnail programNote that nconvert is available from www.xnview.com.
pagemod/shared_templates:
drwxrwxrwx basic - sample 'basic' template dir
drwxrwxrwx special - sample 'special' template dir
pagemod/shared_templates/basic:
-rw-rw-rw- index.main.template.html - sample template file
-rw-rw-rw- index.popup_text.template.html - sample template file
-rw-rw-rw- news.whats_new.template.html - sample template file
pagemod/shared_templates/special:
-rw-rw-rw- index.main.template.html - sample template file
-rw-rw-rw- index.popup_text.template.html - sample template file
-rw-rw-rw- news.whats_new.template.html - sample template file
pagemod/users:
drwxrwxrwx standard - user directory for 'standard' user
pagemod/users/standard:
drwxrwxrwx backup - standard user's backup dir
drwxrwxrwx page_templates - standard user's private template dir
drwxrwxrwx sessions - standard user's session files dir
-rw-r--r-- .pagemod.cnf - standard user's password file
-rw-rw-rw- pagemod.data.pl - standard user's data file
-rw-rw-rw- page_template_dir.pl - standard user's template dir file
(this contains a line that says
which template dir the user is using)
pagemod/users/standard/page_templates:
-rw-rw-rw- index.main.template.html - standard user's sample template file
-rw-rw-rw- index.popup_text.template.html - standard user's sample template file
-rw-rw-rw- news.whats_new.template.html - standard user's sample template file
In Your Web Document Root Directory:drwxrwxrwx pm - main pagemod dir inside the web tree pm: drwxr-xr-x pagemod_graphics - pagemod graphics for pagemod system drwxr-xr-x standard - standard user directory -rw-r--r-- index.html - Forbidden index page pm/pagemod_graphics (I won't list the individual graphic files here.) pm/standard: drwxrwxrwx pages - pages dir for generated output -rwxr-xr-x index.cgi - top 'stub' url script pm/standard/pages: drwxrwxrwx images - images dir for uploaded images -rw-rw-rw- index.html - sample generated page -rw-rw-rw- index.popup_text.html - sample generated page -rw-rw-rw- news.whats_new.html - sample generated page pm/standard/pages/images: -rw-r--r-- index.html - Forbidden index page -rw-rw-rw- index.main.1.courting.jpg - sample uploaded image -rw-rw-rw- index.main.2.true_love.jpg - sample uploaded image -rw-rw-rw- tn_index.main.1.courting.jpg - sample uploaded image -rw-rw-rw- tn_index.main.2.true_love.jpg - sample uploaded imageCOPYRIGHT