Contents |
Helloworld module
- Đây là tutorial tham khảo từ Module_Tutorial và Creating_Modules. Hai tutorial trên mô tả đầy đủ và chi tiết
- Tạo một module mới
- Làm việc với cơ sở dữ liệu
- Trình bày/sử dụng module ở các trang bên ngoài
- Tách giữa code logic và code hiển thị
- Vậy nên trong tutorial này
- Nói thêm một chút về các phương thức overide từ CMSModule.
- Chi tiết hơn về việc xây dựng một admin panel cho module.
Thực hiện
Tạo cây thư mục
Cấu trúc thư mục của module
- <thư mục cài đặt CMSMS>
- <modules>
- <helloworld>
- Helloworld.module.php
- method.install.php
- method.uninstall.php
- action.defaultadmin.php
- action.default.php
- templates
- frontend_hello.tpl
- admin_hello.tpl
- lang
- en_US.php
- ext
- vi_VN.php
- <helloworld>
- <modules>
Mở rộng lớp CMSModule
Thêm vào file Helloworld.module.php
class Helloworld extends CMSModule {
function Helloworld() {
$this->CMSModule(); // call the parent constructor
...your own constructor code...
}
}
Mở rộng một số phương thức khác trong lớp CMSModule
- Nickname của module: là tên tham chiếu khi muốn get instance của module
function GetName() {
return 'Helloworld';
}
- Tên đầy đủ của module: tên hiển thị trong trên Admin panel menu
function GetFriendlyName(){
return $this->Lang('Helloworld friendly name');
}
Thêm vào file en_US.php
<?php $lang['Helloworld friendly name'] = 'name in english'; ?>
Thêm vào file vi_VN.php
<?php $lang['Helloworld friendly name'] = 'Tên tiếng Việt'; ?>
- Có Admin panel cho module này?
function HasAdmin() {
return true;
}
- Menu Section sẽ chứa link đến Admin panel của module
function GetAdminSection() {
<!-- admin panel menu: Contents->Helloworld-->
return 'content';
}
Cài đặt module Helloworld
Tham khảo Modules
Xây dựng admin panel
Mô tả
- Admin panel của module gồm 3 tab
- Tab My form: tạo một form đơn giản
- Tab My template: tạo một template
- Tab Preference: thiết lập các cấu hình
Đây là những tab thường gặp trong admin panel của các module khác
Tạo tab header
Thêm đoạn code sau đây vào action.defaultadin.php. Tham khảo CMSModule api để biết cách dùng các phương thức [StartTabHeaders] và SetTabHeader
<!-- lấy tab được chọn -->
if (FALSE == empty($params['active_tab']))
{
$tab = $params['active_tab'];
} else {
$tab = '';
}
<!-- vẽ tab header -->
echo $this->StartTabHeaders();
echo $this->SetTabHeader('myform',$this->Lang('my form'), ('myform' == $tab)?true:false);
echo $this->SetTabHeader('mytemplate',$this->Lang('my template'), ('mytemplate' == $tab)?true:false);
echo $this->SetTabHeader('myform',$this->Lang('my form'), ('myform' == $tab)?true:false);
echo $this->EndTabHeaders();
Tạo tab content
Nếu tất cả code đặt trong cùng file action.defaultadmin.php thì code rất dài và khó theo dõi. Ở đây tách việc vẽ từng tab ra các file khác nhau, tên file có dạng function.admin_xxxxxtab.php
<!-- bắt đầu xây dựng nội dung từng tab -->
echo $this->StartTabContent();
<!-- tab My form -->
echo $this->StartTab('properties');
include(dirname(__FILE__).'/function.admin_myformtab.php');
echo $this->EndTab();
<!-- end tab My form -->
<!-- tab My template-->
echo $this->StartTab('properties');
include(dirname(__FILE__).'/function.admin_mytemplatetab.php');
echo $this->EndTab();
<!-- end tab My template -->
<!-- tab My form -->
echo $this->StartTab('properties');
include(dirname(__FILE__).'/function.admin_myformtab.php');
echo $this->EndTab();
<!-- end tab My form -->
echo $this->EndTabContent();
<!-- -->
Sau đây là một số ví dụ sử dụng CMSModule api để tạo form element trong tab. Tab Preference là ví dụ về lưu và lấy tham số cấu hình (preference params) của module dùng các hàm CMSModule::GetPreference và CMSModule::SetPreference
Tab My form
- File function.admin_myformtab.php: tạo một form với 1 textbox và một button submit. Ví dụ này giới thiệu cách sử dụng CMSModule api để tạo form, form element; cách dùng smarty template trong CMSMS; cách xử lý một form sau khi submit
<!-- do_formsubmit: cho biết file action.do_formsubmit.php sẽ chứa code xử lý My form -->
<!-- tạo form -->
$this->smarty->assign('startform', $this->CreateFormStart($id, 'do_formsubmit'));
$this->smarty->assign('endform', echo $this->CreateEndStart());
<!-- tạo textbox myname-->
$this->smarty->assign('inputname', $this->CreateInputText($id, 'myname', 'default my name', 20, 255));
<!-- label cho textbox -->
$this->smarty->assign('inputname_prompt', $this->Lang('myname_prompt'));
<!-- tạo nút submit -->
$this->smarty->assign('submit', $this->CreateInputSubmit($id, 'submit', 'Submit'));
<!-- process template myform.tpl -->
echo $this->ProcessTemplate('myform.tpl');
- CMSMS cung cấp các API để tạo form elements. Chú ý trong mỗi hàm Createxxx đều có một biến $id - đây là $id module instance, được tạo bởi CMSMS khi render một trang. Chúng ta sẽ hiểu thêm về việc tại sao phải dùng $id khi xử lý form submit. Tham khảo CreateFormStart api, CreateInputText api
- Hàm $this->ProcessTemplate một wrapper của smarty template để lượng giá một template được lưu ở file myform.tpl. Ngoài ra còn hai hàm nữa tương tự nhưng lấy template từ database và từ nguồn có sẳn là ProcessTemplateFromDatabase và ProcessTemplateFromData.
- Và đây là smarty template code trong file templates/myform.tpl
{$startform}
<div class="pageoverflow">
<p class="pagetext">*{$inputname_prompt}:</p>
<p class="pageinput">{$inputname}</p>
</div>
<div class="pageoverflow">
<p class="pagetext"> </p>
<p class="pageinput">{$submit}</p>
</div>
{$endform}
Các class pageoverflow và pagetext định nghĩa trong admin/themes/default/css/style.css (đây là theme mặc định, cách tuỳ biến admin theme được chi tiết ở một tutorial khác).
- Có hai cách xử lý form này khi submit:
- Overide hàm CMSModule:DoAction($id, $params, $returnid), trong đó
- $id là id của module form trên một trang, có nhiều form trên cùng một trang. Viewsource một trang sẽ thấy textbox có tên là m1_myname, và textarea trong form template ở tab MyTemplate sẽ có tên là m2_mytemplate.
- $params: chứa các params được submit cho form này (thử so sánh với $_REQUEST để thấy sự khác biệt). Trong $params có $params['action'] = 'do_myformsubmit'
- $returnid: id của trang được dùng để hiển thị kết quả trả về sau khi sử lý form.
- Đặt code xử lý trong file action.do_myformsubmit.php. Tên file chính là tên thuộc tính action của form. Ở đây các tham số $id, $params và $returnid xem như global.
- Hàm CMSModule::GetDb() lấy instance của một connection để cơ sở dữ liệu.
Tab My template
- Tab My Template (file function.admin_mytemplatetab.php) chứa một form cùng với một textarea, bốn nút (theo qui tắc chung của CMSMS) Submit, Cancel, Apply, Preview và Restore to default (nút này chỉ dành cho nhưng form dạng chứa template). Template cách để tách phần hiển dữ liệu ra khỏi code logic. Việc tạo một form hiệu chỉnh template thích hợp cho designer dễ dàng tuỳ biến giao diện ngay trên giao diên quản trị module; thay vì phải sửa file xxx.tpl mà việc này chỉ thích hợp cho lập trình viên và người quản trị website. Thêm nữa là việc có nhiều cách hiển thị cho cũng một dữ liệu tuỳ theo ngữ cảnh của người dùng. Tuy nhiên việc này dẫn đến khó quản lý version của template => khó rollback lại những gì đã làm. Có thể khắc phục bằng cách install module Archive để backup. Ví dụ này giới thiệu
- Tạo một WYSIWYG textarea
- CMSModule::GetTemplate và CMSModule::SetTemplate lấy và lưu template của các module
<!-- tạo form -->
$this->smarty->assign('startform', $this->CreateFormStart($id, 'do_templatesubmit'));
$this->smarty->assign('endform', echo $this->CreateEndStart());
<!-- tạo texarea wysiwyg mytemplate -->
$enablewysiwyg = true;//enable wysiwyg
//get template from db
$templatecontent = $this->GetTemplate('mytemplate');
$this->smarty->assign('inputname', $this->CreateTextArea($enablewysiwyg, $id, $templatecontent, 'mytemplate', 20, 255));
<!-- label cho textarea -->
$this->smarty->assign('inputtemplate_prompt', $this->Lang('mytemplate_prompt'));
$this->smarty->assign('submit', $this->CreateInputSubmit($id, 'submit', $this->Lang('submit'));
$this->smarty->assign('apply', $this->CreateInputSubmit($id, 'apply', $this->Lang('apply'));
$this->smarty->assign('preview', $this->CreateInputSubmit($id, 'preview', $this->Lang('preview'));
<!-- tham số thứ sáu 'Are you sure' là confirm message khi người dùng click chọn Cancel hoặc Restore -->
$this->smarty->assign('cancel', $this->CreateInputSubmit($id, 'cancel', $this->Lang('cancel'), '', '', 'Are you sure?');
$this->smarty->assign('restore', $this->CreateInputSubmit($id, 'restore', $this->Lang('restore'), '', '', 'Are you sure?');
<!-- process template myform.tpl -->
echo $this->ProcessTemplate('mytemplate.tpl');
- Code sau ví dụ xử lý 2 cho nút Submit và Cancel. Khi nút Cancel được chọn, redirect về action defaultadmin
if (isset($params['cancel']) {
//redirect to current tab
$this->Redirect($id, 'defaultadmin', $returnid);
}
else if (isset($params['submit']) {
//set template to db
$this->SetTemplate('mytemplate', $params['mytemplate']);
//trùng với code ở trên, nhưng đây chỉ là ví dụ :D
$this->Redirect($id, 'defaultadmin', $returnid);
}
Tab My preference
- Tab này giới thiệu về việc lưu và sử dụng các tham số tuỳ biến, như row_per_page để phân trang chẳng hạn. Dùng hàm CMSModule::GetPreference để lấy giá trị row_per_page.
<!-- file function.admin_preferencetab.php -->
<!-- tạo form -->
$this->smarty->assign('startform', $this->CreateFormStart($id, 'do_editpreference'));
$this->smarty->assign('endform', echo $this->CreateEndStart());
//lấy giá trị row_per_page được lưu trong perference, nếu chưa có thì 20 là giá trị mặc định
$row_per_page = $this->GetPreference('row_per_page', 20);
$this->smarty->assign('inputname', $this->CreateInputText($id, 'row_per_page', $row_per_page, 20, 5));
$this->smarty->assign('submit', $this->CreateInputSubmit($id, 'submit', $this->Lang('submit'));
<!-- process template preference.tpl -->
echo $this->ProcessTemplate('preference.tpl');
- Dùng hàm CMSModule::SetPreference giá trị row_per_page như sau
<!-- file action.do_editpreference -->
if (isset($params['submit']) {
$this->SetPreference($params['row_per_page']);
}
$this->Redirect($id, 'defaultadmin', $returnid, $params);
