==== finaleplugin properties  ====

This page contains a detailed description of the ''finaleplugin'' properties that can be set in the plugindef() function. Normally these values are set by using the //Plug-in Def// dialog box in //JW Lua//.

=== RequireSelection (boolean) ===

If this is set to ''true'', the script will not execute if a selection region isn't available for the current document. Instead, a user alert will display with information that the user should first select a region. Example: <code lua>finaleplugin.RequireSelection = true</code>

=== RequireScore (boolean) ===

If this is set to ''true'', the script will not execute if a part is viewed for the current document. Instead, a user alert will display with information that the user should first switch to the score view. Example: <code lua>finaleplugin.RequireScore = true</code>

=== NoStore (boolean) ===

If this is set to ''true'', the script will run in "sandbox mode". After the script has run, any saves made to Finale's database are automatically rolled back, so such a script will never do any permanent edits to a document. This might be useful for example when creatin diagnostic scripts, or during development to check that the script syntax will work. Example: <code lua>finaleplugin.NoStore = true</code>

=== Author (string) ===

The full name of the author. Example: <code lua>finaleplugin.Author = "John Smith"</code>

=== Copyright (string) ===

One-line copyright string. Example: <code lua>finaleplugin.Copyright = "Copyright (c) John Smith, 2013"</code>

=== Version (string or number) ===

The version number of the current plug-in. Examples: <code lua>finaleplugin.Version = 1.01</code>
or
<code lua>finaleplugin.Version = "1.5.2"</code>
or
<code lua>finaleplugin.Version = "1.01, build 14"</code>

=== CategoryTags (string) ===

The tags that would categorize the plug-in script. Each tag is separated by a spaces and/or commas, and each category name is case insensitive and can contain the characters a-z only. A category name is used to filter the scripts that should be displayed in a //JW Lua// file folder (which helps the user to organize the scripts based on each script's functionality). The categories in the table below are considered to be "standard categories" and should be used whenever possible:

^ Tag   ^ Description ^
| Articulation | Affects character or shape articulations. |
| Chord | Affects chords. |
| Debug | Debug-only tasks for developers. |
| Development | Tasks aimed at script development. |
| Diagnose | Diagnostics tasks. |
| Expression | Affects text or shape expressions. |
| Layout | Layout tasks. |
| Lyric | Affects lyrics. |
| Measure | Affects measures (such as measure attributes). |
| MIDI | Affects MIDI data. |
| Note | Affects notes entries. |
| Page | Affects pages. |
| Percussion | Affects percussion notation. |
| Playback | Affects playback. |
| Pitch | Affects note pitches. |
| Region | Tasks that require region selections. |
| Rest | Affects rests. |
| Report | Report-only tasks. |
| Smartshape | Affects smart shapes. |
| Staff | Affects staves. |
| System | Affects staff systems. | 
| Tempo | Affects tempo (notated or playback). |
| Test | Plug-ins for test purposes. |
| Text | Affects text blocks. |
| UI | Contains a user interface. |

Example: <code lua>finaleplugin.CategoryTags = "Page, Layout"</code>

=== Date (string) ===

The release date (in any text format). Example: <code lua>finaleplugin.Date = "July 28, 2013"</code>

=== Notes (multiline string) ===

Longer description of the plug-in and user instructions. The string can contain multiple lines. Example: <code lua>finaleplugin.Notes = [[
This plug-in hides all rests in the selected region.
Select the region before running the plug-in.
]]</code> 

=== RevisionNotes (multiline string) ===

Revision history text that might be of interest to an end user. The string can contain multiple lines. Example: <code lua>finaleplugin.RevisionNotes = [[
July 26, 2013: Version 1.00
July 28, 2013: Version 1.01 
]]</code>

=== AuthorURL (string) ===

An URL to the script's home page. Example:  <code lua>finaleplugin.AuthorURL = "http://www.theurl.com"</code>

=== AuthorEmail (string) ===

The contact e-mail to the author. Example: <code lua>finaleplugin.AuthorEmail = "john.smith@theurl.com"</code>

=== Id (string) ===

A unique identifier that is specific to the plug-in. This is required if the plug-in should be shared through the //JW Lua// repository. The id is case insenitive and can contain the characters ''abcdefghijklmnopqrstuvwxyz0123456789_.-''. Suggested identifiers are a //author.pluginname// syntax, or a true GUID. Examples:
<code lua>finaleplugin.Id = "johnsmith.hiderests"</code>
or
<code lua>finaleplugin.Id = "742d0ea0-c109-4b81-87ae-d059f27cb028"</code> 

=== ParameterTypes (multiline string) ===

The types to the script parameters. The syntax is similar to the ''SetTypes()'' method when using [[jwlua:uservalueinput|UserInputValue dialog input]]. Use one line for each parameter. Don't use quotation marks around the types. The number of types must be identical to the number of descriptions.

Valid types are ''Number'', ''String'', ''Boolean'' and ''NumberedList''. Example:
<code lua>finaleplugin.ParameterTypes = [[
Number
Boolean
]]</code>

=== ParameterDescriptions (multiline string) ===

The syntax is similar to the ''SetDescriptions()'' method when using [[jwlua:uservalueinput|UserInputValue dialog input]]. Use one line for each parameter. Don't put quotation marks around the descriptions. The number of descriptions must be identical to the number of types. Example:
<code lua>finaleplugin.ParameterDecriptions = [[
Resize (in percent)
Resize relative
]]</code>

=== ParameterLists (multiline string) ===

The syntax is similar to the ''SetLists()'' method when using [[jwlua:uservalueinput|UserInputValue dialog input]]. These settings are optional for script parameters. Use one line for each parameter, but __don't__ put ''{}'' around the list. If a list isn't required for a parameter, set it to ''nil''. If a comma is needed within a list item, quotation marks can be used around that list item. Example:
<code lua>finaleplugin.ParameterLists = [[
nil
Yes, No
]]</code>

=== ParameterInitValues (multiline string) ===

The syntax is similar to the ''SetInitValues()'' method when using [[jwlua:uservalueinput|UserInputValue dialog input]]. These settings are optional for script parameters. Use one line for each parameter. If a user value isn't required for a parameter, set it to ''nil''. Example:
<code lua>finaleplugin.ParameterInitValues = [[
nil
true
]]</code>