Extensions

Stencil supports easily extending its features with code written in Java.

Simple

Since Stencil's expression language can access any Java method usually the easiest way to extend Stencil is to pass in a Java object with the methods you like to use.

	StencilEngine engine = new StencilEngine();
	
	Map<String,Object> params = new HashMap<>();
	params.put("myCustomObject", new MyCustomObject());
	
	engine.render("myTemplate.st", params);

While rendering the template then has access to any methods defined on the MyCustomObject class.

Advanced

Sometimes more advanced integration is needed or wanted. To do that you can implement one or both of the extension interfaces to handle calling and block passing. In API parlance "block passing" is known as "preparation".

Once you've implemented the interface you can simply pass the implementations into Stencil as parameters, provide them through globals.

Function Calling

	public interface Callable {
	  
	  public static final String ALL_PARAM_NAME = "*";
	
		String[] getParameterNames();
		Object call(Map<String,?> params) throws Throwable;
		
	}

Implement this interface is as easy as providing a list of parameters your extension will accept when called and providing the functionality in the call method.

NOTE: Using the ALL_PARAM_NAME will allow you to receive any and all parameters passed to the method. See Parameters for more information

Preparation

	public interface Preparable {
	  
	  public static final String ALL_BLOCK_NAME = "*";
	  public static final String UNNAMED_BLOCK_NAME = "+";
	
		String[] getBlockNames();
		Object prepare(Map<String,?> params) throws Throwable;
		
	}

Implement this interface is as easy as providing a list of blocks your extension will accept when prepared and providing the functionality in the prepare method.

NOTE: Using the ALL_PARAM_NAME will allow you to receive any and all parameters passed to the method. See Blocks for more information

NOTE: Using the UNNAMED_BLOCK_NAME will allow you to receive an unnamed block if one was passed. See Blocks for more information

Extension Methods

Stencil includes one extremely helpful that allows programmers to extend existing Java classes with new methods. This allows you to provide things like your own custom date format function for all dates and use it like it was defined in the original class.

To create an extension method you derive from the marker interface ExtensionMethods.
Extension Methods Interface

	public interface ExtensionMethods {
	}

Note that the ExtensionMethods interface does not require you to implement any specific methods. Instead you create static methods in your extending class. The type of the first parameter of the static method is the Class you wish to extend. Any other parameters are passed to the method when the template calls it.

For example, extending java.util.Date with a custom format function would look like this

	public class DateExtensions implements ExtensionMethods {
		
		public static void myFormat(java.util.Date date, String type) {
			return myFormatter.format(date, type);
		}
		
	}

Using your new extension method is the fun part. You simply call it as if it was defined on the original class.

		$aDateVal.myFormat('short');