Project

General

Profile

Package Structure

MySQL dump

There is a reserved way in the CMS core to import data specific for the package. You only need to create a new folder called dumps in your PACKAGE_NAME/includes/ directory and put your MySQL file there. You will be able to import any of these dumps via Admin Panel - Manage Database - Import.

XML file of installation data

Every package folder must have install.xml file. This file contains information about the package. It has the following structure:

<?xml version="1.0" encoding="utf-8" ?>
<!-- The name of the package -->
<!-- @name the name must be unique -->
<extras name="new_package">
    <!-- The title of the package -->
    <title>My New Package</title>

    <!-- The description of the package -->
    <summary>This is my new simple package.</summary>

    <!-- The author of the package -->
    <author>John Smith</author>

    <!-- The contributor of the package -->
    <contributor>Intelliants LLC</contributor>

    <!-- The version of the package -->
    <version>2.2.2</version>

    <!-- Last updated, use YYYY-MM-DD date format here -->
    <date>2012-10-12</date>

    <!-- Just some simple notes. Can be ignored -->
    <notes>Just some simple notes</notes>

    <!-- The minimal version of the script the package works with -->
    <compatibility>2.2.3</compatibility>

    <!-- The default path to the main front-end page of the package -->
    <!-- Can be changed during the installation process -->
    <!-- Example: The code below will set the pacakge to be accessed by http://www.domain.com/new_package/ -->
    <url>new_package</url>

    <!-- Screenshots of the package. Can be viewed in Admin Panel -> Manage Packages -->
    <!-- @type if type is set to "preview" the image will be used as preview screenshot -->
    <!-- @name name of the image file stored in docs/screenshots/ -->
    <!-- The title of the screenshot is stored inside <![CDATA[]]> -->
    <!-- Example: the code below will set preview.jpg as a preview image and 2 other images can be opened in a pop-up window by clicking on the preview image -->
    <screenshots>
        <screenshot type="preview" name="preview.jpg"><![CDATA[Frontend -> Real Estate Main page]]></screenshot>
        <screenshot name="1.jpg"><![CDATA[Frontend of My New Package]]></screenshot>
        <screenshot name="2.jpg"><![CDATA[Backend of My New Package]]></screenshot>
    </screenshots>

    <!-- Items that will be added with the package -->
    <!-- @url_fields list of fields that are used in URL for the item. Example: http://www.domain.com/{title_alias}/{id}.html -->
    <!-- @pages list of extra pages, where item must work. Example: Favorites, Search, View Member pages -->
    <!-- @main set items as main for the list of specified pages. Example: Add Item, Edit Item, View Item pages -->
    <!-- @table_name name of the table (without prefix) that contains item records. Any Fields operations will add/remove/alter columns of this table. -->
    <!-- @class_name major classname responsible for manipulations with the items. It can be used to avoid built in system with the trailing 'S' letter for an item name to generate class. -->
    <!-- @payable 1 - plans can be assigned for the item, 0 - the item without plans -->
    <packageitems>
        <item url_fields="title_alias,id" pages="favorites,advsearch,view_account" main="item_add,item_edit,item_view" table_name="items" class_name="items">items</item>
        <item url_fields="title_alias" pages="" table_name="categories" payable="0">NewCategories</item>
    </packageitems>

    <!-- The list of buttons in Admin Panel that redirects to action pages like add/browse items and fields -->
    <!-- @name the name of the page the button redirects to -->
    <!-- @url the URL of the page the button redirects to -->
    <!-- @icon the icon name for button -->
    <!-- @order index number of the button in the list -->
    <!-- @pages names of the pages the button will be placed to -->
    <actions>
        <action name="item_list" url="newpackage/items/" icon="list" order="1" pages="item_add,item_edit">List of Items</action>
        <action name="item_add" url="newpackage/item/add/" icon="plus" order="2" pages="item_list,item_edit">Add New Item</action>
    </actions>

    <!-- The list of blocks that will appear at the left column of Admin Panel -->
    <!-- @name The name of the block should be unique -->
    <!-- @url The link opened by clicking the block's caption -->
    <!-- Example: the code below creates a block with the "newpackage" name, linked to http://www.domain.com/admin/home/newpackage/ and "My New Package" title in the caption. -->
    <adminblocks>
        <block name="newpackage" url="home/newpackage/">My New Package</block>
    </adminblocks>

    <!-- The list of pages available in Admin Panel to work with the package -->
    <!-- @group the name of the Admin Panel group which will store the link to the page (default is the name of plugin/package) -->
    <!-- @filename the name of the php file (written without an extension ".php") placed in the admin folder of the package that handles page request (default is "index") -->
    <!-- @name the name of the page itself. Should be unique -->
    <!-- @url the URL a page will be accessible at (e.g. www.yourdomain.com/admin/@url/) -->
    <!-- @menus the menus where the link to the page will be displayed. Available: menu, header -->
    <!-- @parent (optional) defines the name of parent page, used by permissions subsystem. if set, permissions will be checked for the parent page -->
    <!-- @action (optional) defines the action code, used by permissions subsystem. System values are "add", "edit", "delete" and any custom values. Default is "read" -->
    <adminpages>
        <page group="newpackage" name="newpackage_home" url="home/newpackage/" menus="menu">My New Package</page>
        <page group="newpackage" filename="items" name="items" url="newpackage/items/" menus="menu">My Items</page>
        <page group="newpackage" filename="items" name="items_add" url="newpackage/items/add/" parent="items" action="add">Add New Item</page>
        <page group="newpackage" filename="fields" name="items_fields" url="fields/items/" action="items" menus="menu">Item Fields</page>
    </adminpages>

    <!-- The list of pages available on Front-End to work with the package -->
    <!-- @group the group of a page. Pages are grouped in several admin panel sections -->
    <!-- @filename (optional) the name of the php file (written without an extension ".php") placed in the root folder of the package that handles page request. Default is "index" -->
    <!-- @name the name of the page itself. Should be unique -->
    <!-- @url the page will be accessible by the defined url (e.g. www.yourdomain.com/@url/) -->
    <!-- @menus the menus where the link to the page will be displayed -->
    <!-- @parent (optional) defines the name of parent page, used by permissions subsystem. if set, permissions will be checked for the parent page -->
    <!-- @action (optional) defines the action code, used by permissions subsystem. System values are "add", "edit", "delete" and any custom values. Default is "read" -->
    <!-- @service (optional) 0 - the page is used as a common page with a content, 1 - the page is used as an intermediate without a content (e.g. handle ajax requests only) -->
    <pages>
        <page group="newpackage" name="newpackage_home" url="|PACKAGE|" menus="newpackage,main">My New Package</page>
        <page group="newpackage" name="latest_items" url="|PACKAGE|latest_items/" menus="newpackage">Latest Items</page>
        <page group="newpackage" filename="item_submit" name="item_add" url="|PACKAGE|add/" action="add" parent="item_view" menus="newpackage">Add Item</page>
        <page group="newpackage" filename="item_submit" name="item_edit" url="|PACKAGE|edit/" action="edit" parent="item_view" service="1">Edit Item</page>
        <page group="newpackage" filename="item_view" name="item_view" url="|PACKAGE|item/">View Item</page>
        <page group="newpackage" name="my_items" url="|PACKAGE|my_items/" menus="newpackage">My Items</page>
    </pages>

    <permissions>
        <!-- OBJECT tag adds a default access rule for the particular item and adds a corresponding editable entry to Permissions section of Admin Panel-->
        <!-- @id the name of an object to manage. Basically it is the name of a page. Required parameter -->
        <!-- @meta_object the meta object to manage. Possible values are "page" and "admin_page" (default is "page") -->
        <!-- @action the name of the action to manage (default is "read") -->
        <!-- @access allow/disallow access flag (default is 0) -->

        <!-- Example: specifies that by default the "My Items" frontend page will not be accessible and creates an appropriate named item in Permissions section of Admin Panel -->
        <object id="my_items">My Items</object>
        <!-- Example: create a named item for backend page in Permissions section of Admin Panel with default behavior to allow access -->
        <object meta_object="admin_page" id="items" access="1">Manage items</object>
        <!-- Example: create a named item for backend in Permissions section of Admin Panel with default behavior to allow access and custom "action" value -->
        <object meta_object="admin_page" id="items_fields" action="items" access="1">Allow to manage item fields</object>

        <!-- PERMISSION tag sets a permission to the particular item -->
        <!-- @type type of entity. Possible values are "user", "group" and "plan" ("group" is for "usergroup", default is "group") -->
        <!-- @type_id the ID of an entity. Basically it is the ID of a particular user, usergroup or plan. Required parameter -->
        <!-- @access allow/disallow access flag (default is 0) -->
        <!-- @action the name of the action to manage (default is "read") -->
        <!-- @object the type of object to manage. Possible values are "page" and "admin_page" (default is "page") -->

        <!-- Example: technically, specifies that the "add" action of "item_view" page should NOT be accessible to usergroup with ID 4. In other words, guests are not allowed to post new items -->
        <permission type="group" type_id="4" action="add" access="0">item_view</permission>
        <!-- Example: specifies that the "view" action of the page "my_items" should not (default value of parameter "access" is 0) be accessible to usergroup (default value of the parameter "type" is "group" - usergroup) with ID 4. Meaning, guests will not have access to "My Items" page -->
        <permission type_id="4">my_items</permission>
    </permissions>

    <!-- Crontab rules -->
    <cron name="mailer">*/30 * * * * newpackage/includes/cron/cleanup.php</cron>

    <!-- Additional tab for the package in Admin Panel -> Configuration --> 
    <!-- @name the name of the configuration group -->
    <!-- Example: the code below creates a tab with the "newpackage" name and "My New Package" title -->
    <configgroup name="newpackage">My New Package</configgroup>

    <!-- The list of options for configurations of the package -->
    <!-- @group the option is placed to predefined tab on the Configuration page -->
    <!-- @name the name of the option. Should be unique -->
    <!-- @type the type of the option. Available: text, textarea, checkbox, radio, select, combo, divider, hidden, password, image, itemscheckbox -->
    <!-- @values the values of the option. Available for: select, combo, radio, checkbox -->
    <!-- @description the left-handed text part of the option that describes the option-->
    <!-- @show config option dependency, format FIELD_NAME|value -->
    <!-- @wysiwyg enables CKEditor wysiwyg configuration for the config option -->
    <!-- @code_editor enables EditArea code editor for the textarea config option -->
    <config group="newpackage" name="items_divider" type="divider">Items</config>

    <config group="newpackage" name="allow_guests_to_submit" type="radio" values="1,0" 
        description="Allow Guests to Submit Items" show="accounts|1">1</config>

    <config group="newpackage" name="items_per_page" type="text" 
        description="Number of Displayed Items per Page">10</config>

    <!-- The list of groups which stores items' fields -->
    <!-- @item the predefined item the fieldgroup will be assigned to -->
    <!-- @name the name of the fieldgroup. Should be unique for items -->
    <!-- @collapsed 1 - enable minimizing of the group on a front-end, 0 - disable minimizing of the group on a front-end -->
    <fields_groups>
        <group item="items" name="items_general" collapsed="0">General</group>
        <group item="categs" name="categs_general" collapsed="0">General</group>
    </fields_groups>

    <!-- The list of fields -->
    <!-- @name the name of the field. Should be unique for items -->
    <!-- @item the predefined item the field will be assigned to -->
    <!-- @type the type of the field. Available: text, textarea, combo, radio, checkbox, storage, image, number, date, pictures, url-->
    <!-- @group the predefined fieldgroup the field will be assigned to -->
    <!-- @length the number of symbols that are allowed. Available for: text, number, url -->
    <!-- @searchable 1 - include the field to a search criterias on advanced search, 0 - do not include the field to a search criterias -->
    <!-- @required 1 - set the field to be required for submit. 0 - do not set the field to be required. Default value is 0 if ignored -->
    <!-- @adminonly 1 - the field seen in Admin Panel only. 0 - available for all members. Default value is 0 if ignored -->
    <!-- @page the list of predefined front-end pages the field will be displayed on. -->
    <!-- @values the values of the field. Available for: combo, radio, checkbox -->
    <!-- @default default value. Available if @values is set -->
    <!-- @editor 1 - turn on WYSIWYG editor for the field. Available for textearea only-->
    <!-- @width max width of the image(s). Available for: image, pitctures -->
    <!-- @height max height of the image(s). Available for: image, pitctures -->
    <!-- @thumb_width max width of the image(s) thumbnail(s). Available for: image, pitctures -->
    <!-- @thumb_height max height of the image(-s) thumbnail(s). Available for: image, pitctures -->
    <!-- @folder_name a custom folder name for images. The path for the images will be set to uploads/@folder_name/ -->
    <!-- @order the order number of the field -->
    <!-- @relation - parent|dependent field dependency on another field -->
    <!-- @parent - only for relation="dependent", format: "FIELD_NAME:value1,value2;ANOTHER_FIELD_NAME:value1" -->
    <fields>
        <field name="title" item="item" type="text" group="items_general" 
            length="70" searchable="1" required="1" adminonly="0" 
            page="new_items,item_add,item_edit,view_account,item_view,favorites">Title</field>

        <field name="simple_checkbox" group="items_general" item="item" type="checkbox" searchable="1" values="check_1||Choice #1,check_2||Choice #2">Simple Checkbox</field>

        <field name="simple_dropdown" type="combo" group="items_general" item="items" page="new_items,item_add,item_edit,view_account,item_view,favorites" values="Select 1,Select 2,Select 3" default="Select 1" required="0" searchable="1">Dropdown List</field>

        <field name="description" item="item" type="textarea" group="items_general" 
             editor="1" searchable="1" required="1" adminonly="0" length="" default="" 
            page="new_items,item_add,item_edit,view_account,item_view,favorites">Description</field>

        <field name="simple_image" item="item" type="image" group="items_general" 
            width="320" height="320" editable="0" adminonly="1" 
            page="new_items,item_add,item_edit,view_account,item_view,favorites" folder_name="items_images">Item's Image</field>

        <field name="file_storage" item="item" type="storage" group="items_general"  
            page="item_add,item_edit,item_view" prefix="storage_" types="zip,pdf,doc,docx">Item's Storage</field>
    </fields>

    <!-- Phrases that will be used in the package for different languages-->
    <!-- @category the category of the phrase. Available: common, frontend, admin -->
    <!-- @key the key of the phrase. Should be unique -->
    <phrases>
        <phrase category="common" key="item_added">New item is added.</phrase>
        <phrase category="frontend" key="view_item">View Item</phrase>
        <phrase category="admin" key="manage_items">Manage Items</phrase>
    </phrases>

    <!-- The list of blocks that will be displayed on the Fron-End -->
    <!-- @name the name of the block. Should be unique. If ignored serial number will be set instead -->
    <!-- @title the title of the block displayed in the header of the block -->
    <!-- @position position of the block on the front-end -->
    <!-- @type the type of the block's content. Available: php, smarty, html, plain -->
    <!-- @showheader 1 - display the caption of the block, 0 - do not display the cation of the block -->
    <!-- @collapsible 1 - enable minimizing of the block on a front-end, 0 - disable minimizing of the block on a front-end. Ignore if @showheader is set to 0 -->
    <!-- @sticky 1 - displaying the block on every front-end page, 0 - displaying on certain pages only. Default value is 0 if ignored-->
    <!-- @pages the comma separated list of pages the block will be displayed on. Ignore if @sticky is set to 1 -->
    <!-- @filename use the file's code within the block. Works for php and smarty blocks only. -->
    <!-- @classname adds a specific CSS classname for the block html wrapper. It could be useful to create a specifically designed block. -->
    <blocks>
        <!-- @filename usage for smarty blocks [available in 2.2.4 version]: "path/to/the/file.tpl" -->
        <!-- the path is set without the path to subrion folder, e.g. "packages/newpackage/templates/common/author-block.tpl -->
        <!-- @filename usage for smarty blocks [available in 2.2.5 and higher versions]: "package_name:file.tpl" -->
        <!-- where package_name is the name of the package and file.tpl is the name of the file stored in the package's templates/common/ folder -->
        <block name="item_author" title="Author" position="right" type="smarty" sticky="0" showheader="1" pages="item_view" collapsible="1" order="3" filename="newpackage:author.tpl"><![CDATA[]]></block>

        <!-- @filename usage for php blocks [available in 2.2.4 version]: "path/to/the/file.php" -->
        <!-- the path is set without the path to subrion folder, e.g. "packages/newpackage/templates/item_ads.php -->
        <block name="item_ads" title="Item Ads" position="top" type="php" sticky="1" showheader="0" order="1" filename="packages/newpackage/item_ads.php"><![CDATA[]]></block>

        <block name="newblock" title="New Block" position="left" type="smarty" collapsible="1" sticky="0" pages="newpackage_home">
            <![CDATA[
--- some code here ----
            ]]>
        </block>
    </blocks>

    <!-- The list of hooks used in the script -->
    <!-- @name the name of the hook that exists in the system-->
    <!-- @type the code type. Available: php, smarty, html, plain -->
    <!-- @page_type the type of the page. Available: admin, front, both. Default value is both if ignored -->
    <!-- @filename use the file's code within the block. the path is set without the path to subrion folder -->
    <hooks>
        <hook name="phpCoreGetUrlBeforeConstantDefine" filename="packages/newpackage/includes/process.php" type="php"><![CDATA[]]></hook>

        <hook name="phpStatisticsBlockAssembling" type="php" page_type="front">
            <![CDATA[
--- some code here ---
            ]]>
        </hook>
    </hooks>

    <!-- SQL queries run during package installation -->
    <!-- @external (optional) - allows to execute external sql file, the file could be zip or simple text file -->
    <!-- There are {DS} and {DIRECTORY_SEPARATOR} tags to replace separator related to OS -->
    <!-- Add {mysql_version} to force a collate "utf8_general_ci" set for all not int fields -->
    <!-- Add {prefix} to automatically replace with the real table prefix -->
    <install>
        <sql>
            <![CDATA[
CREATE TABLE IF NOT EXISTS `{prefix}items` (
    `id` int(7) unsigned NOT NULL auto_increment,
    `category_id` int(7) unsigned NOT NULL default '0',
    PRIMARY KEY  (`id`),
) {mysql_version};
            ]]>
        </sql>
        <sql external="1">
            <![CDATA[
path{DS}to{DIRECTORY_SEPARATOR}file.sql
            ]]>
        </sql>
        <c?de>
            <![CDATA[
echo "This PHP code is executed during package installation.";
            ]]>
        </c?de>
    </install>

    <!-- SQL queries run during the package's uninstallation -->
    <uninstall>
        <sql>
            <![CDATA[
DROP TABLE IF EXISTS `{prefix}items`;
            ]]>
        </sql>
        <c?de>
            <![CDATA[
echo "This PHP code is executed during package uninstallation.";
            ]]>
        </c?de>
    </uninstall>

    <!-- SQL queries and PHP code which will run when extras upgrades -->
    <!-- @version - version we need to upgrade extras from -->
    <upgrade>
        <c?de>
            <![CDATA[
                echo "This is upgrade PHP code";
            ]]>
        </c?de>
        <sql version="1.0">
            <![CDATA[
ALTER TABLE `{prefix}test` CHANGE `date` `date` DATETIME NOT NULL DEFAULT '0000-00-00';
            ]]>
        </sql>
        <sql version="1.0">
            <![CDATA[
ALTER TABLE `{prefix}test` DROP `lang`;
            ]]>
        </sql>
    </upgrade>
</extras>

Package Icon

It is highly required to add an icon for your package. Icon is displayed on Packages list (Admin Dashboard / Extensions / Packages).
Icon should be place in PACKAGE_NAME/docs/img/ folder and it should have 'icon.png' name (PNG is required icon format).
Recommended dimensions: 350px width, 350px height. Icon should be non-transparent, that means that icon should have a background.