EditTag User Manual

EditTag User's Manual

v1.2 © Greg Billock

1.0 Introduction

EditTag is a package of scripts which enable website management. The scripts allow for definitions of editable portions of regular HTML pages which can then be edited through a web interface by those with the proper permissions and passwords. EditTag is suitable for easy maintenance of contact information, headlines, template updating, collaborative publishing, and more.

EditTag is an enhancement of the functionality of PointEdit. The EditTag scripts render the page on which changes are made to the HTML file using the surrounding content of the page. In consequence, an EditTag-enabled page will have its edit screen look very similar to its public appearance. EditTag's functionality allows for:

single-line edit fields
multi-line edit fields
edit fields with options (SELECTs)
editing of arbitrary tag attributes (e.g. the BORDER, BGCOLOR, etc. of a TABLE tag)
user specification of a prompt for the edit field
user specification of the attributes of the HTML form element used to edit the field (its width/height)
user specification of prompt placement

Since the EditTag package uses multiple scripts, its installation is more flexible, providing a variety of options for the user. It can be installed in password-protected areas on a site, and not make use of its own password system, or be installed publically and require passwords itself. EditTag can recognize passwords stored securely in the HTML documents themselves, and so passwords can be assigned on a file-by-file basis.

When to use EditTag

EditTag is not intended as a template language. If you find yourself wishing for variable substitution, conditionals and loops, you should consider using a language such as PHP, which will allow for complete control over the document. EditTag is intended for use to separate the bulk of page layout from editing more dynamic content within the page. EditTag-enabled documents can provide administrators with no knowledge of HTML a great deal of control over the content, and even appearance, of a document, while shielding the bulk of the layout from any accidental errors which would disable the page.

2.0 Installation

This section will describe how to install EditTag on a system in two configurations: a protected installation which uses HTTP authentication to protect script access, and an installation which will utilize EditTag passwords.

Choosing and configuring directories for a protected installation

For a protected installation, you will use the HTTP password authentication provided by many web servers (such as Apache) to provide security for EditTag. Choose a directory in which to install EditTag and create it on your server. You'll then need to password protect the directory. Doing this may vary quite a bit depending on your server setup. If you are using an ISP, they likely have tools which you can use to password-protect the directory. If you are running your own Apache server, you can use the sample htaccess and htpasswd files in the EditTag distribution on which to model your own. You'll need to use the htpasswd -c /local/path/to/directory username command to add passwords (or you can use Perl or a number of other tools). In this case, you'll install all the scripts to the same (password protected) directory, and not use any EditTag passwords (documented below).

Choosing and configuring directories for a public installation

For a public installation of EditTag, you don't need to worry about creating access or password files; you can use the EditTag built-in password system to control editing access to your files. Choose a directory on your web server to hold EditTag, and make sure that directory exists and you can execute CGI scripts from it. Depending on your server, this may restrict you to a cgi-bin directory, or a mod_perl-specified directory, or you may have more freedom in the selection.

Steps to follow for all installations

Verify System Requirements
Discover what file extension Perl scripts need in order to inter-operate with the web server.
Rename the script files to follow this convention (i.e. if Perl CGI scripts on the server must have the extension ".pl" then rename "edittag.cgi" to "edittag.pl", "parsescript.cgi" to "parsescript.pl", "mkpw.cgi" to "mkpw.pl".
If you are using a UNIX or Linux operating system, find the path to Perl 5 on the server. This should be documented somewhere in your ISP's documentation pages, or, if you are running your own server or can telnet to the server, typing which perl will get you the full path to the command. If you are using Windows NT, you do not need to worry about specifying the path to Perl. If you are using the Apache web server with mod_perl, you don't need this path, but you will need to know the perl alias directory for mod_perl.
Change the first line of the scripts to reflect the path to Perl 5. The line that looks like: #!/usr/bin/perl needs to be changed to look like #!/the/path/to/perl5/on/your/system ....that. If you are running a webserver on Windows NT or with mod_perl, this may not be necessary. It will not hurt the script if you do it anyway, so if you are not sure, go ahead and make the change.
Look in "edittag.cgi" and "parsescript.cgi" in the "Administration Configuration Section" (right at the top). There you will find some variables that you can customize to enhance the operation of the package. You can change these as follows:

EditTag.cgi

$parse_url : this variable need to be set to the full URL of wherever you plan to put the parsing script in your directory structure. (Case sensitive!)
$table_props : this variable should be set to an HTML TABLE tag which the script will use when rendering the edit boxes. The script ships using a light gray background and no visible cell borders. If you are happy with this look, don't change this option. If you would like to customize the look, substitute in another TABLE tag. Be sure it has no quotation marks ("), though!

ParseScript.cgi

$mailnotification : if you would like email notification when edits are made to EditTag files, put something non-zero ("1" is suggested) in this variable. The script ships with email notification turned off, so if this is how you plan to use it, don't worry about any of the options in this file.
$MAILPROG : this is the path to your sendmail (or replacement) program. You can find this path in the same fashion as you found the path to Perl above. If you are using Windows NT, there may be a program installed called blat which you need to find. (Case sensitive! If you are using Windows NT and Blat, remember to use double-back-slashes in your path, i.e. "C:\\blat\\blat.exe")
$fromaddress : this is the address from which notification email will appear to originate. Since it doesn't really matter, you don't really need to change it. If you are using email notification, though, errors may come to this address, so it is preferable to set it to something real, such as the webmaster address for your site. Caution: the address must be specified using an escape before the @, like this: "you\@site.com".
$filedates : this is a parameter which tells the system to use either filenames generated from the date (if set to 1) or random filenames (if set to 0). These filenames are generated for you when you put a directory as the target of an editable file in the EDITTAGDEST parameter.

Upload script files to the directories you chose as conforming to a protected or public installation (or copy them into the public space). You must make sure to do this in ASCII mode!
Change permissions on the files. The scripts all need to have execute permissions set so that the web server can execute them. On UNIX or Linux systems, this may vary depending on the permissions the web server runs with, and whether it executes scripts as directory owner or not. The scripts also need to have read and write permissions to the files and directories which will be edited. If the server is using "suexec" probably no changes are needed. If not, then granting read-write permissions to the group or to "all" may be required. On Windows NT, granting permissions to the user under which the web server executes should be sufficient.
Test. The script ships with some test files which should show if there are any problems.
Create customized EditTag-enabled HTML documents (make sure these have the necessary permissions, passwords, etc.!)
Enjoy!

3.0 Operation

Operation of the EditTag script should be very intuitive. Select a file to edit (either by the interface which ships with the package or through one of your own construction) and the screen should be fairly easy to use. If a password is required, it will be requested at the very bottom of the edit screen.

To EditTag-enable your HTML documents, you include special extension tags to those documents which let EditTag know what you want to do.

Control tags

<EDITTAGPWD z98rGjLyQ11bN>

The EDITTAGPWD command sets a password for this file. The argument is an encrypted password, which can be generated using the "mkpw.cgi" script included in the package. The password is one-way encrypted, so its appearance in the public HTML document does not give a viewer the ability to guess the password. As for any other password, use fairly long passwords (around 8 characters) which aren't dictionary words or easily guessed; include letters, numbers, other symbols. If this tag is not present, EditTag will not require a password to edit the file. This can be the desirable action, if the EditTag scripts are placed in a protected directory, which requires a password to browse. Using the ability of EditTag to create files in a directory, there are applications of EditTag (such as collecting user comments) in which it may be desirable to allow public access to a particular file. This is up to you as the user to determine.

<EDITTAGMAIL someone@somewhere.com>

This tag specifies the receiver for email notification when the page is edited by someone. In order for email to be sent, this tag must be present in the file, and email notification must be turned on in the EditTag scripts (see above) during installation.

<EDITTAGSRC /the/path/to/this/file.html>

Specifies the source path for the document. This may be necessary if the EditTag scripts are located in an out-of-the-ordinary place, or if the renderer and parser script are in different directories. If it is not present, the scripts will deduce the source path from the pathname passed to them to open the file for edit.

<EDITTAGDEST /the/path/to/the/destinationfile.html>

Specifies the destination path for the edited document. This is where the file will be written incorporating any edits. If not specified, the scripts will assume that the destination for the edits is the same as the source file: that is, any edits will be written back to the original file. If a directory is specified here (leave the trailing slash to specify a directory), the script will create a new file in that directory and write the edited file to it. This can be used to let an administrator review "page submissions" from users, by specifying a password-protected directory as the destination and then renaming the submitted files to a public directory after approval.

<EDITTAGURL http://www.somewhere.com/path/destinationfile.html>

This tag specifies a URL for the destination file. This is to make the output of the edit parser easier to use: it will make a link to the edited version so that changes can be inspected, and also mail the URL if notification is used. If a directory is used in the EDITTAGDEST file, leave the URL specified a directory as well (i.e. "http://www.somewhere.com/a/directory/") and the chosen unique filename will be spliced on to send as notification and present to the user.

Editable Field Tags

<EDITTAG TYPE=type WIDTH=l HEIGHT=s NAME=name PROMPT=prompt POS=pos TABLE=yes TRANSLATE=no>
Some default content
</EDITTAG>

This is the main EditTag field tag, which specifies an editable field, options for how its edit box will be rendered, and its present value. Since browsers do not know the <EDITTAG> and </EDITTAG> tags, they will suppress them, and all users will see is the present content of the field, whatever it is. Each EDITTAG field must occur on its own line in the input file. Options to this tag are as follows:

TYPE = {line|area|select}

default = line

WIDTH=[number]

default = 40

In a line context, this indicates how large the edit box will be. In an area context, indicates how wide the edit box will be. In a select context, does nothing.

HEIGHT=[number]

default = 3

In a line context, does nothing. In an area context, sets the height of the edit box. In a select context, sets whether the select will be single line or multi-line, and how many lines will show.

NAME=token name

required

This identifier must be unique for every field in the EditTag document. An additional restriction is that no identifier must be equal to the prompt used for the tag edit prompt (see below). This is the name that EditTag gives internally to each field.

PROMPT=prompt string

no default

An optional prompt to use for the user when rendering the edit page.

POS={top|left|right}

default = left (position of prompt)

Where to place the prompt in relation to the edit field. Illustrated here with PROMPT="Enter title:"

TABLE={yes|no}

default = yes

This tag sets whether or not to use the PROMPT, POS attributes and utilize a table to control the appearance of the edit field, or just render the edit field (as above) with no prompt, and in-line with the surrounding text. It can be useful when the surrounding text or in-file labels are sufficient to identify the field, and can yield a more WYSIWYG look to the resulting edit page.

TRANSLATE={yes|no}

default = no

Controls whether or not HTML translation is done for this field. If the option is YES, EditTag will translate any double line-feeds to the <P> HTML tag, which causes a paragraph break in HTML. This is useful in the AREA context, and for page editors who may not know HTML.

<ANYTAG label="value" label2="value2" EDITTAG="Insert (unique) prompt here">

This use of EDITTAG is as an argument to another tag. Since the browser does not know the meaning of the EDITTAG label in the context of any tags, its presence will be ignored. This tag must be used on its own line in the source file. When EditTag processes the file, it will produce an editable field which looks something like this:

<EDITTAGOPTION option>

This tag is used in conjuction with the <EDITTAG TYPE="select"> command. It specifies the options that will appear in the HTML form select element on the edit page. The currently-selected option comes outside any tags, so the whole statement might look like this:

<EDITTAG NAME=sel1 HEIGHT=1 PROMPT="Make selection">
<EDITTAGOPTION option number one>
<EDITTAGOPTION option number two>
<EDITTAGOPTION option three>
option number two
</EDITTAG>

<EDITTAGQUIET> and </EDITTAGQUIET>

These tags will stop the EditTag input screen from showing any output between the QUIET tags. That is, the normal "WYSIWYG" output is suppressed. This is a good thing if other tags on the target page are interfering with the tables that EditTag constructs for input. If you only wanted to see the prompts, you can enclose must of the file in QUIET tags and then only prompts will be displayed on the input screen.

Again, the browser doesn't know any of these tags, so the only thing visible to the surfer visiting the public page is the currently selected option: "option number two". These tags must be used on their own lines in the source file.

For examples of how to use the tags in more realistic situations, and to see the results on the visible pages, inspect the HTML source for the test files.

4.0 System Requirements and Manifest

System Requirements

Web server capable of running Perl CGI scripts.
Perl 5 or higher.
(for private installation) Web server capable of performing HTTP authentication.

Manifest

edittag.cgi - script which generates the editing page for view
parsescript.cgi - script to record edits
mkpw.cgi - script to generate EditTag passwords for files
index.html - a sample "front page" interface to the script package which gives a couple of ways to edit a file and access to the password generator
test.html - a test page which should work with the EditTag installation
htaccess.sample - sample .htaccess file for a protected installation
htpasswd.sample - sample .htpasswd file for a protected installation
edittag.html - this user's manual
edittag.txt - text user's manual

February 4, 2001

Prompt shows here
label1:
label2: