2. Specifying custom spreadsheet functions

The easiest way to create documents conforming to the http://www.xmlmind.com/xmleditor/schema/spreadsheet/functions schema, is to download and install the corresponding configuration. In order to do so, please use OptionsInstall Add-ons, select the add-on called "XMLmind XML Editor Configuration Pack" from the list and click OK.

After doing this, restart XXE, use FileNew and choose XMLmind XML Editor Spreadsheet Functions/List of functions.

Figure 5.1. Custom function factorial() edited in XXE using the Spreadsheet Functions configuration

Custom function factorial() edited in XXE using the Spreadsheet Functions configuration

The content model of the documents used to specify spreadsheet functions is:

<functions>
  Content: function+
</functions>

<function>
  Content: name parameters category description
           ( macro | method | runtime | intrinsic )
</function>

<name>
  Content: function name (any combination of letter, digit and _
           cannot start with digit or _)  
</name>

<parameters>
  Content: [ parameter name (any combination of letter, digit and _
             cannot start with digit) [ ?|*|+ ]? ]*
</parameters>

<category>
  Content:  non empty token
</category>

<description>
  Content:  an XHTML body (restrict yourself to
            HTML 3.2)
</description>

<macro
  xml:space = preserve
>
  Content: = definition of the function using the
             spreadsheet language
</macro>

<method>
  Content: a Java fully qualified method name
           (ASCII only)
</method>

<runtime
/>

<intrinsic
/>
name

Name of the custom spreadsheet function.

parameters

Specifies the name and the number of the formal parameters of the custom spreadsheet function.

Function factorial has a single, mandatory, formal parameter called n. Note that parameter n is referenced by its name in the specification of the macro-function (=if(n=1,1,n*factorial(n-1))).

The parameters element is as important as the ``formula'' of the custom spreadsheet function because it is used in many places. For example, it is used by the formula parser to check the number of arguments passed to functions (i.e. using factorial(3, 4) will cause the parse to report an error).

Examples:

  • For standard spreadsheet function and: boolean1 boolean2+

  • For standard spreadsheet function numbervalue: text format? locale?

  • For standard spreadsheet function sumif: nodeset test sum_nodeset?

  • For standard spreadsheet function max: value+

  • For standard spreadsheet function today: nothing at all: empty parameters element.

  • For standard spreadsheet function if: test1 value1 alternative* fallback

Without an occurrence specifier, a single argument must be passed for that parameter. Occurrence specifiers are:

?

0 or 1 argument corresponding to that parameter.

*

0 or more arguments corresponding to that parameter.

+

1 or more arguments corresponding to that parameter.

category

Category of the custom spreadsheet function.

You can use any of the predefined categories: Logical, Mathematical, Text, etc, or you can define your own categories.

This category is used by the Formula Editor.

description

Documentation in XHTML (restrict yourself to the HTML 3.2 subset) of the custom spreadsheet function.

This documentation is displayed by the Formula Editor.

macro

Specifies the custom spreadsheet function using the spreadsheet language (macro-function).

This specification must start with =.

This specification can reference the parameter names declared in the parameters sibling.

This specification can reference any other spreadsheet function, including itself (recursive macro-function).

method

Specifies the fully qualified name of the Java™ method used to implement the custom spreadsheet function.

The method name must be the name of the custom spreadsheet function, after converting it to lower case.

If the custom spreadsheet function has a name which is a reserved Java™ keyword (example: standard function char), the method name must be '_' (underscore) followed by the lower-case name of the custom spreadsheet function (example: com.xmlmind.xmleditapp.spreadsheet.FunctionLibrary._char).

More on this in next section.

runtime

Reserved to XMLmind. Do not use.

intrinsic

Reserved to XMLmind. Do not use.