From APID 1.0.46 onwards, you can add page item adornments. This feature is useful even you just write 'regular' InDesign scripts in ExtendScript, VBScript or AppleScript and you're not interested in writing event-driven scripts for InDesign.

Check

http://www.rorohiko.com/wordpress/?p=4

for a sample script.

This feature only works with licensed copies or demo versions of APIDToolAssistant - unlicensed, free versions beyond the trial demo period will prefix the adornments with "DEMO".

ExtendScript samples:

// Add a permanent little label "Hello" in the top left corner of a page item 'theItem'
// Label remains after document is closed and reopened
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$","Hello"); // uses dataStore

// Add a temporary little label "Hello" in the top left corner of a page item 'theItem'
// Label disappears after document is closed and reopened
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$","Hello",1); // uses tempDataStore

// The two samples above use a shorthand syntax. The next two samples do exactly the same but
// now using the 'full' syntax
// Add a permanent little label "Hello" in the top left corner of a page item 'theItem'
// Label remains after document is closed and reopened
// Uses a three-element array: label content, PNG file name (set to null), what side (1 = top)
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$",["Hello",null,1]); // uses dataStore

// Add a temporary little label "Hello" in the top left corner of a page item 'theItem'
// Label disappears after document is closed and reopened
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$",["Hello",null,1],1); // uses tempDataStore

// Next two samples show the labels at the left (side 2) and bottom (side 3) of the page item,
// and use a PNG element instead of a string
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$",[null,"myIcon.png",2]); // uses dataStore

// Next two samples show the labels at the left (side 2) and bottom (side 3) of the page item,
// and use a PNG element instead of a string
theItem.setDataStore("$ADORNMENT_com.rorohiko.kris.test1$",["Hello","myBackground.png",3],1); // uses tempDataStore


AppleScript samples:

tell application "Adobe InDesign CS3"
 set theItem to the first item of the selection
 tell theItem
   -- Add a permanent little label "Hello" in the top left corner of a page item 'theItem'
   -- Label remains after document is closed and reopened
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value "Hello"

   -- Add a temporary little label "Hello" in the top left corner of a page item 'theItem'
   -- Label disappears after document is closed and reopened
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value "Hello" with use temp data store param    
   
   -- The two samples above use a shorthand syntax. The next two samples do exactly the same but
   -- now using the 'full' syntax
   -- Add a permanent little label "Hello" in the top left corner of a page item 'theItem'
   -- Label remains after document is closed and reopened
   -- Uses a three-element array: label content, PNG file name (set to null), what side (1 = top)
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value { "Hello", null, 1 }
   
   -- Add a temporary little label "Hello" in the top left corner of a page item 'theItem'
   -- Label disappears after document is closed and reopened
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value { "Hello", null, 1 } with use temp data store param  

   -- Next two samples show the labels at the left (side 2) and bottom (side 3) of the page item,
   -- and use a PNG element instead of a string
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value { null, "myIcon.png", 2 }
   
   -- Next two samples show the labels at the left (side 2) and bottom (side 3) of the page item,
   -- and use a PNG element instead of a string
   set data store key "$ADORNMENT_com.rorohiko.kris.test1$" value { "Hello", "myBackground.png", 3 } with use temp data store param  
   
 end tell
end tell

More info about the keys and values used

ExtendScript syntax is shown, but VBScript and AppleScript syntax are analogous (see earlier samples).


theItem.setDataStore("$ADORNMENT<unique_key>$",<adornment>,useTempDataStore);


The last parameter (useTempDataStore) is optional, and defaults to 'false'.

<unique_key> should be a unique string (preferably based on your domain name, to avoid clashes with other APID developers). Adornments are a shared resource, and more than one adornment-using script might be installed. By using a unique key, clashes between multiple adornments are avoided; they will be shown concurrently.

<adornment> is either a string or an array. If it's a string, a simple label adornment is shown on top.

If it's an array it contains the following elements (all optional except for the first element):


[  <label>  , <pngfile>  , <side>  , <fillcolor> , <textcolor> , <strokecolor> ]


Only the first element (<label>) is necessary.

<label> can be null or a string

<pngfile> can be a (pathless) file name or a File object.

<side> is 1, 2, 3 or 4 (1=top,2=left,3=bottom,4=right)

the <...color> each are 3-element arrays with floating point RGB values from 0 to 1 (e.g. [1.0, 0, 0] is red)

<pngfile> can be a File object - but it's not recommended - it makes the adornment dependent on the presence of a PNG file on some absolute path.

Transporting a document to another computer would nearly certainly invalidate that path, and the adornment would not display any more.

Instead, the preferred way is to use a simple file name (without path). The corresponding PNG file can then be installed anywhere below the InDesign Application folder - APID will find it and pick it up.

If you're using .spln-based deployment, you'll simply store your PNG files together with your .spln file in some subfolder of the Plug-Ins folder.

If you're using normal InDesign scripts, you'd probably create a subfolder somewhere inside the InDesign Scripts folder, and stuff your script and your PNG files in there.

Because there's no way we can enforce or guarantee that end-users will install things the way you prefer, we've made APID oblivious to the Plug-Ins or Application folder structure - .spln files can be anywhere below the Plug-Ins folder, PNG files can be anywhere below the Application folder,... and things will still be picked up and linked up correctly.

The one drawback of such a lenient matching system is that PNG file names must be globally unique - so for widely distributed APID-based scripts or spln files, you should use a domain name or GUID-based scheme to make sure your PNG files have a unique file name.

For example, we'd use 'com.rorohiko.textexporter.ignoredframe.png' as a file name, and we'd be fairly sure no-one else would have a same-name PNG file installed anywhere under the InDesign Application folder.

Adornment entries are picked up by APID both from the dataStore and the tempDataStore - any data store entries that have a key that starts and ends with a dollar sign, and begin with $ADORNMENT are considered adornment entries.

tempDataStore entries are purposely non-persistent - this would allow you to have adornments that 'disappear' when the document is opened on a computer where your .spln is not present.

The idea is that on processing of the docLoaded event you would re-create the necessary tempDataStore entries to make your adornments display. Then on a computer where your spln is missing, the entries won't be re-created, and the adornments won't show up - which is what you'd typically want.

dataStore entries, on the other hand, are persistent - so you can create adornments that survive even if your script or .spln file is inactive or missing (as long as the APIDToolAssistant is still alive and the needed PNG files are still installed)

The resolution of PNG files is respected - if you want higher-quality adornments, you can use higher-resolution PNG files.