NPDS Notepad Server Syntax

By Grant Hutchinson

Contents

  1. Introduction
  2. Current SSI Tags
  3. Legacy SSI Tags
  4. Tag Syntax: notes
  5. Tag Syntax: notescount
  6. Examples
  7. Using Parameters In Custom SSI Scripts
  8. Contact Information
  9. Change History

Introduction

Starting with Notepad Server 2.103, NPDS uses a simplified, extensible set of SSI (server-side includes) tags for displaying formatted lists of notes. Legacy tags used in older versions of the Notepad Server are also supported in this version. Please note the support of legacy tags may change in future releases of this software.

Current SSI Tags

Notepad Server 2.103 and later support the following SSI tags:

<notes>
Returns a list of notes, formatted as either an unordered HTML list or an HTML table. The title of each note in the list is hyperlinked to the original note. Applying various attributes and values to the base tag, the user can specify the number of notes, the sort order, the note source, and the HTML formatting. For descriptions of available tag attributes, see: Tag Syntax: notes
<notescount>
Returns the number of notes. Applying an attribute and value to the base tag, the user can specify the source of the notes being counted. For descriptions of available tag attributes, see: Tag Syntax: notescount

Legacy SSI Tags

Notepad Server 2.102 and earlier support only the following SSI tags:

<NOTE_LIST>
Returns a chronological list of notes that have been created by the user and stored in the NPDS whiteboard folder as specified in the Notepad Server settings. This tag returns the list of notes formatted as an unordered HTML list. The title of each note in the list is hyperlinked to the original note.
<NOTE_TABLE>
Similar to the <NOTE_LIST> tag. Returns the list of notes formatted as an HTML table. The title of each note in the list is hyperlinked to the original note. The table includes columns for the note title, creation date, last modified date, and size in bytes.
<POST_LIST>
Returns a chronological list of notes that have been posted through the NPDS whiteboard functionality and stored in the whiteboard folder as specified in the Notepad Server settings. This tag returns the list of notes formatted as an unordered HTML list. The title of each note in the list is hyperlinked to the original note.
<POST_TABLE>
Similar to the <POST_LIST> tag. Returns the list of notes formatted as an HTML table. The title of each note in the list is hyperlinked to the original note. The table includes columns for the note title, creation date, last modified date, and size in bytes.
<EVERY_LIST>
Returns a chronological list of all notes that are stored in the NPDS whiteboard folder as specified in the Notepad Server settings. This tag returns the list of notes formatted as an unordered HTML list. The title of each note in the list is hyperlinked to the original note.
<EVERY_TABLE>
Similar to the <EVERY_LIST> tag. Returns the list of notes formatted as an HTML table. The title of each note in the list is hyperlinked to the original note. The table includes columns for the note title, creation date, last modified date, and size in bytes.

Tag Syntax: notes

The <notes> tag supersedes all of the aforementioned legacy tags. The main advantage of this tag is that it supports several options, specified by using attribute and value pairs. Invalid or empty attributes and values are ignored. Tag attributes are currently case insensitive, although this may change in future versions of the software. Attribute values must be enclosed in double quotes, otherwise they will be ignored.

The following tag attributes are currently supported:

type

Attribute syntax:

type="{notes|post|every}"

Value definitions:

notes
Displays notes created directly on the Newton (Default)
post
Displays notes posted via the NPDS whiteboard
every
Displays both created and posted notes

format

Attribute syntax:

format="{list|table}"

Value definitions:

list
Renders the HTML output as an unordered list (Default)
table
Renders the HTML output as a table

limit

Attribute syntax:

limit="n"

Value definitions:

n
The number of notes displayed (If omitted, all notes are displayed)

order

Attribute syntax:

order="reverse"

Value definitions:

reverse
Displays notes in reverse order, based on sortKey (See: sortKey)

sortKey

Attribute syntax:

sortKey="{timestamp|_uniqueID|<key>}"

Value definitions:

timestamp
Sorts notes based on creation date and time
_uniqueID
Sorts notes based on the unique ID associated with each note
<key>
Sorts notes on a soup index specified by <key>

About Soup Indexes

The sortKey attribute passes the indexPath as a symbol directly to the query. If the index does not exist, then the indexPath is undefined and cannot be used. By default, notes have two predefined indexes: the creation date and time (designated by the value timestamp) and the tags (designated by the value labels).

The tags index should not be confused with the Notepad Server SSI tags. Tags associated with notes are used to represent the folder that the notes are stored in. Since all notes accessible by the Notepad Server reside in the same folder, it is not very useful to sort using the tags index. In fact, attempting to use sortKey="labels" will cause an “Invalid index description” error.

It is possible to sort notes by title or modification time stamp if you add the proper index to your notes soups.

Cf Newton Programmer’s Guide page 11-36 sqq.

Adding Indexes To The Notes Soup

To add an index for the titles of all notes in a notes soup, use the following NewtonScript snippet:

GetUnionSoup("Notes"):AddIndexXmit({structure: 'slot, path: 'title, type: 'string}, nil);

After adding the title index, notes may be sorted by using the following syntax:

<notes sortKey="title">

To add an index for the modification time stamp of all notes in a notes soup, use the following NewtonScript snippet:

GetUnionSoup("Notes"):AddIndexXmit({structure: 'slot, path: '_modTime, type: 'int}, nil);

After adding the modification time stamp index, notes may be sorted by using the following syntax:

<notes sortKey="_modTime">

Removing Indexes From The Notes Soup

To remove the title index from a notes soup, use the following NewtonScript snippet:

GetUnionSoup("Notes"):RemoveIndexXmit('title, nil);

To remove the modification time stamp index, use:

GetUnionSoup("Notes"):RemoveIndexXmit('_modTIme, nil);

Additional Information Regarding Soup Indexes

There are several important points you should be aware of before adding indexes to your notes soup.

Tag Syntax: notescount

The <notescount> tag returns the number of notes.

The following tag attributes are currently supported:

type

Attribute syntax:

type="{notes|post|every}"

Value definitions:

notes
Displays the number of notes created directly on the Newton (Default)
post
Displays the number of notes posted via the NPDS whiteboard
every
Displays the total number of created and posted notes

Examples

Legacy Tag Syntax Equivalents

<NOTE_LIST>
Equivalent to: <notes>
Equivalent to: <notes format="list">
Equivalent to: <notes format="list" type="notes">
Equivalent to: <notes type="notes">
<NOTE_TABLE>
Equivalent to: <notes format="table">
Equivalent to: <notes format="table" type="notes">
<POST_LIST>
Equivalent to: <notes type="post">
Equivalent to: <notes format="list" type="post">
<POST_TABLE>
Equivalent to: <notes format="table" type="post">
<EVERY_LIST>
Equivalent to: <notes type="every">
Equivalent to: <notes format="list" type="every">
<EVERY_TABLE>
Equivalent to: <notes format="table" type="every">

Practical Syntax Examples

To display the first 10 notes created, in list format:

<notes limit="10">

To display the last 10 notes created, in list format:

<notes limit="10" order="reverse">

To display the last 10 notes created, in table format:

<notes limit="10" order="reverse" format="table">

Displaying the last 15 posted messages, time stamped in a table.

<notes type="post" format="table" limit="15" order="reverse" sortKey="timestamp">

Using Parameters In Custom SSI Scripts

Starting with Notepad Server 2.103, parameters can be defined and implemented in custom SSI scripts. The use of parameters in custom SSI scripts requires nHTTPd 2.107 or later.

Defining Parameter Handling In User Scripts

In this example, we have defined an SSI script with an SSI tag of example_script. The basic script to handle passing of a single parameter would be similar to the following:

func(param)
		begin
		   if param and param.attributes and param.attributes.title then  
			  param.attributes.title
		   else "Default Title";
		end

The tag <example_script> alone - without any additional parameters will return the text “Default Title”. By adding a custom attribute and value pair to the SSI tag, you are able to pass the data into the script to manipulate the result. For example, the tag <example_script title="A Custom Title"> will return the text “A Custom Title”.

How The Script Works

if param checks to see if a parameter is being passed by the SSI tag. If there is no parameter being passed from the SSI tag, param evaluates as nil.

if param.attributes is required if the code is executed by previous builds of nHTTPd which doesn’t define the attributes.

if param.attributes.title tests for the presence of the title attribute.

Contact Information

To obtain help or ask questions, please subscribe to the NPDS mailing list.

This document was written by , based on release notes by .

Comments are welcome.

Change History

15 Jun 2007
Updated style sheet to use fixed page width
Changed doctype to XHTML 1.1 Strict
Added ‘Contents’ section
Fixed anchors for the ‘Introduction’ and ‘Contact Information’ sections
Revised ‘Tag Syntax’ section headings and related anchors
Changed semantic hierarchy of some of the section subheads
Corrected document title
16 Jan 2007
Changed the name of the ‘Notepad Server SSI Tags’ section to ‘Introduction’
Minor formatting changes coinciding with updates to external style sheet
Removed document draft date
Added author attribution
Added standard meta tags
Corrected misspellings
14 Dec 2006
Edited Using Parameters In Custom SSI Scripts introduction for clarity
Minor edits to section headings
Implemented rudimentary external style sheet
13 Dec 2006
Initial release