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.
- You can create entirely new stacks.
- You can extend native stacks.
- You can replace native stacks.
The page below explains the details.
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.
- 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.
# 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.
# 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:
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:
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:
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.