ابزار سایت

معرفی_کلاس_ها_و_توابع_مهم_در_موتوشاب

تفاوت‌ها

تفاوت دو نسخهٔ متفاوت از صفحه را مشاهده می‌کنید.

پیوند به صفحه‌ی تفاوت‌ها

معرفی_کلاس_ها_و_توابع_مهم_در_موتوشاب [2019/01/15 12:45] (فعلی)
خط 1: خط 1:
 +====== فصل 6- معرفی کلاس‌ها و توابع مهم در موتوشاب ======
  
 +در این بخش به شرح و معرفی کلاس‌ها و توابع مهم در موتوشاب پرداخته شده است. این بخش در حقیقت مرجع توسعه‌دهندگان موتوشاب برای فراگیری قابلیت‌هایی است که هسته موتوشاب در اختیار آن‌ها قرار داده است.
 +
 +===== 6-1- OW_EventManager =====
 +
 +از کلاس مذکور برای مدیریت رویدادهای سامانه استفاده می‌شود. برای مثال رویداد ورود کاربر به سامانه (با وارد نمودن نام کاربری و رمز ‌عبور خود) و یا رویداد خروج کاربر از سامانه و غیره در این کلاس مدیریت می‌شود.
 +
 +==== 6-1-1- bind ====
 +
 +با استفاده از این تابع، می‌توان یک تابع را به یک رویداد الصاق کرد. در این صورت هنگام رخداد رویداد مذکور، تابع مذکور نیز فراخوانی می‌شود. برای مثال در کد زیر:
 +
 +
 +#;;
 +<code php>
 +OW::​getEventManager()->​bind(IISEventManager::​ON_BEFORE_VALIDATING_FIELD,​ array($this,​ '​onBeforeValidatingField'​));​
 +</​code>​
 +#;;
 +
 +تابع onBeforeValidatingField به رویداد IISEventManager::​ON_BEFORE_VALIDATING_FIELD الصاق شده است. در این صورت هنگام رخداد این رویداد، تابع مذکور فراخوانی خواهد شد. تابع bind دارای سه ورودی بوده که عبارت‌اند از نام رویداد تعریف‌شده <wrap :​en>​($name)</​wrap>​، نام تابع <wrap :​en>​($callback)</​wrap>​ و اولویت اجرای تابع <wrap :​en>​($priority)</​wrap>​.
 +==== 6-1-2- trigger ====
 +
 +این تابع یک ورودی از نوع رویداد (OW_Event) گرفته و آن را اجرا می‌کند.
 +
 +#;;
 +<code php>
 +$yearChangedEvent = OW::​getEventManager()->​trigger(new OW_Event(IISEventManager::​ON_BEFORE_VALIDATING_FIELD,​ array('​field'​ => $element, '​data'​ => $data)));
 +</​code>​
 +#;;
 +
 +کد بالا تابع الصاق شده به رویداد ON_BEFORE_VALIDATING_FIELD را با پارامترهای ورودی مربوط به رویداد اجرا می‌کند. در بخش بعد بیشتر درباره کلاس OW_Event و پارامترهای ورودی آن توضیح داده خواهد شد.
 +
 +===== 6-2- OW_Event =====
 +
 +توابع اصلی و پایه‌ای یک رویداد در این کلاس تعریف شده است. توابع مهم این کلاس در ادامه توضیح داده شده‌است:​
 +
 +==== 6-2-1- ​ تابع سازنده ====
 +
 +تابع سازنده OW_Event به شرح زیر است:
 +
 +#;;
 +<code php>
 +public function __construct( $name, array $params = array(), $dataValue = null )
 +</​code>​
 +#;;
 +
 +<wrap :​en>​name$</​wrap>​ نام رویداد، <wrap :​en>​params$</​wrap> ​ آرایه‌ای از پارامترهای ورودی و  <wrap :​en>​dataValue$</​wrap>​ نیز داده‌های پردازش‌شده ارسالی به خروجی است.
 +
 +**نکته:​** توابع set و get مربوط به سه پارامتر ورودی تابع بالا در کلاس مذکور تعریف شده‌اند. برای مثال شبه کد زیر:
 +
 +#;;
 +<code php>
 +OW_Event $event;
 +$params = $event->​getParams();​
 +</​code>​
 +#;;
 +
 +پارامترهای داده‌شده ‌(params$) به رویداد مورد نظر را برمی‌گرداند.
 +===== 6-3- OW_CONFIG =====
 +
 +هدف از این کلاس کار با تنظیمات سیستمی موتوشاب است که عموما در جدول ow_base_config ذخیره شده‌اند. در ادامه به توابع مهم این کلاس اشاره شده است.
 +
 +==== 6-3-1- generateCache ====
 +
 +از این تابع برای سپردن کلیه تنظیمات سیستم (جدول ow_base_config) به حافظه نهان به منظور افزایش سرعت و کارایی استفاده می‌شود.
 +
 +**نکته:​** به طور کلی پس از هر بار تغییر در جدول ow_base_config با فراخوانی توابع حذف، ایجاد و یا به‌روزرسانی (که در ادامه به توضیح مفصل این توابع پرداخته شده است)، این تابع به صورت خودکار در انتهای توابع مذکور فراخوانی می‌شود. در نتیجه توسعه‌دهنده در اغلب موارد نیازی به استفاده از این تابع ندارد.
 +
 +==== 6-3-2- addConfig ====
 +
 +هدف از این تابع اضافه‌کردن تنظیمات جدید به تنظیمات موجود در جدول ow_base_config است. تابع مذکور به ترتیب چهار ورودی نام افزونه <wrap :​en>​($key)</​wrap>​، نام تنظیم مورد نظر <wrap :​en>​($name)</​wrap>​، مقدار تنظیم <wrap :​en>​($value)</​wrap>​ و توضیحات مربوط به تنظیم <wrap :​en>​($description)</​wrap>​ که اختیاری بوده را دارا است. به عنوان مثال:
 +
 +#;;
 +<code php>
 +$config = OW::​getConfig();​
 +$config->​addConfig('​iisjalali',​ '​dateLocale',​1);​
 +</​code>​
 +#;;
 +
 +برای افزونه iisjalali تنظیم dateLocale مقدار 1 را وارد جدول بالا می‌کند. در نتیجه همان‌طور که مشخص است برای هر تنظیم می‌بایست نام افزونه مرتبط با آن نیز مشخص شود.
 +
 +==== 6-3-3- deleteConfig ====
 +
 +هدف از این تابع حذف نمودن تنظیمی از تنظیمات موجود در جدول ow_base_config است. این تابع دو ورودی به ترتیب نام افزونه <wrap :​en>​($key)</​wrap>​ و نام تنظیم مورد نظر <wrap :​en>​($name)</​wrap>​ را گرفته و تنظیم مورد نظر را حذف می‌کند. به عنوان مثال:
 +
 +#;;
 +<code php>
 +OW::​getConfig()->​deleteConfig('​mailbox',​ '​results_per_page'​);​
 +</​code>​
 +#;;
 +
 +برای افزونه mailbox تنظیم results_per_page را از جدول ow_base_config حذف می‌کند.
 +
 +==== 6-3-4- getValue و getValues ====
 +
 +هدف از این توابع استخراج نمودن تنظیمی‌ (تنظیماتی) از تنظیمات موجود در جدول ow_base_config است. برای مثال تابع getValue با گرفتن دو پارامتر ورودی نام افزونه <wrap :​en>​($key)</​wrap>​ و نام تنظیم <wrap :​en>​($name)</​wrap>​ مقدار تنظیم انجام شده را بر می-گرداند. مثال:
 +
 +#;;
 +<code php>
 +OW::​getConfig()->​getValue('​iisjalali',​ '​dateLocale'​)
 +</​code>​
 +#;;
 +
 +==== 6-3-5- configExists ====
 +
 +هدف از این تابع بررسی وجود تنظیمی از بین تنظیمات موجود در جدول ow_base_config است که به ترتیب دو ورودی نام افزونه <wrap :​en>​($key)</​wrap>​، نام تنظیم مورد نظر <wrap :​en>​($name)</​wrap>​ را گرفته و موجودیت تنظیم مورد نظر را بررسی می‌کند.
 +
 +مثال کد زیر در صورت عدم وجود تنظیم dateLocale آن را اضافه می‌کند.
 +
 +#;;
 +<code php>
 +if ( !$config->​configExists('​iisjalali',​ '​dateLocale'​) )
 +{
 +    $config->​addConfig('​iisjalali',​ '​dateLocale',​1);​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-3-6- saveConfig ​ ====
 +
 +هدف از این تابع به‌روزرسانی تنظیم مورد نظر در جدول ow_base_config است.‌ تفاوت اصلی این تابع با تابع addConfig این است که در saveConfig هدف تنها به‌روزرسانی تنظیم مورد نظر است که حتما می‌بایست از قبل وجود داشته باشد و در صورت عدم وجود پیغام خطا نمایش داده می‌شود. این تابع به ترتیب سه ورودی نام افزونه <wrap :​en>​($key)</​wrap>​، نام تنظیم مورد نظر <wrap :​en>​($name)</​wrap>​ و مقدار تنظیم <wrap :​en>​($value)</​wrap>​ را گرفته و به‌روزرسانی را انجام می‌دهد.
 +
 +#;;
 +<code php>
 +$config->​saveConfig('​iisjalali',​ '​dateLocale',​ $form->​getElement('​dateLocale'​)->​getValue())
 +</​code>​
 +#;;
 +
 +کد بالا تنظیم dateLocale مربوط به افزونه iisjalali را به‌روزرسانی می‌کند.
 +
 +بسیاری از توابع کاربردی موتوشاب در این کلاس تعریف می‌شوند.
 +
 +==== 6-4-1- getConfig ====
 +
 +این تابع یک شیء از کلاس Config که شامل تنظیمات موجود در جدول ow_base_config است را ساخته و ارائه می‌کند.
 +
 + ​$config = OW::​getConfig();​
 +
 +در حقیقت این کلاس واسط ارتباطی با جدول ow_base_config و تمامی تنظیمات سامانه است.
 +
 +==== 6-4-2- getSession ====
 +
 +یک نمونه از کلاس Session که شامل تنظیمات مربوط به نشست بوده را ساخته و بر می‌گرداند. در حقیقت شیء برگردانده‌شده واسط ارتباطی با نشست کاربر است.
 +
 +==== 6-4-3- getUser ====
 +
 +یک نمونه از کلاس User که مربوط به کاربر فعلی را ساخته و ارائه می‌کند.
 +
 +==== 6-4-4- getDbo ====
 +
 +دسترسی به پایگاه داده با تنظیمات پیش‌فرض با استفاده از فراخوانی این تابع انجام می‌شود. کاربرد بسیار مهم این تابع در هنگام نصب افزونه‌ها برای ایجاد جداول لازم برای آن‌ها در فایل install.php این افزونه‌ها است؛ مانند کد زیر برای ایجاد جدول برای افزونه تولد:
 +#;;
 +<code php>
 +OW::​getDbo()->​query("​
 +CREATE TABLE IF NOT EXISTS `" . OW_DB_PREFIX . "​birthdays_privacy` (
 +  `id` int(11) NOT NULL auto_increment,​
 +  `userId` int(11) NOT NULL,
 +  `privacy` varchar(32) NOT NULL,
 +  PRIMARY KEY  (`id`),
 +  UNIQUE KEY `userId` (`userId`)
 +) ENGINE=MyISAM ​ DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;"​);​
 +</​code>​
 +#;;
 +
 +==== 6-4-5- getLanguage ​ ====
 +
 +یک نمونه از کلاس Language که مربوط به تنظیمات زبان سامانه است را ساخته و ارائه می‌کند.
 +
 +==== 6-4-6- getPluginManager ====
 +
 +یک نمونه از کلاس Plugin Manager که مربوط به مدیریت افزونه‌های سامانه است را ساخته و ارائه می‌کند.
 +
 +==== 6-4-7- geThemeManager ====
 +
 +یک نمونه از کلاس ThemeManager که مربوط به مدیریت تصاویر پس‌زمینه و نمای گرافیکی سامانه است را ساخته و ارائه می‌کند.
 +
 +==== 6-4-8- getEventManager ====
 +
 +یک نمونه از کلاس Event Manager که مربوط به مدیریت رویدادهای سامانه است را ساخته و ارائه می‌کند.
 +
 +==== 6-4-9- getRouter ====
 +
 +یک نمونه از کلاس Router که مسئول یافتن کنترل‌کننده ​ و عملیات ​ مناسب است را ساخته و ارائه می‌کند.
 +
 +==== 6-4-10- تابع getRequest ====
 +
 +یک نمونه از کلاس Request ساخته و ارائه می‌کند.
 +
 +==== 6-4-11- تابع getDocument ====
 +
 +با استفاده از این تابع می‌توان به اجزای صفحه HTML سامانه دسترسی داشت. برای مثال عموما کدهای جاوااسکریپتی که برای افزونه‌ها نوشته می‌شود در مسیر ثابت <wrap :​en>​static/​js/​{code_name.js}</​wrap>​ مربوط به آن افزونه قرار می‌گیرد، فایل مذکور به صورت زیر قابل دسترسی است:
 +
 +#;;
 +<code php>
 +$jsDir = OW::​getPluginManager()->​getPlugin('​iisjalali'​)->​getStaticJsUrl();​
 +OW::​getDocument()->​addScript($jsDir.'​iisjalali.js'​);​
 +</​code>​
 +#;;
 +
 +===== 6-5- Language =====
 +
 +
 +با استفاده از این کلاس می‌توان به برخی توابع پرکاربرد مربوط به متون سامانه از قبیل واردسازی عبارت‌های لازم برای یک افزونه در سامانه، نمایش عبارات مورد نیاز برای استفاده در زبان جاوااسکریپت به آن منتقل نمود.
 +
 +==== 6-5-1- text ====
 +
 +تابع مورد نظر سه ورودی عبارت از نام افزونه‌ای که متن می‌بایست از آن استخراج شود <wrap :​en>​($prefix)</​wrap>​ و همچنین نام متن مورد نظر ​
 +<wrap :​en>​($key)</​wrap>​ و همچنین آرایه‌ای از پارامترهای ورودی پویا به متن برای نمایش <wrap :​en>​($vars)</​wrap>​ را گرفته و متن مورد نظر را نمایش می‌دهد. به عنوان مثال کد زیر متن مربوط به افزونه iisjalali با کلید date_locale_jalali_format را برمی‌گرداند.
 +
 +#;;
 +<code php>
 +OW::​getLanguage()->​text('​iisjalali',​ '​date_locale_jalali_format'​)
 +</​code>​
 +#;;
 +
 +==== 6-5-2- valueExist ​ ====
 +
 +تابع فوق با گرفتن دو ورودی نام افزونه‌ای که متن می‌بایست از آن استخراج شود و همچنین نام متن مورد نظر، بررسی می-کند که آیا متن مورد نظر وجود دارد یا خیر. برای مثال:
 +
 +#;;
 +<code php>
 +if ( OW::​getLanguage()->​valueExist('​base',​ "​local_page_meta_tags_{$this->​getDocumentKey()}"​) )
 +{
 +    OW::​getDocument()->​addCustomHeadInfo(OW::​getLanguage()->​text('​base',​ "​local_page_meta_tags_{$this->​getDocumentKey()}"​));​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-5-3- addKeyForJs ​ ====
 +
 +تابع فوق با گرفتن نام افزونه‌ای که متن می‌بایست از آن استخراج شود و همچنین نام متن مورد نظر، متن لازم را در هنگام بارگذاری برای استفاده کدهای جاوااسکریپت در اختیار آن قرار می‌دهد. برای مثال:
 +
 +
 +#;;
 +<code php>
 +OW::​getLanguage()->​addKeyForJs('​iispasswordstrengthmeter',​ '​strength_poor_label'​);​
 +</​code>​
 +#;;
 +
 +پس از فراخوانی کد بالا عبارت مربوط به افزونه iispasswordstremgthmeter با کلید strength_poor_label در جاوااسکریپت قابل استفاده است.
 +نکته: فایل ow.js دارای توابعی برای استفاده از متون در جاوااسکریپت است. به عنوان مثال متناظر با تابع text از کلاس Language تابعی با نام getLanguageText نیز تعریف شده است؛ بنابراین خواندن تنظیم کد بالا در یک کد جاوااسکریپت و با استفاده از توابع ow.js به صورت زیر انجام می‌شود.
 +
 +#;;
 +<code php>
 +OW.getLanguageText('​iispasswordstrengthmeter',​ '​strength_poor_label'​);​
 +</​code>​
 +#;;
 +
 +==== 6-5-4- importPluginLangs ====
 +
 +تابع فوق عموما در هنگام نصب افزونه‌های سامانه در فایل install.php مربوط به افزونه‌ و به منظور واردسازی عبارات زبان افزونه فراخوانی می‌شود مانند کد زیر که برای اضافه‌سازی زبان افزونه «birthdays» فراخوانی شده است:
 +
 +#;;
 +<code php>
 +OW::​getLanguage()->​importPluginLangs(OW::​getPluginManager()->​ getPlugin('​birthdays'​)->​getRootDir() . '​langs.zip',​ '​birthdays'​);​
 +</​code>​
 +#;;
 +
 +===== 6-6- Router =====
 +
 +کلیه مسیریابی‌ها از قبیل مسیریابی مربوط به کنترل‌کننده‌ها و یا عملیات‌ مورد نیاز در این کلاس تعریف می‌شوند.
 +
 +==== 6-6-1- سازنده ====
 +
 +تابع سازنده پنج ورودی: نام مسیر، آدرس مسیر، نام کنترل‌کننده، نام تابع لازم برای تنظیمات اولیه‌ (همان تابع عملیات ) و آرایه‌ای از پارامترهای ورودی انتخابی را گرفته و مسیر مورد نظر را می‌سازد مانند کد زیر:
 +
 +
 +#;;
 +<code php>
 +new OW_Route('​iisjalali_admin_config',​ '​iisjalali/​admin',​ '​IISJALALI_CTRL_Admin',​ '​index'​) ​
 +</​code>​
 +#;;
 +
 +==== 6-6-2- addRoute ====
 +
 +مسیر ساخته‌شده در قسمت قبل با استفاده از این تابع برای استفاده به router اضافه می‌شود:​
 +
 +
 +#;;
 +<code php>
 +OW::​getRouter()->​addRoute(new OW_Route('​iisjalali_admin_config',​ '​iisjalali/​admin',​ '​IISJALALI_CTRL_Admin',​ '​index'​));​
 +</​code>​
 +#;;
 +
 +
 +کلیه توابع لازم جهت نمایش فرم‌های موجود در سامانه که برای ورود اطلاعات از کاربران مورد استفاده قرار می‌گیرد، در این کلاس تعریف شده‌است.
 +
 +==== 6-7-1- سازنده Form ====
 +
 +تابع فوق با گرفتن یک ورودی نام فرم مورد نظر، آن را ایجاد می‌کند.
 +==== 6-7-2- setAjax ====
 +
 +در صورتی که فرم مورد نظر به صورت Ajax باشد این تابع با مقدار true فراخوانی می‌شود‌‌، در غیر این صورت با مقدار false فراخوانی می‌شود.
 +
 +==== 6-7-3- setAjaxResetOnSuccess ====
 +
 +با استفاده از این تابع تعیین می‌شود که فرم مورد نظر پس از فراخوانی پاک‌سازی شود و به حالت اولیه برگردد یا خیر. در صورت عدم نیاز با مقدار false فراخوانی می‌شود. برای مثال زمانی که یک مقداری از یک فهرست، انتخاب شده و با زدن دکمه ثبت بخواهیم مقدار انتخاب‌شده همچنان نمایش داده شود مقدار آن false قرار داده می‌شود.
 +
 +==== 6-7-4- setAction ====
 +
 +با استفاده از این تابع مسیر و آدرس لازم برای خواندن تنظیمات انجام‌شده‌ (تمامی موارد ذکرشده در بالا و همچنین برخی تنظیمات دیگر) در اختیار فرم مورد نظر قرار می‌گیرد. به عنوان مثال:
 +
 +#;;
 +<code php>
 +$form->​setAction(OW::​getRouter()->​urlForRoute('​iisjalali_admin_config'​));​
 +</​code>​
 +#;;
 +
 +==== 6-7-5- bindJsFunction ====
 +
 +این تابع نوع رویداد و یک تابع جاوااسکریپت را به عنوان ورودی گرفته و هنگام وقوع رویداد با نوع داده شده، تابع را اجرا می‌کند.
 +
 +**نکته 1:** نوع رویداد به صورت متغیرهای ثابت در ابتدای کلاس Form تعریف شده است.
 +
 +**نکته2:​** ​ تابع جاوااسکریپت را می‌توان در همان ورودی نیز نوشت؛ مانند کد زیر:
 +
 +#;;
 +<code php>
 +$form->​bindJsFunction(Form::​BIND_SUCCESS,'​function( data ){ if(data && data.result){OW.info(\''​.$language->​text('​iisjalali',​ '​settings_updated'​).'​\'​) ​ }  }');
 +</​code>​
 +#;;
 +
 +در صورتی که فرم با موفقیت ثبت شود و داده‌ای برگردانده شود، پیغام مربوط به افزونه iisjalali و کلید settings_updated نمایش داده می‌شود.
 +
 +==== 6-7-6- addElement ====
 +
 +با استفاده از این تابع می‌توان به فرم مورد نظر فیلد اضافه کرد.
 +
 +==== 6-7-7- isValid ====
 +
 +در صورتی که فیلد‌هایی از یک فرم نیاز به بررسی برای صحت داده‌های واردشده داشته باشد، بررسی صحت مقادیر با استفاده از این تابع انجام می‌شود. برای مثال ممکن است واردسازی مقدار یک المان اجباری باشد و یا داده یک المان باید به فرمت مشخصی وارد شود مثلا x-xxxx-xxx-xxxx-xx.
 +
 +==== 6-7-8- getElement ====
 +
 +یک فیلد در فرم را می‌توان با این تابع دریافت نمود.
 +
 +**نکته:​** به طور کلی برای گرفتن مقدار یک فیلد در فرم از این تابع استفاده می‌شود مانند کد زیر:
 +
 +#;;
 +<code php>
 +$form->​getElement('​dateLocale'​)->​getValue()
 +</​code>​
 +#;;
 +
 +==== 6-7-9- getValues ====
 +
 +کلیه مقادیر موجود در المان‌های یک فرم را برمی‌گرداند.
 +
 +==== 6-7-10- getErrors ====
 +
 +این تابع کلیه خطاهای یک فرم را برمی‌گرداند.
 +
 +==== 6-8- OW_Example ====
 +
 +این کلاس به منظور استفاده هرچه آسان‌تر DAO از پرسمان‌های لازم برای پایگاه داده تعریف شده است.
 +
 +==== 6-8-1- andFieldEqual ====
 +
 +دو ورودی نام فیلد مورد نظر و مقدار مورد نظر را به عنوان ورودی گرفته و در پاسخ سطری از جدول پایگاه داده را برمی‌گرداند که مقدار فیلد مورد نظر آن دقیقا با مقدار تعیین شده، برابر باشد. به عنوان مثال:
 +#;;
 +<code php>
 +public function getActiveUsers(){
 +    $ex = new OW_Example();​
 +    $ex->​andFieldEqual('​lock',​ 0);
 +    return $this->​findListByExample($ex);​
 +}
 +</​code>​
 +#;;
 +
 +کلیه کاربران فعال را برمی‌گرداند.
 +==== 6-8-2- andFieldLike ====
 +
 +این تابع دو ورودی گرفته؛ اولی نام فیلد مورد نظر و دومی مقدار مورد نظر است و با مقایسه مقدار مربوطه برای فیلد که شبیه باشد سطر مناسب را ارائه می‌کند.
 +سایر توابع نیز مشابه توابع بالا پالایش‌های ​ مربوط به پرسمان را پوشش می‌دهند.
 +
 +**نکته 1:** توابع دیگری نیز مانند دو تابع ذکرشده در بالا وجود دارند که بسته به کاربرد می‌توانند فیلتر‌های دیگری را برای استخراج داده مورد نظر اعمال کنند.
 +
 +**نکته2:​** هر کلاس DAO که تعریف می‌شود از کلاس OW_BaseDao ارث می‌برد. در این کلاس چند تابع اصلی مربوط به اجرای کلاس Ow_Example نوشته شده که در ادامه به آن‌ها پرداخته شده است.
 +===== 6-9- OW_BaseDao =====
 +
 +هر کلاس DAO که تعریف می‌شود از کلاس OW_BaseDao ارث می‌برد. در این کلاس چند تابع اصلی قرار دارد.
 +==== 6-9-1- findById ====
 +
 +مقدار Id یک شیء موجودیت را گرفته و سطر متناظر با آن در جدول داده را در صورتی که وجود داشته باشد، برمی‌گرداند. به عنوان مثال:
 +#;;
 +<code php>
 +public function findById( $id )
 +{
 +    $dao = $this->​dao;​
 +    return $dao->​findById($id);​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-9-2- findByIdList ====
 +
 +فهرستی از Id‌های موجودیت‌های یک نوع را گرفته و سطرهای متناظر با آن‌ها را در جدول پایگاه‌ داده در صورت وجود برمی-گرداند.
 +
 +==== 6-9-3- findListByExample ====
 +
 +متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند. به عنوان مثال:
 +#;;
 +<code php>
 +public function getActiveUsers(){
 +    $ex = new OW_Example();​
 +    $ex->​andFieldEqual('​lock',​ 0);
 +    return $this->​findListByExample($ex);​
 +}
 +</​code>​
 +#;;
 +
 +کد فوق فهرستی از کاربران که مقدار فیلد lock در آن‌ها صفر باشد را بر‌می‌گرداند.
 +
 +==== 6-9-4- save ====
 +برای ذخیره‌سازی یک موجودیت ​ از این تابع استفاده می‌شود.
 +==== 6-9-5- delete ====
 +برای حذف یک موجودیت از این تابع استفاده می‌شود.
 +==== 6-9-6- findAll ====
 +کلیه داده‌های مربوط به یک جدول را برمی‌گرداند.
 +==== 6-9-7- countAll ====
 +تعداد کل سطر‌های مربوط به یک جدول را برمی‌گرداند.
 +==== 6-9-8- deleteByExample ====
 +
 +این تابع متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود حذف می‌کند.
 +#;;
 +<code php>
 +public function deleteByAuthorId( $userId )
 +{
 +    $ex = new OW_Example();​
 +    $ex->​andFieldEqual('​authorId',​ $userId);
 +
 +    $this->​deleteByExample($ex);​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-9-9- countByExample ====
 +
 +متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example تعداد سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند.
 +#;;
 +<code php>
 +public function countFullsizePhotos()
 +{
 +    $example = new OW_Example();​
 +    $example->​andFieldEqual('​hasFullsize',​ 1);
 +
 +    return $this->​countByExample($example);​
 +}
 +</​code>​
 +#;;
 +
 +کد فوق فهرستی از کاربران که مقدار فیلد lock در آن‌ها صفر باشد را بر‌می‌گرداند.
 +
 +==== 6-9-4- save ====
 +
 +برای ذخیره‌سازی یک موجودیت ​ از این تابع استفاده می‌شود.
 +
 + ==== 6-9-5- delete====
 +برای حذف یک موجودیت از این تابع استفاده می‌شود.
 +
 +====6-9-6- findAll====
 +کلیه داده‌های مربوط به یک جدول را برمی‌گرداند.
 +
 +====6-9-7- countAll====
 +
 +تعداد کل سطر‌های مربوط به یک جدول را برمی‌گرداند.
 +
 +====6-9-8- deleteByExample====
 +این تابع متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود حذف می‌کند
 +#;;
 +<code php>
 +public function deleteByAuthorId( $userId )
 +{
 +    $ex = new OW_Example();​
 +    $ex->​andFieldEqual('​authorId',​ $userId);
 +
 +    $this->​deleteByExample($ex);​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-9-9- countByExample ====
 +
 +متناسب با پرسمان تعریف‌شده با استفاده از کلاس ow_Example تعداد سطر‌(سطرهای) متناظر با آن‌ها در جدول داده را در صورت وجود برمی‌گرداند.
 +#;;
 +<code php>
 +public function countFullsizePhotos()
 +{
 +    $example = new OW_Example();​
 +    $example->​andFieldEqual('​hasFullsize',​ 1);
 +
 +    return $this->​countByExample($example);​
 +}
 +</​code>​
 +#;;
 +
 +===== 6-10- OW_entity =====
 +
 +به طور کلی تمامی موجودیت‌ها ​ از کلاس پایه‌ای OW_Entity ارث می‌برند. کلاس مذکور دارای دو پارامتر اصلی با نام $Id و $_fieldsHash و چهار تابع اصلی به شرح ذیل است.
 +==== 6-10-1- SetId و GetId ====
 +
 +به ترتیب Setter و Getter مربوط به id موجودیت هستند. مقصود از موجودیت، جداول پایگاه داده و مقصود از $Id ستون Id این جداول است. شایان ذکر است که تمامی موجودیت‌ها در موتوشاب شناسه Id را به صورت پیش‌فرض دارند.
 +
 +====6-10-2- generateFieldsHash====
 +
 +برای ایجاد فیلدهای موجودیت مورد نظر‌(که عموما یکتا نیز می‌باشند) از این تابع استفاده می‌شود.
 +**نکته:​** دو تابع queryForObject و queryForObjectList مربوط به کلاس OW_Database از این تابع استفاده می‌کنند.
 +
 +====6-10-3- getEntinyUpdatedFields====
 +
 +کلیه فیلدهای مربوط به یک موجودیت که نیاز به به‌روزرسانی دارند با استفاده از این تابع و به صورت یک آرایه دریافت می-شوند. تابع updateObject مربوط به کلاس OW_Database از این آرایه ​ استفاده می‌کند.
 +
 +#;;
 +<code php>
 +Ow_Entity $obj;
 +$fieldsToUpdate = $obj->​getEntinyUpdatedFields ();
 +</​code>​
 +#;;
 +
 +===== 6-11- BOL_UserService =====
 +
 +از این کلاس برای دسترسی به جدول مربوط به اطلاعات کاربران‌ (با استفاده از موجودیت‌های userDao، userOnlineDao، userSuspendDao و غیره که تمامی در تابع سازنده آن مقداردهی می‌شوند) استفاده می‌شود. این کلاس دارای توابع مختلفی است که در ادامه به مهم‌ترین آن‌ها اشاره شده است:
 +
 +==== 6-11-1- findUserForStandardAuth ====
 +
 +تابع مذکور با گرفتن یک متغیر و جایگذاری آن به عنوان نام کاربری و یا ایمیل کاربر، او را در صورت یافتن برمی‌گرداند.
 +
 +به عنوان مثال، تابع authenticate مربوط به کلاس BASE_CLASS_StandardAuth از تابع فوق برای بررسی صحت موجودیت افراد به عنوان کاربر استفاده می‌‌کند:​
 +#;;
 +<code php>
 +$user = $this->​userService->​findUserForStandardAuth($this->​identity);​
 +$language = OW::​getLanguage();​
 +if ( $user === null )
 +{
 +    return new OW_AuthResult(OW_AuthResult::​FAILURE_IDENTITY_NOT_FOUND,​ null, array($language->​text('​base',​ '​auth_identity_not_found_error_message'​)));​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-11-2- findUserById ====
 +
 +تابع مذکور با گرفتن یک متغیر و جایگذاری آن به عنوان نام کاربری کاربر و یا ایمیل او، کاربر مورد نظر را در صورت یافتن برمی‌گرداند. تابع فوق با گرفتن سه پارامتر ورودی <wrap :​en>​$id</​wrap>​، <wrap :​en>​$cacheLifeTime</​wrap>​ و یک آرایه Tag، کاربر را در فهرست ذخیره موقت ​ خود جستجو می‌کند و همچنین در صورت خالی بودن، آن را به حافظه موقت خود اضافه می‌کند.
 +
 +**نکته:​** دو پارامتر آخر اختیاری است.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$user = BOL_UserService::​getInstance()->​findUserById($params['​userId'​]);​
 +</​code>​
 +#;;
 +
 +==== 6-11-3- getDisplayName ====
 +
 +یک ورودی (شناسه کاربر) ​ گرفته و بر اساس آن نام قابل نمایش کاربر را بر‌می‌گرداند.
 +
 +مثال:
 +#;;
 +<code php>
 +$userName = BOL_UserService::​getInstance()->​getDisplayName($userId);​
 +</​code>​
 +#;;
 +
 +====6-11-4- getDisplayNamesForList====
 +
 +یک آرایه ورودی (شناسه کاربران) گرفته و بر اساس آن، یک آرایه لیست از نام قابل نمایش کاربران را بر‌می‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$displayNameList = BOL_UserService::​getInstance()->​getDisplayNamesForList($authorIdList);​
 +</​code>​
 +#;;
 +
 +
 +
 +====6-11-5- getUserName====
 +
 +یک ورودی (شناسه کاربر) گرفته و بر اساس آن نام کاربری کاربر را بر‌می‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$this->​assign('​username',​ BOL_UserService::​getInstance()->​getUsername($userId));​
 +</​code>​
 +#;;
 +
 +
 +
 +====6-11-6- getUserNamesForList====
 +
 +یک آرایه ورودی (شناسه کاربران) گرفته و بر اساس آن یک آرایه لیست از نام کاربران را بر‌می‌گرداند. به عنوان مثال:
 +
 +#;;
 +<code php>
 +$userNameList = $userService->​getUserNamesForList($userIdList);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-7- getUserUrl====
 +
 +شناسه کاربر را به عنوان ورودی گرفته و بر اساس آن آدرس مربوط به پروفایل کاربر را بر‌می‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$userUrl = BOL_UserService::​getInstance()->​getUserUrl($userId);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-8- getUserUrlForUsername====
 +
 +یک ورودی (نام کاربری) گرفته و بر اساس آن آدرس مربوط به پروفایل کاربر را بر‌می‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$userUrl = BOL_UserService::​getInstance()->​getUserUrlForUsername($userDto->​ username);
 +</​code>​
 +#;;
 +
 +
 +====6-11-9- getUserUrlForUsername====
 +
 +نام کاربری را گرفته و بر اساس آن آدرس پروفایل کاربر مورد نظر را جستجو و برمی‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$user = BOL_UserService::​getInstance()->​findByUsername($passwordValidationByToken->​ username);
 +</​code>​
 +#;;
 +
 +
 +====6-11-10- getUserUrlsListForUsernames====
 +
 +آرایه‌ای از نام‌های کاربری را گرفته و بر اساس آن آرایه‌ای از آدرس‌های کاربران مورد نظر را جستجو و برمی‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$urlArr = BOL_UserService::​getInstance()->​ getUserUrlsListForUsernames($usernameList);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-11- findByUserName====
 +
 +نام کاربری را گرفته و بر اساس آن کاربر مورد نظر را جستجو و برمی‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$user = BOL_UserService::​getInstance()->​findByUsername($username);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-12- findByEmail====
 +
 +ایمیل کاربری را گرفته و بر اساس آن کاربر مورد نظر را جستجو کرده و برمی‌گرداند.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$parentUser = BOL_UserService::​getInstance()->​findByEmail($parentEmail);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-13- saveLoginCookie====
 +
 + با استفاده از این تابع کوکی مورد نیاز برای ثبت ورود کاربر ساخته و ذخیره می‌شود.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$loginCookie = $this->​saveLoginCookie(OW::​getUser()->​getId());​
 +</​code>​
 +#;;
 +
 +
 +====6-11-14- getResetForm====
 +
 + با استفاده از این تابع فرم مربوط به فراموش کردن رمز عبور ساخته می‌شود.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$form = $this->​userService->​getResetForm();​
 +$this->​addForm($form);​
 +</​code>​
 +#;;
 +
 +
 +====6-11-15- processResetForm====
 + 
 +با استفاده از این تابع در صورتی که کاربر فرایند فراموشی رمز عبور را آغاز کرده باشد، رمز جدید ساخته شده و برای کاربر ارسال می‌شود.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +if ( $form->​isValid($_POST) )
 +{
 +    $data = $form->​getValues();​
 +
 +    try
 +    {
 +        $this->​userService->​processResetForm($data);​
 +    }
 +    catch ( LogicException $e )
 +    {
 +        OW::​getFeedback()->​error($e->​getMessage());​
 +        $this->​redirect();​
 +    }
 +
 +    OW::​getFeedback()->​info($language->​text('​base',​ '​forgot_password_success_message'​));​
 +    $this->​redirect();​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-11-16- getDataForUsersList ====
 +
 + با استفاده از این تابع کلیه اطلاعات مربوط به کاربرانی که آنلاین هستند و یا آخرین کاربران آنلاین و یا کاربرانی که هنوز حساب کاربری خود را فعال نکرده‌اند و غیره را بر اساس پارامتر ورودی <wrap :​en>​$lisKey</​wrap>​ می‌توان دریافت نمود. این تابع سه پارامتر ورودی گرفته که اولین پارامتر آن <wrap :​en>​($listKey)</​wrap>​ نوع کاربر ‌(کاربرانی) که باید جستجو شوند ‌(غیرفعال، آنلاین و غیره) را مشخص می‌کند. دومین پارامتر <wrap :​en>​$first</​wrap>​و سومین پارامتر <wrap :​en>​$count</​wrap>​ به ترتیب مشخص می‌کنند از چندمین و چه تعداد کاربر مورد نظر است (برای مثال از سومین کاربر تا نهمین برابر است با <wrap :​en>​$first=3</​wrap>​ و <wrap :​en>​$count=7</​wrap>​).
 +
 +مثال:
 +
 +
 +#;;
 +<code php>
 +$service = BOL_UserService::​getInstance();​
 +return $service->​getDataForUsersList($listKey,​ $first, $count);
 +</​code>​
 +#;;
 +
 +==== 6-11-17- findRecentlyActiveList ====
 +
 + با استفاده از این تابع اطلاعات آخرین کاربران فعال گرفته می‌شود. این تابع سه پارامتر ورودی دارد: اولین پارامتر <wrap :​en>​$first</​wrap>​ و دومین پارامتر <wrap :​en>​$count</​wrap>​ مشخص می‌کنند از چندمین و چه تعداد کاربر مورد نظر است (برای مثال از سومین کاربر تا نهمین برابر است با <wrap :​en>​$first=3</​wrap>​ و <wrap :​en>​$count=7</​wrap>​) و سومین پارامتر <wrap :​en>​$isAdmin</​wrap>​ که به صورت پیش‌فرض برابر false است مشخص می‌کند که آیا مدیریت سامانه نیز در نظر گرفته شود یا خیر.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +$userDtos = BOL_UserService::​getInstance()->​findRecentlyActiveList(0,​ 100);
 +</​code>​
 +#;;
 +
 +==== 6-11-18- findOnlineList ====
 +
 +با استفاده از این تابع اطلاعات کاربران فعال گرفته می‌شود. این تابع دو پارامتر ورودی دارد: پارامتر اول (<wrap :​en>​$first</​wrap>​) و پارامتر دوم (<wrap :​en>​$count</​wrap>​) به ترتیب مشخص می‌کنند که از چندمین و چه تعداد کاربر مدنظر هستند. برای مثال از سومین کاربر تا نهمین برابر است با <wrap :​en>​$first=3</​wrap>​ و <wrap :​en>​$count=7</​wrap>​.
 +
 +مثال:
 +#;;
 +<code php>
 +$userDtos = BOL_UserService::​getInstance()->​findOnlineList(0,​ 100);
 +</​code>​
 +#;;
 +
 +==== 6-11-19- findUserIdByAuthToken ====
 +
 +با استفاده از این تابع بر اساس توکن ساخته‌شده برای کاربر،‌ شناسه کاربر مربوطه بازیابی می‌شود. عموما در موارد خاصی توکن برای کاربر ساخته می‌شود، مثلا هنگامی که کاربر در سامانه ثبت‌نام کرده باشد. در این صورت برای او یک توکن جهت فعال‌سازی حساب کاربری ساخته می‌شود.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +if ( $token !== null )
 +{
 +    $this->​userId = (int) BOL_UserService::​getInstance()->​ findUserIdByAuthToken($token);​
 +}
 +</​code>​
 +#;;
 +
 +==== 6-11-20- addTokenForUser ====
 +
 + با استفاده از این تابع برای کاربر با شناسه ورودی تابع مذکور توکن جدید ساخته شده و در صورتی که قبلا توکنی برای کاربر وجود داشته باشد توکن قبلی پاک شده و توکن جدید جایگزین آن می‌شود.
 +
 +مثال‌:​
 +#;;
 +<code php>
 +$this->​userId = $userId;
 +$this->​token = BOL_UserService::​getInstance()->​addTokenForUser($this->​userId);​
 +</​code>​
 +#;;
 +
 +==== 6-11-21- getUserViewQuestions ====
 +
 +با استفاده از این تابع، اطلاعات سوالات پایه‌ای (سوالاتی که توسط مدیر سامانه برای کاربران در قسمت مدیر تنظیم شده و برخی از سوالات را کاربران در هنگام ورود اولیه به سایت و یا برخی دیگر را به صورت انتخابی در نمایه شخصی خود پاسخ می‌دهند) بازیابی می‌شوند ‌‌(مانند سال تولد، جنسیت و غیره). تابع مذکور چهار پارامتر ورودی گرفته که مهم‌ترین آن شناسه کاربر مورد نظر است.
 +
 +مثال‌:​
 +#;;
 +<code php>
 +$questions = BOL_UserService::​getInstance()->​getUserViewQuestions($userId,​ $adminMode, $questionNames,​ $sectionNames);​
 +</​code>​
 +#;;
 +
 +==== 6-11-22- getQueryFilter ====
 +
 +با استفاده از این تابع می‌توان پالایش‌هایی ​ برای دریافت کاربران سامانه وارد کرده و اطلاعات کاربران مورد نظر را دریافت نمود. این تابع دارای سه پارامتر ورودی است که اولین پارامتر ورودی آن آرایه‌ای از جداول مورد نظر برای اجرای پرسمان، دومین پارامتر آرایه‌ای از فیلدهای مورد نظر و سومین، آرایه‌ای از پارامترهای مورد نظر برای بررسی است.
 +
 +مثال‌:​ تابع یافتن کاربران مسدود شده به شرح زیر است:
 +#;;
 +<code php>
 +public function findBlockedUserList($userId,​ $first, $count)
 +{
 +    $queryParts = BOL_UserService::​getInstance()->​getQueryFilter(array(
 +        BASE_CLASS_QueryBuilderEvent::​TABLE_USER => '​u'​
 +    ), array(
 +        BASE_CLASS_QueryBuilderEvent::​FIELD_USER_ID => '​blockedUserId'​
 +    ), array(
 +        BASE_CLASS_QueryBuilderEvent::​OPTION_METHOD => __METHOD__
 +    ));
 +
 +    $query = "​SELECT u.* FROM " . $this->​getTableName() . " u " . $queryParts["​join"​]
 +        . " WHERE " . $queryParts["​where"​] . " AND u.userId=:​userId ​ LIMIT :lf, :lc";
 +
 +    return $this->​dbo->​queryForObjectList($query,​ $this->​getDtoClassName(),​ array(
 +        "​userId"​ => $userId,
 +        "​lf"​ => $first,
 +        "​lc"​ => $count
 +    ));
 +}
 +</​code>​
 +#;;
 +
 +===== 6-12- OW_User =====
 +
 +از این کلاس برای دسترسی به برخی توابع مرتبط با جدول کاربران استفاده می‌شود در ذیل به مهم‌ترین آن‌ها اشاره شده است:
 +
 +==== 6-12-1- isAuthorized ====
 +
 +تابع فوق سه پارامتر ورودی دارد که اولین آن <wrap :​en>​($groupname)</​wrap> ​ نام گروه یا افزونه‌ای است که کاربر در حال حاضر وارد آن شده و یا با آن کار می‌کند، پارامتر دوم <wrap :​en>​($actionName)</​wrap>​ نام فعالیتی است که انجام می‌شود و پارامتر سوم آن <wrap :​en>​($extra)</​wrap> ​ پارامتر اضافی در صورت نیاز است. با استفاده از تابع مذکور بررسی می‌شود که آیا کاربر در گروه مورد نظر اجازه فعالیت داده شده را دارد یا خیر.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +if ( !OW::​getUser()->​isAdmin() && !OW::​getUser()->​isAuthorized('​iisnews',​ '​view'​) )
 +{
 +    $status = BOL_AuthorizationService::​getInstance()->​getActionStatus('​iisnews',​ '​view'​);​
 +    throw new AuthorizationException($status['​msg'​]);​
 +
 +    return;
 +}
 +</​code>​
 +#;;
 +
 +==== 6-12-2- isAdmin ====
 +
 +بررسی می‌کند که کاربر کنونی مدیر سامانه است یا خیر.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +if ( !OW::​getUser()->​isAdmin() )
 +{
 +    throw new AuthenticationException();​
 +    exit();
 +}
 +</​code>​
 +#;;
 +
 +==== 6-12-3- isAuthenticated ====
 +بررسی می‌کند که هویت کاربر کنونی احراز شده است یا خیر.
 +
 +مثال:
 +#;;
 +<code php>
 +if ( !OW::​getUser()->​isAuthenticated() )
 +{
 +  $this->​echoOut($_POST['​feedAutoId'​],​ array("​error"​ => "You need to sign in to post."​));​
 +}
 +</​code>​
 +#;;
 +
 +===== 6-13- OW_Request =====
 +
 +از این کلاس برای مدیریت درخواست‌های ارسالی مانند پارامترهای ارسالی از URL، آدرس IP درخواست‌دهنده و غیره استفاده می‌شود.
 +
 +====6-13-1- getRequestUri====
 +
 +این تابع درخواست URI مورد نظر را بر می‌گرداند. به عنوان مثال کد زیر بررسی می‌کند که آیا آدرس مورد درخواست کاربر آدرس «خروج از حساب کاربری» است یا خیر.
 +
 +#;;
 +<code php>
 +if (OW::​getRequest()->​getRequestUri() == '​sign-out'​){
 +    return true;
 +}
 +</​code>​
 +#;;
 +
 +====6-13-2- isAjax====
 +
 +بررسی می‌کند آیا نوع درخواست به صورت Ajax است یا خیر.
 +
 +مثال:
 +#;;
 +<code php>
 +if ( !OW::​getRequest()->​isAjax() )
 +{
 +    throw new Redirect404Exception();​
 +}
 +</​code>​
 +#;;
 +
 +====6-13-3- isPost====
 +
 +بررسی می‌کند آیا نوع درخواست Post است یا خیر. عموما از این تابع برای بررسی اینکه آیا فرم بعد از پر شدن اطلاعات ارسال شده ​ یا خیر استفاده می‌شود.
 +
 +مثال:
 +
 +#;;
 +<code php>
 +if (OW::​getRequest()->​isPost()) {
 +    if ($form->​isValid($_POST)) {
 +        $data = $form->​getValues();​
 +            IISCONTACTUS_BOL_Service::​getInstance()->​addDepartment($data['​email'​],​ $data['​label'​]);​
 +            $this->​redirect();​
 +    }
 +}
 +</​code>​
 +#;;
 +
 +====6-14- OW_Session====
 +
 +از این کلاس برای مدیریت نشست ایجادشده برای کاربر استفاده می‌شود. در ادامه به مهم‌ترین توابع مربوط به این کلاس اشاره شده است:
 +==== 6-14-1- set ====
 +
 +این تابع دو پارامتر ورودی گرفته که اولین پارامتر ورودی <wrap :​en>​($key)</​wrap>​ کلید و پارامتر دوم <wrap :​en>​($value)</​wrap>​ مقدار مورد نظر برای کلید مذکور بوده و آن را در نشست مربوطه ذخیره می‌کند.
 +
 +مثال:
 +
 +==== 6-14-1- set ====
 +
 +این تابع دو پارامتر ورودی گرفته که اولین پارامتر ورودی ​
 +<wrap :​en>​($key)</​wrap>​ کلید و پارامتر دوم <wrap :​en>​($value)</​wrap>​ مقدار مورد نظر برای کلید مذکور بوده و آن را در نشست مربوطه ذخیره می‌کند.
 +
 +مثال:
 +#;;
 +<code php>
 +OW::​getSession()->​set('​iiscontactus.dept',​ $contactEmails[$data['​to'​]]['​label'​]);​
 +</​code>​
 +#;;
 +
 +====6-14-2- get====
 +این تابع کلید یک نشست را گرفته و مقدار آن را به عنوان خروجی برمی‌گرداند.
 +
 +مثال:
 +#;;
 +<code php>
 +$uidValue = OW::​getSession()->​get('​mailbox.new_message_form_attachments_uid'​);​
 +</​code>​
 +#;;
 +
 +====6-14-3- isKeySet====
 +این تابع نام پارامتر ​
 +<wrap :​en>​($key)</​wrap>​ را به عنوان ورودی گرفته و با استفاده از آن بررسی می‌کند که آیا پارامتری با نام داده شده در نشست مقداردهی شده است یا خیر
 +
 +مثال:
 +#;;
 +<code php>
 +if( OW::​getSession()->​isKeySet('​privacyRedirectExceptionMessage'​) )
 +{
 +    $this->​assign('​message',​ OW::​getSession()->​get('​privacyRedirectExceptionMessage'​));​
 +}
 +</​code>​
 +#;;
 +
 +===== 6-15- OW_Validator =====
 +
 +یک کلاس پایه ‌(به همراه توابع اولیه) برای تعریف کلاس‌هایی برای اعتبارسنجی داده‌های واردشده در فیلد‌های ورودی فرم‌های سامانه است. برای مثال افزونه آلبوم تصاویر از یک کلاس اعتبارسنجی داده‌ها با نام AlbumPhotosValidator استفاده می‌کند که این کلاس از کلاس مذکور ارث می‌برد. سپس در هنگام تعریف فرم واردسازی آلبوم تصاویر این کلاس به فرم اضافه می‌شود.
 +#;;
 +<code php>
 +$this->​albumPhotosValidator = new AlbumPhotosValidator();​
 +$photos->​addValidator($this->​albumPhotosValidator);​
 +</​code>​
 +#;;
 +
 +====6-15-1- isValid====
 +درون این تابع کلیه شرایط مربوط به بررسی صحت اطلاعات مورد نظر بررسی می‌شود.
 +
 +مثال:
 +#;;
 +<code php>
 +public function isValid( $data )
 +{
 +    $this->​albumPhotosValidator->​setAlbumId($data['​from-album'​]);​
 +    ​
 +    if ( !empty($data['​to-album'​]) )
 +    {
 +        $this->​getElement('​to-album'​)->​setRequired()->​addValidator(new PHOTO_CLASS_AlbumOwnerValidator());​
 +    }
 +    ​
 +    return parent::​isValid($data);​
 +}
 +</​code>​
 +#;;
 +
 +====6-15-2- getError====
 +پیغام خطای مورد نظر با استفاده از این تابع گرفته می‌شود.
 +#;;
 +<code php>
 +public function getJsValidator()
 +{
 +    return '{
 +        validate : function( value )
 +        {
 +            if ( value.length === 0 )
 +            {
 +                alert(OW.getLanguageText("​photo",​ "​no_photo_selected"​));​
 +                throw "​Required";​
 +            }
 +        }
 +    }';
 +}
 +</​code>​
 +#;;
 +
 +====6-15-3- setErrorMessage====
 +متن پیغام خطای مورد نظر با استفاده از این تابع مقداردهی می‌شود.
 +
 +مثال:
 +#;;
 +<code php>
 +if ( !UTIL_Validator::​isUserNameValid($value) )
 +{
 +    $this->​setErrorMessage($language->​text('​base',​ '​join_error_username_not_valid'​));​
 +    return false;
 +}
 +</​code>​
 +#;;
 +
 +====6-15-4- getJsValidator====
 +از این تابع برای بررسی صحت اطلاعات به صورت جاوااسکریپت استفاده می‌شود.
 +
 +مثال:
 +#;;
 +<code php>
 +function getJsValidator()
 +{
 +
 +    return "{
 +       ​validate : function( value ){
 +            if( $('#​address1'​).attr('​checked'​) && ​ !value ){ throw " . json_encode($this->​getError()) . "; }
 +            return true;
 +    },
 +       ​getErrorMessage : function(){ return " . json_encode($this->​getError()) . " }
 +    }";
 +}
 +</​code>​
 +#;;
 +
 +**نکته:​** کلاس‌های پایه‌ای دیگری نیز وجود دارند که از کلاس مذکور ارث برده و به عنوان کلاس‌های پایه برای استفاده تعریف شده‌اند؛ مانند کلاس RequiredValidator که عموما توابع getJsValidator و همچنین isValid آن از پیش تعریف شده است.
 +
 +مثال زیر از این کلاس برای اجباری بودن پر شدن یک فیلد ورودی استفاده می‌کند:​
 +#;;
 +<code php>
 +$textarea->​addAttribute('​placeholder',​ $language->​text('​mailbox',​ '​message_invitation'​));​
 +$requiredValidator = new WyswygRequiredValidator();​
 +$requiredValidator->​setErrorMessage( $language->​text('​mailbox',​ '​chat_message_empty'​) );
 +$textarea->​addValidator($requiredValidator);​
 +</​code>​
 +#;;
 +
 +کلاس‌های دیگری نیز مانند stringValidator، regularExpValidator و غیره وجود دارند که مانند کلاس بالا دارای توابع getJsValidator و همچنین isValid از پیش تعریف شده هستند.
 +
 +===== 6-16- OW_Cron=====
 +
 +این کلاس به عنوان یک کلاس پایه‌ به جهت تعریف کلاس‌هایی برای بخش‌های مختلف که یک سری وظایف برای انجام به صورت دوره‌ای و در بازه‌های زمانی مختلف دارند استفاده می‌شود. از جمله وظایف دوره‌ای می‌توان به بررسی جدول ایمیل‌های آماده ارسال در هر 10 دقیقه و ارسال آن‌ها و یا بروز رسانی حافظه موقت در هر یک دقیقه و غیره اشاره نمود. شایان ذکر است که منظور از وظایف همان توابع تعریف شده است.
 +
 +==== 6-16-1- addJob ====
 +
 +از این تابع برای اضافه کردن وظیفه‌‌ (وظایف) استفاده می‌شود که دارای دو پارامتر ورودی است: اولین پارامتر <wrap :​en>​($methodName)</​wrap>​ نام تابع مورد نظر و دومین پارامتر ورودی <wrap :​en>​($runInterval)</​wrap>​ نیز بازه زمانی بر حسب دقیقه است که تابع مورد نظر اجرا می‌شود. به صورت پیش‌فرض و در صورت عدم مقدار‌دهی 1 در نظر گرفته می‌شود.
 +
 +==== 6-16-2- getJobList ====
 +
 +این تابع فهرستی از وظایف مربوطه برای اجرا را برمی‌گرداند.
 +
 +در ادامه مثالی از چگونگی استفاده از زیرساخت کرون‌جاب برای افزونه «تصاویر» آمده است:
 +
 +در اغلب موارد در تابع سازنده وظایف (توابع) تعریف‌شده مربوطه به زیرساخت کرون افزوده می‌شوند:​
 +
 +#;;
 +<code php>
 +    parent::​__construct();​
 +
 +    $this->​addJob('​albumsDeleteProcess'​);​
 +    $this->​addJob('​contentIndexing'​);​
 +    $this->​addJob('​cleareCache',​ 10);
 +    $this->​addJob('​deleteLimitedPhotos',​ 180);
 +    $this->​addJob('​updatePhotoTags'​);​
 +}
 +</​code>​
 +#;;
 +در افزونه «تصاویر» تابع clearCache به صورت زیر و با هدف حذف داده‌های تصاویر موجود در حافظه‌نهان تعریف شده است.‌
 +#;;
 +<code php>
 +public function cleareCache()
 +{
 +    PHOTO_BOL_PhotoCacheDao::​getInstance()->​cleareCache();​
 +}
 +</​code>​
 +#;;
 +
 +شایان ذکر است که فرزندان OW_Cron همواره دارای یک تابع run هستند:
 +
 +#;;
 +<code php>
 +public function run()
 +{
 +    ​
 +}
 +</​code>​
 +#;;
 +
 +نام فایل حاوی کلاس فرزند OW_Cron می‌بایست cron.php باشد. فایل run.php واقع در شاخه ow_cron تمامی افزونه‌ها را بررسی کرده و در صورتی که دارای فایل cron.php باشند آن را اجرا می‌کند.
 +
 +بخشی از کد مذکور که به دنبال فایل‌های cron.php موجود در افزونه‌ها می‌گردد، در زیر قابل مشاهده است.
 +
 +#;;
 +<code php>
 +foreach ( $plugins as $plugin )
 +{
 +    /* @var $plugin BOL_Plugin */
 +    $pluginRootDir = OW::​getPluginManager()->​getPlugin($plugin->​getKey())->​getRootDir();​
 +    if ( file_exists($pluginRootDir . '​cron.php'​) )
 +    {
 +        include $pluginRootDir . '​cron.php';​
 +        $className = strtoupper($plugin->​getKey()) . '​_Cron';​
 +        $cron = new $className;
 +</​code>​
 +#;;
معرفی_کلاس_ها_و_توابع_مهم_در_موتوشاب.txt · آخرین ویرایش: 2019/01/15 12:45