History of Framework - Developer's Guide
{maketoc}
The Bitweaver Framework, consisting of Liberty and Kernel, offers you a lot of functionality. Here we'll try to show how you can make use of that.
!Business Objects a la Liberty
!!Which base class?
If you want to create your own [http://en.wikipedia.org/wiki/Business_object_(computer_science)|Business Object], you will probably use LibertyAttachable as base class, as it offers most functionality. Use LibertyContent or LibertyBase when you know what you are doing.
!!LibertyAttachable
Classes derived from LibertyAttachable come with this functionality:
*They can take title and formatted text
*They maintain creation date, creator and modification date/modificator information
*their text content is subject to the full text seach
*The calendar can display events occurring to LibertyAttachable objects.
*Upon database access (store, load) other service plugins are triggered
If all you need is a new data type that contains some formatted text, you might be pretty quick in implementation:
{code}
<?php
require_once( LIBERTY_PKG_PATH.'LibertyAttachable.php' ); //import base class
define( 'BITRESOURCE_CONTENT_TYPE_GUID', 'bitresource' ); // This is used to uniquely identify the object type
class BitResource extends LibertyAttachable {
/**
* During initialisation, be sure to call our base constructors
**/
function BitResource( $pContentId=NULL ) {
LibertyAttachable::LibertyAttachable();
$this->mContentId = $pContentId;
$this->mContentTypeGuid = BITRESOURCE_CONTENT_TYPE_GUID;
$parms = array(
'content_type_guid' => BITRESOURCE_CONTENT_TYPE_GUID,
'content_description' => 'Managed Resource',
'handler_class' => 'BitResource',
'handler_package' => 'mypackage',
'handler_file' => 'BitResource.php',
'maintainer_url' => 'mailto:guess@who.com'
);
$this->registerContentType( BITRESOURCE_CONTENT_TYPE_GUID, $parms ); // register class with Bitweaver
}
}
?>
{/code}
!!!Custom fields
Probably you will want to add some custom fields. This will be some more work, as Liberty won't know about them and we have to handle them ourselves.
First think of a place to store the data. We will have to use our own table in the database. To match the liberty data with our own we should use an identifier. [content_id] is the one provided by liberty, and it will serve us well now. So create a table with two columns, just as shown. Later you will see how Bitweaver automatically creates the table upon package installation.
{code}
create table mydata (
content_id integer(4),
expires timestamp
)
{/code}
*getServicesSQL
*prepGetList
*postGetList
!!!History functionality
How can you enable history tracking in Liberty?
!!LibertyContent
!!LibertyBase
!Sorted Lists
Up to now, the answer is to look at the ((SamplePackage)) and guess.
*$gBitSystem->display(...)
!Detail Views
Up to now, the answer is to look at the ((SamplePackage)) and guess.
!Feedback and Confirmation
Up to now, the answer is to look at the ((SamplePackage)) and guess.
*gBitSystem->setBrowserTitle()
*gBitSystem->confirmDialog()
!Authorisation Required
Up to now, the answer is to look at the ((SamplePackage)) and guess.
!!Menus and Modules
Up to now, the answer is to look at the ((SamplePackage)) and guess.
Layout assigned module titles and parameters
!Services
The previous section showed how you can add a nice HTML GUI to your code. Now see what can be done behind the scenes.
!Installation and Migration
!!The Database Schema
Your package contributes to Bitweaver. That also is during database creation. To setup the correct tables, privileges and the such make use of the _admin/schema_inc.php_ script. It is called by the Bitweaver package installer during database creation time. The version shown here creates the table for our custom field in the BitResource class, registers the package and installs some privileges.
{code}
<?php
$tables = array(
'resources' => "
content_id I4 NOTNULL PRIMARY,
expires T
",
);
global $gBitInstaller;
foreach( array_keys( $tables ) AS $tableName ) {
$gBitInstaller->registerSchemaTable( MYPACKAGE_PKG_NAME, $tableName, $tables[$tableName] );
}
$gBitInstaller->registerPackageInfo( MYPACKAGE_PKG_NAME, array(
'description' => "What my package is made for",
'license' => '<a href="http://www.gnu.org/licenses/licenses.html#LGPL">LGPL</a>',
'version' => '0.1',
'state' => 'developing',
'dependencies' => 'users',
) );
// ### Default UserPermissions
$gBitInstaller->registerUserPermissions( MYPACKAGE_PKG_NAME, array(
array('p_event_create', 'Can create a resource', 'registered', MYPACKAGE_PKG_NAME),
array('p_event_admin', 'Can admin resources', 'editors', MYPACKAGE_PKG_NAME),
array('p_event_read', 'Can read resources', 'registered', MYPACKAGE_PKG_NAME),
) );
?>{/code}
*More about $gBitInstaller
!!Data Pump
If you want to populate the database with sample data during the installation process, you have to make use of the data pump.
For the easy to use BitResource type, simply create a file named _pump_mypackage_inc.php_ in the bitweaver/install directory with the following content. All it does is fill an array with the data to populate, then loop through that array and feed everything into BitResource::store(). Error/success messages are stored in variables.
This file will be called from the Bitweaver installer after the user agreed to populate the database, and afterwards the installer will display the error or success messages.
{code}
<?php
require_once( MYPACKAGE_PKG_PATH.'BitResource.php' );
$resourcesHash = array (
array(
'title' => 'Coffee',
'edit' => 'just the classic instant coffe',
),
);
foreach( $resourcesHash as $resource ) {
$newResource = new BitResource();
if( $newResource->store( $resource ) ) {
$pumpedData['EventCal'][] = $resource['title'];
} else {
$error = $newResource->mErrors;
error_log('Error creating mypackage resources: '.$error, 0);
xdebug_debug_zval('error');
$gBitSmarty->assign( 'error',$error );
}
}
?>
{/code}
If you have custom fields that need population, simply add them to the array above and you are done.
!!Data Format
!!!National language characters
What encoding should be used for the PHP file? How shall national language characters (at worst the complete unicode character set) be escaped?
!!!Timestamps
Bitweaver is said to use UTC times within the database. What times are used on timestamps in the installer?
(MySQL does not support timestamps with timezone information. However the timezone used must be set in the database connection. How is that handled?
The Bitweaver Framework, consisting of Liberty and Kernel, offers you a lot of functionality. Here we'll try to show how you can make use of that.
!Business Objects a la Liberty
!!Which base class?
If you want to create your own [http://en.wikipedia.org/wiki/Business_object_(computer_science)|Business Object], you will probably use LibertyAttachable as base class, as it offers most functionality. Use LibertyContent or LibertyBase when you know what you are doing.
!!LibertyAttachable
Classes derived from LibertyAttachable come with this functionality:
*They can take title and formatted text
*They maintain creation date, creator and modification date/modificator information
*their text content is subject to the full text seach
*The calendar can display events occurring to LibertyAttachable objects.
*Upon database access (store, load) other service plugins are triggered
If all you need is a new data type that contains some formatted text, you might be pretty quick in implementation:
{code}
<?php
require_once( LIBERTY_PKG_PATH.'LibertyAttachable.php' ); //import base class
define( 'BITRESOURCE_CONTENT_TYPE_GUID', 'bitresource' ); // This is used to uniquely identify the object type
class BitResource extends LibertyAttachable {
/**
* During initialisation, be sure to call our base constructors
**/
function BitResource( $pContentId=NULL ) {
LibertyAttachable::LibertyAttachable();
$this->mContentId = $pContentId;
$this->mContentTypeGuid = BITRESOURCE_CONTENT_TYPE_GUID;
$parms = array(
'content_type_guid' => BITRESOURCE_CONTENT_TYPE_GUID,
'content_description' => 'Managed Resource',
'handler_class' => 'BitResource',
'handler_package' => 'mypackage',
'handler_file' => 'BitResource.php',
'maintainer_url' => 'mailto:guess@who.com'
);
$this->registerContentType( BITRESOURCE_CONTENT_TYPE_GUID, $parms ); // register class with Bitweaver
}
}
?>
{/code}
!!!Custom fields
Probably you will want to add some custom fields. This will be some more work, as Liberty won't know about them and we have to handle them ourselves.
First think of a place to store the data. We will have to use our own table in the database. To match the liberty data with our own we should use an identifier. [content_id] is the one provided by liberty, and it will serve us well now. So create a table with two columns, just as shown. Later you will see how Bitweaver automatically creates the table upon package installation.
{code}
create table mydata (
content_id integer(4),
expires timestamp
)
{/code}
*getServicesSQL
*prepGetList
*postGetList
!!!History functionality
How can you enable history tracking in Liberty?
!!LibertyContent
!!LibertyBase
!Sorted Lists
Up to now, the answer is to look at the ((SamplePackage)) and guess.
*$gBitSystem->display(...)
!Detail Views
Up to now, the answer is to look at the ((SamplePackage)) and guess.
!Feedback and Confirmation
Up to now, the answer is to look at the ((SamplePackage)) and guess.
*gBitSystem->setBrowserTitle()
*gBitSystem->confirmDialog()
!Authorisation Required
Up to now, the answer is to look at the ((SamplePackage)) and guess.
!!Menus and Modules
Up to now, the answer is to look at the ((SamplePackage)) and guess.
Layout assigned module titles and parameters
!Services
The previous section showed how you can add a nice HTML GUI to your code. Now see what can be done behind the scenes.
!Installation and Migration
!!The Database Schema
Your package contributes to Bitweaver. That also is during database creation. To setup the correct tables, privileges and the such make use of the _admin/schema_inc.php_ script. It is called by the Bitweaver package installer during database creation time. The version shown here creates the table for our custom field in the BitResource class, registers the package and installs some privileges.
{code}
<?php
$tables = array(
'resources' => "
content_id I4 NOTNULL PRIMARY,
expires T
",
);
global $gBitInstaller;
foreach( array_keys( $tables ) AS $tableName ) {
$gBitInstaller->registerSchemaTable( MYPACKAGE_PKG_NAME, $tableName, $tables[$tableName] );
}
$gBitInstaller->registerPackageInfo( MYPACKAGE_PKG_NAME, array(
'description' => "What my package is made for",
'license' => '<a href="http://www.gnu.org/licenses/licenses.html#LGPL">LGPL</a>',
'version' => '0.1',
'state' => 'developing',
'dependencies' => 'users',
) );
// ### Default UserPermissions
$gBitInstaller->registerUserPermissions( MYPACKAGE_PKG_NAME, array(
array('p_event_create', 'Can create a resource', 'registered', MYPACKAGE_PKG_NAME),
array('p_event_admin', 'Can admin resources', 'editors', MYPACKAGE_PKG_NAME),
array('p_event_read', 'Can read resources', 'registered', MYPACKAGE_PKG_NAME),
) );
?>{/code}
*More about $gBitInstaller
!!Data Pump
If you want to populate the database with sample data during the installation process, you have to make use of the data pump.
For the easy to use BitResource type, simply create a file named _pump_mypackage_inc.php_ in the bitweaver/install directory with the following content. All it does is fill an array with the data to populate, then loop through that array and feed everything into BitResource::store(). Error/success messages are stored in variables.
This file will be called from the Bitweaver installer after the user agreed to populate the database, and afterwards the installer will display the error or success messages.
{code}
<?php
require_once( MYPACKAGE_PKG_PATH.'BitResource.php' );
$resourcesHash = array (
array(
'title' => 'Coffee',
'edit' => 'just the classic instant coffe',
),
);
foreach( $resourcesHash as $resource ) {
$newResource = new BitResource();
if( $newResource->store( $resource ) ) {
$pumpedData['EventCal'][] = $resource['title'];
} else {
$error = $newResource->mErrors;
error_log('Error creating mypackage resources: '.$error, 0);
xdebug_debug_zval('error');
$gBitSmarty->assign( 'error',$error );
}
}
?>
{/code}
If you have custom fields that need population, simply add them to the array above and you are done.
!!Data Format
!!!National language characters
What encoding should be used for the PHP file? How shall national language characters (at worst the complete unicode character set) be escaped?
!!!Timestamps
Bitweaver is said to use UTC times within the database. What times are used on timestamps in the installer?
(MySQL does not support timestamps with timezone information. However the timezone used must be set in the database connection. How is that handled?