• Current Designs |
• Archive |
• Petestack Page Assistant

Petestack Page Assistant — Draft User Help

Petestack Page Assistant is a straightforward web editor designed to build and display standards-compliant pages through the simplest of user interfaces. While it’s targeted at delivering core features with a minimum of fuss, its ability to safely integrate custom code blocks and stylesheets also makes it deceptively powerful.

Please note that this project is still very much under development (or was back in 2004–5... long since abandoned!), so this Help Page is not guaranteed to cover the latest changes.

Help Topics

• The Top Toolbar • Super-Quick Guide
• Text Items • List Items • Image Items • Layout Items • Custom Items
• Tag Parsing • Separating or Escaping Tags • Font Control
• Fluid Layouts and Design Issues
• Save/Restore • Session Tools

The Top Toolbar

• The Select menu and button currently offer the choice of five content types (text, list, image, layout, custom) as well as the save/restore and session tools.
• The Move menus and button allow you to move items to new positions.
• The Edit menu and button allow you to reload items for editing.
• The Delete menu and button allow you to delete items.
• The Recover button enables you to recover deleted items from the current ‘session’, even after adding new items.

Super-Quick Guide

• To see the Text option in action, simply select ‘Text’, type or paste some text into the window and hit ‘Add to Page’ (no other settings are required, but all can be added/amended later by editing).
• To see the List option in action, simply select ‘List’, type or paste some text into the window, mark the start and finish of each list item with ‘##’ and hit ‘Add to Page’ (no other settings are required, but all can be added/amended later by editing).
• To see the Image option in action, simply select ‘Image’ and hit ‘Add to Page’ (no other settings are required, but all can be added/amended later by editing).
• To see the Layout option in action, simply select ‘Layout’ and hit ‘Add to Page’ (no other settings are required, but all can be added/amended later by editing).
• To use the Custom option you need a valid Admin Key, but you can see how the integration works by looking at the sub-menus from the departmental templates.
• To use the Save/Restore facility you need to be logged in with a valid username and password.
• To see the Session Tools in action, simply try them out (but note that ‘Destroy Session?’ means what it says).

Text Items

• The left-hand menu sets the text type and currently offers headings (four levels), paragraph, block quotation and preformatted text.
• Contextual (mouseover) help is provided for all options in bold.
• Text types should be selected strictly according to their purpose. So big, bold paragraphs pressed into service as headings (or vice versa) might convey one message on screen, but they send a very different one to (for example) a blind person with a voice browser!
• While all text items have been given a configurable bottom margin, this feature has been included mainly with minor headings in mind.
• The size, alignment and colour options affect how the text is displayed on the page, but not the underlying structure.
• The colour option supports both named colours and 6-figure hexadecimal colour codes (for which many helpful guides can be found by searching the web).
• Text alignment is not currently supported for block quotations, but might be offered in future.
• The limitations of font control for all web pages are outlined separately below.
• While preformatted text can be resized and coloured, it is immune to alignment, font control and tag parsing (described separately below).
• Anchors can be added for sub-page links. Their IDs should be restricted to letters, numbers, hyphens and underscores (maximum 20 characters) and be unique within the current page.

List Items

• The left-hand menu sets the list type and offers nine options.
• Contextual (mouseover) help is provided for all options in bold.
• The size and colour options are described under Text Items above.
• Text alignment is not currently supported for lists, but might be offered in future.
• Configurable bottom margins are not currently planned for lists.
• Note that line breaks are allowed within ##items## but not outside them. So you can space ##items## like this:
  

      ##Item 1
  
      ##
      ##Item 2##

  But not this:
  

      ##Item 1##
  
      ##Item 2##

• Nesting lists are not currently supported, but might be implemented at some stage.
• Anchors and IDs are described under Text Items above.
• Tag parsing is described separately below.

Image Items

• The image dialogue might look complicated, but almost everything in it is optional.
• Contextual (mouseover) help is provided for all options in bold.
• The image location is the URL (address) of the image. While images can be tested from any webspace, no images should be ‘hotlinked’ from other sites without the consent of the owner(s) and all images used should be uploaded to the site before the page is published.
• The blank image provided (blank.png) can be used for mocking up page layouts.
• All images should be in .gif, .jpg or .png format, suitably sized and optimised for the web.
• ‘Clear all’ breaks (described under Layout Items below) prevent the page content from wrapping round left or right-aligned images.
• Image width and height are optional, but both (in pixels) or neither should be specified.
  • Specifying image dimensions is good because this creates placeholders for the images while the other content loads (important for users with slower connections).
  • Using image dimensions to resize images on the fly is generally bad because it results in poorer quality images, but recommended for mocking up layouts with the ‘blank’ image provided.
• Alternate text describes the image for those who can’t see it and should not be assumed to provide the mouseover tooltips wrongly implemented by some browsers.
  • Blank alternate text is recommended for purely decorative images.
  • Alternate text for linked images should describe the target of the link.
• Anchors and IDs are described under Text Items above.
• ‘Make Image Link?’ hyperlinks the image to the URL specified in the target field.

Layout Items

• The layout options currently comprise horizontal rules and two line break types as described under the ‘Layout’ dialogue.

Custom Items

• Custom items are briefly described under the ‘Custom’ dialogue and cannot be created or edited without a valid admin key.
• While there is really no limit to what can be accomplished with this facility, two examples might be:
  • Tables (such as the simple departmental sub-menus or more complicated school calendar), which aren’t currently planned as a core feature of the Page Assistant.
  • Forms (as demonstrated by every drop-down, radio button, checkbox and text entry field of the Page Assistant), which aren’t ever likely to be offered as a core feature.

Tag Parsing

• Tag parsing is probably easier tried than explained because it’s much simpler than it looks here!
• The simple tags offered by the Text and List dialogues are parsed as follows:
  • Type **bold** for bold.
  • Type %%italic%% for italic.
  • Type ^^superscript^^ for ^superscript.
  • Type __subscript__ for _subscript.
• Note that headings and sub-headings are bold by default.
• The external link tag opens a new window, respects the protocol (http, https, ftp, mailto) if specified and makes an intelligent guess (http, mailto) if not:
  • Type ~~http://www.example.org/~~ for http://www.example.org/.
  • Type ~~www.example.org~~ for www.example.org/.
  • Type ~~mailto:example@example.org~~ for mailto:example@example.org.
  • Type ~~example@example.org~~ for example@example.org.
  • Type ~~https://example.org/~~ for https://example.org/.
  • Type ~~ftp://example.org/~~ for ftp://example.org/.
• The internal link tag opens in the original window and doesn’t assume any protocol since it also needs to accommodate relative and sub-page links:
  • Type ==userHelp.php== for userHelp.php.
  • Type ==#topToolbar== for #topToolbar.
• All link types can be named (ie the text can differ from the target) by adding the pipe symbol:
  • Type ~~Link Example|http://www.example.org/~~ for Link Example.
  • Type ==Text Items|#textItems== for Text Items.
• Tags can be nested to any depth but must follow the nesting rules (ie behave like physical boxes/Russian dolls):
  • Type **%%^^bold italic superscript^^%%** for ^{bold italic superscript}.
  • Type __==Tag Parsing|#tagParsing==__ for _{Tag Parsing}.

Separating or Escaping Tags

• So you need to separate tags from text or possibly escape them altogether? Just use backslashes:
  • Type **bold*\** for bold*.
  • Type %%10%\%% for 10%.
  • Type \*\*\*\* for ****.
• But note that backslashes belonging to your text must themselves be escaped:
  • Type \\ for \.

Font Control

• Fonts displayed on web pages depend on what fonts the end user has installed, so don’t work the way you might expect if you’re used to word processing.
• It’s standard practice to specify a narrow range of commonly installed screen fonts, backed up by one of five generic families in case of unavailability.
• Since two of these generic families (cursive and fantasy) are extremely wide-ranging — and even apparently ‘safe’ choices from the other three (serif, sans-serif and monospace) may lead to unpredictable results — only the following options are offered here:
  • Sans-Serif (Verdana, sans-serif), as specified by default.
  • Serif (Georgia, serif), for when a serif font is preferred.
  • Monospace (as used for all preformatted text).
• While both Verdana and Georgia were designed for the screen and specified for their clarity, most generic alternatives appear slightly smaller for the same nominal size.

Fluid Layouts and Design Issues

• People browse with different screen resolutions and window/font sizes, so beware of assumptions that everyone sees what you see.
• While the Page Assistant toolbar should just fit into an 800 pixel wide window, pages should also be tested at higher resolutions.
• Be especially careful with images, where content that’s forced down the page at 800x600 can wrap up the side of your image(s) at higher resolutions. (So that’s fine if it’s what you want, but can otherwise be easily cured by a ‘clear all’ break.)

Save/Restore

• The current save/restore facility is skeletal and likely to be replaced by a database ‘back end’.
• Like IDs, file names should be restricted to letters, numbers, hyphens and underscores (maximum 20 characters) and will be rejected if they do not meet these criteria.

Session Tools

• Petestack Page Assistant uses simple session tracking to build and display your page, meaning that you can’t edit more than one page at once in the same browser.
• The debugging controls were included as a development aid, but left in because they list the current ‘page’ and ‘recover’ settings.
• ‘Destroy Session?’ does exactly what it says (wipes the current page and recycle bin)!
• The recoverable (deleted) items are not currently saved to files, so can’t be recovered at later sessions.

© Peter Duggan 2004–7 (feedback to webmaster@petestack.com)

Valid HTML5