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:
;;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:
;; My custom token produced this output: <CUSTOM_FIELD_LOOP_TOKEN>
public class CustomFieldLoopToken implements IExpansionToken
public property TokenName, String
public property Description, String
mreturn "An example of a custom field loop token."
public property Validity, TokenValidity
public property TokenCase, TokenCaseMode
public method Expand, String
lambda doExpand(str, field)
;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"
mreturn TokenExpander.ExpandFieldLoopToken(tkn, template, loops, doExpand)
Copyright © 2021 Synergex International, Inc.