کدنویسی در MODx Evolution
۶ تير ۱۳۸۹ ساعت ۱۱:۰۳

مادایکس

نکات اساسی کدنویسی در MODx Evolution

در این مقاله APIهای مهم و نکات به دردبخور کدنویسی در مادایکس Evolution معرفی خواهد شد. این مقاله نه ترجمه است و نه براساس الگوی خاصی نوشته شده. اینها تجربیات من از کدنویسی در مادایکس هستند. اونجوری که فهمیدم توضیح میدم و اونهایی که به نظرم پرکاربردتر هستند رو معرفی می کنم.

از ثابتهای مهم شروع می کنیم:
MODX_BASE_PATH: مسیر یا Path فیزیکال محل نصب مادایکس روی سرور. برای include کردن فایلها، این ثابت خیلی استفاده میشه.
MODX_BASE_URL: آدرس یا URL محلی از محل نصب مادایکس. مناسب برای ایجاد URLهای محلی (بدون http اینا) برای استفاده در تگ img و script و غیره.
MODX_SITE_URL: آدرس URL اصلی سایت.:
MODX_MANAGER_PATH: مسیر یا Path فیزیکال فولدر manager ازمحل نصب مادایکس روی سرور.
MODX_MANAGER_URL: آدرس URL محلی فولدر manager از محل نصب مادایکس.

$assets_path = MODX_BASE_PATH . 'assets';
// /usr/xxx/assets

$mages_Url = MODX_BASE_URL . 'assets/images';
// /assets/images

$site_url = MODX_SITE_URL;
// http://boplo.ir/

$assets_path = MODX_MANAGER_PATH;
// /usr/xxx/manager/

$manager_url = MODX_MANAGER_URL;
// /manager/

 

 

با اجرای سایت، کلاسی به نام DocumentParser اجرا میشه و شیء با نام modx$ رو میسازه. همه APIهای مادایکس از طریق این شیء قابل دسترسی است.

DocumentParser :: documentIdentifier: حاوی ID صفحه ای که در حال اجراش هستیم. مثلا اگر در حال مشاهده صفحه اصلی باشیم، مقدار این مشخصه به درد بخور برابر 1 خواهد بود. این متغیر از نوع integer هست و قابل Echo شدن نیست و برای چاپش باید به string تبدیل بشه.

echo (string) $modx->documentIdentifier;

DocumentParser :: documentObject: یک آرایه حاوی اطلاعات صفحه جاری است. اطلاعات صفحات در جدول site_content قرار دارند و این آرایه، سطر مربوط به صفحه جاری در این جدول است.

echo $modx->documentObject['pagetitle'];
echo $modx->documentObject['id'];
echo $modx->documentObject['content'];

DocumentParser :: config: یک آرایه حاوی اطلاعات تنظیمات مادایکس. این تنظیمات از جدول system_settings میاد.

echo $modx->config['site_name'];
echo $modx->config['site_url'];

()DocumentParser :: getFullTableName: موقع نصب، مادایکس پیشنهاد استفاده کلمه _modx به عنوان پیشوند جداول یا Table Prefix میده. این کلمه به نام همه جدولهای ساخته شده توسط مادایکس اضافه میشه. مثلا نام یکی از جدولها site_content هست که اگر پیشوند رو _modx بذاریم، بصورت modx_site_content ساخته میشه. وقتی داریم کد استاندارد مینویسیم، باید پیش بینی این رو بکنیم که شاید کس دیگه ای از کد استفاده کنه و پیشوند جدوالش مثل ما نباشه. برای اینکار باید نام جداول رو داینامیک استفاده کنیم. این تابع نام جدول رو میگیره و نام دیتابیس به همراه پیشوند جداول رو بهش اضافه می کنه.

$modx->getFullTableName($tablename);
echo $modx->getFullTableName('site_content');
// `dbname`.`modx_site_content`

()DocumentParser :: stripTags: مادایکس یه سری تگ داره. این تابع این تگها رو از متن حذف می کنه که مثلا یکی نتونه یک چانک رو توی کامنتش قرار بده. این تابع کار تابع strip_tags در PHP رو هم می کنه.

$modx->stripTags($str, $allowed='');
$stripped = $modx->stripTags($str, '<b>');

()DocumentParser :: isBackend: چک کردن اینکه این کد داره در بخش manager اجرا میشه یا خیر.

$modx->isBackend();
if($modx->isBackend())
	echo 'We are in the MODx Manager.';

()DocumentParser :: isFrontend: چک کردن اینکه این کد داره بخش خروجی سایت یا Front-End اجرا میشه یا خیر. این تابع دقیقا نتیجه عکس ()DocumentParser :: isBackend خواهد بود.

$modx->isFrontend();
if($modx->isFrontend())
	echo 'We are NOT in the MODx Manager (We are in the Front-End).';

()DocumentParser :: makeUrl: این تابع ID یک صفحه رو میگیره و باهاش URL درست می کنه که این URL کاملا براساس تنظیمات سایت خواهد بود یعنی اگر Friendly-URLs استفاده کنیم، آدرس تولید شده هم بصورت Friendly-URL خواهد بود. این تابع امکان اضافه کردن کوئری هم به آدرس میده و غیره.

$modx->makeUrl($id, $alias='', $args='', $scheme='');
$href = $modx->makeUrl($modx->documentIdentifier, '', '&a=5&b=1', 'HTTPS');
// https://mySite.com/currentPage.html?a=5&b=1
// https://mySite.com/index.php?id=45&a=5&b=1
echo '<a herf="' .$href . '">Current Page</a>';

()DocumentParser :: sendRedirect: انتقال کاربر به یک URL دیگه.

$modx->sendRedirect($url, $count_attempts=0, $type='', $responseCode='');
$modx->sendRedirect( $modx->makeUrl(125) );

()DocumentParser :: sendForward: انتقال کاربر به یکی از صفحات سایت بصورتیکه URL در Address Bar مرورگر تغییر نمی کنه.

$modx->sendForward($id, $responseCode='');
$modx->sendForward(15);

()DocumentParser :: runSnippet: اجرای یک اسنیپت با امکان تعیین پارامترهاش و گرفتن خروجی اش. نکته مهم این تابع یا متد اینه که خروجی رو return می کنه و چاپ نمی کنه.

$modx->runSnippet($snippetName, $params=array());
$result = $modx->runSnippet('Ditto', array('id'=>'someId', 'parents'=>5));
echo $result; /***/
// Same as [!Ditto? id=`someId` &parents=`5`!] in page

()DocumentParser :: getChunk: گرفتن محتوای یک چانک.

$modx->getChunk($chunkName);
echo $modx->getChunk('someChunk');

()DocumentParser :: parseChunk: گرفتن محتوای یک چانک و پردازش اطلاعات داخلش. مثلا یک چانک میسازیم که یه سری Placeholder توش هست با این متد، می تونیم اون متغیرها رو توش ترجمه کنیم.

$modx->parseChunk($chunkName, $chunkArr, $prefix="{", $suffix="}");
echo $modx->parseChunk('someChunk', array('name'=>'Amir Hossein', 'nickname'=>'AHHP'));
// Translates {name} and {nickname} in someChunk

()DocumentParser :: setPlaceholder: ایجاد یک Placeholder سراسری. با اجرای این تابع، می تونیم از Placeholderهای خودمون در صفحه استفاده کنیم.

$modx->setPlaceholder($name, $value);
$modx->setPlaceholder('name', 'Amir Hossein');

()DocumentParser :: regClientCSS: اضافه کردن CSS به صفحه. این تابع به تگ HEAD صفحه، CSS رو اضافه می کنه که هم میتونه تگ STYLE بگیره و هم آدرس فایل css برای تگ LINK.

$modx->regClientCSS($src, $media='');
$modx->regClientCSS('
	<style type="text/css">
		body { font-size: 12px; }
	</style>
');
$modx->regClientCSS('css/styles.css', 'all');

()DocumentParser :: regClientStartupScript: اضافه کردن جاوااسکریپت به بخش HEAD صفحه. که میتونه کد جاوااسکریپت یا آدرس فایل js رو بگیره. استفاده از options باعث جدا تشخیص کدهای تکراری میشه. مثلا این متد رو چند بار اجرا کردیم ولی اسکریپتمون باید یکبار به صفحه اضافه بشه که برای اینکار، من براش name میذارم و مادایکس میفهمه و فقط یکبار چاپش می کنه.

$modx->regClientStartupScript($src, $options=array('name'=>'', 'version'=>'0', 'plaintext'=>false));
$modx->regClientStartupScript('
	<script type="text/javascript">
		function fn(){
			alert("Boplo.ir");
		}
	</script>
');
$modx->regClientStartupScript('js/scripts.js');
$modx->regClientStartupScript('js/scripts.js', array('name' => 'someName'));

()DocumentParser :: regClientStartupHTMLBlock: کاملا شبیه متد ()regClientStartupScript ولی برای چاپ کدهای HTML در HEAD.

$modx->regClientStartupHTMLBlock($html);
$modx->regClientStartupHTMLBlock('');

()DocumentParser :: regClientHTMLBlock: مشابه ()regClientStartupHTMLBlock ولی خروجی رو به انتهای صفحه اضافه می کنه بجای HEAD.

$modx->regClientHTMLBlock($html);
$modx->regClientHTMLBlock('');

()DocumentParser :: getParentIds: گرفتن ID پرونده های بالادستی یا Parent یا والد با مراحل دلخواه.

$modx->getParentIds($id, $height=10, $parents=array());
$parentsIds_array = $modx->getParentIds(15);

()DocumentParser :: getChildIds: گرفتن ID پرونده های زیردستی یا Child یا فرزند با تعداد مراحل دلخواه.

$modx->getChildIds($id, $depth=10, $children=array());
$childrenIds_array = $modx->getChildIds(15);

()DocumentParser :: getAllChildren: گرفتن اطلاعات همه پرونده های زیردستی.

$modx->getAllChildren($id=0, $sort='menuindex', $dir='ASC', $fields='id, pagetitle, description, parent, alias, menutitle');
$childrenIds_array = $modx->getAllChildren(27);

()DocumentParser :: getDocument: گرفتن اطلاعات یک پرونده براساس IDاش.

$modx->getDocument($id=0, $fields="*", $published=1, $deleted=0);
$documentData = $modx->getDocument(24, "*", 0);

()DocumentParser :: getDocuments: مشابه ()getDocument :: DocumentParser برای چند پرونده بطور همزمان.

$modx->getDocuments($ids=array(), $published=1, $deleted=0, $fields="*", $where='', $sort="menuindex", $dir="ASC", $limit="");
$documentsData = $modx->getDocuments(array(45,85,1));

()DocumentParser :: getTemplateVars: گرفتن محتوای متغیرهای قالب براساس نام یا ID متغیر قالب و پرونده.

$modx->getTemplateVars($idnames=array(), $fields="*", $docid="", $published=1, $sort="rank", $dir="ASC");
$tvData = $modx->getTemplateVars(array('someTV'), '*', 17);

()DocumentParser :: userLoggedIn: گرفتن یه سری اطلاعات کلی از کاربر لاگین کرده.

$modx->userLoggedIn();
$currentUser = $modx->userLoggedIn();
/* 
$currentUser = array(
	'loggedIn' => true,
	'id' => 86,
	'username' => 'user_Name',
	'usertype' => 'web'
)
*/

()DocumentParser :: getLoginUserID: بدست آوردن ID کاربر لاگین کرده. کاربر بخش خروجی یا Front-End یا بخش Manager.

$modx->getLoginUserID($context='');
echo $modx->getLoginUserID();
echo $modx->getLoginUserID('web'); //  Front-End User
echo $modx->getLoginUserID('mgr'); // Manager User

()DocumentParser :: getWebUserInfo: این تابع اطلاعات کاربر وب رو بصورت کامل میده.

$modx->getWebUserInfo($uid);
$userData = $modx->getWebUserInfo(13);
/* 
$userData = array(
	'usertype' => 'web',
	'fullName' => 'users fullname',
	...
)
*/

()DocumentParser :: getUserDocGroups: بدست آوردن گروههایی که کاربر لاگین کرده درشون عضو هست. اگر به پارامتر این متد مقدار true بدیم، نام گروهها رو میگیریم در غیراینصورت ID میگیریم.

$modx->getUserDocGroups($resolveIds=false);
$documentGroupIDs = $modx->getUserDocGroups(); // Get Groups ID
$documentGroupNames = $modx->getUserDocGroups(true);// Get Groups Name

()DocumentParser :: isMemberOfWebGroup: تعیین اینکه کاربر لاگین کرده، عضو گروههای تعیین شده هست یا خیر.

$modx->isMemberOfWebGroup($groupNames=array());
if($modx->isMemberOfWebGroup(array('someGroup1', 'someGroup2'))) {
	echo 'You can pass!';
} else {
	echo 'Get Lost!';
}

()DocumentParser :: invokeEvent: فراخوانی یک رویداد MODx بصورت دستی. با فراخوانی یک رویداد MODx، همه پلاگینهای منتسب به اون رویداد اجرا میشوند!

$modx->invokeEvent($evtName, $extParams=array());
$modx->invokeEvent('OnBeforeWebLogin', array('id' => 52));

()DocumentParser :: clearCache: یروزرسانی Cache مادایکس. مادایکس همه چانک ها و اسنیپتها و پلاگینها و تنظیمات و اطلاعات صفحات رو به شکل فایل php کش می کنه. به اضافه صفحاتی که بصورت دستی قابل کش، تعریف می کنیمشون. با این متد می تونیم این کش رو از اول بسازیم. کاربردش زمانی هست که داریم توسط کدهامون، اطلاعات قابل کش رو تغییر میدیم و باید کش رو بروز کنیم تا مادایکس به روند عادی اش ادامه بده.

$modx->clearCache();

()DocumentParser :: logEvent: مادایکس یک بخش Log داره که errorهای سیستم رو ثبت می کنه که این آمار در بخش manager مادایکس قابل دسترسیه. با این متد می تونیم اطلاعاتی که لازم داریم رو توسط این امکان، log کنیم. مثلا اتفاق خاصی یا خطایی چیزی.

$modx->logEvent($evtid, $type, $msg, $source='Parser');
// Types: 1 = information, 2 = warning, 3 = error
$modx->logEvent(56, 2, 'This is a WARNING', 'My Snippet');

توابع دیگه هم وجود داره که در این فایل می تونید پیداشون کنید: manager/includes/document.parser.class.inc.php

 

 

مادایکس یک کلاس مخصوص برای دستیابی به دیتابیس تعریف کرده به نام DBAPI که توسط مشخصه DocumentParser :: db نمونه گیری شده (یعنی توسط modx->db$ قابل دسترسیه). این شیء حاوی متدها و مشخصه های مهم زیره:

DBAPI :: conn: لینک کانکشن ساخته شده برای دسترسی به دیتابیس. یعنی مقدار برگشتی از تابع mysql_connect که چون اتصال به دیتابیس مادایکس توسط خود مادایکس انجام میشه، این مقدار کاربرد خیلی خاص داره.

DBAPI :: config: آرایه حاوی اطلاعات دیتابیس از جمله نام کاربری و پسورد دیتابیس. یعنی باید مواظبش باشیم! مهمترین عناصرش، موارد زیر هستند:

echo $modx->db->config['table_prefix'];
echo $modx->db->config['dbase'];

()DBAPI :: escape: یک متد جمع و جور و کاربردی و مهم برای Escape کرده ورودی ها برای جلوگیری از SQL Injection. این متد تلاش می کنه تا تابع mysql_real_escape_string رو اجرا کنه و درصورت عدم موفقیت (قدیمی بودن نسخه PHP یا نبود اتصال به دیتابیس)، از تابع mysql_escape_string استفاده می کنه.

$modx->db->escape($string);
$googooli_data = $modx->db->escape($_POST['data']);

()DBAPI :: query: این متد کار تابع mysql_query رو میکنه ولی با کانکشن مادایکس و بدست گیری خطاها توسط مادایکس.

$modx->db->query($query);
$modx->db->query("
	SELECT table.col1 
	FROM table 
	INNER JOIN anotherTable
	WHERE table.someCol = anotherTable.someOtherCol
");

()DBAPI :: select: اجرای دستور SELECT از MySQL و گرفتن خروجی از تابع ()DBAPI :: query.

$modx->db->select($fields="*", $from="", $where="", $orderby="", $limit="");
$select = $modx->db->select('col1', 'table', 'someCol=5', 'col2 ASC', 10);

()DBAPI :: getRow: مشابه تابع mysql_fetch_assoc با کانکشن مادایکس.

$modx->db->getRow($select, $mode='assoc');
$select = $modx->db->select('*', 'table', 'id>5');
while($row = $modx->db->getRow($select)) {
	echo $row['someCol'];
}

()DBAPI :: getRecordCount: مشابه تابع mysql_num_rows با کانکشن مادایکس.

$modx->db->getRecordCount($select);
if($modx->db->getRecordCount($select) == 0)
	echo 'No record found!';

()DBAPI :: delete: اجرای دستور DELETE از MYSQL.

$modx->db->delete($from,$where='',$fields='');
$modx->db->delete('table', 'id=120');

()DBAPI :: insert: اجرای دستور INSERT از MYSQL.

$modx->db->insert($fields, $intotable, $fromfields="*", $fromtable="", $where="", $limit="");
$fields = array(
	'col1' => 'hello',
	'col2' => 'world'
);
$insertId = $modx->db->insert($fields, 'table');

()DBAPI :: update: اجرای دستور UPDATE از MYSQL.

$modx->db->update($fields, $table, $where="");
$fields = array(
	'col1' => 'hello',
	'col2' => 'world'
);
$modx->db->update($fields, 'table', 'id=45');

()DBAPI :: getInsertId: گرفتن آخرین سطر INSERT شده.

$modx->db->getInsertId();
$lastId = $modx->db->getInsertId();

()DBAPI :: getLastError: بدست آوردن آخرین خطای رخ داده مشابه تابع mysql_error.

$modx->db->getLastError();
$select = $modx->db->select('*', 'table');
if(!$select)
	echo $modx->db->getLastError();

()DBAPI :: getColumnNames: دریافت نام ستونها براساس یک دستور resource.

$modx->db->getColumnNames($select);
$columns = $modx->db->getColumnNames( $modx->db->query('SELECT * FROM table LIMIT 1') );

()DBAPI :: getValue: گرفتن اطلاعات وقتی داریم یک رکورد از یک سطر رو انتخاب می کنیم. این متد رو خیلی دوست دارم چون اگر ازش استفاده نکنیم واسه گرفتن یک رکورد باید یکبار آرایه بگیریم و از توش بخونیم.

$modx->db->getValue($select);
$id = $modx->db->getValue( $modx->db->select('id', 'table', 'id=10') ); // $id = 10

توابع دیگه هم وجود داره که در این فایل می تونید پیداشون کنید: manager/includes/extenders/dbapi.mysql.class.inc.php

 

 

مادایکس یه سری SESSION استاندارد موقع لاگین در بخش Front-End داره که شامل موارد مهم زیر هست. در این SESSIONها اگر بجای کلمه "web" اولشون، کلمه "mgr" قرار بدیم، SESSIONهای کاربر میدیریت وارد شده رو میگیریم.
['SESSION['webInternalKey_$: شناسه یا ID کاربر وارد شده.
['SESSION['webValidated_$: تعیین اینکه کاربر لاگین کرده یا نه (یک flag محسوب میشه).
['SESSION['webShortname_$: نام کاربری کاربر وارد شده.
['SESSION['webFullname_$: نام کامل کاربر وارد شده.
['SESSION['webEmail_$: آدرس ایمیل کاربر وارد شده.
['SESSION['webFailedlogins_$: تعداد ورودهای ناموفق کاربر وارد شده (دفعاتی که پسوردش رو اشتباه وارد کرده).
['SESSION['webLastlogin_$: زمان آخرین ورود کاربر بصورت Timestamp.
['SESSION['webDocgroups_$: آرایه حاوی لیست گروههای پرونده که کاربر وارد شده عضوشون هست.
['SESSION['webUserGroupNames_$: آرایه حاوی لیست گروههای کاربری که کاربر وارد شده عضوشون هست.
['SESSION['webUsrConfigSet_$: آرایه حاوی تنظیمات مختص کاربر وارد شده.

 

 

مادایکس یه سری کلاس جداگانه داره که مستقیما ازشون استفاده نمی کنه مثل کلاس ساختن کلمات امنیتی (CAPTCHA) یا کلاس برای صفحه بندی یا ساختن جدول یا ارسال ایمیل یا بدست آوردن جزییات اطلاعات کاربر از قبیل آی پی و مرورگر و غیره که من دو تا مهمترش رو معرفی می کنم.

کلاس VeriWord در آدرس manager/includes/veriword.php امکان ساختن تصاویر امنیتی یا CAPTCHA رو ایجاد می کنه. این فایل خودش کلاس رو اجرا می کنه، تصویر رو به خروجی میفرسته و کلمه امنیتی رو در یک SESSION با کلید veriword به شکل ['SESSION['veriword_$ قرار میده.

$src = MODX_MANAGER_URL .'includes/veriword.php?noCache='. time();
echo '<img src="'. $src .'" alt="captcha" />';
echo $_SESSION['veriword'];

کلاس بعدی، کلاس مهم و خیلی کاربردی PHPMailer هست. این PHPMailer به نظر من بهترین و ساده ترین کلاس برای ارسال ایمیل هست. این کلاس در آدرس manager/includes/controls/class.phpmailer.php قابل دسترسیه که البته نسخه جدیدش رو می تونید از سایت خود PHPMailer هم بگیرید اگر دوست دارید.

include MODX_MANAGER_PATH . 'includes/controls/class.phpmailer.php';
$malier = new PHPMailer;
$mailer->CharSet = 'utf-8';
$mailer->ContentType = 'text/html';
$mailer->From = 'boplo@boplo..ir';
$mailer->FromName = 'Boplo.ir';
$mailer->Subject = 'موضوع ایمیل';
$mailer->Body = '
<!DOCTYPE html>
<html dir="rtl">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
	<p>متن ایمیل</p>
</body>
</html>
';
$mailer->AltBody = 'متن ایمیل';

$mailer->AddAddress('mail1@example.com', 'Mail1 at Example');
$mailer->AddAddress('mail2@example.com', 'Mail2 at Example');
$mailer->AddCC('mail3@example.com', 'Mail3 at Example');
$mailer->AddCC('mail4@example.com', 'Mail4 at Example');
$mailer->AddBCC('mail5@example.com', 'Mail5 at Example');
$mailer->AddBCC('mail6@example.com', 'Mail6 at Example');
$mailer->AddReplyTo('replyto@example.com', 'Reply to Example');

if($mailer->Send()) {
	echo 'Email send successfully!';
} else {
	echo 'Sending email failed!';
}

 

 

به این نکته مهم اشاره کنم که این مقاله به کل درباره نسخه Evolution مادایکس بود. شیوه کدنویسی در نسخه Revolution کاملا عوض شده.

منابع مفید:
• معرفی MODx Evolution (از همین وبلاگ)
• اصطلاحات مادایکس (از همین وبلاگ)
• سایت سیستم مدیریت محتوا و فریم ورک MODx
• بخش راهنمای MODx Evolution (به زبان انگلیسی و به روز)

 

 

موفق باشید
امیرحسین

•  
•  
•  
•  
•  
•  
•  

امیرحسینم. اسمم رو دوست دارم، خودم رو دوست دارم. تهران زندگی می کنم. فارغ التحصیل مهندسی صنایع هستم. برنامه‌نویسی و طراحی وب می کنم. در واقع Web Developer محسوب میشم. برنامه نویسی و وقت گذرونی با وب تنها کاریه که خسته ام نمی کنه.
آدم خیلی سردی هستم، اینو دور و وری هام میگن. ولی به نظر خودم سرد نیستم در واقع گرمای خودم رو کم بروز می دم! آدما رو اغلب دوست دارم غیر از اون مواقعی که اونا من رو نادیده میگیرن!

این سایت رو بعد از کلی اینور اونور دوباره راه انداختم تا هرچی دوست دارم توش بنویسم، چه کسی بخونه چه نخونه.
خلاصه اینجا خونه منه،

به خونه امیرحسین خوش اومدی...