Parsing a .vtl File - Documentation topics on: creating a simple dynamic listing,dotparse,parse,simple widget,velocity,vtl,vtl include widget,.

Parsing a .vtl File

Writing Velocity, HTML/CSS, and/or Javascript directly in a Simple Widget on a Page is expedient, but has a few disadvantages:

  • Code reusability is limited.
  • The code can't be edited via webdav connection.
  • The code is not abstracted away from the content on the page.
  • Permissions to edit the code can't be separated from permissions to edit the content.

Therefore, the recommended way to build basic or “Simple Widgets” is to place the code in a .vtl (Velocity Template Language) file, upload the file, and then parse or “include” that .vtl file from the widget. There are two ways to parse a .vtl file in a widget:

  • Use the VTL Include widget to select and parse the .vtl file onto the page.
  • Create a simple widget and use the #dotParse method to include the Velocity code from the file on the Page.

Both methods are explained in the tutorials below. These tutorials assume that you have already finished both the Building Your First Content Type and Creating A Simple Dynamic Listing tutorials.

Using the VTL Include Widget

After creating your .vtl file during the Creating A Simple Dynamic Listing tutorial, use the following steps to execute your .vtl file code on a dotCMS Page using the VTL Include widget:

  1. Upload your .vtl file to a folder under the Site Browser tab.



  2. Allow the .vtl file to be uploaded as the default File Asset Content Type.



  3. Upload the .vtl file.
    Note: Make sure you are not uploading a file with the extension .txt.



  4. Create a new HTML page, click +Add Content in the body area of the page, and select Add Widget.



  5. Select the .VTL Include widget and then click the Create New VTL Include button.



  6. Select the SimpleStaffListing.vtl file that you created in the Creating a Simple Dynamic Listing tutorial.



  7. Title the widget and click the Save / Publish button.



  8. The code in the .vtl should execute on the page and display the existing Staff content.
    Note: The .vtl file icon that appears inside the executed widget. Clicking on the .vtl file icon will allow you to edit the .vtl file from the Page.



Using the #dotParse Method

After creating your .vtl file during the Creating A Simple Dynamic Listing tutorial, use the following steps to execute your .vtl file code on a dotCMS Page using the #dotParse() method:

  1. Upload your .vtl file to a folder under the Site Browser tab.
  2. Add a Simple Widget to the body area of a Page.
  3. In the Simple Widget code field, use the following statement, adjusting the pathing to match the pathing of your file on the same host:
    #dotParse("/training/SimpleStaffListing.vtl")
    

Note: Parsing .vtl Files Across dotCMS Sites

Velocity .vtl files can be parsed from other Sites hosted on the same dotCMS instance.

  • If you use the VTL Include widget, you can browse to a .vtl file on any site hosted on your dotCMS instance to select the file.
  • If you use the #dotParse method, you can parse a .vtl file from another Site by specifying a double forward slash (//), then the name of the Site, and then the path to your .vtl file, as in the following example:
    #dotParse('//sitename/application/vtl/SimpleStaffListing.vtl')