External data
*************

The LOAD instruction enables the client implementer to define external data retrieval and processing code.

It can be used to:

  * Query and store data

  * Alter the menu execution flow

  * Change language

The LOAD handler
================

In the golang code, the handler of the LOAD instruction is an implementation of the resource.Resource interface.

It uses the method resource.Resource.FuncFor to return a function pointer of type resource.EntryFunc that can resolve the symbol.

The resource.Result value that it returns has the following capabilities:

  * Returned data payload (can be empty).

  * A client-defined status code.

  * A list of client-defined signal flags to set.

  * A list of client-defined signal flags to unset.

Size limits
===========

LOAD instructions include a size parameter.

This indicates the maximum byte size of the result that will be allowed.

If the returned data payload exceeds this size, execution will terminate.

"Sink" symbols
--------------

A sink is a symbol loaded with size parameter 0.

This allows the contents to expand to all remaining available space when rendering a template. See Dynamic templates for details.

Scope
=====

The result data payload is stored under the symbol key for which it was loaded. It is kept in the cache until execution ascends from the execution stack level in which it was loaded.

Consider the symbol foo loaded at node root/one/two. The symbol will still remain available in cache for e.g. node root/one/two/three, but will be freed when entering root/one.

Duplicate LOAD
--------------

If a LOAD statement with the same symbol is issued twice within the same scope, it will fail and execution will terminate.

If a LOAD statement with the same symbol is issued twice in the same node, the latter will be ignored.

For example, if LOAD is called on node foo/bar, then execution descends to foo/bar/baz before returning to foo/bar, the second time the LOAD statement is encountered in foo/bar will have no effect.

However, if LOAD is called on node foo/bar/baz, then execution ascends to foo/bar before returning to foo/bar/baz, the LOAD will be executed again.

Refreshing cache contents
=========================

The RELOAD instruction will trigger the LOAD handler again. The RELOAD instruction is bound to the same size constraint as the initial LOAD.

It is not possible for the handler code to distinguish between a LOAD and a RELOAD instruction.

Note that using RELOAD when rendering multi-page menus can have unpredictable consequences for the lateral navigation state.