@@ -1,17 +1,20 @@ |
{maketoc}
|
-!!Introduction
|
+ |
+ |
+!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:
|
-{CODE()}$ mkdir newPackage
|
+{CODE source='php' num='off'} |
+$ mkdir newPackage |
$ mkdir newPackage/modules
|
$ mkdir newPackage/templates{CODE}
|
!!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
|
-{CODE()}-- Note: This first CREATE statement works for postgreSQL
|
+* 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. |
+{CODE source='php' num='off'}-- Note: This first CREATE statement works for postgreSQL |
CREATE TABLE test_table
|
(
|
test_table_id int NOT NULL,
|
|
|
@@ -27,7 +30,7 @@ |
{CODE}
|
|
Insert several rows into the table.
|
-{CODE()}--These INSERT statements work for postgreSQL, MySQL and MSSQL
|
+{CODE source='php' num='off'}--These INSERT statements work for postgreSQL, MySQL and MSSQL |
INSERT INTO test_table (test_table_id, memo) VALUES (1, 'The first memo' );
|
INSERT INTO test_table (test_table_id, memo) VALUES (2, 'The second memo' );
|
INSERT INTO test_table (test_table_id, memo) VALUES (3, 'The third memo' );{CODE}
|
|
|
@@ -35,7 +38,7 @@ |
!!3) Create your PHP file
|
* Go to __newPackage/__ and create a file called ''index.php''
|
* Add the following lines
|
-{CODE()}<?php
|
+{CODE source='php' num='off'}<?php |
require_once('../bit_setup_inc.php'); //initialized the entire system!
|
$result = $gBitDb->query("SELECT * FROM test_table");
|
$gBitSmarty->assign('test_table', $result->GetArray());
|
|
|
@@ -44,9 +47,23 @@ |
!!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:
|
-{CODE()}<?php
|
+{CODE source='php' num='off'}<?php |
global $gBitSystem;
|
$gBitSystem->registerPackage( 'newPackage', dirname( __FILE__ ).'/' );
|
+if( $gBitSystem->isPackageActive( 'newPackage' ) ) { |
+ // ... maybe do some initialization stuff if your package is turned on |
+} |
+?>{CODE} |
+* For Bitweaver 2.0 you will want the file to look like this: |
+{CODE source='php' num='off'}<?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
|
}
|
|
|
@@ -54,7 +71,7 @@ |
!!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:
|
-{CODE()}<table>
|
+{CODE source='php' num='off'}<table> |
{section name=colnum loop=$test_table}
|
<tr>
|
<td>{$test_table[colnum].test_table_id}</td>
|
|
|
@@ -62,6 +79,7 @@ |
</tr>
|
{/section}
|
</table>{CODE}
|
+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
|
|
|
@@ -72,22 +90,48 @@ |
!Voila!
|
Go to __http://yourbitweaverURL/newPackage/__ and your table should be displayed!
|
|
-!!7) Now, create a Module
|
+!!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:
|
-{CODE()}<table>
|
+{CODE source='php' num='off'}<table> |
<tr>
|
- <td class="boxtitle"><b>Planning</b><br></td>
|
+ <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>
|
+ <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>{CODE}
|
(: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 ((function_biticon|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. |
+{CODE source='php' num='off'} |
+<ul> |
+ <li><a class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}index.php">{tr}New Package Home{/tr}</a></li> |
+ <li><a class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}view1.php">{tr}View Something{/tr}</a></li> |
+ <li><a class="item" href="{$smarty.const.NEWPACKAGE_PKG_URL}view2.php">{tr}View something else{/tr}</a></li> |
+</ul> |
+{CODE} |
+ |
+Then register the menu in bit_setup_inc.php. |
+{CODE source='php' num='off'} |
+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 ); |
+} |
+{CODE} |
+To read more about menus, read ((Adding YOUR OWN dropdown menu to the Nav bar!)). |
|
!!8) List of available constants in bitweaver
|
|
|
|
@@ -101,6 +145,9 @@ |
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
|
|
|
@@ -114,10 +161,10 @@ |
|
!!9)Make the package installable
|
In order to make the package installable, you need an additional directory in newPackage/admin
|
-{CODE()}$ mkdir newPackage/admin{CODE}
|
-and the schema information to chack the database with which comes in the form of a ))''schema_inc.php''(( file
|
+{CODE source='php' num='off'}$ mkdir newPackage/admin{CODE} |
+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
|
-{CODE()}
|
+{CODE source='php' num='off'} |
<?php
|
|
$tables = array(
|
|
|
@@ -144,3 +191,14 @@ |
) );
|
?>
|
{CODE} |
+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 |
+*Have a look at the ((SamplePackage)) and its explanation ((SamplePackageDissection)). |
+*If you want to add automated testing, read ((TestingSuites)). |
+*Become a template whizard by reading ((Smarty Functions)). |
+*Think of sorting your list results? Consider using ((function_smartlink)) as column header. |
+*Missing: Search integration. How does the search engine know about the new tables? |
|
|