Freemarker自定义标签配置流程

       在这里通过JEECMS所使用的架构来描述Freemarker自定义标签配置流程，以@cms_content_list为例来说明，在一个HTML中引用标签的实例代码如下：

       <div class="rmht-list">
           [@cms_content_list typeId='2' count='5' orderBy='9' channelId='75' channelOption='0']
             [#list tag_list as a]
          <div [#if a_index<1]class="item first"[#else]class="item"[/#if]>
            <a href="${a.url}" target="_blank" class="title">[@text_cut s=a.title len='19' append='...' /]</a>
            [#if a_index<1]<div class="first-des clearfix"><a href="${a.url}" target="_blank"><img src="${a.typeImg!}"></a><span>[@text_cut s=a.description! len='34' append='...' /]</span></div>[/#if]
          </div>
          [/#list]
   [/@cms_content_list]
        </div>

为了能够使用上面的标签我们只需要做如下三个步骤就能实现：

1.定义实现此标签功能的Class

自定义标签需要实现TemplateDirectiveModel这个接口中的execute方法  实例代码如下：

package com.jeecms.cms.action.directive;

import static com.jeecms.cms.Constants.TPL_STYLE_LIST;
import static com.jeecms.cms.Constants.TPL_SUFFIX;
import static com.jeecms.common.web.Constants.UTF8;
import static com.jeecms.common.web.freemarker.DirectiveUtils.OUT_LIST;
import static com.jeecms.core.web.util.FrontUtils.PARAM_STYLE_LIST;

import java.io.IOException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.apache.commons.lang.StringUtils;

import com.jeecms.cms.action.directive.abs.AbstractContentDirective;
import com.jeecms.cms.entity.main.Content;
import com.jeecms.common.web.freemarker.DefaultObjectWrapperBuilderFactory;
import com.jeecms.common.web.freemarker.DirectiveUtils;
import com.jeecms.common.web.freemarker.ParamsRequiredException;
import com.jeecms.common.web.freemarker.DirectiveUtils.InvokeType;
import com.jeecms.core.entity.CmsSite;
import com.jeecms.core.web.util.FrontUtils;

import freemarker.core.Environment;
import freemarker.template.TemplateDirectiveBody;
import freemarker.template.TemplateException;
import freemarker.template.TemplateModel;

/**
 * 内容列表标签
 */
public class ContentListDirective extends AbstractContentDirective {
	/**
	 * 模板名称
	 */
	public static final String TPL_NAME = "content_list";

	/**
	 * 输入参数，文章ID。允许多个文章ID，用","分开。排斥其他所有筛选参数。
	 */
	public static final String PARAM_IDS = "ids";

	@SuppressWarnings("unchecked")
	public void execute(Environment env, Map params, TemplateModel[] loopVars,
			TemplateDirectiveBody body) throws TemplateException, IOException {
		CmsSite site = FrontUtils.getSite(env);
		List<Content> list = getList(params, env);

		Map<String, TemplateModel> paramWrap = new HashMap<String, TemplateModel>(
				params);
		paramWrap.put(OUT_LIST, DefaultObjectWrapperBuilderFactory.getDefaultObjectWrapper().wrap(list));
		Map<String, TemplateModel> origMap = DirectiveUtils
				.addParamsToVariable(env, paramWrap);
		InvokeType type = DirectiveUtils.getInvokeType(params);
		String listStyle = DirectiveUtils.getString(PARAM_STYLE_LIST, params);
		if (InvokeType.sysDefined == type) {
			if (StringUtils.isBlank(listStyle)) {
				throw new ParamsRequiredException(PARAM_STYLE_LIST);
			}
			env.include(TPL_STYLE_LIST + listStyle + TPL_SUFFIX, UTF8, true);
		} else if (InvokeType.userDefined == type) {
			if (StringUtils.isBlank(listStyle)) {
				throw new ParamsRequiredException(PARAM_STYLE_LIST);
			}
			FrontUtils.includeTpl(TPL_STYLE_LIST, site, env);
		} else if (InvokeType.custom == type) {
			FrontUtils.includeTpl(TPL_NAME, site, params, env);
		} else if (InvokeType.body == type) {
			body.render(env.getOut());
		} else {
			throw new RuntimeException("invoke type not handled: " + type);
		}
		DirectiveUtils.removeParamsFromVariable(env, paramWrap, origMap);
	}

	@SuppressWarnings("unchecked")
	protected List<Content> getList(Map<String, TemplateModel> params,
			Environment env) throws TemplateException {
		Integer[] ids = DirectiveUtils.getIntArray(PARAM_IDS, params);
		if (ids != null) {
			return contentMng.getListByIdsForTag(ids, getOrderBy(params));
		} else {
			return (List<Content>) super.getData(params, env);
		}
	}

	@Override
	protected boolean isPage() {
		return false;
	}
}

2.把类进行Spring中注册，形成Spring Bean

    在JEECMS中，所有的标签类都是在jeecms-context.xml中进行注册的，注册代码如下：

<bean id="cms_pagination" class="com.jeecms.cms.action.directive.PaginationDirective"/>

 3.将spring bean 配置到freemarkerConfig全局变量中去

  FreemarkerConfig是Freemarker的一个全局变量配置，便于Freemarker能够通过标签查找到标签实现类，在JEECMS中，FreemarkerConfig Bean配置在jeecms-servlet-front.xml文件中，如代码所示：

	<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
		<!--获取标签配置-->
		<property name="freemarkerVariables" value="#{propertyUtils.getBeanMap('directive.')}"/>
		<property name="templateLoaderPath" value=""/>
		<property name="freemarkerSettings">
			<props>
				<prop key="tag_syntax">auto_detect</prop>
				<prop key="template_update_delay">5</prop>
				<prop key="defaultEncoding">UTF-8</prop>
				<prop key="url_escaping_charset">UTF-8</prop>
				<prop key="locale">zh_CN</prop>
				<prop key="boolean_format">true,false</prop>
				<prop key="datetime_format">yyyy-MM-dd HH:mm:ss</prop>
				<prop key="date_format">yyyy-MM-dd</prop>
				<prop key="time_format">HH:mm:ss</prop>
				<prop key="number_format">0.######</prop>
				<prop key="whitespace_stripping">true</prop>
				<!--空值处理<prop key="classic_compatible">true</prop>-->
				<prop key="auto_import">/WEB-INF/ftl/jeecms/index.ftl as p,/WEB-INF/ftl/spring.ftl as s</prop>
			</props>
		</property>
	</bean>

而对于配置文件中有一属性FreemarkerVariables是用来配置自定义标签的实现类，通过情况下是这样配置的，如下面代码 ：

<span style="font-size:12px;"><bean id="freemarkerConfig2"
        class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
        <property name="templateLoaderPath" value="/" />
        <property name="freemarkerVariables">
            <map >
                <entry key="userListDirective" value="userListTag" />
            </map>
        </property>
        <property name="freemarkerSettings">
            <props>
                <prop key="template_update_delay">0</prop>
                <prop key="defaultEncoding">UTF-8</prop>
                <prop key="url_escaping_charset">UTF-8</prop>
                <prop key="locale">zh_CN</prop>
                <prop key="boolean_format">true,false</prop>
                <prop key="datetime_format">yyyy-MM-dd HH:mm:ss</prop>
                <prop key="date_format">yyyy-MM-dd</prop>
                <prop key="time_format">HH:mm:ss</prop>
                <prop key="number_format">0.######</prop>
                <prop key="whitespace_stripping">true</prop>
            </props>
        </property>
    </bean></span>

通过上面可以看到属性值FreemarkerVariables中是一个Map类型，里面的Key指向的是标签实现类，Value是指向的页面中的标签，而在Jeecms中为了配置更多的标签实现类，而Value采用了这样的方式 ：value="#{propertyUtils.getBeanMap('directive.')}"，是通过一个属性类查找对应的配置文件，这个配置文件就是Jeecms.properties，里面的内容如下：

directive.uuid=uuid
directive.process_time=process_time
directive.text_cut=text_cut
directive.html_cut=html_cut
directive.cms_pagination=cms_pagination
directive.cms_channel_list=cms_channel_list
directive.cms_channel_page=cms_channel_page
directive.cms_channel=cms_channel
directive.cms_content=cms_content
directive.cms_content_list=cms_content_list
directive.cms_content_page=cms_content_page
directive.cms_tag_list=cms_tag_list
directive.cms_tag_page=cms_tag_page
directive.cms_topic_list=cms_topic_list
directive.cms_topic_page=cms_topic_page
directive.cms_comment_list=cms_comment_list
directive.cms_comment_page=cms_comment_page
directive.cms_guestbook_ctg_list=cms_guestbook_ctg_list
directive.cms_guestbook_list=cms_guestbook_list
directive.cms_guestbook_page=cms_guestbook_page
directive.cms_vote=cms_vote
directive.cms_lucene_list=cms_lucene_list
directive.cms_lucene_page=cms_lucene_page
directive.cms_friendlink_ctg_list=cms_friendlink_ctg_list
directive.cms_friendlink_list=cms_friendlink_list
directive.cms_advertising=cms_advertising
directive.cms_vote_list=cms_vote_list
directive.cms_model=cms_model
directive.cms_score_group=cms_score_group
directive.cms_searchword_list=cms_searchword_list

从中可以看出JEECMS中的Key和Value是一样的。

到此为止Freemarker的自定义标签配置流程已经完成，可以正常使用标签了。