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 two 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

logMessage "debug", "Your Library Loaded"



# DECLARE LOCAL VARIABLES





# PROTOTYPE OF THE FOLLOWING HANDLER NAME: runInitialLibrarynameConfig

command runInitialYourlibConfig

    --Run initial configuration procedures. Don't remove this handler, even if it does nothing.

end runInitialYourlibConfig





command someHandler



end someHandler

Using Your Library

From within any of your Controller methods you can initialize your library using the standard:

loaderLoadLibrary "Somelibrary"

Where Somelibrary is the file name, without the ".irev" file extension. You can submit the file name capitalized or lower case. revIgniter doesn't care.

Once loaded you can access the methods 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"]



loaderLoadLibrary "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

logMessage "debug", "Your Library Loaded"



# DECLARE LOCAL VARIABLES





# PROTOTYPE OF THE FOLLOWING HANDLER NAME: runInitialLibrarynameConfig

command runInitialYourlibConfig pParams

    --Do something with pParams.

end runInitialYourlibConfig

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.irev.

To load your library you'll see the standard loading function:

loaderLoadLibrary "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.irev.

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: