plugin

Extra plug-in services, such as setting variables.

Types#Back to top

VariableSetter#Back to top

The VariableSetter class is a helper to set multiple variables at once. It should be somewhat faster than repeated calls to set_variable().

Initialization#Back to top

VariableSetter()
Parameters

This constructor takes no parameters.

Result and side effects

This constructor creates and returns a new instance of VariableSetter.

add()#Back to top

Add a name-value pair:

VariableSetter.add(name, value[, repetition=1])
Parameters
nametext, valid FileMaker variable name

Name of the FileMaker variable.

valueany supported type

Variable value. Use None or empty text to clear the variable.

repetitionnumber, positive integer

Optional variable repetition number, by default 1.

Result and side effects

The method adds the name-value pair to the setter, but does not set it just yet. The method returns no result.

Discussion

The method won't complain if you specify the same variable-repetition pair more than once. Internally it will add them all to a list of variables in the order of appearance and then set in the same order, so in the end the variable will be set to the last supplied value.

clear()#Back to top

Clear all stored name-value pairs without setting them:

clear()
Parameters

The method takes no parameters.

Result and side effects

The method clears all accumulated name-value pairs without setting these variables. The method returns no result.

Discussion

This method is optional; VariableSetter instances call it automatically when they are deleted.

set()#Back to top

Set the accumulated variables:

set()
Parameters

The method takes no parameters.

Result and side effects

The method sets all the accumulated variables in a single call to evaluate() and then clears them up. The method returns no result.

Global functions#Back to top

add_to_cache()#Back to top

Add one or more objects to a temporary cache to be retrieved with PyPop.

add_to_cache(*objects) -> (int, int, ...)
Parameters
objectsany supported type

Objects to add to the cache. It's OK to use volatile objects as long as you make sure to use them during this function call. It is also OK to use Python types; PyPop() will automatically convert them into corresponding FileMaker types.

Result and side effects

The function adds the passed objects to a temporary cache to got them later from FileMaker with PyPop. For each object the function returns a numeric ID to use with PyPop().

Discussion

FileMaker API assumes a plug-in is to provide a function that returns a single result or, perhaps, uses the SQL API. This is not always convenient. It would be much more handy if a plug-in could set a variable, for example. (Imagine returning lots of data directly into script variables. .) You can do this with evaluate(), but the expression is evaluated as text, so you cannot use rich FileMaker types like formatted text or container. And the SQL API, albeit powerful, does not fully support containers. You can retrieve a container with execute_sql_2(), but you cannot insert or update container.

PyFM comes with a set of Python and FileMaker functions to cross this bridge. It has a cache to store objects in numbered slots, a function to add objects to the cache from within Python and a FileMaker function to retrieve an object from this cache by its slot number: PyPop.

For example, assume we have a container:

>>> from filemaker import Container, evaluate
>>> c = Container(FILE='abc def ghi', FNAM='abc.txt')

Now let's set a FileMaker variable to this container:

>>> from plugin import add_to_cache
>>> i = add_to_cache(c)
>>> evaluate('Let( $myvar = PyPop( %d ); "" )' % i)

As you see we first add the container to the cache and get back the slot numbers and then immediately evaluate an expression that calls PyPop() with this number. PyPop() returns the container as it is, so $myvar is set to the container.

Note that we get back a tuple of numbers, not a single number. In our case its OK, because we can use it with the % operator just fine. But if you need the number itself, you'll have to unpack the tuple:

>>> i, = add_to_cache(v)

You don't need to go through all this if you simply need to set a variable; all this code has been written already and neatly packed into a set_variable() function and VariableSetter class (the latter is more convenient if you need to set lots of variables). But you'll need it to set container fields via SQL.

Normally you cannot set containers via SQL; even the modern execute_sql_2(), which accepts and returns native FileMaker types simply ignores container data in INSERT or UPDATE statements. But you can set a container to a text value (this is how you set it to a reference to a field, by the way). And with PyPop() you can use this to fetch the real container.

There is no generic way, you have to prepare the FileMaker table for this. Change the auto-enter calculation for the container to be that:

PyPop( GetAsNumber( GetAsText( Self ) )

This way if you insert a slot number via the SQL API, it will automatically fetch the actual container with PyPop.

This may be sufficient if you fill the table only through SQL; if not, you'll probably need a more robust formula here. For example, you might first check if the value looks like a number and if not, leave it as is:

If( Filter( Self, '0123456789' ) = Self;
  PyPop( GetAsText( GetAsNumber( Self ) ) );
/* else */
  Self )

I'd also recommend you to always remove the values afterwards with remove_from_cache().

path()#Back to top

Return the path to the main plug-in modules directory:

path() -> unicode
Parameters

The function takes no parameters.

Result and side effects

The function returns the path to the main plug-in modules directory. The function has no side effects.

remove_from_cache()#Back to top

Remove an object from the temporary cache used by PyPop:

remove_from_cache(*indices)
Parameters
indicesnumbers

Numeric slot indices received from preious calls to add_to_cache().

Result and side effects

The function removes the specified objects from cache. The function does not raise errors if the objects are not there. The function returns no result.

Discussion

The function is optional, but may be necessary for solid programming or to handle errors. Normally an object is removed from cache as soon as PyPop fetches it into FileMaker. But if there is an error, the code may not call PyPop() at all or maybe not call it for all the added objects, so the objects will stay in the cache.

Technically it should not cause problems except wasting memory to store objects that are not going to be retrieved. At shutdown the plug-in empties the cache anyway. But just in case you might want to add an extra code to make sure all the objects are gone, like this:

from plugin import add_to_cache, remove_from_cache
i = add_to_cache('some value')
try:
    ...
finally:
    remove_from_cache(*i)

Here even if something went wrong in the try block, the finally will always make sure to clean the cache.

set_variable()#Back to top

Set a FileMaker variable:

set_variable(name, value[, repetition=1)
Parameters
nametext, valid FileMaker variable name

Name of the variable to set. Must be a valid FileMaker variable name.

valueany supported type

Value to set the variable to.

repetitionnumber

Optional repetition number, by default 1.

Result and side effects

The function sets the specified variable to the passed value. The function returns no result.

Discission

To set multiple variables use VariableSetter. See also add_to_cache(), remove_from_cache(), and PyPop to understand how this works.

version()#Back to top

Return the plug-in version as a four-element tuple:

version() -> (major, minor, micro, build)
Parameters

The function takes no parameters.

Result and side effects

The function returns the plug-in version as a four-element tuple. The function has no side effects.