Writing Custom Expression Tokens

CodeGen supports the ability for developers to define custom expression tokens by writing plug-in modules to provide the logic associated with those tokens. This plug-in mechanism is implemented in a way that does not require developers to edit the core CodeGen source files. This is important because it means that it will not impede the ability to download future source code updates to the core CodeGen environment.

Writing Custom Expression Tokens

Custom expression tokens are implemented as classes in a class library assembly. To implement custom expression tokens a developer creates a class library assembly containing one or more extension classes, and simply drops the library into the main CodeGen folder alongside the other CodeGen assemblies.

If you prefer to have your custom extensions loaded from a different location then you can set the environment variable CODEGEN_EXTDIR to the location of the custom token extensions assembly.

When CodeGen loads it will check for any custom token assemblies, and if it finds any it will dynamically load them. In order to achieve this a naming convention is used. The name of any custom extensions assembly must begin with the word "custom". For example you might chose to create an assembly named CustomTokens.dll.

Each class that implements a custom expression token must implement the interface CodeGen.Engine.IExpressionToken which can be accessed by adding a reference to the CodeGenEngine.dll assembly.

Source Code Example

The CodeGen source code package includes a sample project called CustomExtensionsExample which contains examples of implementing all of the various types of custom expression tokens. This project is configured not to build when you build the main solution, because it is intended to only be an example. Developers are encouraged to develop their custom expression processors in a separate solution.

The code below shows an example of a custom field loop expression token:

import System
import System.Collections.Generic
import CodeGen.Engine
import CodeGen.RepositoryAPI

namespace CustomExtensionsExample

;;To implement a custom expression you must build a class that implements the
;;CodeGen.Engine.IExpressionToken interface. The class MUST have a default constructor.
;;By default classes have an implicit default constructor, but if you need to
;;explicitly define a constructor, make sure you don't define any parameters.
;;
;;You can use this expression in field loops, like this:
;;
;; <FIELD_LOOP>
;; If you see YES then the expression evaluated to true: <IF CUSTOM_FIELD_LOOP_EXPRESSION>YES</IF>
;; </FIELD_LOOP>
;;

public class CustomFieldLoopExpression implements IExpressionToken

    public property TokenName, String
      method get
      proc
        mreturn "CUSTOM_FIELD_LOOP_EXPRESSION"
      endmethod
    endproperty

    public property Description, String
      method get
      proc
        mreturn "An example of a custom field loop expression."
      endmethod
    endproperty

    public property Validity, TokenValidity
      method get
      proc
        mreturn TokenValidity.FieldLoop
      endmethod
    endproperty

    public method Evaluate, Boolean
      tkn, @Token
      template, @FileNode
      loops, @IEnumerable<LoopNode>
      endparams
    proc

      lambda doEvaluate(str, field, index)
      begin
        ;TODO: Add code here to determine the result of the expression, and return true or false
        mreturn true
      end

mreturn ExpressionEvaluator.EvaluateFieldLoopExpression(tkn, template, loops, doEvaluate)

endmethod

endclass

endnamespace