Adding a Page

Webpage editors offer dozens of ways to start creating a page. One simple way is to copy an existing page, change its name, and revise/replace the contents. To preserve the Pictool-ness of the page, you should only edit between pairs InstanceBeginEditable name="sectionname" and InstanceEndEditable. Editing with DreamWeaver will enforce this. To follow the rule when editing otherwise will preserve the option of fallling back to DreamWeaver.

The first thing to do to your new page is edit the "HeadAdditions" area to define a page title. Find the line with

$sp->setprop("page.maintitle", " . . . "); 

remove the leading "//", if any, and change "from server" to a proper title for the page. This title will appear in the browser tab and atop the page itself.

Next replace the contents in the "BodyCell" with the page's content.

Styles

The appearance of your site can be profoundly affected by choice of styles: colors, borders, fonts, etc. The general approach is to provide a class for each tag to be styled. For instance, the header for this section is:

<h4 class="pdoc-subhead">Styles</h4>

Styles for pdoc-subhead item, or any other tag or class can then be specified as described in stylesoverview. Style elements can be specified in the file's header, in a local .css file, in styles.css in the same directory or any parent directory, or GeneralStyles.css. (If in a local xxx.css file, that file must be linked in from the header: <link href="xxx.css" rel="stylesheet" type="text/css" />.)   For Pictools documentation, styles are in /pictools/doc/pdocStyles.css.

Images

Images help alleviate the tedium of unending text. They should illustrate a point in the text. (Bad example to the right.) The image can be in the same directory as the .php file or in an images/ sub directory (or anywhere else). I recommend relative addresses for simple cases where the image is in the current directory, its parent, or one of its descendants; otherwise use absolute addresses as in the image to the right. Irregular image shapes are touched on in MakingLogos.

Properties

Properties are set for a page with setprop as shown above for page.maintitle. The most useful of the defined properties are prefetchlist and the layout properties. Set the prefetchlist property to ensure instant reaction as the mouse rolls over buttons. Set the page layout properties to replace the default contents of the areas around the "body" cell that has your page contents. To make properties apply to an entire subtree of pages, set them in file Pictools.properties in the root of the tree.

Downloads

Normally when a file is sent to a browser, the browser "renders" it to make it visible for viewing. Some types of files like spreadsheets or word documents are instead downloaded and saved on the client machine for access by other processers. It  may be that you want to have downloaded a file that would normally be rendered. To do so, write a link to /scripts/download.php passing a query string to indicate the file. The query is like this

/scripts/download.php?dir=site-relative-directory&file=file-name

To be elligible for download, some files must be listed in the downloadable property in the file's directory. See properties.php:downloadable for details.

Scripts to run on the server

Common content for multiple files can be relegated to .php scripts. In Pictools, one simple way to do this is to define localdefs.php in a directory. It will be included in each page of that directory.

Although called a "php" file, such a file is actually HTML text with optional embedded php sections. Php code must be surrounded with the markers <?php and ?>. For instance to interpolate the value of a property in page text, the incantation is

<?php echo $sp->getprop("property-name"); ?>

The $sp variable is predeclared (by Siteprops as called by beginpage). To use it inside a function, it must be declared global at the beginning of that function:

function fff(xxx) {
    global $sp;
    ...
}

More generally, a script from anywhere on the site can be included with calls in PHP code.

$sp->inclood("xxx.php");

Here xxx.php is a site-rooted path to a php file. To use $sp, it must be declared global at the top of the file and at the top of every function that needs it.

Scripts to run on the browser

To provide an interactive experience for the user, scripts must be run on the user's browser. The usual tool is JavaScript, but Adobe Flash is also possible.  Both are beyond the scope of this document. Examples of Javascript can be found in these files /pictools/debugMore.js, /hotspots.js, /library/framekeys.js, /library/slideshowdefs.js, /scripts.js, /annals/2007/ToTheBetterEnd/livingwills.php, /annals/2013/AlaskaBlog/index.php, /index.php, /library/displayCode.html, and /library/slidescontrol.php

Debugging

A. Makefiles and shell scripts on the site development machine. The environment variable PICTOOLSDEBUG, when set to a small integer, will cause the Makefile and some scripts to send notes to /tmp/pictoolsdebug.txt. Value 1 produces visitation notes. Values over 4 will additionally dump all environment variable.

B. Php code on the server. SiteProps (which is included in all pages derived from the PhyspicsMain template) defines php_debug. When the site administrator (identified by cookie) visits a page that contains a call on this macro

php_debug("note");

the note will be appended to file /admin/logs/debug.txt on the host server. I have defined the alias ldb on my server to provide instant access to that file:

alias ldb less /home/physpics/physpics.com/admin/logs/debug.txt

C. Javascript code on a client machine. To debug javascript code, Pictools offers a separate window displaying a sequence of debug messages. Calls to dbgmsg in javascript code will append lines to the debug window:

dbgmsg("this will appear in the debug window");

The debug window is opened in a browser as pictools.com/pictools/debuglog.php; if the user has the proper admin cookie, the dbgmsg values will appear in the window. See debuglog.php for details.

Creating a sub-tree of pages

1. Create a subdirectory in the source platform tree as a descendant of the directory denoted by SRCROOT (See directories).

2. Create a minimal Makefile in the new directory. Its contents should be:

include $(PICTOOLS)/MakeVars
include $(PICTOOLS)/MakeTargets

3. Add the name of the directory to the SUBDIRS line in the Makefile of the parent directory.

Optional files for the new directory

index.php

This is the default file that is opened if the user browses to the directory without giving a file name.

images/

If the files will use a lot of images, they can be put in a subdirectory. The name images is by convention and has no signifigance. It can be useful to add Makefiles as noted above; however, I myself use DreamHost's PUT to get the images to the server. I recommend using .png images.

styles.css

Create style.css if you want a set of styles for the pages in this directory and its children. If you want styles just for this directory, add a .css file with another name and link it from the head of each file:

<link href="XXxstyles.css" rel="stylesheet" type="text/css"/>

(No such link is needed for styles.css; it is linked automatically by Pictools.)

localdefs.php

If it exists, this file is automatically included at the start of each Pictools page. It is a reasonable place to define php functions for pages in the directory.