Plug-in Patterns

Patterns for Plug-in hooks.

There are two kinds of plug-in hooks. 

HookMethod
The first type of hook is called HookMethod.  It is placed at the very top of a method and is designed to let the plug-in designer completely replace the method with their own code.  This is the code that is placed at the top of the method:

a typical example might look like this

if(Plugins.HookMethod(this,"ContrFamily.gridPat_CellDoubleClick",PatCur)){ return; }

If the method has a return type instead of void, then the code would look more like this: ReturnType retVal=new ReturnType(); if(Plugins.HookMethod(this,"ClassName.MethodName",retVal,param2,param3,etc)) { return retVal; }

a typical example might look like this

Document doc=new Document(); if(Plugins.HookMethod(this,"FormRpStatement.CreateDocument",doc,pd,fam,pat,dataSet,Stmt)) { return doc; }

HookAddCode
The second type of hook is called HookAddCode.  This type of hook allows the plug-in designer to add extra code in at some point without disturbing any existing code.  These are typically added at the end of form constructors to allow adding controls to a form, adding events to existing controls, etc. 

This is the code that is placed in the main program:

a typical example might look like this

Plugins.HookAddCode(this,"ContrAccount.InitializeOnStartup_end");

Parameters
The first parameter of a hook is always the sending form or class.  It may be null if the sending method is static.  Any changes to the sender from within the plug-in code will affect the the original sending form or class.

Subsequent parameters are passed in as objects.   The object types and positions are not checked at compile time, and errors are instead found by testing.  Because they are all passed in as objects, all value types are boxed.  Value types include int, bool, etc.  If the plug-in attempts to alter the value of a value type variable, the new value will not be reflected in the main program.  In contrast, if the value of a reference type is altered in the plug-in, then it will change the original object in the main program.  But be careful, because reinitializing a reference inside the plug-in by using the "new" keyword will cause the change to not be reflected in the main program.

For parameters that are value types and for strings, if a user wishes the changed value to persist after the hook is run, then we will need to follow this pattern:

object[] parameters={myInt,myStr}; Plugins.HookAddCode(this,"FormClaim.GetClaims_beginning", parameters); myInt=(int)parameters[0]; myStr=(string)parameters[1];

Steps to Add a Hook
(for our programmers)

1. Determine which of the above two hook types is needed.
2. Locate the position in the code where it is needed and paste in a stub from above.
3. Fill out a preliminary hook name.
4. If it is a HookAddCode, determine a good name for the locationdescription portion of the hook name.  Right click on HookAddCode, and Find All References.  Pick a locationdescription that is the same as or similar to other locationdescriptions used.
5. Determine which parameters to pass in. Study the Parameters section of Plugins.  Since a reference to 'this' is already passed in, no public class-level fields will need to be passed in.  If a class field is private and not part of Controls, then you will need to pass it in.  Rarely, the field can be made public (must get approval from Jordan).
6. Using feedback from the requesting developer, it is ok to make changes to the hook if not too much time has passed.
7. If enhancing an old existing hook, it's ok to add more parameters, but not to remove existing parameters if at all possible.
8. Backport to the beta version, but never to the stable version.
9. It is not necessary to make an entry in the bug list.