DOTCMS Page Build Best Practice

Owned by An Nguyen (Unlicensed)
Last updated: Nov 25, 2019

This document describe best practice when create new page / template / widget in DOTCMS. It contain 3 part of building a page: 

  • Template
  • Page
    • HTML
    • JS
    • CSS
  • Widget
    • JS 
    • CSS

1. Create Template

The purpose of this is define containers within a template (how many Row your template has? How many column of each row?....) 

Go to the site that you want to create template. 

Go to Template tab at Left Menu

Click Option Button at top right of your screen and select Add Template Designer

  • Enter your new template title
  • Select Theme in correct project (your current project). Theme is included header & footer & standard scripts such as GTM, Everflow....
  • IF you dont want to inherit Header & Footer from the site (such as Presale & Index page), you can uncheck Header & Footer checkbox.
  • There is one row has been created by default. Add more row if you want by click on "add row" 

As below screenshot, 3 more rows have been added. You can choose how many column of each row. . 

  • After added rows, please add Container to each row, otherwise you cant add content/widget to that row / column. 
  • Please only choose 1 container among below list of common container, within one page, 1 container can be used once: 
    • [SiteCommon]LargeColumn(100%) - 1, 
    • [SiteCommon]LargeColumn(100%) - 2, 
    • [SiteCommon]LargeColumn(100%) - 3,
    • .... 
    • [SiteCommon]LargeColumn(100%) - 20, 
    • [SiteCommon]HeadTag, (mostly this will be used in Presale & Index page since we did uncheck header & footer when create template as mentioned above) 
    • [SiteCommon]FootTag (mostly this will be used in Presale & Index page since we did uncheck header & footer when create template as mentioned above) 

  • After all containers have been added, click on Save and Publish Button to Save Changes & Publish the template. 


You can take a look a demo template in Basesite2 Project → Templates → demo_template 


2.  Create Page using Template 

In site browser, select folder that you want to create page. Then click add page in menu. 

Leave dropdown box option as default "Page Asset" → Select. 

Enter needed information to create page, fields with Red title in required
1. Title: all characters are in normal case (a-z), dont use special characters & capital characters

2. Url: example: demo.html

3. Host or Folder: choose current folder & site

4. Template: select created template (in previous step) or a default template

5. Friendly name: Site Title

In Advanced Properties tab. you can configure below information:

1. Redirect URL: replace all Relative URL in this page with a new one
Note:

- All Absolute URL & URLs in footer will not be affected by this configuration

2. Campaign Webkey: Used for Index - Pre-sale & Order page (most important). To declare webkey which is used to get price from CRM

3. Campaign Name: enter campaign name of entered webkey for better management. DONT LEAVE THIS BLANK if you already entered webkey.

4. GTM: Leave this blank if this page inherit GTM key of the site. 

Click Save to initiate page. 

  • How to Add JS to page

1. Go to src/js folder and create new js folder as below: 


2. Go back to page editor and add new widget to last container (last "add content" button). 

3. Find and select [SiteComment]AddstaticFileWidget, static files which already used before will appeared on right column. (Important Note: Do not reuse widget with  [Common] Prefix.). Click on Create New to create new widget to declare JS File. 

4. Enter Needed information

- Widget Title: Only use Alphabet in Normal Case & "_" character. 

- File Type: Javascript

- URL: select js path. Ex: /src/js/demo.js

-  Type: Should choose Lib & Page

- Site or Folder: Current Site Folder

- Click Save / Publish 

  • How to Declare CSS for this page

Go to Application/themes/pages and create a less file with this template:  [pagetitle]-en.page.less. (page title of the page you want to use this CSS file demo below: 

Is case you wanna help separate css file, you can do the same as how to declare JS file for page. 

3. Create & Add Widget 

  • Go to menu Types & Tag → Content Types 

  • You can see a screen of all content type & widget as below, click on Add new content type as below screenshot:

Enter required information to create widget

  • Type: select Widget
  • Name: Should follow this format: [Sitename] Section - Feature Name 
  • Description: Put whatever you want to describe this functionality
  • Site or Folder: SiteCommon
  • Double check all entered information and click Save

After you have a widget, please Add field to widget by click on "add new field"

  • Enter needed information to create new field then click save. 

  • Note: When create widget/content, always create field Site Or Folder to indicate Site when we add widget to site. 

Too add HTML code to this widget, we have to create new VTL file follow below steps: 

  1. Create new VTL file, this VTL file shoud be create in Site Common → Widgets Folder. 
  2. Then go back to our widget properties and Edit Widget Code by click on Edit Icon as below screenshot: 

  3. Then declare new VTL file by adding below Code: 

    #dotParse("$!{sitecommon_vtlpath}/widgets/demo.vtl"),

2a. JS for widget

You have to create new JS file in local site (within site folder, you create new js file in SRC/JS/.... as below screenshot) 

Then declare this new js file in demo.vtl to load this js in html. 


<script type="text/javascript" src="/src/js/jsfile.js" scriptType="page" defer></script>


2b. CSS for widget

The same for CSS, you should create css file in less folder, and declare in vtl file: 

<link linkType="page" rel="stylesheet/less" type="text/css" href="/src/less/pages/lessFile.less">