Tutorial_Custom_Package

Step by step tutorial to create your own package.

Created by: fire, Last modification: 14 Jan 2007 (13:14 UTC) by hiran

Introduction

This is a BASIC tutorial that will show you how to make a quick package that loops through a table and displays its data. I wrote this because I am starting from the VERY beginning here in bitweaver, and want to make tutorials as I go to help new opensource developers who are joining the project and need a booster seat to sit at the table! I hope it is useful to you!
Thanks for your help Spiderr

1) Create a New bitweaverPackage

  • Go to the root of your bitweaver installation and make a directory:

<?php
mkdir newPackage
mkdir newPackage/modules
mkdir newPackage/templates
?>

2) Create your table

  • In your bitweaver database, create a table called test_table, and add two colums: test_table_id, and memo, or use the sql below. Later we shall see how such tables can be created during plugin installation.

<?php
-- NoteThis first CREATE statement works for postgreSQL
CREATE TABLE test_table
(
  
test_table_id int NOT NULL,
  
memo text[]
WITHOUT OIDS;
--
-- 
This CREATE TABLE statement works for MySQL and MSSQL
CREATE TABLE test_table
(
  
test_table_id int NOT NULL,
  
memo text
)
?>


Insert several rows into the table.

<?php
--These INSERT statements work for postgreSQLMySQL and MSSQL
INSERT INTO test_table 
(test_table_idmemoVALUES (1'The first memo' );
INSERT INTO test_table (test_table_idmemoVALUES (2'The second memo' );
INSERT INTO test_table (test_table_idmemoVALUES (3'The third memo' );
?>


3) Create your PHP file

  • Go to newPackage/ and create a file called index.php
  • Add the following lines

<?php
  
require_once('../bit_setup_inc.php'); //initialized the entire system!
  
$result $gBitDb->query("SELECT * FROM test_table");
  
$gBitSmarty->assign('test_table'$result->GetArray());
  
$gBitSystem->displayNEWPACKAGE_PKG_PATH '/templates/newPackage.tpl''New Package Page' );
?>

4) Create your package's bit_setup_inc file

  • Go to newPackage/ and create a file called bit_setup_inc.php
  • Add the following lines:

<?php
global $gBitSystem;
$gBitSystem->registerPackage'newPackage'dirname__FILE__ ).'/' );
if( 
$gBitSystem->isPackageActive'newPackage' ) ) {
  
// ... maybe do some initialization stuff if your package is turned on
}
?>

  • For Bitweaver 2.0 you will want the file to look like this:

<?php
global $gBitSystem;
$registerHash = array(
    
'package_name' => 'newPackage',
    
'package_path' => dirname__FILE__ ).'/',
    
'homeable' => TRUE,
);
$gBitSystem->registerPackage$registerHash );

if( 
$gBitSystem->isPackageActive'newPackage' ) ) {
  
// ... maybe do some initialization stuff if your package is turned on
}
?>

5) Create your Smarty TPL file

  • Now go to newPackage/templates and create a file using pico, or whatever you use, called newPackage.tpl
  • Add these lines:

<?php
<table>
  {
section name=colnum loop=$test_table}
  <
tr>
    <
td>{$test_table[colnum].test_table_id}</td>
    <
td>{$test_table[colnum].memo}</td>
  </
tr>
  {/
section}
</
table>
?>

Bitweaver uses the Smarty template engine, enriched with some custom functions. Read more about that on Smarty Functions.

6) Activate your new package

  • Click Administration -> Kernel -> Packages
  • Scroll down to find "newPackage" (the list is alphabetical)
  • Check the box to enable the package
  • Go all the way to the bottom and click the "Activate" button

Voila!

Go to http://yourbitweaverURL/newPackage/ and your table should be displayed!

7a) Now, create a Module

  • To create a module (a little box that you can display in the left or right columns) with a pointer to your awesome new package, we will use the modules directory you created in step 1
  • Create a file using pico, or whatever text editor you use, called mod_newPackage.tpl.
  • The file name must be formated like this so bitweaver can include it in the Administration / Modules dropdown list.
  • Add these lines to the file:

<?php
<table>
  <
tr>
    <
td class="boxtitle"><b>Planning</b>
</
td>
  </
tr>
  <
tr>
    <
td><a href="{$smarty.const.NEWPACKAGE_PKG_URL}index.php">
    { 
biticon ipackage=newPackage iname=iconname iexplain="this is a cool icon"}My New Package</a></td>
  </
tr>
</
table>
?>

(:exclaim:) $smart.const.whatever_PKG_URL is a pointer to a folder called whatever in the root...
to use icons check out our cool new icon system called biticon

7b) Add menu entries

Maybe you chose your package be no module. Maybe you have additional functionality that shall plugin into Bitweaver's menu bar. This is a two step procedure.

First create your templates/menu_newPackage.tpl file with the menu items you want to add.

<?php
<ul>
    <
li><class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}index.php">{tr}New Package Home{/tr}</a></li>
    <
li><class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}view1.php">{tr}View Something{/tr}</a></li>
    <
li><class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}view2.php">{tr}View something else{/tr}</a></li>
</
ul>
?>


Then register the menu in bit_setup_inc.php.

<?php
if( $gBitSystem->isPackageActive'newPackage' ) ) {
    
$menuHash = array(
        
'package_name'  => NEWPACKAGE_PKG_NAME,
        
'index_url'     => NEWPACKAGE_PKG_URL.'index.php',
        
'menu_template' => 'bitpackage:eventcal/menu_newPackage.tpl',
    );
    
$gBitSystem->registerAppMenu$menuHash );
}
?>

To read more about menus, read ((Adding YOUR OWN dropdown menu to the Nav bar!)).

8) List of available constants in bitweaver


automagically generated constants for each package of the form
<package>_PKG_PATH --> example: WIKI_PKG_PATH
this will give you the full path to the wiki folder
<package>_PKG_URL --> example: WIKI_PKG_URL
this will give you the full url to the wiki folder

in addition there are a few more
these contain the full path and url to the root of the application
BIT_ROOT_PATH
BIT_ROOT_URL

contains the table name prefix as given in the install script
BIT_DB_PREFIX

contains the name of the currently active package
ACTIVE_PACKAGE

full path and url to the currently active style
THEMES_STYLE_PATH
THEMES_STYLE_URL

Stay tuned for more Tutorials!
Fire

9)Make the package installable

In order to make the package installable, you need an additional directory in newPackage/admin

<?php
mkdir newPackage/admin
?>

and the schema information to chack the database with which comes in the form of a schema_inc.php file. In case you want to create columns with other data types, see DataDict.
The sample for this package is

<?php

$tables 
= array(

'test_table' => "
  test_table_id I4 NOTNULL PRIMARY,
  memo X
"
,

);

global 
$gBitInstaller;

foreach( 
array_keys$tables ) AS $tableName ) {
    
$gBitInstaller->registerSchemaTableNEWPACKAGE_PKG_NAME$tableName$tables[$tableName] );
}

$gBitInstaller->registerPackageInfoNEWPACKAGE_PKG_NAME, array(
    
'description' => "A test package.",
    
'license' => '<a href="http://www.gnu.org/licenses/licenses.html#LGPL">LGPL</a>',
    
'version' => '0.1',
    
'state' => 'beta',
    
'dependencies' => '',
) );
?>

To add a nice looking icon besides the package name, simply create an icons folder inside your newpackage directory and drop a file named newpackage.png there.

10)Populate database

By providing sample data you can populate the database during module install time. See Installer Data Pump for more information.

11)Further reading

Comments

Great tutorial

by JG Estiot, 10 Oct 2006 (06:52 UTC)
Great tutorial, well explained and well presented. Thank you.

Re: Great tutorial

by Kozuch, 11 Apr 2007 (13:51 UTC)
Very nice tutorial indeed.
  Page 1 of 1  1