DOTCMS Page Build Best Practice

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, các static file đã được sử dụng trước đó sẽ hiện ra bên phải, nếu file muốn add đã tồn tại rồi, chỉ cần tìm và chọn select, file đó sẽ được add vào page (chú ý: đối với những widget không có [common] ở đầu câu thì không nên reuse lại những project của khác để sử dụng). Nếu static file này chưa tồn tại, chúng ta có thể bấm vào Create New để tạo mới

4. Điền các thông tin cần thiết để tạo widget

- Widget Title: Nhập vào title cho widget. Chú ý: để cho để dàng tìm kiếm widget sau này, nên replace tất cả khoảng trắng hoặc dấu - thành dấu _ . Quy tắc này nên được app dụng cho việc tạo content và widget.

- File Type: Chọn Javascript

- URL: chọn đường dẫn chứa file js, như lúc nãy chúng ta upload file demo.js lên thư mục /src/js/, do đó ngay tại vị trí này sẽ dùng là /src/js/demo.js

- Type: Trong mục này có nhiều option, thường sử dụng nhất là Lib và Page (đối với những js mà chỉ dùng riêng cho trang này thì chúng ta nên chọn là Page. Không nên chọn None ở mục này, nếu không khi build sẽ bị lỗi)

- Site or Folder: Default là project đang select

- Click Save / P

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"

Select field type that you need, description about each field type can be found in this document: https://dotcms.com/docs/latest/field-properties

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:

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

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

Then Save this field. Now when you edit code in demo.vtl, new code will be reflected in demo widget.
More information you can find here: https://dotcms.com/docs/latest/parsing-a-vtl-file

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.

2b. CSS for widget

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