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.

Naming Conventions

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

The Library File

Libraries are script only stacks and should have this basic prototype (Note: We are using the name someHandler purely as an example):

script "Library_Name"


global gRigA

local sStackInUse


on libraryStack
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target = the short name of me then
    if sStackInUse <> TRUE then
      put TRUE into sStackInUse

      # LOGGING
      if the environment is "server" then
        rigLogMessage "debug", "Library_Name Library Loaded"
      end if
      
      # SET INITIAL VALUES OF THE LIBRARY VARIABLES
      _rigSetDefaultValues
      #
    end if -- if sStackInUse <> TRUE
    
  else
    pass libraryStack
  end if -- if the short name of the target = the short name of me
end libraryStack



# SET INITIAL VALUES
private command _rigSetDefaultValues
  -- your code here
end _rigSetDefaultValues



# PROTOTYPE OF THE FOLLOWING HANDLER NAME: rigRunInitial[name of your library]Config
command rigRunInitial[name of your library]Config
  --Run initial configuration procedures. Don't remove this handler, even if it does nothing.
end rigRunInitial[name of your library]Config


command someHandler
  -- your code here
end someHandler

Note: All revIgniter script only stack files use "livecodescript" as file extension. This convention you should keep in mind when you build models, libraries, helpers etc.

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 ".livecodescript" file extension.

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 tParamsA["type"]
put "red" into tParamsA["color"]

rigLoaderLoadLibrary "Somelibrary", tParamsA

If you use this feature you must set up your initialization handler to expect data:

# PROTOTYPE OF THE FOLLOWING HANDLER NAME: rigRunInitial[name of your library]Config
command rigRunInitial[name of your library]Config pParamsA
  if pParamsA is not an array then
    if pParamsA is not empty then
      split pParamsA using numToCodepoint(1) and numToCodepoint(2)
    end if
  end if
	
  if pParamsA is an array then
    -- do something with pParamsA
  end if
end rigRunInitial[name of your library]Config

Note: 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.livecodescript.

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 handler 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.livecodescript.

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.

Library Getter and Setter

To be able to access native library script variables in your sub-library most libraries provide a getter function and a setter command.
The prototype for the getter function is: rig<Libraryname>Get(pWhat). The prototype for the setter command is: rig<Libraryname>Set pKey pVal.
So, for example to access the Formvalidation library variables you can use the handlers rigFormvalidationGet pWhat and rigFormvalidationSet pKey pVal.

Note: All values you can set or get are combined in one array variable.

Extending Native Libraries Example

Let's say you would like to add validation rules to the Formvalidation library. To achieve this the process is as follows:

Step1: Check the getter or setter handler in the Formvalidation library which reveals the required array variable name. In this case this is sFormValidA.
Note: These handlers are always at the bottom of the script. The _rigSetDefaultValues handler tells you that the validation rules are stored in sFormValidA["ruleNames"]. This is the information you need to extend the list of available validation rules.

Step 2: Create a file named MY_Formvalidation.livecodescript in application/libraries.

Step 3: Add your code to extend the validation rules list using the library getter and setter. Your code may look like the following example.

script "MY_Formvalidation"


global gRigA

local sStackInUse



on libraryStack
  local tRuleNames
  
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target = the short name of me then 
    if sStackInUse <> TRUE then
      put TRUE into sStackInUse
      
      # LOGGING
      if the environment is "server" then
        rigLogMessage "debug", "MY_Formvalidation Library Loaded"
      end if
    
      # EXTEND THE VALIDATION RULES LIST USING THE GETTER AND SETTER OF THE NATIVE LIBRARY
      put rigFormvalidationGet("ruleNames") & ",validPasswordR,validRoleR,validNHSpasswordR" into tRuleNames
      rigFormvalidationSet "ruleNames", tRuleNames
      #
    end if
    
  else
    pass libraryStack
  end if -- if the short name of the target = the short name of me
end libraryStack




# ADD YOUR CUSTOM VALIDATION RULES
command rigValidPasswordR pStr
  local tRegEx
  
  put "^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[\p{P}]).{8,40}$" into tRegEx
  return matchText(pStr, tRegEx)
end rigValidPasswordR



command rigValidRoleR pStr
  local tRegEx
  
  put "^((?!initialRole).)*$" into tRegEx
  return matchText(pStr, tRegEx)
end rigValidRoleR



command rigValidNHSpasswordR pStr
  local tRegEx
  
  put "^.+(@nhs\.net)$" into tRegEx
  return matchText(pStr, tRegEx)
end rigValidNHSpasswordR

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 Quartam PDF Library server include file "Qrtpdflib.livecodescript"):

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.livecodescript".
Replace "<?rev" at the top of the script with:

script "Qrtpdflib"

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

global gRigA

local sStackInUse


on libraryStack
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target = the short name of me then
    if sStackInUse <> TRUE then
      put TRUE into sStackInUse

      # LOGGING
      if the environment is "server" then
        rigLogMessage "debug", "Qrtpdflib Library Loaded"
      end if
    end if -- if sStackInUse <> TRUE
    
  else
    pass libraryStack
  end if -- if the short name of the target = the short name of me
end libraryStack


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