Migrating Web content templates from Velocity to Freemarker: tools, tips and tricks

thumbnail
Sergio Sánchez
Published Date4 Years Ago - 17599 Views

This blog post contains a simple procedure to upgrade the templates created for Web Content in Liferay Portal 6.x EE with Velocity to Freemarker in Liferay Portal/DXP 7.x. As you might know, the use of Velocity is deprecated in Liferay Portal/DXP 7.x and it’s advisable to migrate from Velocity to Freemarker.

This post is not magic or rocket science, just a set of steps that can help in automatization of some steps that would otherwise be manual.

Let’s start reviewing the tools used and then the tips and tricks within a complete procedure.

Tools used and configuration

  1. Sublime Text is the Text editor used.

  2. Freemarker Bundle for Sublime Text useful for syntax highlighting.
    • For its installation, follow the instructions on the link above.
  3. HTMLBeautify package for Sublime Text

    • It can be installed in Sublime Text following Preferences > Package Control > Install and write HTMLBeautify.

    • Configure the indentation rules to include the Freemarker tags for HTMLBeautify to work. To do this, you need:
      • In Sublime Text go to Preferences > Package Settings > HTMLBeautify > Settings - Default and copy the text that is displayed.
      • Go to Preferences > Package Settings > HTMLBeautify > Settings - user and paste the text copied from the previous item.
      • Include the Freemarker tags (separated with the pipe character | ) in the following sections and then save these changes:
        • In tag_indent section, include: <#if, <#foreach
        • In tag_unindent section, include: </#if, </#foreach
        • In tag_unindent_line section, include: <#elseif, <#else

    Below is a picture of the final configuration:

    HTMLBeautify configuration
  4. USCavalry tool, that allows to translate Velocity templates to Freemarker. Although it’s legacy and not maintained anymore it’s very useful and it can still be downloaded from the Sourceforge repository.
    • Unzip USCavalry in a working directory.

  5. Obviously, Liferay Portal or DXP 7.x after its database has been upgraded.

Tips and Tricks 

Follow this procedure with one of your Velocity templates for Web Content to test if it’s useful for you:

  1. In order to copy the code inside the templates, it can be very useful to load them using WebDAV. For that, open a remote connection using the File Explorer in your OS to one URL like this one: http://localhost:8080/webdav/guest/journal/Templates/ . In the URL, remember to change:

    • Instead of “localhost:8080”, the domain of your Liferay server where the templates are hosted.

    • Instead of “guest”, the name of the Website where the templates are stored.

  2. Once the templated directory is mounted through WebDAV, copy the files to the working directory where you unzipped USCavalry.

  3. Add an extension to those files, such as “.vm”.

  4. In the working directory, run the following command with one of the existing files as the first argument and a new file as the second argument: java -jar cavalry.jar 11843.vm 11843.ftl

  5. After the previous step is completed, you will see that the output of the Freemarker file (the .ftl one), is unindented making the readability of that file very difficult. In order to tidy up that file, follow these steps:

    • First, separate every HTML or Freemarker tag into a different line. To achieve this, in Sublime Text replace the closing tag character  (>) with the same character followed by the new line escape sequence (>\n), as you can see in the following image:

    • Second, apply HTMLBeautify. In Sublime Text, go to Edit > Beautify HTML (if it doesn’t work, go to line 1 and run it again)

      At this stage, the code in the templates would be correctly indented and formatted to allow easy reading.

  6. Lastly, you will need to apply additional adaptations to your template, such as:

    • First, after the process by the USCavalry tool, you will need to change some if sentences. To check if a variable is not null, follow this example:
      <#if someVariable && someVariable.getData() != "">
      You must change it and include the ‘??’ operator:
      <#if someVariable?? && someVariable.getData() != "">

       

    • Second, if you need to access services through serviceLocator, keep in mind that the fully qualified name of the class changed in Liferay 7.x. So, after the process with USCavalry tool you will still have the original names, like this one:
      <#assign journalArticleLocalService = serviceLocator.findService("com.liferay.portlet.journal.service.JournalArticleLocalService")>
      And you will need to replace them for the current service names:
      <#assign journalArticleLocalService = serviceLocator.findService("com.liferay.journal.service.JournalArticleLocalService")>

       

      The solution above applies to other services like: assetEntryLocalService, assetCategoryLocalService and assetVocabularyLocalService, the names need to be replaced as follows:
      Orinal service name Replacement service name

      com.liferay.portlet.asset.service.AssetEntryLocalService

      com.liferay.asset.kernel.service.AssetEntryLocalService

      com.liferay.portlet.asset.service.AssetCategoryLocalService

      com.liferay.asset.kernel.service.AssetCategoryLocalService

      com.liferay.portlet.asset.service.AssetVocabularyLocalService

      com.liferay.asset.kernel.service.AssetVocabularyLocalService

       

    • If you need to access metadata from the Web Content piece, after the process through USCavalry you will see sentences like this one:
      <#assign ja = journalArticleLocalService.getArticle(getterUtil.getLong(groupId), getterUtil.getString(reserved-article-id.data))>
      This needs to be changed to the following syntax:
      <#assign ja = journalArticleLocalService.getArticle(getterUtil.getLong(groupId), getterUtil.getString(.vars['reserved-article-id'].data))>

      Keep in mind that other data fields are available. See the following class for a complete reference.

       

    • If you have repeatable fields in your Web Content structure and you need to check them in your template, after the process through USCavalry,  your Freemarker template will have something similar to this:
      <#if !repeatableField.getSiblings().isEmpty()>
      In these cases, you will need to change them to the following:
      <#if repeatableField.getSiblings()?has_content>

       

    • Be careful if you have anchors (href="#something") in your <a> tags because USCavalry might have deleted them.

       

    • Lastly, remember that you have a wide selection of variables that allow you to access a great amount of data and information stored in Liferay. Here is the list of variables and the type of each variable. You can check the methods available for each type at the javadocs site.

       

      VARIABLE

      TYPE

      accountPermission

      com.liferay.portal.kernel.service.permission.AccountPermission

      arrayUtil

      com.liferay.portal.kernel.util.ArrayUtil_IW

      auditMessageFactoryUtil

      com.liferay.portal.kernel.audit.AuditMessageFactory

      bodyCssClass

      java.lang.String

      browserSniffer

      com.liferay.portal.kernel.servlet.BrowserSniffer

      calendarFactory

      com.liferay.portal.kernel.util.CalendarFactory

      colorScheme

      com.liferay.portal.kernel.model.ColorScheme

      commonPermission

      com.liferay.portal.kernel.service.permission.CommonPermission

      company

      com.liferay.portal.kernel.model.Company

      dateFormatFactory

      com.liferay.portal.kernel.util.FastDateFormatFactory

      dateFormats

      com.liferay.portal.kernel.util.FastDateFormatFactory

      dateUtil

      com.liferay.portal.kernel.util.DateUtil_IW

      enumUtil

      freemarker.ext.beans.BeansWrapper

      expandoColumnLocalService

      com.liferay.expando.kernel.service.ExpandoColumnLocalService

      expandoRowLocalService

      com.liferay.expando.kernel.service.ExpandoRowLocalService

      expandoTableLocalService

      com.liferay.expando.kernel.service.ExpandoTableLocalService

      expandoValueLocalService

      com.liferay.expando.kernel.service.ExpandoValueLocalService

      freeMarkerPortletPreferences

      com.liferay.portal.template.TemplatePortletPreferences

      fullCssPath

      java.lang.String

      fullTemplatesPath

      java.lang.String

      getterUtil

      com.liferay.portal.kernel.util.GetterUtil_IW

      groupPermission

      com.liferay.portal.kernel.service.permission.GroupPermission

      htmlUtil

      com.liferay.portal.kernel.util.Html

      httpUtil

      com.liferay.portal.kernel.util.Http

      httpUtilUnsafe

      com.liferay.portal.kernel.util.Http

      imageToken

      com.liferay.portal.kernel.webserver.WebServerServletToken

      imageToolUtil

      com.liferay.portal.kernel.image.ImageTool

      init

      java.lang.String

      jsonFactoryUtil

      com.liferay.portal.kernel.json.JSONFactory

      languageUtil

      com.liferay.portal.kernel.language.Language

      layout

      com.liferay.portal.kernel.model.Layout

      layoutPermission

      com.liferay.portal.kernel.service.permission.LayoutPermission

      layouts

      java.util.List

      layoutTypePortlet

      com.liferay.portal.kernel.model.LayoutTypePortlet

      locale

      java.util.Locale

      localeUtil

      com.liferay.portal.kernel.util.LocaleUtil

      locationPermission

      com.liferay.portal.kernel.service.permission.OrganizationPermission

      navItems

      java.util.List

      objectUtil

      freemarker.template.TemplateMethodModelEx

      organizationPermission

      com.liferay.portal.kernel.service.permission.OrganizationPermission

      pageTitle

      java.lang.String

      paramUtil

      com.liferay.portal.kernel.util.ParamUtil_IW

      passwordPolicyPermission

      com.liferay.portal.kernel.service.permission.PasswordPolicyPermission

      permissionChecker

      com.liferay.portal.kernel.security.permission.PermissionChecker

      plid

      java.lang.String

      portal

      com.liferay.portal.kernel.util.Portal

      portalPermission

      com.liferay.portal.kernel.service.permission.PortalPermission

      portalUtil

      com.liferay.portal.kernel.util.Portal

      portletDisplay

      com.liferay.portal.kernel.theme.PortletDisplay

      portletGroupId

      java.lang.Long

      portletModeFactory

      com.liferay.portal.kernel.portlet.PortletModeFactory_IW

      portletPermission

      com.liferay.portal.kernel.service.permission.PortletPermission

      portletProviderAction

      java.util.Map

      portletURLFactory

      com.liferay.portal.kernel.portlet.PortletURLFactory

      prefsPropsUtil

      com.liferay.portal.kernel.util.PrefsProps

      propsUtil

      com.liferay.portal.kernel.util.Props

      randomizer

      com.liferay.portal.kernel.util.Randomizer

      realUser

      com.liferay.portal.kernel.model.User

      request

      javax.servlet.http.HttpServletRequestWrapper

      rolePermission

      com.liferay.portal.kernel.service.permission.RolePermission

      saxReaderUtil

      com.liferay.portal.kernel.xml.SAXReader

      scopeGroupId

      java.lang.Long

      serviceLocator

      com.liferay.portal.template.ServiceLocator

      sessionClicks

      com.liferay.portal.kernel.util.SessionClicks_IW

      xmlRequest

      java.lang.Object

      staticFieldGetter

      com.liferay.portal.kernel.util.StaticFieldGetter

      staticUtil

      freemarker.ext.beans.StaticModels

      stringUtil

      com.liferay.portal.kernel.util.StringUtil_IW

      theme

      com.liferay.portal.kernel.model.Theme

      themeDisplay

      com.liferay.portal.kernel.theme.ThemeDisplay

      timeZone

      java.util.TimeZone

      timeZoneUtil

      com.liferay.portal.kernel.util.TimeZoneUtil_IW

      unicodeFormatter

      com.liferay.portal.kernel.util.UnicodeFormatter_IW

      unicodeLanguageUtil

      com.liferay.portal.kernel.language.UnicodeLanguage

      user

      com.liferay.portal.kernel.model.User

      userGroupPermission

      com.liferay.portal.kernel.service.permission.UserGroupPermission

      userPermission

      com.liferay.portal.kernel.service.permission.UserPermission

      utilLocator

      com.liferay.portal.template.UtilLocator

      validator

      com.liferay.portal.kernel.util.Validator_IW

      webServerToken

      com.liferay.portal.kernel.webserver.WebServerServletToken

Take-aways

I hope this blog post was useful for you and it can save you some time in the task of migrating off your Web content templates from Velocity to Freemarker.

The combination of the migration tool (USCavalry) and a Text editor that can tidy up your template will make all that process easier.

 

Comment (1)

More Blog Entries

thumbnail

Drag&Drop Indication on Liferay CE 7.3.1 GA2

thumbnail
Olaf Kock
06 Apr
0
thumbnail

Kaleo workflowContext should be a unmodifiable map

Michael Chen
10 Apr
4
Blogs