-
-Ader
TemplateEngine is a .NET class library (written in C#) for generating text output from source template and input parameters.
-It can be used in many scenarios: website page building, email generation, xml generation, source code generation, etc.
-It's idea is based on antlr stringTemplate (http://www.stringtemplate.org/), but the syntax is based on cold fusion language.
-
-
-Currently only .NET AderTemplateEngine works with .NET 2.0 only, but I have plans on making it work with .NET 1.0/1.1 and maybe Java.
-This document is for version 2.1 of the engine. You can see version 1
here.
-
-Ader TemplateEngine is released under GNU General Public License.
-
-
Here is a very simple template:
-
-Thank You for your order #order.billFirstName# #order.billLastName#.
-<br>
-Your Order Total is: #format(order.total, "C")#
-<br>
-<ad:if test="#order.shipcountry isnot "US"#">
-Your order will arrive in 2-3 weeks
-<ad:else>
-Your order will arrive in 5-7 days
-</ad:if>
-
-
-The templates can have expressions, if/elseif/else statement, foreach statement, for statement, set statement and other templates.
-
-
-
Templates API:
-There are 2 classes mainly used in Template Engine: Template and TemplateManager.
-
-Template holds a single instance of a template and TemplateManager is used for executing templates.
-
-Easiest way of creating Templates is by using static methods of Template or TemplateManager:
-
-Template template = Template.FromString(string name, string data)
-Template template = Template.FromFile(string name, string filename)
-
-then you use it to instantilate TemplateManager.
-
-TemplateManager mngr = new TemplateManager(template);
-
-or even easier:
-
-TemplateManager mngr = TemplateManager.FromFile(filename);
-TemplateManager mngr = TemplateManager.FromString(template);
-
-when using FromString method, the string passed contains template code. This method can be used
-to dynamically generate text without having templates in files.
-
-You use SetValue(string name, object value); to add values that can be used within the templates.
-
-Ex:
-
-mngr.SetValue("customer", new Customer("Tom", "Jackson"));
-
-
-then you can refer to customer within the template. You can use any type of object for value.
-When the value of variable is to be output ToString() method will be called.
-
-
-
-
- Expressions
-
-Expressions are enclosed with # (hash or pound) characters:
-
-ex.
-
-#firstName#
-
-
-This example will output value of first name. If you need to output # character, just escape it with another #.
-
-ex.
-
-Your SS## is #ssnumber#
-
-
-Inside of expression block you can output any variable:
-
-#somevar#
-
-
-access property or field of a variable:
-
-#somestring.Length#
-
-
-property name is not case senstivie. So you can call: #string.length# or #string.LENGTH#
-
-
-or call a function:
-
-#trim(somename)#
-
-You can nest property accesses:
-#customer.firstname.length#
-
-You can also call methods on any objects:
-
-#firstname.substring(0, 5)#
-
-or
-
-#customer.isValid()#
-
-Version 2.1 also allows you to use array access from indexed variables:
-#somearray[3]# - gets 3rd element of array
-#hastable["somekey"]# - gets value of "somekey" from hashtable.
-You can use array access with any object that has indexer property.
-
-
-There are several built in functions and additional functions can be easily added.
-The built in functions are:
-
-
equals(obj1, obj2) - invokes equals method on obj1 with obj2 as parameter. Returns boolean value.
-
-
-
notequals(obj1, obj2) - Returns !equals(obj1, obj2). Is equavilant to calling: not(equals(obj1, obj2))
-
-
-
iseven(num) - tests whether number is an even number
-
-
-
isodd(num) - tests whether number is an odd number
-
-
-
isempty(string) - test whether string has 0 characters. Same as equals(string.Length, 0)
-
-
-
isnotempty(string) - tests whether string has at least 1 character.
-
-
-
isnumber(num) - tests whether num is of numeric type
-
-
-
toupper(string) - converts string to upper case
-
-
-
tolower(string) - converts string to lower case
-
-
-
isdefined(varname) - tests whether variable named varname is defined
-
-
-
ifdefined(varname, value) - returns value if varname is defined. Especiall useful: #ifdefined("name", name)# - will output value of name if it's defined, otherwise will output nothing
-
-
-
len(string) - returns length of string
-
-
-
tolist(collection, property, delim) - will convert collection to string with delim as seperator. If you pass property,
- the value of the property will be evaluated on each element of collection. If you omit property, then the object itself
- will be used.
-
- Ex:
-
- suppose you have list as:
-
-
- ArrayList list = new ArrayList();
- list.Add("one");
- list.Add("two");
- list.Add("three");
- template.SetValue("mylist", list);
-
- then in your template:
-
- #toList(mylist, " & ")#
-
- the output will be: one & two & three
-
-
- suppose you have list as:
-
- list.Add(new Customer("Tom", "Whatever"));
- list.Add(new Customer("Henry", "III"));
- list.Add(new Customer("Tom", "Jackson"));
- template.SetValue("mylist", list);
-
- then in template:
-
- #toList(mylist, "firstName", ",")#
-
- the output will be: Tom,Henry,Tom
-
-
-
-
isnull(obj) - tests whether obj is null
-
-
-
not(boolvalue) - returns not (!) of boolean value
-
-
-
iif(booleanExpression, iftruevalue, iffalsevalue) - same as
- booleanExpression ? iftruevalue : iffalsevalue in C#
-
- Ex:
-
- #iif(isodd(i), "bgcolor=yellow", "bgcolor=red")#
-
- will output bgcolor=yellow if i is odd number and bgcolor=red if i is not odd number
-
-
-
-
format(object, formatstring) - will call ToString(formatstring) on object. Object has to implement
- IFormattable interface, otherwise ToString() will be called.
-
- Ex:
-
- (suppose total is decimal with value 1208.45)
-
- #format(total, "C")#
-
- will output: $1,208.45
-
-
-
-
trim(string) - will trim string object
-
-
-
-
filter(collection, booleanproperty) - will return new List from collection for those objects
- whose booleanproperty property evaluates to true
-
-
-
gt(obj1, obj2) - will return true if obj1 > obj2 (obj1 and obj2 must implement IComparable. All numeric types do)
-
-
-
lt(obj1, obj2) - will return true if obj1 < obj2 (obj1 and obj2 must implement IComparable. All numeric types do)
-
-
-
compare(obj1, obj2) - will return -1 if obj1 < obj2, 0 is obj1 == obj2, and 1 if obj1 > obj2 (obj1 and obj2 must implement IComparable. All numeric types do)
-
-
-
or(bool1, bool2) - will return true if either bool1 or bool2 are true
-
- ex:
-
- #or(equals(state, "IL"), equals(state, "NY"))# - returns true if state is either IL or NY
-
-
-
-
and(bool1, bool2) - will return true if both bool1 and bool2 are true
-
-
-
-
comparenocase(string1, string2) - will do case insenstive comparison of string1 and string2 and return true if they are equal
-
-
-
-
stripnewlines(string) - will return all \r\n instances and replace them with space
-
-
-
typeof(object) - will return string representation of the type of object. Ex: typeof("hello") return "string". typeof(3) returns int
-
-
-
cint(value) - converts value to integer (internally used Convert.ToInt32 from .net library)
-
-
-
cdouble(value) - converts value to double
-
-
-
cdate(value) - converts value to DateTime type. You can use this function if you want to create datetime objects.
-Ex: #cdate("2005-5-1")#
-
-
-
createtypereference(type) - you can use this function to create references to static types so that you can access static properties or call methods of a static object.
-It's most useful when combind with <ad:set tag (explained below)
-
-#createtypereference("System.Math").Round(3.39789)#
-#createtypereference("System.Math").PI#
-or
-<ad:set name="MyMath" value="#createtypereference("System.Math")#" />
-#MyMath.Round(3.3)#
-#MyMath.PI#
-
-
-
-Version 2.1 also adds some operators for common expressions:
-
is - same as calling function equals. Ex: #obj1 is obj2# will return true if obj1 is equal to obj2.
-
-
-
isnot - same as calling function notequals. Ex: #obj1 isnot obj2#
-
-
-
and - used in if expressions tests (same as && in C#)
-
-
-
or - same as || in c#
-
-
-
lt,
lte,
gt,
gte - less than ("<" in C#), less than or equal ("<="),
-greater than (">") and greater than or equal (">="). Both operands have to implement IComparable interface. When using numeric types, they have to be of the same type.
-If you want to compare int to double, you have to convert int to double first using cdbl function.
-
-
-#varOne lt 3#
-#varTwo lte cdbl(3)#
-#varThree gt varFour and varFive gte 5.0#
-
-
-
-
Built In Tags:
-
-
IF
-
-You can also conditionally output text based on some expression using special if tag:
-
-<ad:if test="#booleanexpression#">
-
-<ad:elseif test="#bool#">
-
-<ad:else>
-
-</ad:if>
-
-elseif and else are optional. If test of "if" evaluates to true, then block inside of "if" will be output, otherwise
-elseif will be tested (if exists) and then else.
-
-Ex:
-
-
-<ad:if test="#cust.country is "US"#">
-You are US customer.
-<ad:else>
-You are from: #cust.country# country.
-</ad:if>
-
-If cust.country is "US" then the output will be: You are US customer.
-
-
-
FOREACH
-
-You can loop through collection of elements (any object that implements IEnumerable interface) using FOREACH tag.
-
-<ad:foreach collection="#collection#" var="cust" index="i">
-#i#: #cust.lastname#, #cust.firstname#
-</ad:foreach>
-
-
-Suppose customers is array of customer objects: customers = Customer("Tom", "Jackson"), Customer("Mary", "Foo")
-
-The output will be:
-
-1. Jackson, Tom
-
-2. Foo, Mary
-
-
-During execution, variable name that is passed as var attribute will be assigned with element from the collection.
-Index attribute can be omitted, and is used to represent index variable for the loop. It starts with 1 and gets
-increments with each iteration.
-
-
-
FOR
-
-You can use FOR tab to loop through integer values by one.
-
-<ad:for from="1" to="10" index="i">
-#i#: #customers[i].name#
-</ad:for>
-
-
-
-
SET
-
-Set tag allows you to set values based on other expressions:
-<ad:set name="var" value="#someexpression#" />
-After set statement is executed you can use var as if it was a local variable.
-It might be useful when accessing complex object values.
-Instead of writing:
-#customers[i].address.firstname# #customers[i].address.lastname# #customers[i].address.address1#
-You can do:
-lt;ad:set name="add" value="#customers[i].address#" />
-#add.firstname# #add.lastname# #add.address1#
-
-It's especially useful with createtypereference function (see above)
-
-
-
Custom Templates:
-
-You can also create your own templates inside of template file that you can call.
-You do that using template tag:
-
-<ad:template name="ShowCustomer">
-#customer.lastname#, #customer.firstname#
-</ad:template>
-
-<ad:showcustomer customer="#cust#" />
-
-You can pass any attributes to the template, and you can use those inside of the template.
-The template can also access all variables that are defined outside of the template.
-When calling template you have to put trailing slash at the end, or put closing tag:
-
-<ad:showcustomer />
-
-or
-
-<ad:showcustomer></ad:showcustomer>
-
-
-The template also received special variable: innerText that is the content of executing the inner elements of calling template.
-
-<ad:template name="bold">
-<b>#innerText#</b>
-</ad:template>
-
-<ad:bold>#cust.lastname#, #cust.firstname#</ad:bold>
-
-the output will be:
-<b>Jackson, Tom</b>
-(if customer is Tom Jackson)
-
-
-You can also nest those:
-
-<ad:template name="italic">#innerText#</ad:template>
-
-<ad:bold><ad:italic>This will be bold and italic</ad:italic></ad:bold>
-
-
-You can also invoke templates based on the name using apply tag:
-
-<ad:apply template="#usetemplate#">this is content</ad:apply>
-
-If usetemplate is "bold" then "bold" template will be called.
-
-
-Templates can be nested inside other template:
-
-<ad:template name="doit">
- <ad:template name="colorme">
- <font color=#color#>#innerText#</font>
- </ad:template>
-
-<ad:colorme color="blue">colorize me</ad:colorme>
-</ad:template>
-
-colorme template can only be used within doit template.
-
-Templates can also be added programmatically:
-
-TemplateManager mngr = ...;
-mngr.AddTemplate(Template.FromString("bold", "<b>#innerText#</b>"));
-
-now bold template can be used anywhere within processing.
-
-
-Version 2.0 adds ability to create custom tags in C# (or any .net language) that can extend the TemplateManager with additional functionality.
-Together with the sources is Example 2 which includes 2 custom tags
email for sending email and
base64 for base64 encoding content.
-
-Once those tags are registered with TemplateManger you can call them like:
-
-<ad:email from="andrew@adersoftware.com" to="someuser@example.com" subject="Hello" server="127.0.0.1">
-Hello #customer.firstname# #customer.lastname#
-</ad:email>
-
-
-Version 2 also added ITemplateHandler interface for better interaction with template execution. You can than set templateManager's Handler property to a handler,
-and this handler will be called before and after manager is done processing the template. This handler is also available as
this object, and you can access
-any property or call methods of the handler from within the template. Example 2 includes "MyHandler.cs" as an example on how to use it.
-
-
--------------------------
-Here is a sample based on order confirmation.
-
-
-class Order
-{
- string firstname, lastname, address1, city, state, zip, country;
-
- public string Address1
- {
- get { return this.address1; }
- }
-
- public string City
- {
- get { return this.city; }
- }
-
- public string Country
- {
- get { return this.country; }
- }
-
- public string Firstname
- {
- get { return this.firstname; }
- }
-
- public string Lastname
- {
- get { return this.lastname; }
- }
-
- public string State
- {
- get { return this.state; }
- }
-
- public string Zip
- {
- get { return this.zip; }
- }
-}
-
-Order order = GetOrder();
-TemplateManager mngr = TemplateManager.FromFile("order-confirmation.st");
-mngr.SetValue("order", order);
-System.IO.StringWriter writer = new System.IO.StringWriter();
-mngr.Process(writer);
-
-string emailBody = writer.ToString();
-
--------------------------------------------
-
-order-confirmation.st
-
--------------------------------------------
-
-
-<ad:showitem>
-#item.sku# - #item.name#<br>
-<ad:if test="#equals(item.qty, 1)#">
-Price: #format(item.price, "C")#<br>
-<ad:else>
-You bought #item.qty# items for #format(item.price, "C")#
- (total: #format(item.total, "C")#)
-</ad:if>
-</ad:showitem>
-
-#order.firstname# #order.lastname#<br>
-#order.address1#<br>
-<ad:if test="#isnotempty(order.address2)#">#order.address2#<br></ad:if>
-#order.city#, #order.zip# #order.state#
-<br>
-<table>
-<ad:foreach collection="#order.orderitems#" var="orderitem" index="i">
-<tr>
- <td>#i#.</td>
- <td bgcolor="#iif(isodd(i), "##DEDEDE", "white")#">
- <ad:showitem item="#orderitem#" />
- </td>
-</tr>
-</ad:foreach>
-</table>
-Shipping: #format(order.shipping, "C")#<br>
-Taxes: #format(order.tax, "C")#<br>
-Order Total: #format(order.total, "C")#<br>
-
---------------------------------------------
-
-Description of order-confirmation.st
-
-First showitem template is defined which shows a single line item of the order.
-item is passed as attribute to showitem.
-
-Then address is shown. Note how if is used to conditionally display second line of address with ending <br> tag.
-
-Then each line item of order is looped through using ad:forech tag.
-iif function is used to color everyother line with #DEDEDE color.
-
-
---------------------------------------------------
-
-Example #2 for constructing complex SQL queries:
-
---------------------------------------------------
-
-
-string[] cols = new string[]{"id", "name", "email"};
-TemplateManager mngr = TemplateManager.FromFile(file);
-mngr.SetValue("colums", cols);
-mngr.SetValue("tablename", "customer");
-string query = mngr.Process();
-
-and the template file is:
-
-
-select #toList(columns, ",")# from #tablename#
-
-
-
----------------------------------
-
-Example 1 project has 2 sample templates that are used to process the same data.
-First it outputs it as a C# class to the screen, then it uses html template to create
-html file.
-
-There are more examples in the includes source code distribution. Look at directories: Example 1, Example 2 and Tester.
-
-If you have any questions, you can use AderTemplates forums at
-
http://www.adersoftware.com/adertools/
-
-
-
Download Source Code (440KB)
-- includes full source code for the library, example program and simple GUI for testing templates.
-Solution is for VS2005 beta 2.
-
-
-Download Library Only (18KB)
-- includes only dll for library. Works with .NET 2.0 only.
-