Number is Even or Page is Even / Odd

/*

Determine if a passed value is even or odd

*/

//

function isEven(value){

//-------------------------------------------------------------------------

//-- I S E V E N

//-------------------------------------------------------------------------

//-- Generic: Yes. Generic JavaScript, works with all versions and is

//-- self contained -- calls nothing.

//-------------------------------------------------------------------------

//-- Purpose: Determeins if a value is even or odd. Was originally used

//-- to see if the number of a page was even (a left hand page) or

//-- odd (a right hand page).

//-------------------------------------------------------------------------

//-- Returns: true if the passed value is considered to be an even

//-- number or false otherwise. Works with all types of values.

//-------------------------------------------------------------------------

//-- Function from: http://archives.hwg.org/hwg-techniques/38CCFF2B.B763AE47@mitre.org

//-- found 2008.08.08. Source not determinable. No copyright listed.

//-------------------------------------------------------------------------

//-- Modified by: electronic publishing support

//-------------------------------------------------------------------------

//-- % is the Modulus function.

//-- %2 == 0 means divide by 2 and see if the remainder is 0

try {

return ( value%2 == 0 ) ;

}

catch (anError) {

return false ;

}

}

Useful Generic Function Documentation

Guidelines for Useful Generic Function Documentation

To be really useful, generic function documentation should contain the following items.

1. Function Name in large type
2. A declaration if it is generic to all of ExtendScript, to all of JavaScript, unique to Adobe InCopy or Adobe InDesign.
3. The function's purpose. List what the function does and why you would want to use it. This should be like a sales statement -- why should a user want to use this function.
4. What is returned and under what conditions. Note, not every function has to return things. Some really useful generic functions modify things without returning anything.
5. What other functions are called. A perfect generic function shouldn't call other functions, but, sometimes it is handy, so list what other functions will be called.
6. Function Version or Edit Date. Because functions can be updated, it is a good idea to list the date the function was written or edited each time the function has changed.
7. Copyright or usage notes.

And example of a function which such documentation standards is the Has Notes function posted recently. That function only has about 6 real lines of code but because of good documentation standards, the function is much longer. But it makes the function usable to more people because they know how and why to use it.

Comments?

Story Has Notes

/*

Determine if there are notes in a story.

*/

//

#target incopy

var aStory = app.documents[0].stories[0] ;

if ( storyNotesExists ( aStory ) )

alert ('that story has notes' ) ;

//

function storyNotesExists ( storyRef ) {

//----------------------------------------------------------------------

//-- S T O R Y N O T E S E X I S T S

//----------------------------------------------------------------------

//-- Generic: Yes for Adobe InDesign or Adobe InCopy CS2, CS3, CS4

//----------------------------------------------------------------------

//-- Purpose: To return true or false after determining if notes exist

//-- within the passed story.

//-- This is useful if you are cleaning up stories and placing

//-- undesirable text within a note. If is extremely safe to assume

//-- that any story with notes has already been edited and/or cleaned.

//----------------------------------------------------------------------

//-- Arguments: 1

//-- storyRef: A reference to a story in Adobe InDesign or Adobe InCopy

//-- this might be in the form of many things including:

//-- app.documents[0].stories[0]

//-- app.selectionp[0].parentStory

//-------------------------------------------------------------------------

//-- Calls: Nothing

//-------------------------------------------------------------------------

//-- Returns: True or false.

//-------------------------------------------------------------------------

//-- Written by: Jon S. Winters on 2009.06.20

//-- Edited: 2009.06.23

//-- eps@electronicpublishingsupport.com

//-------------------------------------------------------------------------

try {

//-- See if passed story reference has a notes collection with more

//-- zero items. If so, return true. If not, return false.

return ( storyRef.notes.length > 0 ) ;

}

catch (err) {

//-- If anything caused an error, return false. This protects us when

//-- the function was called with something other than a story.

return false ;

}

}

//

Generic ExtendScript Functions

What is a Generic ExtendScript Function?

A Generic ExtendScript Function is an ExtendScript (JavaScript for those that don't understand the difference) function that is not specific to a particular main script, but can be used in multiple scripts.

Generic ExtendScripts can be easily used in a 'Library' of script functions and called with

#include

Generic ExtendScripts can also be included in the body of scripts, and for most users, this is likely how they will be used.

A good Generic ExtendScript Function will have the following qualities:

• It is well documented. To be useful to others, they must be documented so that its use can be easily understood.
• It is self-sufficient. If additional functions are needed they are either included in the body, or are well documented in the function's header.
• Solves a unique problem and does it reliably.

This blog, ExtendScript Support, will be posting multiple Generic ExtendScript Functions and wants you to summit your functions for inclusion.