آموزش ایجاد هوک

[محمد عنبرستانی 207]

این آموزش در واقع ترجمه ای از آموزش موجود در سایت IPS برای توسعه دهندگان هستش که به مرور در همین تاپیک قرار می گیره لذا از ارسال پست در این تاپیک خودداری کنید!

منبع: https://www.invisionpower.com/support/guides/_/advanced-and-developers/hooks/start-here-creating-a-hook-r40

 

امیدوارم این مطلب برای شما عزیزان مفید باشه.

 

مقدمه

 

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

 

امکاناتی که هوک پیش روی شما خواهند گذاشت عبارتند از:

• افزایش یک کارایی یک فایل عملگر (فایل که در پوشه های modules_public یا modules_admin قرار دارد)
• افزایش یک کارایی پوسته
• افزودن کد های HTML به پوسته
• افزودن فایلهای جدید پوسته یا CSS
• افزودن یا تغییر داده قبل از آنکه مورد استفاده قرار گیرد
• گسترش کلاس های کتابخانه هایی که در آي پی بورد مورد استفاده اند
• افزودن تنظیمات
• افزودن رشته های زبانی (متن ها و کلمات)
• افزودن ماژول ها به یک نرم افزار موجود
• افزودن فایل های راهنما
• اجرای وظایف زمانبدی شده
• اجرای کوئری های SQL در هنگام نصب برای ایجاد جداول

همان طور که می بینید هوک ها در ایجاد امکانات دلخواه و سفارشی سازی بیسار مفید و قدرتمند هستند، حال وقتی بدانیم ایجاد آنها به سادگی ایجاد یک فایل XML می باشد این موضوع جلوه ی بیشتری خواهد داشت. شما می توانید هوک ها را بسادگی به کمک پنل مدیریت نصب کنید و از آن ساده تر آنها را مدیریت کنید.

[محمد عنبرستانی 207]

دست بکار شوید

 

قبل از هرچیزی لازم است حالت توسعه را در آی پی بوردتان فعال کنید.

حال وارد پنل شده و مسیر زیر را طی کنید:

Admin CP --> System --> Manage Hooks

بر روی Create New Hook کلیک کنید.

فرم را آن طور که می خواهید پر کنید در سربرگ Requirements می توانید حداقل و حداکثر ورژن پشتبانی شده ی PHP را که هوک شما با آن کار می کند را وارد کنید همچنین برای سایر نرم افزار های مورد نیاز مانند IP.Calendar ، IP.Board و... . برای آي پی بورد در قسمت Additional Application گزینه System را انتخاب کنید. در سربرگ Global Caches می توانید ذخیره ساز هایی را که به صورت کلی در هر صفحه ای اجرا می شوند را انتخاب کنید. در این مورد با آگاهی عمل کنید گرچه اگر هوک شما از ذخیره ساز (cache) خاصی استفاده می کنند  و در تمام صفحات اجرا می شود و آن را مورد استفاده قرار می دهد این گزینه آن را قادر به اجرا در runtime همراه با سایر ذخیره ساز ها برای ذخیره سازی یک کوئری پایگاه داده خواهد کرد.

 

در همین مرحله هوک خود را ذخیره کنید تا در آموزش بعدی بتوانبد با ویرایش، مراحل افزودن فایل ها را طی کنید.

[محمد عنبرستانی 207]

فایل های هوک

 

فایل های هوک شامل کد های PHP هوک شما هستند. هر هوک می تواند شامل تعداد بی نهایتی از این فایل ها باشد. فایل های هوک شما در پوشه hooks در root آی پی بورد شما قرار قرار می گیرند.

 

انواع فایل های هوک:

 

• تشدید کننده های عملکرد (Action Overloaders)

این فایل ها شما را در گسترش فایل های عملگر (فایلی که در پوشه modules_public یا modules_admin قرار داشته باشد) برای نادیدگرفتن (override) متد ها (methods) یاری خواهند کرد.

• افزاینده های کارایی قالب (Skin Overloaders)

به شما در گسترش یک گروه الگو پوسته (skin template) برای نادیده گرفتن هر الگویی یاری خواهند گرد.

• هوک های قالب (Template Hooks)

به شما در اضافه کردن کد به یک قالب یاری خواهند رساند.

• هوک های داده (Data Hook)

این فایل ها به طور معمول با ارائه یک آرایه از اطلاعات به یک هوک معین قبل از ثبتشان در پایگاه داده، موجب تغییر در داده ها قبل از مورد استفاده قرار گرفتن آنها می شوند.

• هوک های کتابخانه (Library Hook)

به شما در گسترش یک کلاس کتابخانه برای افزودن یا نادیده گرفتن متد ها یاری می رسانند.

 

 

مفاهیم بالا برای درک کامل فایل های هوک کافی نیست و بزودی به طور مفصل مورد بحث قرار خواهند گرفت.

 

سایر آيتم ها:

 

سایر آيتم هایی که می توانید به هوک خود اضافه کنید تا در انتها آنها را نیز همراه با آن استخراج (exporting) کنید عبارتند از:

 

• تنظیمات
• رشته های زبانی
• ماژول ها
• فایل های راهنما
• الگو های قالب
• فایل های CSS
• وظایف

استخراج هوک

 

پس اتمام کارهای ایجاد هوک می توانید به راحتی آن را در مسیر زیر به کمک انتخاب گزینه Export Hook از قسمت کناری هوک استخراج کنید.

Admin CP --> System --> Manage Hooks

حالا شما وارد صفحه ای می شوید که می توانید با انتخاب سایر آيتم های افزوده شده به هوک خود آن را استخراج کنید. (انتخاب آيتم های اضافی اختیاریست و بستگی به انتخاب شما دارد که چه چیزهایی برای هوک شما لازم است.)

 

تغییرات در پایگاه داده

 

شما می توانید در صورت لزوم تغییرات لازم پایگاه داده را برای نصب هوک خود، همراه با آن استخراج کنید تا در سایت های مقصد اعمال شوند.

برای این امر گزینه Add Database Changes را بزنید تا بتوانید بخش های تغییر یافته مورد نظرتان از پایگاه داده که لازم است ایجاد شوند یا بروز شوند و ... را انتخاب کنید. اگر کاربر هوک شما را حذف کنید این تغییرات همراه با هوک شما حذف خواهند شد.

 

اسکریپت های سفارشی

 

گاهی اوقات در مراحل نصب یا حذف هوک لازم است اسکریپتی اجرا شود که بصورت پیشفرض تحت پوشش سیستم نیست و می بایست خودتان آن را اضافه کنید. برای انجام این کار فایل php خود را پوشه hooks با عنوان install_KEY ایجاد کنید. توجه داشته باشید در عبارت عنوان کلمه KEY کلیدیست که به دلخواه انتخاب می کنید. این فایل باید شامل یک کلاس هم نام کلیدی که در نام فایل قرار دارد و دو متد (methods)، یکی install که در زمان نصب اجرا خواهد شد و دیگری uninstall که هنگام حذف هوک اجرا خواهد شد. در نسخه های جدید آي پی بورد (نسخه ۳.۳ به بعد) دو متد دیگر نیز مورد پشتیبانی هستند، یکی pre_install که قبل از آنکه از هوک چیزی به انجمن افزوده شود، اجرا می شود و دیگری pre_uninstall که قبل از شروع عملیات حذف، اجرا خواهد شد. پس از ایجاد این فایل، در هنگام استخراج باید این فایل را برای استخراج همراه با سایر اجزای هوک انتخاب کنید برای این کار روی Add Custom Script کلیک کنید و کلیدی که قبلا در نام فایل استفاده کرده اید را وارد کنید.

[محمد عنبرستانی 207]

هوک های قالب (Template Hooks)

 

یکی از پر استفاده ترین انواع هوک ، هوک های قالب هستند. به کمک این فایل نوع فایل ها به هوک خود می توانید کد های دلخواه خود را به قالب های موجود اضافه کنید. تمام قالب های آی پی بورد دارای  hook points هستند که در قسمت پایین توضیح داده خواهند شد و شما به کمک هوک قالب می توانید کد های HTML خود را در این hook points ها قرار دهید که در نتیجه می توانید در صفحه های سایت تغییر ایجاد کنید.

 

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

 

تقریبا تمام دستور های If و foreach در قالب یک بخش هوک به شمار می آیند. به مثال زیر از بخش skin_global --> userInfoPane دقت کنید:

<if test="ismember:|:$author['member_id']">
...
<foreach loop="customFieldsOuter:$author['custom_fields'] as $group => $data">

هر دوی آنهای بخش های هوکی هستند. نام این بخش های هوکی با کلید آنها که به ترتیب ismember و customFieldsOuter است، تعریف می شود. اگر شما نرم افزاری را توسعه می دهید و لازم دارید در قالب شخصی خودتان بخش های هوکی تعریف کنید لازم است بدانید سینتکس (syntax) تعریف بخش هوکی برای شروط IF و حلقه های Foreach متفاوت است. در if ها برای جدا کردن شناسه بخش هوکی از : |: استفاده می شود اما برای foreach ها از : استفاده می شود. توجه داشته باشید تعیین بخش های هوکی در قالب امر اختیاریست و تحلیلگر قالب (parser) ، پوسته بدون وجود آنها نیز تحلیل و اجرا می کند.

 

برای ایجاد هوک قالب وارد پنل شده و سربرگ System را انتخاب کنید سپس Manage Hooks و پس از آن Create Hook را بزنید. در سربرگ Files ، یک فایل و یک نام کلاس انتخاب کنید سپس در قسمت File hook type گزینه Template Hookرا انتخاب کرده پس از آن پوسته ای که می خواهید هوک را وارد آن کنید انتخاب کنید حال تابع(function) ای را که بخش هوکی مورد نظر در آن قرار دارد را انتخاب کنید اکنون انتخاب کنید نوع بخش هوکی از نوع دستور if است یا foreach و سپس شناسه بخش هوکی مورد نظرتان را انتخاب کنید.

نکته ۱: توجه کنید اگر شما در حال توسعه یک نرم افزار شخصی بر روی لوکال هستید و شناسه بخش هوکی ای که ایجاد کرده اید در لیست موجود نیست احتمالا پوسته قالب (skin templates) خود را از طریق بخش Template Tools وارد پایگاه داده نکرده اید.

در انتها شما باید محل قرار گرفتن کد هایتان را نسبت به بخش هوکی انتخاب کنید (before the if statement, after the if statement, inside the if statement و...) توجه داشته باشید اگر برای مثال کد های هوک خود را در یک شرط if قرار می دهید و اگر آن شرط برقرار نشود (false شود) هوک شما به نمایش در نخواهد آمد همچینین اگر کد هوک را در یک حلقه foreach قرار می دهید کد شما برای هر تکرار آن حلقه به نمایش در خواهد آمد یا اجرا می شود. این نکات را همیشه در ذهن داشته باشید.

 

پس از تعیین فایل هوک قالب(template hook) شما باید یک فایل در پوشه hooks واقع در root انجمن خود ایجاد کنید با نامی دلخواه که این فایل شامل یک کلاس با نام دلخواه که خود این کلاس باید شامل یک متد با نام getOutput (که می بایست کد را برای نمایش بازگرداند) باشد. البته می توانید یک متد دلخواه دیگر به نام replaceOutput (که محتوای قالب را می پذیرد و به شما اجازه می دهد در آن تغییرات ایجاد کنید) اضافه کنید.

نکته: getOutput() اجباریست ولی replaceOutput() اختیاریست.

 

مثال زیر کد های یک هوک برای نمایش آدرس IP کاربران در پروفایلشان به مدیران ارشد(global moderators) و مدیران کل (administrators) را نشان میدهد. الگویی که پروفایل را نمایش می دهد profileModern است که در گروه الگو های skin_profile می باشد. این همان بخشی است که اطلاعات کاربر را به نمایش می گذارد( تاریخ عضویت و...):

			<dl>
				<dt>{$this->lang->words['m_group']}</dt>
				<dd>{$member['g_title']}</dd>
				<dt>{$this->lang->words['m_posts']}</dt>
				<dd title='{$member['_total_pct']}% {$this->lang->words['total_percent']}'>{parse format_number="$member['posts']"} ({$member['_posts_day']} {$this->lang->words['posts_per_day']})</dd>
				<if test="favoriteForum:|:!$this->settings['disable_profile_stats'] AND $member['favorite_id']">
					<dt>{$this->lang->words['m_active_in']}</dt>
					<dd title='{$member['_fav_percent']}% {$this->lang->words['fav_percent']}'>
						<a href='{parse url="showforum={$member['favorite_id']}" seotitle="{$this->registry->class_forums->forum_by_id[ $member['favorite_id'] ]['name_seo']}" template="showforum" base="public"}'>{$this->registry->class_forums->forum_by_id[ $member['favorite_id'] ]['name']}</a> ({$member['_fav_posts']} {$this->lang->words['fav_posts']})
					</dd>
				</if>
				<dt>{$this->lang->words['m_member_since']}</dt>
				<dd>{parse date="$member['joined']" format="joined"}</dd>
				<dt>{$this->lang->words['m_profile_views']}</dt>
				<dd>{parse format_number="$member['members_profile_views']"}</dd>
				<dt>{$this->lang->words['m_last_active']}</dt>
				<dd><if test="memberOnline:|:$member['_online']">{parse replacement="user_online"}<else />{parse replacement="user_offline"}</if> {$member['_last_active']}</dd>
				<dt>{$this->lang->words['m_currently']}</dt>
				<dd><if test="onlineDetails:|:$member['_online']">
						{$member['online_extra']}
					<else />
						{$this->lang->words['online_offline']}
					</if>
				</dd>
			</dl>

در این لیست یک بخش هوکی (favoriteForum) وجود دارد که می توانم به کمک آن به این لیست بیافزایم.

در پنل مدیریت هوک قالب خودم را مانند تصویر زیر تنظیم کرده ام:

 

حال فایلی به نام ipInProfiles.php را در پوشه hooks با محتوای زیر ایجاد می کنم:

<?php

class ipInProfiles
{
	public function getOutput()
	{

	}
}

حال می بایست به کمک getOutput کدی که می خواهم در قالب (الگو) قرار گیرد را بازگردانم. کلاسی که نوشته ام به صورت زیر خواهد شد:

class ipInProfiles
{
	public function getOutput()
	{
		$member = ipsRegistry::instance()->member()->fetchMemberData();;

		$profile = ipsRegistry::instance()->output->getTemplate('profile')->functionData['profileModern'][0]['member'];

		if ( $member['g_access_cp'] or $member['g_is_supmod'] )
		{
			return <<<HTML
			<dt>IP Address</dt>
			<dd>{$profile['ip_address']}</dd>
HTML;
		}

		return '';
	}
}

نکته: می توانم به کمک متغییر ipsRegistry::instance()->output->getTemplate('global')->functionData به متغییر هایی که به قالب اصلی داده شده دسترسی داشته باشم. اولین کلید آرایه نام تابع ، دومی نمونه ایست که این قالب به آن فراخوانده شده (اگر تابع ۱۰ بار فراخوانی شود، ۰-۹ کلید آرایه در عمق دوم وجود خواهد داشت)، و سومین کلید آرایه نشانگر متغییر بر اساس نشان الگو پوسته (skin template signature) است.

function profileModern( $tabs=array(), $member=array(), $visitors=array(), $default_tab='status', $default_tab_content='', $friends=array(), $status=array(), $warns=array() ) {

'member' در مثال قبل به آرگومان دوم بعنی $member مرتبط است در حالی که 'default_tab' به آرگومان چهارم یعنی $default_tab مربتط است و به همین صورت برای بقیه.

 

همان طور که دیدید بدون تغییر دستی قالب می توانید به کمک هوک قالب کد های خودمان را در قالب جای دهیم.

 

متد replaceOutput() به طور مشابه شما را قادر به تغییر در خروجی صفحه بدون ایجاد تغییر در قالب می کند اما این متد برای وظایف مکرر(مانند قرار دادن یک دکمه برای هر پست در یک موضوع(تاپیک)) کاربرد بیشتری دارد. در IP.Content هوکی وجود دارد که به کمک متد replaceOutput() یک دکمه (کلید) با نام "Promote To Article" را به هر پست برای کاربرانی که اجازه استفاده از آن را دارند اضافه می کند. کد هوک در قسمت پایین موجود است:

<?php

class contentPromoteToArticle
{
	/**
	 * Registry object
	 *
	 * @var		object
	 */	
	protected $registry;

	/**
	 * Constructor
	 *
	 * @return	@e void
	 */
	public function __construct()
	{
		$this->registry	= ipsRegistry::instance();
	}

	/**
	 * Get the output
	 *
	 * @return	string
	 */
	public function getOutput()
	{
	}

	/**
	 * Replace output
	 *
	 * @param	string		Output
	 * @param	string		Hook key
	 * @return	string		Output parsed
	 */
	public function replaceOutput( $output, $key )
	{
		if( is_array($this->registry->output->getTemplate('topic')->functionData['post']) AND count($this->registry->output->getTemplate('topic')->functionData['post']) )
		{
			if( !$this->registry->isClassLoaded('articles') )
			{
				$classToLoad = IPSLib::loadLibrary( IPSLib::getAppDir( 'ccs' ) . '/sources/promote.php', 'promoteArticle', 'ccs' );

				$this->registry->setClass( 'articles', new $classToLoad( ipsRegistry::instance() ) );
			}

			$tag	= '<!--hook.' . $key . '-->';
			$last	= 0;

			foreach( $this->registry->output->getTemplate('topic')->functionData['post'] as $_post )
			{
				$pos	= strpos( $output, $tag, $last );

				if( $pos AND !$_post['post']['post']['_isDeleted'] AND !$_post['topic']['_isArchived'] )
				{
					$pid	= $_post['post']['post']['pid'];
					$string	= $this->registry->articles->getPostHook( $pid );
					$output	= substr_replace( $output, $string . $tag, $pos, strlen( $tag ) );
					$last	= $pos + strlen( $tag . $string );
				}
			}
		}

		return $output;
	}
}

همان طور که می بینید متد replaceOutput() دو آرگومان را می پذیرد:

• آرگومان اول خروجی کامل قالب است.
• آرگومان دوم کلید هوکی است که هوک قالب بدنبال آن است.

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

 

این بخش از مطلب ادامه دارد و هنوز تکمیل نشده!