разработка:фильтры [InstantCMS]

Ссылки

К оглавлению
Разработка других дополнений: Плагины
Разработка других дополнений: Модули
Разработка других дополнений: Компоненты
Разработка других дополнений: Шаблоны

Разработка собственного фильтра

Фильтры в InstantCMS — это …

Ниже приведена методика создания и подключения фильтра своими силами на примере создания фильтра «Счетчик скачиваний».

Перед созданием нового фильтра убедитесь, что никто не сделал ничего подобного до Вас. Это можно сделать, заглянув на блоги наших постоянных пользователей или в раздел "Дополнения" на официальном сайте проекта. Помните, всегда проще отредактировать готовый и рабочий фильтр, чем создавать свой собственный с нуля.
Перед тем, как начать, Вам следует получить минимальное представление о синтаксисе языка программирования PHP.
Перед созданием фильтра необходимо:

Придумать имя фильтра. В нашем случае пусть будет »Счетчик скачиваний»
Придумать имя папки, содержащей фильтр. В нашем случае f_filelink. Отнеситесь к этой задаче серьезно, потому что это имя будет встречаться во многих местах и функциях модуля, при всем при этом надо проверить не используется ли данное имя уже другими фильтрами. (сделаю некоторую оговорку имя фильтра всегда должно начинаться с префикса f_.
Продумать функционал фильтра. В нашем случае фильтр находит в текстах статей и модулей выражения »{СКАЧАТЬ=/path/file.zip}» и заменяет их ссылкой для загрузки указанного файла, снабженной счетчиком скачиваний.)

Пишем фильтр

Каждый системный фильтр InstantCMS находится в отдельном файле внутри собственной папки.

Перейдем в папку filters в корне сайта и создайте в ней папку f_filelink. В папке f_filelink создаем файл filter.php. Кроме того, создайте там же пустой файл index.html (из соображений элементарной безопасности).

Откройте файл filter.php любым текстовым редактором (например, Блокнотом), и поместите внутрь код модуля. Здесь все зависит от Вашего мастерства в php. Имя объявляемой функции должно совпасть с именем папки, содержащей фильтр. Далее представлен код самого фильтра с очень подробными комментариями.

<?php
/*************************************************/
// InstantCMS v1.5   (c) 2009 FREEWARE           //
// http://www.instantcms.ru/, info@instantcms.ru //
//                                               //
// written by Vladimir E. Obukhov, 2007-2009     //
/*************************************************/
 
 
function getDownLoadLink($file){    // объявляется вспомогательная функция для формирования 
                                    // ссылки на файл + счетчика скачивании.
     $inCore = cmsCore::getInstance();  // получаем окружение нашей системы.
     trim($file);                       // Обрезаем пробелы в названии файла, 
                                        // которое находиться в переменной $file                       
     $filefull = $_SERVER['DOCUMENT_ROOT'].$file; // получаем полный путь до файла. 
                                                  // $_SERVER['DOCUMENT_ROOT'] - позволяет получить 
                                                  // главный каталог сайта.	
     if (file_exists($filefull)){                 // проверяем существует ли файл в данном каталоге.
          $downloaded = $inCore->fileDownloadCount($file); // Получаем количество скачивании файла, 
                                                           // путем выполнения функции из ядра системы.
  	  $filesize = round(filesize($filefull)/1024, 2);  // определяем размер файла.			
	  $link = '<table border="0" cellpadding="2" cellspacing="0"><tr>';		                      
	  $link .= '<td width="16"><img src="/images/icons/download.gif" border="0"</td>';                    
	  $link .= '<td width=""><a href="/load/url='.$file.'" alt="Скачать">'.basename($file).'</a></td>'; 
	  $link .= '<td width="">| '.$filesize.' Kб</td>';                                                          
	  $link .= '<td width="">| Скачан: '.$downloaded.' раз</td>';					             
	  $link .= '</tr></table>';                      // формируем шаблон для вывода ссылки и счетчика
      } else {
	  $link = 'Файл "'.$filefull.'" не найден!'; // выводим надпись если файл не найден.
      }	
      return $link;
}
 
//////////////////////////////////////////////////////////////////////////////////////
 
function f_filelink(&$text){                   // Непосредственно функция нашего фильтра 
                                               // которая будет выполнять нашу задачу.
    //REPLACE FILE DOWNLOAD LINKS
    $regex = '/{(СКАЧАТЬ=)\s*(.*?)}/i';        // определяем регулярное выражение по которому 
                                               // будем искать в тексте статей и модулей и заменять 
                                               // на свои.
    $matches = array();                        // определяем массив для хранения наших тегов.
    preg_match_all( $regex, $text, $matches, PREG_SET_ORDER );	// непосредственно осуществляем 
                                                                // поиск наших тегов.	
    foreach ($matches as $elm) {	           // организуем цикл в котором переберем все найденные теги.
         $elm[0] = str_replace('{', '', $elm[0]);  // убираем лишние запятые
	 $elm[0] = str_replace('}', '', $elm[0]);	
	 parse_str( $elm[0], $args );              // получаем аргумент тега в нашем случае это - СКАЧАТЬ
	 $file=@$args['СКАЧАТЬ'];	           // выделяем значение аргумента, в нашем случае ссылка на файл.
	 if ($file){		                   // проверяем на пустое значение нашу переменную $file
	      $output = getDownLoadLink($file);	   // вызываем вспомогательную функцию формирования ссылки и счетчика.
	 } else { $output = ''; }                  // выводим пустое значение так как не указан файл. 
	 $text = str_replace('{СКАЧАТЬ='.$file.'}', $output, $text ); // осуществляем окончательную вставку 
                                                                      // преобразованной ссылки в текст статьи 
                                                                      // или модуля.	
     }
     return true;                                                // делаем возврат из фильтра.
}
?>

Подключаем фильтр

Откройте в админке пункт меню «Дополнения - Фильтры» и подключите Ваш созданный фильтр. Затем откройте статью и внесите в ее текст следующую запись {СКАЧАТЬ=/путь до каталога с файлом/Ваш файл для скачки.zip} сохраните и перейдите на сайт. Убедитесь, что фильтр при выводе строки заменил данный тег на ссылку для скачивая и счетчик. Прежде чем наслаждаться успехом, оформите свою работу в виде документации.

Создание документации

Поверьте, потеряв пять минут на создание документации, Вы в дальнейшем избавите себя, от пяти часов разбора своей писанины, которую успели забыть. Если Вы сделали фильтр на заказ, у Вас появится моральное право на все дурацкие вопросы заказчика отвечать коротко: «RTFM» LOL .
Создайте любой текстовый файл (например read_me.txt и кратко опишите фильтр:

Автор (Вы, наверно)
дата создания
функции фильтра - что он умеет
даты последующих редакций и краткий лог модификаций функциональности
для какой системы и версии системы создавался.
переносимость, то есть для каких версий системы может применяться
настройки (если есть)
краткую инструкцию, как ставить

Сложите все файлы (папку с именем фильтра и файлом filter.php, текстовый файл read_me.txt в один архив.
Наслаждайтесь :-P !

Записал: Max Kostjukevich aka MaxiSoft