Using Stacks

In order to maintain separation between your local resources and the global framework resources there are two storage locations for stack files.

This concept permits your stacks to extend native stacks in system/stacks if you simply need to add some functionality to an existing stack. Or you can even replace native stacks just by placing identically named versions in your application/stacks folder.

In summary:

You can create entirely new stacks.
You can extend native stacks.
You can replace native stacks.

The page below explains the details.

Storage

Your stacks should be placed within your application/stacks folder, as this is where revIgniter will look for them when they are initialized. revIgniter stacks are located at system/stacks.

Naming Conventions

The stack name can be titelcase, lowercase, camelcase or pascalcase.
The stack name can include underscores.
The stack name should not include hyphens.

The Stack File

If your stack expects configuration data on load, your stack should have this basic prototype, that is the following code is optional:

Note: It is not mandatory to modify your existing stacks that you may have inherited from other platforms in any way, as long as the stacks in question do not need to be configured on load like other revIgniter libraries. If you don't add the following code the part used for debugging is automatically added by revIgniter using a behavior.

Stack script:

# LOGGING
on libraryStack
  rigLogMessage "debug", "Stack" && the short name of me && "Loaded"
end libraryStack

# RUN INITIAL CONFIGURATION PROCEDURES.
command rigRunInitial<StacknameWithoutExtension>StackConfig pConfig
  if pConfig is not an array then
    if pConfig is not empty then
      split pConfig using numtochar(1) and numtochar(2)
    end if
  end if

  if pConfig is an array then
    --Do something with pConfig.
  end if
end rigRunInitial<StacknameWithoutExtension>StackConfig

Replace "<StacknameWithoutExtension>" with the file name of your stack. Don't use the stack name.

Card script:

# LOGGING
on openStack
  if the environment <> "development" then
    rigLogMessage "debug", "Stack" && the short name of this stack && "Loaded"
  end if
end openStack

Using Your Stack

From within any of your Controller handlers you can initialize your stack using the standard:

rigLoadStack "Somestack"

Where Somestack is the file name, without the ".rev" / ".livecode" file extension.

Once loaded you can access the handlers of your stack.

Passing Parameters When Initializing Your Stack

Note: The following applies only to stacks which include the configuration handler as outlined above.

In the stack loading handler you can dynamically pass data as an array via the second parameter and it will be passed to your stack:

put "large" into tParamsA["type"]
put "red" into tParamsA["color"]

rigLoadStack "Somestack", tParamsA

Note: You can also pass parameters stored in a config file. Simply create a config file named identically to the stack file name, add the file extension revIgniter uses (like Somestack.lc) and store it in your application/config/ folder. Note that if you dynamically pass parameters as described above, the config file option will not be available.

Replacing Native Stacks with Your Versions

Simply by naming your stack files identically to a native stack will cause revIgniter to use it instead of the native one. To use this feature you must name the file exactly the same as the native stack.

To load your stack you'll see the standard loading handler:

rigLoadStack "Nativestack"

Extending Native Stacks

If all you need to do is add some functionality to an existing stack - perhaps add a function or two - then it's overkill to replace the entire stack with your version. In this case it's better to simply extend the stack. Extending a stack is nearly identical to replacing a stack with one exception:

Your new stack name must be prefixed with MY_ (this item is configurable. See below.).

For example, to extend the native Nativestack stack you'll create a file named application/stacks/MY_Nativestack.livecode.

Loading Your Sub-stack

To load your sub-stack you'll use the standard syntax normally used. DO NOT include your prefix. For example, to load the example above, which extends the Nativestack stack, you will use:

rigLoadStack "Nativestack"

Setting Your Own Prefix

To set your own sub-stack prefix, open your application/config/config.lc file and look for this item:

put "MY_" into gConfig["sublibraryPrefix"]

Keep in mind that this setting applies to libraries too.

Your Stack and the Home Stack

To tell the engine where your stack script should sit in relation to the home stack you can use the optional third parameter. There are two options "front" and "behind". If you omit this parameter it is set to "behind".

Note: If you set the third parameter to "front" you need to make sure that the stack's name property is identical to the file name of the stack.

Note: It seems that "go stack" is currently not working properly in the server environment. As a workaround "start using" followed by "set the defaultStack" is used if you set this parameter to "front". Unfortunately this means that in this case the stack does not receive any open and preOpen messages.

revIgniter Stack Example Using the Quartam PDF Library

Let's say you want to integrate the Quartam PDF Library 1.1.5 stack (mind the version number) into revIgniter. This requires the following work steps (Note: This example assumes you name your copy of the server stack file "qrtpdflib.livecode"):

Step 1: Download the Quartam PDF Library stack from http://downloads.quartam.com/qrtpdflib_115_xplatform.zip

Step 2: Prepare a copy of the qrtpdflib.livecode stack. This involves the following:
Insert the lines below right after the license notes:

# LOGGING
on libraryStack
  rigLogMessage "debug", "Stack" && the short name of me && "Loaded";
end libraryStack

Insert the following lines right before it says "-> library handlers":

# RUN INITIAL CONFIGURATION PROCEDURES.
command rigRunInitialqrtpdflibStackConfig pConfig
  qrtPDF_ResetAll ------------------------------- this is a Quartam command!!!!!

  if pConfig is not an array then
    if pConfig is not empty then
      split pConfig using numtochar(1) and numtochar(2)
    end if
  end if

  if pConfig is an array then
    --Do something with pConfig.
  end if
end rigRunInitialqrtpdflibStackConfig

The parameter is optional. It is used to dynamically pass data to your stack on initialization.
Comment out the libraryStack handler.
Comment out the qrtPDF_InitLibrary handler. These two handlers are not needed as qrtPDF_ResetAll is called in rigRunInitialqrtpdflibStackConfig.

There are two server script blocks. Search for "START LIVECODE SERVER BLOCK". Uncomment both blocks.

Add the following code to the card script:

# LOGGING
on openStack
  if the environment <> "development" then
    rigLogMessage "debug", "Stack" && the short name of this stack && "Loaded";
  end if
end openStack

Step 3: Place the qrtpdflib.livecode stack into application/stacks, the dedicated location for your own stacks.

Step 4: Load the stack in your controller like: rigLoadStack "qrtpdflib"

Step 5: Testing and error reporting. For testing purposes you can use the scripts from qrtpdf demos. Do not load any view file.

Note: Be careful, comment out the qrtPDF_InitLibrary line in the demo scripts of Quartam.

For error reporting please see the Creating Libraries section of the User Guide.