SamplePackageDissection

A Breakdown of the SamplePackage

Created by: Sean Lee, Last modification: 25 Nov 2008 (08:16 UTC) by xing

Bitweaver uncovered


First have a look at the big picture: Bitweaver uses a Model View Controller pattern to ease creation and maintenance of the software. The files in the sample package are the pieces glued together by the Bitweaver framework, so it is essential to understand which part is which. See also Model View Controller - MVC.

While editing Sample entries, the browser directs its requests to edit.php. Here the request data (user input) is processed and stored in the model, an instance of the BitSample class. Depending on the action requested by the user (store, load, ...) the model can be stored to the database before finally the template edit_sample.tpl is invoked which generates the HTML output. You may want to also read bitweaverPackage.

Speaking more generally, we can see these types of files:
  • sample/Bit*.php (Model)
    These files contain classes as container for data. As subclasses of LibertyContent they can easily be stored and loaded in the database. These classes contain your data and the code to validate, store and load themselves.

  • sample/templates/*.tpl (View)
    These Smarty templates render the model to HTML. Together with the CSS (located in the theme used) these files define what your application will look like.

  • sample/*.php (Controller)
    The remaining files usually are called by the browser and process the HTTP request. Data entered by the user can be stored in the model before the Smarty template engine is called to render the new page. These files contain the proramming logic.

A Breakdown of the files included in the SamplePackage


This is an attempt to list and explain all of the files in the SamplePackage put together by spiderr. Any corrections you make or additions you have to this document are warmly appreciated. After all, that is what a wiki is for, right?

These files are being tackled in an order that seems a bit odd - Start where bitweaver starts - I.E. the install. After that - index.php and bit_setup_inc.php. Then a list of everything in a directory one at a time.

sample/admin/schema_inc.php

sample/admin/schema_inc.php is the file responsible for integrating SamplePackage into the InstallPackage and thus into bitweaver. When you go to the kernal/admin/index.php page and click on Packages this file gets automatically loaded in order to display the information about your package as provided in the call to registerPackageInfo. When you click on "Activate bitweaver packages" the various things you registered are actually stored into the database for use by your package.

At the top of the file is the array of tables that the package will use to do its job. The format for the schema is not straight SQL but rather is ADOdb style DataDict style code as documented in the
ADOdb Data Dictionary Documentation Note that the last column in the table can not be followed by a ',' or the installer will choke when trying to create the table.

The next bit of code tells bitweaver that this package can be used as
a homepage:

<?php
// Release One style (this is outdated and will not work in Release 2
$gBitInstaller->makePackageHomeableSAMPLE_PKG_NAME );

// Release Two style
$registerHash = array(
    
'package_name' => 'sample',
    
'package_path' => dirname__FILE__ ).'/',
    
'homeable' => TRUE,
);
$gBitSystem->registerPackage$registerHash );
?>

This should only be called if it is appropriate for your package, i.e. it is content and not some kind of plugin package.

The rest of the code registers the tables, indexes, sequences, package information, preferences and permissions for the package. This is all relatively straight forward and should be self explanatory.

sample/templates/menu_sample_admin.tpl

This is the template which is used to create the entry in the Administration menu for the package. Bitweaver finds this template using a standard naming scheme and the package name.

sample/admin/admin_sample_inc.php

This file is the interface for administrating the package itself. It is used when you go to kernel/admin/index.php and click on Sample Settings. This page places the data into the smarty context for the "list settings tab" in the admin interface. This works in conjunction with the next file we will talk about sample/templates/admin_sample.tpl which is used to create the html used to display the settings loaded into the smarty context in this file. It also loads all the samples you have created and places them in context as well so that the home selection portion of the template can select from the available samples.

sample/templates/admin_sample.tpl

This is the template which renders the settings loaded by sample/admin/admin_sample_inc.php. It is pretty simple over all just creating two different tabs, one for setting the home tab and one for selecting the packages preferences.

sample/index.php

This is the main php script that is run if you go to the sample package directory as most webservers are configured to run index.php when the bare directory is given. It starts with including the bit_setup_inc.php that sets up all the bitweaver magic.

It then verifies that the package is installed and activated properly. This is the bit of code that will generate an error page indicating that the package is disabled if you haven't run through the installer to install the package yet. The next check ensures that the user has permissions to read pages of this type in the permissions system. This will generate a not-allowed error page if the user is lacking that permission.

The next chunk of code checks to see if the id of a particular sample has been given and if it hasn't loads the 'home_directory' configuration. This is the default which is set in the admin screen discussed above. Finally the lookup_sample_inc.php file is run to load the content in question. The addHit() function is called to increment the hit counter for this content. Finally the page is rendered by making a call to display and passing in the template sample_display.tpl which is stored in sample/templates. The tra call attempts to translate the package name if it is possible.

sample/lookup_sample_inc.php

This bit of code is responsible for loading a particular instance of sample from the database and placing it in $gContent.

The top require includes the class that will hold the particular content for this package and the second one includes some magic from liberty to load the content by structure_id or content_id if that is how the object to load is being requested. This is why the next bit checks to see if $gContent is already loaded.

If a valid object isn't loaded by the inclusion of the liberty magic then the code attempts to load the content by the unique ID associated with the content, i.e. the sample_id provided in one of two places in the request.

It seems that the load by content_id is redundant since it would have been loaded by liberty if it matches but there may be some case where the liberty load fails but it works in this file though the author (Nick Palmer) has a hard time seeing how this could be the case. At worst it is never called and it is only a couple of lines of code so it is still there.

sample/templates/sample_display.tpl

This template renders an instance of the content stored in $gContent.

The first line in the file includes any templates that are registered with Liberty as navigational services. Likewise the last line includes templates for any services which are registered as view related services.

The middle portion of the file simply displays the content including edit and remove icons and information on the modifier of the content. It should be pretty self explanatory but does demonstrate the use of permissions, icons and various bits of information stored in $gContent->mInfo.

sample/bit_setup_inc.php

This is the file included by bitweaver to load the package and hook it into the system. The first part of the file registers the package with bitweaver providing only the bare minimum of information about the package, i.e. it's name and the directory for the package.

The file next checks if this package has been activiated and if it is registers the application menu for inclusion. Note that this call specifies the template to be used for the menu.

sample/templates/menu_sample.tpl

This is the template which is used to display the menu. It is pretty straight forward.

sample/BitSample.php

This is the class which represents an instance of the data type. It extends LibertyAttachable in order to allow it to be integrated into the Liberty system properly. The constructor thus calls the LibertyAttachable constructor and then sets it's internal id fields and ensures that the data type has been registered with Liberty properly.

The load() method is responsible for loading the actual data from the database. It starts by trying to verify that the id's in the object set in the constructor are valid. If they are it begins setting up the bindVars array to have the sql required to join properly to get the instance.
It uses the LibertyAttachable provided getServicesSQL to load some of the variables and does some Joins to be able to pull out creator and modifier information in a single query. It then uses the results of this query to set various fields in the mInfo hash for the object.

The store() method is responsible for storing an instance of the object to the database. It uses a call to associateInsert to update the database making calls to StartTrans() and CompleteTrans() to make sure the update is done atomicly making sure the data is verified first using the verify() method.

The verify() method verifies the data in the request meets the requirements for the class and stores values to be stored away in the content_store hash in order to make it so Liberty can store the class properly.

The expunge() method removes an instance of the object again using transactions to ensure that everything is done properly.

The isValid() method checks that the sample_id in the object is valid.

The getList() method returns an array of structures suitable for a list.

The getDisplayURL() method gives a url suitable for linking to the object. There currently doesn't seem to be support here for pretty URLs through the usage of mod_rewrite but there probably should be.

sample/list_samples.php

This file presents a list of all of the content of the sample type. The top of the file includes the usual magic to include all the bitweaver code and the data type. It then does the package and permission verification steps taken in index.php described above.

The list page includes the ability to delete a large number of samples. So the next bit of this file is designed to handle that for of "edit". It does a confirmation first to make sure the user isn't making a mistake and then calls expunge for each of the items in order to delete them.

The next bit of code simply uses the BitSample class to load all of the samples from the database and places them in the context and then calls the display function on the list_samples.tpl template.

sample/list_samples.tpl

This template simply renders the samples from the context providing a form to do the mass delete described above if that is active. It is pretty simple over all but contains some functionality easily overlooked.
E.g. sorting the result set is accomplished using function_smartlink in the table header.

sample/edit.php

This is the file responsible for displaying an edit page for editing a sample. It first looks up a sample if there is one, fills out various parts of the mInfo structure of this object based on variables in the request and then saves out the object if requested to do so. If the save works it redirects to the display of this new entry.

The one unusual area in this file is the inclusion of the quicktags include file to load up the quicktags stuff and the setting of the textarea_id in the context. This variable is used by the WYSWIG and QuickTags stuff to know what text area to target when they are doing their thing.

Finally it displays the templte edit_sample.tpl to render the page.

sample/templates/edit_sample.tpl

This is the template which renders the edit page for a sample. The interesting bits of this file are the inclusion of the liberty templates as well as the smileys and quicktags templates. The inclusion of the liberty edit templates provides hooks for any liberty edit oriented services and the quicktags and smileys provide the ability to have those functions hooked to the text area through the name of the text area.

sample/remove_sample.php

This file is responsible for handling the removal of a single sample as might be done from the edit page. There isn't really a lot in here that shouldn't make sense by this point from the understanding of all the other files. The one interesting bit is the use of the confirmDialog to show a handy confirmation dialog with a form on it for continuing. Doesn't bitweaver rock for making such things easy?

sample/mkpackage.sh

This script can be used to rename the sample package in order to make it easier to use it as a base for new packages. See SamplePackage for more information on using this to repackage the sample package as your own.

Other optional files

Package specific Styles and Javascript

If you need some CSS to make your package 'work', you can put these into your own css in your own package. You can put this anywhere you like, such as

<?php
sample
/styles/sample.css
?>
and then call that file from your sample/bit_setup_inc.php file using:

<?php
$gBitThemes
->loadCssSAMPLE_PKG_PATH.'styles/sample.css' );
?>

The same applies to javascript files you wish to add that are not present in util/javascript/

Example bit_setup_inc.php file with additional CSS and Javascript loading


<?php
global $gBitSystem;

$registerHash = array(
    
'package_name' => 'sample',
    
'package_path' => dirname__FILE__ ).'/',
    
'homeable' => TRUE,
);
$gBitSystem->registerPackage$registerHash );

if( 
$gBitSystem->isPackageActive'sample' ) ) {
    
$menuHash = array(
        
'package_name'  => SAMPLE_PKG_NAME,
        
'index_url'     => SAMPLE_PKG_URL.'index.php',
        
'menu_template' => 'bitpackage:sample/menu_sample.tpl',
    );
    
$gBitSystem->registerAppMenu$menuHash );

    
// Load CSS file
    
$gBitThemes->loadCssSAMPLE_PKG_PATH.'styles/sample.css' );
    
// Load Javascript file
    
$gBitThemes->loadJavascriptSAMPLE_PKG_PATH.'scripts/sample.js' );
}
?>


Using this method is the least invasive and the most flexible since it allows other developers to

<?php
$gBitThemes
->unloadCssSAMPLE_PKG_PATH.'styles/sample.css' );
?>
if they do not want to load the CSS file.

Header and Footer templates

bitweaver allows you to insert code into the <head> section without touching any files in the core. You can achieve this by adding a file called:

<?php
sample
/templates/header_inc.tpl
?>
This file will be picked up and inserted automagically. You can test this with a simple script:

Example header_inc.tpl


<?php
{if $gBitSystem->isPackageActive'sample' )}
    <
script type="text/javascript">/* <![CDATA[ */
        
alert"It's a small world, but I wouldn't want to have to paint it." );
    
/* ]]> */</script>
{/if}
?>


The same is true for

<?php
sample
/templates/footer_inc.tpl
?>