When we use the term "Libraries" we are normally referring to the libraries that are located in the libraries directory and described in the Library Reference of this user guide. In this case, however, we will instead describe how you can create your own libraries within your application/libraries directory in order to maintain separation between your local resources and the global framework resources.
As an added bonus, revIgniter permits your libraries to extend native libraries if you simply need to add some functionality to an existing library. Or you can even replace native libraries just by placing identically named versions in your application/libraries folder.
- You can create entirely new libraries.
- You can extend native libraries.
- You can replace native libraries.
The page below explains these concepts in detail.
Note: The Database libraries can not be extended with your own libraries. All other libraries are able to be extended.
Your libraries should be placed within your application/libraries folder, as this is where revIgniter will look for them when they are initialized.
The Library File
Libraries should have this basic prototype (Note: We are using the name someHandler purely as an example):
<?rev put gBASEPATH into gBASEPATH if gBASEPATH is "gBASEPATH" then put "No direct script access allowed." exit to top end if # LOGGING rigLogMessage "debug", "Your Library Loaded" # DECLARE LOCAL VARIABLES # PROTOTYPE OF THE FOLLOWING HANDLER NAME: rigRunInitialLibrarynameConfig command rigRunInitialYourlibConfig --Run initial configuration procedures. Don't remove this handler, even if it does nothing. end rigRunInitialYourlibConfig command someHandler end someHandler
Using Your Library
From within any of your Controller handlers you can initialize your library using the standard:
Where Somelibrary is the file name, without the ".lc" file extension. You can submit the file name capitalized or lower case. revIgniter doesn't care.
Once loaded you can access the handlers of your library.
Passing Parameters When Initializing Your Library
In the library loading handler you can dynamically pass data as an array via the second parameter and it will be passed to your library:
put "large" into tParams["type"] put "red" into tParams["color"] rigLoaderLoadLibrary "Somelibrary", tParams
If you use this feature you must set up your library to expect data:
<?rev put gBASEPATH into gBASEPATH if gBASEPATH is "gBASEPATH" then put "No direct script access allowed." exit to top end if # LOGGING rigLogMessage "debug", "Your Library Loaded" # DECLARE LOCAL VARIABLES # PROTOTYPE OF THE FOLLOWING HANDLER NAME: rigRunInitialLibrarynameConfig command rigRunInitialYourlibConfig pParams --Do something with pParams. end rigRunInitialYourlibConfig
You can also pass parameters stored in a config file. Simply create a config file named identically to the library file name 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 Libraries with Your Versions
Simply by naming your library files identically to a native library 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 library. For example, to replace the native Email library you'll create a file named application/libraries/Email.lc.
To load your library you'll see the standard loading handler:
Note: At this time the Database libraries can not be replaced with your own versions.
Extending Native Libraries
If all you need to do is add some functionality to an existing library - perhaps add a function or two - then it's overkill to replace the entire library with your version. In this case it's better to simply extend the library. Extending a library is nearly identical to replacing a library with one exception:
- Your new library name must be prefixed with MY_ (this item is configurable. See below.).
For example, to extend the native Email library you'll create a file named application/libraries/MY_Email.lc.
Loading Your Sub-library
To load your sub-library you'll use the standard syntax normally used. DO NOT include your prefix. For example, to load the example above, which extends the Email library, you will use:
Setting Your Own Prefix
To set your own sub-library 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 stacks too.
Custom Library Example Using the Quartam PDF Library
Let's say you want to integrate the Quartam PDF Library 1.1.5 (mind the version number) into revIgniter. This requires the following work steps (Note: This example assumes you name your copy of the server include file "Qrtpdflib.lc"):
Step 1: Download the Quartam PDF Library from http://downloads.quartam.com/qrtpdflib_113_xplatform.zip
Step 2: Prepare a copy of the server include file generated by qrtpdflib.livecode. This involves the following:
Name it "Qrtpdflib.lc".
Replace "<?rev" at the top of the script with:
<?rev put gBASEPATH into gBASEPATH if gBASEPATH is "gBASEPATH" then put "No direct script access allowed." exit to top end if
Insert the following lines right after the license notes:
# LOGGING rigLogMessage "debug", "Qrtpdflib Library Loaded"
Insert the following lines right before it says "--> library handlers":
command rigRunInitialQrtpdflibConfig pConfig qrtPDF_ResetAll end rigRunInitialQrtpdflibConfig
The parameter is optional and is used to change settings upon loading the library like: rigLoaderLoadLibrary "Qrtpdflib", mySettingsArray
Comment out the libraryStack handler.
Comment out the qrtPDF_InitLibrary handler. These two handlers are not needed as qrtPDF_ResetAll is called in rigRunInitialQrtpdflibConfig.
Step 3: Place the PDF library into system/application/libraries, the dedicated location for your own libraries.
Step 4: Load the PDF library in your controller like: rigLoaderLoadLibrary "Qrtpdflib"
Step 5: Testing and error reporting.
For testing purposes you can use the scripts from http://quartam.on-rev.com/qrtpdfdemos.irev
Note: Be careful, comment out the qrtPDF_InitLibrary line in the demo scripts of Quartam.
For error reporting you should use revIgniter's built in mechanism. To write qrtPDFlib errors to the error log use:
rigLogMessage "error", tError
To display qrtPDFlib errors use:
rigLogMessage "error", rigHtmlSpecialChars(tError), TRUE
Note: tError is the variable of the try catch statements of the Quartam examples.
Note: To display the result of the demo scripts don't load any view.
To store the result on disk there is a handler called qrtPDF_SaveDocument. After saving the PDF to disk you could attach it to eMails with the help of revIgniter's Email library or whatever you want.
Step 6: Have fun!