Документация к компонентам

Компонент позволяет выводить документацию к сторонним компонентам. Для этого разработчику компонента достаточно создать html страницы с документацией и разместить их в папке компонента. Так как предполагается, что документация нужна только в административной части сайта, то просмотр документации доступен только администраторам сайта на странице your_site.site/ihelps.

Файловая структура документации проста. Создаете папку, например для компонента Капча smCaptcha это будет smcaptcha. Название папки может быть любым, но главное, чтобы не пересекалось с другими компонентами. Поэтому лучше всего использовать для названия папки системное имя компонента. В ней должно быть два обязательных файла: component_options.php и index.tpl.php. Дополнительно сюда можно добавить файл styles.css с дополнительными css классами и папку «images» с картинками используемыми в документации. По умолчанию к странице грузятся стили и яваскрипты bootstrap, поэтому можно максимально использовать его разметку. Например, чтобы сделать картинку кликабельной можно вывести такой код

    <div class="col col-sm-6 col-md-4 col-lg-2 mb-3">
        <a class="ajax-modal" href="<?= $images_path; ?>image1.jpg">
            <img class="img-fluid img-thumbnail" src="<?= $images_path; ?>image1.jpg">
        </a>
    </div>

где, <?= $images_path; ?> автоматически заменится на полный путь к картинке вашей папки «images».

В component_options.php указывается метод get_options_smcaptcha() который возвращает массив описания документации компонента. Данные этого массива используются на главной странице документации и в «хлебных крошках». В названии метода smcaptcha это название вашей папки. В массиве указываются заголовок (title), описание (description) и название картинки в папке «images», если есть. 

В index.tpl.php можно прописать сразу html-код с документацией к компоненту. Либо простое общее описание, а полное описание разбить на несколько файлов с любыми названиями. К этим страницам можно будет отдельно обращаться по ссылке «Помощь».

Если в начале файла ...tpl.php разместить такой код с комментариями

<?php
/**
 * Template Name: 0. Главная
 * Template Type: index
 */
?>

то из этих данных будет автоматически создано оглавление с сортировкой по «Template Name». Причем в «Template Type» указывается название этого файла без окончания .tpl.php. Сам файл index.tpl.php в оглавлении не участвует.

В файле шаблона доступны такие переменные:

<?php
/**
 * Доступные переменные:
 * $component - опции с заголовком и описанием компонента
 * $images_path - путь к папке с картинками компонента
 * $name - системное имя компонента (smcaptcha)
 * $slug - запрашиваемая страница документации в выбранном компоненте (index)
 * $files - массив со списком файлов документации данного компонента
 * $config - настройки всего сайта
 */
?>

Для того, чтобы пользователь смог быстро обратиться к документации, необходимо вывести ссылки любым доступным способом. Например для вывода в хлебных крошках админки можно использовать такой код:

        if (cmsCore::isControllerExists('ihelps')){
 
            $template->addMenuItem('breadcrumb-menu', [
                'title' => LANG_HELP,
                'url'   => href_to('ihelps', 'smcaptcha'),
                'options' => [
                    'icon' => 'question-circle',
                    'class' => 'ajax-modal'
                ]
            ]);
 
            $template->addMenuItem('breadcrumb-menu', [
                'title' => LANG_IHELPS_DOCUMENTATION,
                'url'   => href_to('ihelps', 'smcaptcha'),
                'options' => [
                    'target' => '_blank',
                    'icon' => 'bookmark'
                ]
            ]);
 
        }
 

Этот код проверит наличие данного компонента и если он есть, то выведет две ссылки. Первая будет открываться в модальном окне, а вторая будет вести на главную страницу документации данного компонента в отдельном окне. Для компонента с капчей этот код прописывается в файле system\controllers\smcaptcha\backend\forms\form_options.php. В данном конкретном случае файл один и поэтому ссылка будет открывать одну и ту же страницу документации. Но первая ссылка может вести на конкретную страницу, например для конструктора форм ссылка на страницу опций поля будет выглядеть так:

href_to('ihelps', 'iforms', ['field_options'])

Для удобства распространения, свою документацию разработчик может обернуть в отдельный пакет для установки компонентов с установкой зависимости от компонента ihelps. Либо просто грузить вместе с компонентом. В этом случае, если компонент не установлен, то файлы будут просто лежать в папке дефолтного шаблона до тех пор, пока не установят ihelps.