2. Specifying custom spreadsheet functions
Prev | Chapter 5. Defining custom spreadsheet functions | Next

## 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 Options → Install Add-ons, select the add-on called "XMLmind XML Editor Configuration Pack" from the list and click OK.

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

Figure 5.1. 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.

Prev | Up | Next
1. Registering custom spreadsheet functions with XXE | Home | 3. Custom spreadsheet functions written in the Java™ programming language