Установщик модулей
Пред. Глава 14. VamShop для разработчика  След.

Установщик модулей

Описание системы.

Введение

Установщик модулей предназначен для лёгкой установки/удаления модулей (дополнительных функций) в VamShop, установки обновлений, для добавления/изменения/удаления записей в базу данных и т.д.

CIP пакеты

Установщик работает с так называемыми CIP (Contrib Installer Package) пакетами, CIP пакет - это обычный zip архив, содержащий в себе файлы нового модуля и инструкции для установщика, которые он должен выполнить для установки/удаления модуля.

Структура CIP пакета

CIP_name/

CIP_name/install.xml

CIP_name/catalog/

CIP_name/catalog/*.*

CIP_name/catalog/admin/*.*

Файлы для каталога должны обязателньо находиться в папке catalog

Файлы для админки должны обязательно находиться в папке catalog/admin

Файл архива должен называться как CIP_name.zip

Например, если Вы создали архив mymodule.zip, то внутри архива должна быть папка mymodule и только внутри этой папки install.xml файл и все остальные файлы модуля. Соблюдайте всегда данные правила при создании модулей.

Любой CIP пакет в обязательном порядке должен содержать файл install.xml, в котором содержатся директивы для установщика.

Формат XML файла

Нужно соблюдать всего 2 условия при создании install.xml:

  1. install.xml должен содержать правильный (валидный) XML код, соответствующий спецификации XML 1.0.

  2. Каждый install.xml файл должен начинаться со следующей строки: 

    <?xml version="1.0" encoding="utf-8" standalone="yes"?>

Текст должен быть обязательно в кодировке utf-8.

Описание доступных XML тэгов

В install.xml Вы можете использовать следующие тэги:

Depend

Depend - позволяет устанавливать зависимости между CIP пакетами.

Действие

Устанавливает зависимости между CIP пакетами.

Синтаксис 

<depend>
	<cip [version="1.0"]>CIP</cip>
	<active>

          тэги, которые будут выполнены, если указанный CIP уже установлен или будет установлен в будущем.

	</active>
	<inactive>

          тэги, которые будут выполнены, если указанный CIP не установлен или будет удалён в будущем.

	</inactive>
</depend>

Описание

У Вас есть два CIP'a: CIP1 и CIP2. CIP1 зависит от CIP2.

Файл install.xml в CIP1 содержит следующий код: 

<depend>
	<cip>CIP2</cip>
	<active>
...
	</active>
	<inactive>
...
	</inactive>
</depend>

CIP2 не установлен. Когда Вы установите CIP1, будет выполнена только часть depend тэга.

Затем Вы установите CIP2. Когда CIP2 будет установлен, установщик прочитает все install.xml файлы всех установленных CIP'ов и посмотрит на блок depend установленного CIP2.

Если в системе уже установлен модуль, который зависит от CIP2, тогда будет выполнена active часть блока depend данного CIP'a.

Если установлен CIP1, а затем устанавливается CIP2, то выполняется active тэг. Если Вы удаляете CIP2, выполяется inactive тэг.

Примечание

Используйте тэг depend только если оба CIP'a изменяют разные участки кода. Используйте тэг require если Вам нужно изменить один и тот же участок кода двумя разными CIP'ами.

Типичный пример, когда depend не работает - когда Вы добавляете новую колонку в select запросе. Первый cip добавляет одну колонку и второй cip добавляет вторую колонку.

Пример: 

	<depend>
		<cip>BTS</cip>
		<active>
			<findreplace>
				<file name="templates/fallback/index_default.php" />
				<findlinenumbers start="27" end="29" />
				<find>
   	      <tr>
            <td><?php 
                   include(DIR_FS_MODULES . FILENAME_NEW_PRODUCTS); ?>
            </td>
          </tr>
				</find>
				<replace type="html">
   	      <tr>
            <td><?php 
               include(DIR_FS_MODULES . FILENAME_FEATURED); ?>
            </td>
          </tr>
				</replace>
			</findreplace>
		</active>
		<inactive>
			<findreplace>
				<file name="index.php" />
				<findlinenumbers start="299" end="301" />
				<find>
   	      <tr>
            <td><?php 
              include(DIR_FS_MODULES . FILENAME_NEW_PRODUCTS); ?>
            </td>
          </tr>
				</find>
				<replace type="html">
   	      <tr>
            <td><?php 
              include(DIR_FS_MODULES . FILENAME_FEATURED); ?>
            </td>
          </tr>
				</replace>
			</findreplace>
		</inactive>
	</depend>

AddLangDef

AddLangDef - Добавляет константы в языковые файлы.

Действие

Используйте данный тэг если Вам нужно добавить новые константы в любые языковые файлы.

Синтаксис 

  <addlangdef>
	<lang type="admin" lng="russian" name="MY_MODULE_TEXT">Мой текст</lang>
        ...
	<lang type="admin" lng="russian" name="MY_MODULE_TEXT1">Ещё текст</lang>
  </addlangdef>
и: 
  <addlangdef>
	<lang type="admin" lng="russian" name="MY_MODULE_TEXT">Мой текст</lang>
	<lang type="admin" lng="english" name="MY_MODULE_TEXT">My text</lang>
  </addlangdef>

Если язык в магазине не установлен, установщик ничего не делает. Это значит, что если Вы сначала установили установили модуль, затем добавили новый язык в магазин, то строки для нового языка установщик не добавит, т.к. на момент установки модуля язык был только один. Удалите модуль (CIP) и установите снова.

Чтобы избежать подобных проблем, создавайте отдельные CIP для каждого языка.

Описание

addlangdef добавляет новый перевод, changelangdef вносит изменения в существующий перевод. Данные тэги конвертируются в кодировку магазина, которая устанавливается в Админке - Языки/Валюты - Языки, в настройках языка опция кодировка.

Новые языковые константы добавляются вниз файла.

AddCode

AddCode - Добавляет произвольный код в файл.

Действие

Ищет указанный код в файле и добавляет после новый код.

Синтаксис 

        <addcode>
            <file name="index.php" />
            <findlinenumbers type="continued"/>
            <find>echo "world";</find>
            <add type="php">echo "Hello";</add>
        </addcode>

или: 

        <addcode>
            <file name="index.php" />
            <findlinenumbers start="12" end="12"/>
            <find>echo "world";</find>
            <add type="php">echo "Hello";</add>
        </addcode>

Описание 

<find>echo "world";</find>

Используется для указания установщику, после какого существующего кода следует добавить новый код: 

<add type="php">echo "Hello";</add>

Код будет заключён в комментарий в зависимости от указанного типа в атрибуте type. Разрешённые значения атрибута type: php, html, bash.

Стиль комментариев в зависимости от указаннного типа: 

"php" - //comment (default so you could not write it)
"html" - <!-- comment-->
"bash" - #comment

Имя файла: 

<file name="index.php" />

Используется для указания файла, в который следует добавить новый код.

Для файла в каталоге нужно записывать так: 

<file name=""catalog/includes/application_top.php"" />

Для файла в админке нужно записывать так: 

<file name=""catalog/admin/index.php"" />

Не беспокойтесь о путях, установщик сам определит, где расположена админка, а где каталог. С помощью catalog и admin Вы просто указывается установщику, что это файл в каталоге, либо это файл в админке.

Вы можете использовать: 

<findlinenumbers type="continued"/>

Если хотите добавить новый код после каждого встречающегося куска кода, например если один и тот же код встречается в файле несколько раз.

Либо используйте: 

<findlinenumbers start="12" end="12"/>

Примечание

Не обязательно в атрибутах start и end указывать точные номера строк, на данный момент установщик не проверяет указанные строки в атрибутах start и end, а просто ищет в файле код, указанный в тэге find.../find, достаточно просто писать любые числа (кроме 0), например так: 

<findlinenumbers start="1" end="1"/>

Add2End

Add2End - Добавляет произвольный код в конец файла.

Действие

Добавляет новый код в конец указанного файла.

Синтаксис 

    <add2end>
        <file name="admin/includes/column_left.php" />
        <add type="php">require(DIR_WS_BOXES . 'contrib_installer.php');</add>
    </add2end>

Описание

Имя файла: 

<file name="admin/includes/column_left.php" />

Используется для указания файла, в который следует добавить новый код.

Для файла в каталоге нужно записывать так: 

<file name=""catalog/includes/application_top.php"" />

Для файла в админке нужно записывать так: 

<file name="admin/includes/column_left.php" />

Не беспокойтесь о путях, установщик сам определит, где расположена админка, а где каталог. С помощью catalog и admin Вы просто указывается установщику, что это файл в каталоге, либо это файл в админке. 

<add type="php">require(DIR_WS_BOXES . 'contrib_installer.php');</add>

Код будет заключён в комментарий в зависимости от указанного типа в атрибуте type. Разрешённые значения атрибута type: php, html, bash.

Стиль комментариев в зависимости от указаннного типа: 

"php" - //comment (default so you could not write it)
"html" - <!-- comment-->
"bash" - #comment

AddFile

AddFile - добавляет новый файл в магазин.

Действие

Добавляет новый файл в магазин из CIP архива.

Синтаксис 

   <addfile> 
     <file name="admin/images/blank_galina.gif" /> 
     <file name="templates/fallback/content/post_blank.php" /> 
     <file name="post_blank.php" /> 
   </addfile>

или: 

   <addfile>
     <file name="images/blank_galina.gif" />
   </addfile>
   <addfile>
     <file name="templates/fallback/content/post_blank.tpl.php" />
   </addfile>
   <addfile>
     <file name="post_blank.php" />
   </addfile>

Описание

При установке модуля Установщик добавляет в магазин новые файлы, но мы не хотим терять сделаные уже изменения, поэтому есть некоторые проверки.

В CIP архиве должен быть файл, который Вы хотите добавить в магазин. Если файла нет, то при установке модуля будет ошибка.

Если указанный файл уже существует в магазине, установщик проверяет, изменялся ли раньше указанный файл установщиком. Для этой проверки используется папка с резеврными копиями установщика.

Если на сущствующий файл установлены неправильные права доступа, установщик остановится и выведет ошибку.

Если права доступа верные, файл будет перезаписан.

Установщик создаёт резервные копии файлов если:

  • - файл существует и не был изменён установщиком

  • - файл изменён и установлены права доступа на запись

При удалении модуля

При удалении модуля, содержащего тэг addfile, также проверяется, был ли изменён тот файл, что был добавлен при установке через addfile.

Установщик сравнивает файл, которые находится в магазине с файлом, который находится в архиве модуля. Если файл был изменён после установки модуля и не установлены права доступа на запись в этот файл, Вы получите ошибку.

Файл будет восстановлен из резервной копии если:

  • - файл не был изменён

  • - файл был изменён, но установлены права доступа на запись в файл

Таким образом, установщик восстановит файл, который был в магазине до установления модуля, если:

  • - файл найден в магазине,

  • - файл, добавленный модулем, не был изменён после установки модуля,

  • - файл был изменён, но есть права доступа на запись в этот файл.

SQL

SQL- вносит изменения в базу данных.

Действие

Выполняет SQL запросы.

Синтаксис

Вы можете использовать SQL инструкции в одном тэге, в качестве разделителя используйте ;

Например: 

<sql>
    <query>
        INSERT INTO configuration_group 
            VALUES (NULL, 'Contrib Installer', 
             'Configuration for the Contrib Installer', NULL, 1);
        UPDATE configuration_group SET
            sort_order=LAST_INSERT_ID() 
            WHERE configuration_group_id=LAST_INSERT_ID();
    </query>
    <remove_query>
        DELETE FROM configuration_group 
          WHERE configuration_group_title = 'Contrib Installer';
    </remove_query>
</sql>

Вы также можете использовать другой синтаксис: 

<sql>
    <query>
        INSERT INTO configuration_group
                VALUES (NULL, 'Contrib Installer', 
                'Configuration for the Contrib Installer', NULL, 1);
    </query>
    <query>
        UPDATE configuration_group
                SET sort_order=LAST_INSERT_ID()
                WHERE configuration_group_id=LAST_INSERT_ID();
    </query>
    <remove_query>
        DELETE FROM configuration_group 
          WHERE configuration_group_title = 'Contrib Installer';
    </remove_query>
</sql>

Описание

Добавляем записи - INSERT запросы.

Выполняются запросы для изменения базы данных.

Выполняются в том порядке, в котором они указаны в файле install.xml.

Пример: 

<sql>
    <query>
        INSERT INTO configuration_group
                VALUES (NULL, 'Contrib Installer', 
                'Configuration for the Contrib Installer', NULL, 1);
    </query>
</sql>

Удаляем записи - DELETE запросы.

Пример: 

<sql>
    <remove_query>
        DELETE FROM configuration_group 
          WHERE configuration_group_title = 'Contrib Installer';
    </remove_query>
</sql>

Если при удалении CIP'а Вы не хотите удалять из базы данных изменения, сделанные CIP'ом при установке, используется в remove тэге “SELECT 1;”.

Например: 

<remove_query>SELECT 1;</remove_query>

Также следите затем чтобы при удалении CIP'a из базы данных удалялись только записи данного модуля и не затрагивались другие данные магазина.

Создаём новую таблицу

Вы можете создавать новые таблицы.

Пример: 

<sql>
  <createtable>
    <table name="cip_depend">
(
            `cip_ident` varchar(255) NOT NULL,
            `cip_ident_req` varchar(255) NOT NULL,
            `cip_req_type` int(2) NOT NULL,
            PRIMARY KEY  (`cip_ident`(100),`cip_ident_req`(100),`cip_req_type`)
        );
        </table>
  </createtable>
</sql>

Изменяем таблицу

Вы можете добавлять новые колонки в существующие таблицы.

Пример: 

<sql>
  <modifytable>
  	<table name="configuration_group"/>
  	<column name="configuration_group_key" 
           action="addcol">VARCHAR(64) NOT NULL</column>
  </modifytable>
</sql>

Изменяем/добавляем записи в таблицу configuration_group: 

<config_group>
	<key>CG_CIP_MANAGER</key>
	<title>Contrib Installer</title>
	<descr>Configuration for the Contrib Installer</descr>
	<visible>1</visible>
</config_group>

Изменяем/добавляем записи в таблицу configuration: 

<config>
	<group_key>CG_CIP_MANAGER</group_key>
	<key>ALLOW_FILES_BACKUP</key>
	<title>Backup Files Before Install Each CIP</title>
	<value>true</value>
	<descr>Choose TRUE and files will be backuped.<br>Backup 
                 contain only files which CIP will modify.</descr>
	<sort_order>15</sort_order>
	<set_function>vam_cfg_select_option(array(\'true\', 
            \'false\'), </set_function>
</config>

make_dir

make_dir - Создаёт новую папку в магазине.

Действие

Создаёт указанную папку.

Синтаксис 

    <make_dir>
        <parent_dir name="" />
        <dir name="temp" />
    </make_dir>

Описание

Создаёт новую папку, если установлены верные права доступа.

findreplace

findreplace - Поиск и замена кода в файле.

Действие

Ищет и меняет код в файле.

Синтаксис 

    <findreplace>
        <file name="admin/index.php" />
        <originallinenumbers start="56" end="56" />
        <find>array('title' => TOOLS_FILES, 'link' => 
vam_href_link(FILENAME_FILE_MANAGER, 'selected_box=tools')))));
</find>
        <replace type="php">
                                         array('title' => TOOLS_FILES, 'link' => 

vam_href_link(FILENAME_FILE_MANAGER, 'selected_box=tools')))),
               array(
                   'title' =>BOX_HEADING_CONTRIB_INSTALLER,
                   'image' => 'contrib_installer.png',
                   'href' => vam_href_link(FILENAME_CIP_MANAGER, 
'selected_box=contrib_installer'),
                    'children' =>
                        array(
                             array('title' =>BOX_CONTRIB_INSTALLER_CIP_MANAGER,
                                     'link' => vam_href_link(FILENAME_CIP_MANAGER, 
                                     'selected_box=contrib_installer')
                             ),
                            array('title' =>BOX_CONTRIB_INSTALLER_UPLOAD_CIP,
                                     'link' =>vam_href_link(FILENAME_CIP_MANAGER, 
                                      'action=upload&goto='.DIR_FS_CIP)
                             ),
                             array('title' =>'CIP.NET.UA', 
                                      'link' =>vam_href_link('http://cip.net.ua/'))
                        )
                )
);
</replace>
    </findreplace>

Описание 

<find>array('title' => TOOLS_FILES, 'link' => 
vam_href_link(FILENAME_FILE_MANAGER, 'selected_box=tools')))));
</find>

Используется для указания установщику, какой код искать в файле. Код должен существовать в файле, указанном в тэге file. 

        <replace type="php">
                                         array('title' => TOOLS_FILES, 'link' => 

vam_href_link(FILENAME_FILE_MANAGER, 'selected_box=tools')))),
               array(
                   'title' =>BOX_HEADING_CONTRIB_INSTALLER,
                   'image' => 'contrib_installer.png',
                   'href' => vam_href_link(FILENAME_CIP_MANAGER, 
'selected_box=contrib_installer'),
                    'children' =>
                        array(
                             array('title' =>BOX_CONTRIB_INSTALLER_CIP_MANAGER,
                                     'link' => vam_href_link(FILENAME_CIP_MANAGER, 
                                     'selected_box=contrib_installer')
                             ),
                            array('title' =>BOX_CONTRIB_INSTALLER_UPLOAD_CIP,
                                     'link' =>vam_href_link(FILENAME_CIP_MANAGER, 
                                      'action=upload&goto='.DIR_FS_CIP)
                             ),
                             array('title' =>'CIP.NET.UA', 
                                      'link' =>vam_href_link('http://cip.net.ua/'))
                        )
                )
);
</replace>

Код для замены найденного в тэге find.

Код будет заключён в комментарий в зависимости от указанного типа в атрибуте type.

Разрешённые значения атрибута type: php, html, bash.

Стиль комментариев в зависимости от указаннного типа: 

"php" - //comment (default so you could not write it)
"html" - <!-- comment-->
"bash" - #comment

Имя файла: 

<file name="admin/index.php" />

Используется для указания файла, в котором будет произведена поиск и замена.

Для файла в каталоге нужно записывать так: 

<file name=""catalog/includes/application_top.php"" />
Для файла в админке нужно записывать так: 
<file name=""catalog/admin/index.php"" />

Не беспокойтесь о путях, установщик сам определит, где расположена админка, а где каталог.

С помощью catalog и admin Вы просто указывается установщику, что это файл в каталоге, либо это файл в админке. 

<originallinenumbers start="56" end="56" />

Используется для указания строк, в которых находится код, который указан в тэге find.

Примечание

Не обязательно в атрибутах start и end указывать точные номера строк, на данный момент установщик не проверяет указанные строки в атрибутах start и end, а просто ищет в файле код, указанный в тэге find.../find, достаточно просто писать любые числа (кроме 0), например так: 

<originallinenumbers start="1" end="1" />

Можно также использовать такой вариант для поиска нужного кода в файле. 

<originallinenumbers type="continued"/>
Пред. Наверх След.
Основные отличия VamShop от osCommerce  Начало  Создаём модуль для установщика