Creating Libraries

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.

In summary:

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.

Storage

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:

rigLoaderLoadLibrary "Somelibrary"

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:

rigLoaderLoadLibrary "Email"

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:

rigLoaderLoadLibrary "Email"

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_115_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!