Sharetronix

Sharetronix App installer

From Sharetronix Developer Documentation
Jump to: navigation, search

Sharetronix OPEN SOURCE App Installer

This short documentation/tutorial is intended to be read by app developers and explain how they should pack their app in order to benefit from our automatic install system.Basic InstallerFirst of all, you have to write your app and create a folder where to store all app files. Alongside all files you must create a file called "installer.php". This file is going to contain a single class which must be called MyInstaller and always extend class Installer. Do not worry about including all files and resolving dependency issues, the installer is going to do this for you. So, the first few rows of your app should look something like this:

class MyInstaller extends Installer 
{
    public function MyInstaller(){
        parent::Installer();
    }
}

So, what we are doing here is just extend the base Installer class and calling its contructor. If your app does not require and database modifications this is everything you should do. Just copy and paste it in your installer.php file. @note still not implemented, but there is an idea if no Installer.php file is found, the marketplace system to assume it requires no special actions and autogenerate the file.<?php  class MyInstaller extends Installer {

public function MyInstaller(){
    parent::Installer();
}
public function up(){}
public function down(){}

The main idea is verry simple. Everything you type in method "up" is executed when your app is installed and everyting you type in method "down" is executed when your app is uninstalled. It is mandatory to implement both methods and its likely your app not to be approved if "down" method is not implemented. So .. I mentioned a database before, how can we access it. Luckily for you your new class MyInstaller have a public property called db which contains an object which implements DatabaseInterface.php. Everything database related you might want to do can be done with using this object. Lets take a look of DatabaseInterface`s methods.

/*** create_table** 
@access public* 
@param string $table_name* 
@return void
*/

public function create_table($table_name);

Just creating a table, nothing special, just provide a name of the table. The table is going to be instanly created with a first column id INT(11) NOT NULL AUTO_INCREMENT and of course - primary key. As you may assume you cannot duplicate table names or drop other developers tables, so we stronly advise you to use some kind of prefix for your table names.

/*** drop_table** 
@access public* 
@param string $table_name* 
@return void
*/

public function drop_table($table_name);

This is the method you can use to delete tables, just keep in mind that you cannot delete system tables or tables created by other apps. This method is supposed to be used if you want to get rid of some table you`ve created in the previous version of your app.

/*** add_field** 
@access public* 
@param string $table_name* 
@param string $field_name* 
@param DatabaseType $field_type* 
@param array<FieldOption> $options* 
@return void
*/

public function add_field($table_name, $field_name, $field_type, $options = array());

The fun starts here. Of course you are going to need to add columns/fields to your tables and this is how you do it. $table_name and $field_name should be self explanatory. $field_type should be a constant from class DatabaseType which looks like this:

abstract class ColumnType {
    const INTEGER = "INT";
    const STRING = "VARCHAR"; 
    const TEXT = "TEXT";
    const FLOAT = "FLOAT";
    const DECIMAL = "DECIMAL";
    const DATETIME = "DATETIME";
    const TIME = "TIME";
    const DATE = "DATE";
    const BINARY = "BLOB";
    const BOOLEAN = "TINYINT";
}

These are all column types we currently support and we stronly advise you to use these contants. Let me just explain what $options is and I`m going to give you a comlete example. $options should always be array containing FieldOption object. Currently we have 3 FieldOption objects - FieldOptionDefault, FieldOptionLimit and FieldOptionNull and the easiest way to explain what they do is just by showing you.ex1:

$this->db->add_field('myTable', 'counter', ColumnType::INTEGER, array(new FieldOptionLimit(11), new FieldOptionDefault(0)));

This is going to create a column called `counter` of type INT(11) which default value is going to be 0 and NULL value is going to be allowed. If we want to make the column NOT NULL, we just have to add in the options array something like:

new FieldOptionNull(false); 

or maybe in the second example:ex2:

$this->db->add_field('test_table',  'name', ColumnType::STRING,  array(new FieldOptionLimit(50), new FieldOptionNull(true)));

this is going to result in:


name VARCHAR(50) NOT NULL

You can combine all options when this makes sense. You can add fields only to system tables and tables created by your app. You cannot add fields to tables created by other apps. If you can add fields you should be able to remove them.

/*** remove_field** 
@access public* 
@param string $table_name* 
@param string $field_name* 
@return void
*/

public function  remove_field($table_name, $field_name);

Pretty straight forward, you give table name and the name of the field which should be removed; You cannot remove fields from system tables and tables which are created by other apps. You have create_table, drop_table, add_field and remove_field, for everything else there is execute.

/*** execute** 
@access public* 
@param string $sql* 
@return bool
*/

public function execute($sql);

Because we know that not everything about app installation is creating tables and adding fields we provide you the ability to execute your own sql queries. Do not use this method for trivial stuff like creating tables, adding fields, ect. because this way is harder for us to detect conflicts with other apps. Use cutom queries only when absolutely necessary, they will be displayed to the user and confirmation will be asked before executing.ManifestThe manifest file is a simple json file telling our system some basic information about your app. The file should be called manifest.json and have to be placed alongside your installer.php file. Creating such file is not mandatory, our marketplace will attempt to create it automaticly from the information you enter when submiting the app. After all, human touch is always better so maybe you would like to create your own. Here is the template:

{
"app_name": "My_Test_App",
"descr": "This is longer description of my test app",
"version": "1.0.1",
"author": "Hristo Georgiev",
"email": "hristo@stx.com"
}
I think it is a good idea to check for manifest.json file while submiting the app and automaticly enter information in the submit form.Packing your app
[myPlugdinDir] (should not be included in the archive)
    [system]
    [static]
    installer.php
    manifest.json
    plugin.php 

and you should create an archive from this directory without uncluding the parrent folder. Using winrar (on windows) your command should look like this:

cd c:\myappdir 
del ..\test_app.zip 
winrar a -r ../test_app.zip

Mind the dot at the end. Just keep this command in your command line for easy and fast repacking of app during development.

Personal tools
Namespaces

Variants
Actions
STX User guide
STX Developer guide
Sharetronix Sites