Project

General

Profile

h1. Package Structure

h2. 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.

h2. 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 -->

<!-- The title of the package -->
My New Package

<!-- 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 ----
]]>

<!-- 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 ---
]]>

<!-- 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};
]]>


<![CDATA[
path{DS}to{DIRECTORY_SEPARATOR}file.sql
]]>


<![CDATA[
echo "This PHP code is executed during package installation.";
]]>

<!-- SQL queries run during the package's uninstallation -->
<uninstall>
    <sql>
        <![CDATA[

DROP TABLE IF EXISTS {prefix}items;
]]>


<![CDATA[
echo "This PHP code is executed during package uninstallation.";
]]>

<!-- 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';
]]>


<![CDATA[
ALTER TABLE {prefix}test DROP lang;
]]>


h2. 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.