History of CreatingServices
a brief outline of what a service is and what it does, can be found on LibertyServices
{maketoc}
! Turning a package into a service
!! register the package as service
to turn any package into a service, you need to modify your <pkg>/bit_setup_inc.php file and declare your package into a service. this can be done by modifying the way the package is registered:
{code}
$gBitSystem->registerPackage( 'pigeonholes', dirname( __FILE__).'/', TRUE, LIBERTY_SERVICE_CATEGORIZATION );
{/code}
explaining the parameters of registerPackage:
# name of the package
# package path
# specify if the package can be activated
# specify what type of service the package belongs to
the service type needs to be defined as a constant in liberty/LibertySystem.php - this is also the place where you can check what types of services we already have and if your's fits into one of the existing ones, please use one of those.
!! register the service
this is the cruicial bit. we register the service and when to display what and where.
{code source=PHP}
if( $gBitSystem->isPackageActive( 'pigeonholes' ) ) {
$gLibertySystem->registerService( LIBERTY_SERVICE_CATEGORIZATION, PIGEONHOLES_PKG_NAME, array(
'content_display_function' => 'pigeonholes_content_display',
'content_preview_function' => 'pigeonholes_content_preview',
'content_edit_function' => 'pigeonholes_content_input',
'content_store_function' => 'pigeonholes_content_store',
'content_expunge_function' => 'pigeonholes_content_expunge',
'content_edit_tab_tpl' => 'bitpackage:pigeonholes/pigeonholes_input_inc.tpl',
'content_view_tpl' => 'bitpackage:pigeonholes/display_members.tpl',
'content_nav_tpl' => 'bitpackage:pigeonholes/display_paths.tpl',
) );
{/code}
you can see that the pigeonholes package first checks to see if it's active, if so, it adds the service specifications.
!! Service Options
!!! Sql Extensions
__content_list_sql_function__
allows the extension of existing SQL while getList() is called. table aliases are kept constant throughout so you can easily join pertinent data to the existing SQL when getList() is called from any package.
{code source=PHP}
function protector_content_list() {
global $gBitUser;
$groups = array_keys($gBitUser->mGroups);
$ret = array(
'join_sql' => " LEFT JOIN `".BIT_DB_PREFIX."liberty_content_group_map` lcgm ON ( lc.`content_id`=lcgm.`content_id` ) LEFT OUTER JOIN `".BIT_DB_PREFIX."users_groups_map` ugm ON ( ugm.`group_id`=lcgm.`group_id` ) ",
'where_sql' => " AND (lcgm.`content_id` IS NULL OR lcgm.`group_id` IN(". implode(',', array_fill(0, count($groups), '?')) ." ) OR ugm.`user_id`=?) ",
'bind_vars' => array( $gBitUser->mUserId ),
);
$ret['bind_vars'] = array_merge( $groups, $ret['bind_vars'] );
return $ret;
}
{/code}
You can also insert some select_sql as well, to limit the selection critieria.
__content_load_sql_function__
This is basically the same as content_list_sql_function but it's called during the load() process. the output should be virtually the same.
!!! Functions
__content_display_function__
This function is called during the displaying of the content, i.e. while the page is being loaded. this means, you can add more sophisticated queries and checks in here, if there is no possibility to do this with the SQL functions above.
__content_preview_function__
This function is called when a page is being editied and a user hits preview. it's mostly there for you to make any selections the user has made persistent during the preview phase.
__content_edit_function__
When a user wants to edit content, this function is called. it allows you to generate data for any templates you need to fill in the edit page (more below).
__content_store_function__
Here you can store the content data in your serice tables.
__content_expunge_function__
Make sure the data from your tables is removed when a user removes the content it belongs to.
!!! Templates
__content_edit_tab_tpl__
This template is displayed as a seperate tab when a user is editing content. this is useful for services that might contain several lines of code and want to have their own section when a user edits a page. This template is only available when the user is editing data.
__content_edit_mini_tpl__
This template is displayed during the edit process and is particularly useful when you have a single dropdown to display, since it's displayed below the textarea a user uses to edit the content. This template is only available when the user is editing data.
__content_view_tpl__
This template is appended to the bottom of the page, like a list of pages in the same category. This is only visible when the full content is loaded i.e.: when an article is being read but not just viewed on the front page.
__content_nav_tpl__
You can use this to insert a narrow template at the top of a page. this can be useful to display the path to an object or the status of a page. This is only visible when the full content is loaded i.e.: when an article is being read but not just viewed on the front page.
__content_icon_tpl__
insert an icon in the list of existing icons in the top right on a page. This will enable you to get your users to link to a template in your own package and deal with certain needs that way.
__content_body_tpl__
insert a small template into the top of the <div class="body"> part of the content. this template will be visible in listings such as the articles front page as well.
{maketoc}
! Turning a package into a service
!! register the package as service
to turn any package into a service, you need to modify your <pkg>/bit_setup_inc.php file and declare your package into a service. this can be done by modifying the way the package is registered:
{code}
$gBitSystem->registerPackage( 'pigeonholes', dirname( __FILE__).'/', TRUE, LIBERTY_SERVICE_CATEGORIZATION );
{/code}
explaining the parameters of registerPackage:
# name of the package
# package path
# specify if the package can be activated
# specify what type of service the package belongs to
the service type needs to be defined as a constant in liberty/LibertySystem.php - this is also the place where you can check what types of services we already have and if your's fits into one of the existing ones, please use one of those.
!! register the service
this is the cruicial bit. we register the service and when to display what and where.
{code source=PHP}
if( $gBitSystem->isPackageActive( 'pigeonholes' ) ) {
$gLibertySystem->registerService( LIBERTY_SERVICE_CATEGORIZATION, PIGEONHOLES_PKG_NAME, array(
'content_display_function' => 'pigeonholes_content_display',
'content_preview_function' => 'pigeonholes_content_preview',
'content_edit_function' => 'pigeonholes_content_input',
'content_store_function' => 'pigeonholes_content_store',
'content_expunge_function' => 'pigeonholes_content_expunge',
'content_edit_tab_tpl' => 'bitpackage:pigeonholes/pigeonholes_input_inc.tpl',
'content_view_tpl' => 'bitpackage:pigeonholes/display_members.tpl',
'content_nav_tpl' => 'bitpackage:pigeonholes/display_paths.tpl',
) );
{/code}
you can see that the pigeonholes package first checks to see if it's active, if so, it adds the service specifications.
!! Service Options
!!! Sql Extensions
__content_list_sql_function__
allows the extension of existing SQL while getList() is called. table aliases are kept constant throughout so you can easily join pertinent data to the existing SQL when getList() is called from any package.
{code source=PHP}
function protector_content_list() {
global $gBitUser;
$groups = array_keys($gBitUser->mGroups);
$ret = array(
'join_sql' => " LEFT JOIN `".BIT_DB_PREFIX."liberty_content_group_map` lcgm ON ( lc.`content_id`=lcgm.`content_id` ) LEFT OUTER JOIN `".BIT_DB_PREFIX."users_groups_map` ugm ON ( ugm.`group_id`=lcgm.`group_id` ) ",
'where_sql' => " AND (lcgm.`content_id` IS NULL OR lcgm.`group_id` IN(". implode(',', array_fill(0, count($groups), '?')) ." ) OR ugm.`user_id`=?) ",
'bind_vars' => array( $gBitUser->mUserId ),
);
$ret['bind_vars'] = array_merge( $groups, $ret['bind_vars'] );
return $ret;
}
{/code}
You can also insert some select_sql as well, to limit the selection critieria.
__content_load_sql_function__
This is basically the same as content_list_sql_function but it's called during the load() process. the output should be virtually the same.
!!! Functions
__content_display_function__
This function is called during the displaying of the content, i.e. while the page is being loaded. this means, you can add more sophisticated queries and checks in here, if there is no possibility to do this with the SQL functions above.
__content_preview_function__
This function is called when a page is being editied and a user hits preview. it's mostly there for you to make any selections the user has made persistent during the preview phase.
__content_edit_function__
When a user wants to edit content, this function is called. it allows you to generate data for any templates you need to fill in the edit page (more below).
__content_store_function__
Here you can store the content data in your serice tables.
__content_expunge_function__
Make sure the data from your tables is removed when a user removes the content it belongs to.
!!! Templates
__content_edit_tab_tpl__
This template is displayed as a seperate tab when a user is editing content. this is useful for services that might contain several lines of code and want to have their own section when a user edits a page. This template is only available when the user is editing data.
__content_edit_mini_tpl__
This template is displayed during the edit process and is particularly useful when you have a single dropdown to display, since it's displayed below the textarea a user uses to edit the content. This template is only available when the user is editing data.
__content_view_tpl__
This template is appended to the bottom of the page, like a list of pages in the same category. This is only visible when the full content is loaded i.e.: when an article is being read but not just viewed on the front page.
__content_nav_tpl__
You can use this to insert a narrow template at the top of a page. this can be useful to display the path to an object or the status of a page. This is only visible when the full content is loaded i.e.: when an article is being read but not just viewed on the front page.
__content_icon_tpl__
insert an icon in the list of existing icons in the top right on a page. This will enable you to get your users to link to a template in your own package and deal with certain needs that way.
__content_body_tpl__
insert a small template into the top of the <div class="body"> part of the content. this template will be visible in listings such as the articles front page as well.