This document describe best practice when create new page / template / widget in DOTCMS. It contain 4 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?....)
Step 1: Go to the site that you want to create template.
Step 2: Go to Template tab at Left Menu
Step 3: Click Option Button at top right of your screen and select Add Template Designer
Step 4:
- 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. (not recommended) (you should use CSS to hide unnecessary part in header & footer instead)
- 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
- Để xóa một container đã add, click vào Remove Container. Template sau khi đã hoàn thành sẽ có giao diện như hình bên dưới. Click Save and Publish để lưu template lại
...
2. Create & Add Widget
Step 1: Click menu Types & Tag → Content Types bên trái màn hình
Giao diện quản lý Content type và widget sẽ hiện ra như bên dưới
Step 2: Click vào button góc trên màn hình và chọn Add New Content Type
Step 3: Điền các thông tin cần thiết để tạo widget
- Type: chọn Widget
- Name: Điền tên của widget muốn tạo
- Description: mô tả cho widget
- Site or Folder: Nên chọn là SiteCommon (tất cả các widget của mình đều được đặt ở SiteCommon)
- Bấm Save sau khi đã điều đủ thông tin
- Sau khi tạo xong widget, giao diện sẽ nhìn giống như bên dưới
Step 4: Để thêm mới một field trong widget, bấm vào nút Add New Field bên góc phải
- Điền một số thông tin cho field này, đầu tiên chọn Type cho field như hình bên dưới.
- Ví dụ chọn Type là Text, các thông tin cần thiết dùng cho field này sẽ xuất hiện như bên dưới. Bấm Save Field để hoàn thành.
- Chú ý: Đối với mỗi Widget/Content, khi tạo nên thêm field Site Or Folder vào, field này được sử dụng khi các widget được add vào site.
Step 5: Để thêm các mã code HTML, JS, CSS vào widget, chọn edit Widget Code
- Bạn có thể thêm trực tiếp mã HTML, JS, CSS vào phần Value như trong hình bên dưới. Nhưng chúng tôi không khuyến khích bạn sử dụng mã code trược tiếp ở đây, bởi vì nếu như widget có xảy ra sự cố gì chúng ta sẽ không có source backup, đồng thời nếu để mã code ở đây sẽ rất có để làm việc và quản lý.
- Một cách khác để chúng ta có thể chèn mã code ở đây là tạo một file VTL ở một thư mục khác (chúng tôi thường sử dụng thư mục SiteCommon để chứa các loại file như vầy), đường dẫn sẽ như #dotParse
- (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"
- 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:
Info #dotParse("$!{sitecommon_vtlpath}/widgets/demo.vtl"),
...
Step 6: Tạo file demo.vtl trong SiteCommon
- Chọn Project SiteCommon → widgets
- Tạo một file và đặt tên là demo.vtl, sau đó upload file này từ máy tính vào thư mục trên
- Các mã code chúng ta có thể viết tại đây. Để gọi các field chúng ta đã thêm vào ở trong widget, chúng ta có thể dùng các lệnh sau:
- $!{con.title} : In giá trị của biến title (có kiểm tra null)
- $con.title: gọi biến title lên và sử dụng
2a. JS for widget
Để thêm js vào trong Widget, chúng ta nên viết ở một file riêng, sau đó đưa file này lên Cloud và thêm vào như trong hình ở trên
2b. CSS for widget
...
- 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.
| Info |
|---|
<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:
| Info |
|---|
<link linkType="page" rel="stylesheet/less" type="text/css" href="/src/less/pages/lessFile.less"> |