Writing Custom Expansion Tokens

CodeGen supports the ability for developers to define custom expansion tokens by writing plug-in modules to provide 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 Expansion Tokens

Custom expansion tokens are implemented as classes in a class library assembly. To implement custom 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 token 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 expansion token must implement the interface CodeGen.Engine.IExpansionToken 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 expansion 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 token processors in a separate solution.

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

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

namespace CustomExtensionsExample

;;To implement a custom expansion token you must provide a class that
;;implements the CodeGen.Engine.IExpansionToken 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.
;;
;;This token can be used in field loops, like this:
;;
;;                    <FIELD_LOOP>
;;                    My custom token produced this output: <CUSTOM_FIELD_LOOP_TOKEN>
;;                    </FIELD_LOOP>
;;

public class CustomFieldLoopToken implements IExpansionToken

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

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

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

    public property TokenCase, TokenCaseMode
      method get
      proc
        mreturn TokenCaseMode.UppercaseOnly
      endmethod
    endproperty

    public method Expand, String
      tkn, @Token
      template, @FileNode
      loops, @IEnumerable<LoopNode>
      endparams
    proc

      lambda doExpand(str, field)
      begin
        ;TODO: Add any code you need here, and return the string
        ;that is to be used to replace the token.
        mreturn "This is the output from CUSTOM_FIELD_LOOP_TOKEN"
      end

mreturn TokenExpander.ExpandFieldLoopToken(tkn, template, loops, doExpand)

endmethod

endclass

endnamespace