History of CreatingServices
Version 2 | Current version | |
---|---|---|
a brief outline of what a service is and what it does, can be found on LibertyServices Turning a package into a serviceregister the package as serviceto 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:
explaining the parameters of registerPackage:
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 servicethis is the cruicial bit. we register the service and when to display what and where.
you can see that the pigeonholes package first checks to see if it's active, if so, it adds the service specifications. Service OptionsSql Extensionscontent_list_sql_functionallows 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.
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. Functionscontent_display_functionThis 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. Templatescontent_edit_tab_tplThis 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 part of the content. this template will be visible in listings such as the articles front page as well. </pkg> | This page contains two tutorials on how to create Liberty Services. The first explains how to create a Service from scratch, while the second explains how to add Services to an existing bitweaver Package. If you are not familiar with what Services are or what they are good for, please first read: LibertyServices. If you are not familiar with bitweaver Packages, you might want to read up on what those are also, though this tutorial also gives some basic instruction about creating a Package for the first time. Creating A Liberty Service PackageOverviewCreating a service is very similar to creating a regular bitweaverPackage. This tutorial will take you though setting up the minimal files you need to create a simple service and register it with the Liberty CMS Engine.This tutorial mostly uses the GeoPackage for its examples. The Geo Package is very simple but clearly shows the elegance and power of Liberty Services. Via Liberty Services the Geo Package makes it easy to attach location data to any type of content in bitweaver without having to modify any of the packages! So, wiki pages, blog posts, articles, users, and any new content types that might come along, like events for example, can have latitude and longitude coordiates associated with it. Via Liberty Services any Package then can automagically store this geo-spacial data, look it up, or remove it. Files You NeedLike setting up any bitweaver package, the first thing you need is a directory in you bitweaver folder which is the name of your package. The convention is to give this directory a lowercase name:Inside your package directory you will need a few more directories and a couple of files. The directories you will need are admin and templates. In your package directory also add the file bit_setup_inc.php and your package class file following this naming convention: LibertyYourpackage.php. All bitweaver packages use a class to register themselves with the CMS Engine, the package class file is then, obviously where this code will go. If your package is only a service the bitweaver convention is to prefix your class file will 'Liberty'; if your package is a regular package creating a new content type like wiki or aritcles, then the convention is to prefix the file with 'Bit', e.g. BitYourpackage.php. The Geo Package is a service only package, so it's class file name is LibertyGeo.php. There are a few more files to create that you will need. In admin create schema_inc.php. In templates you will create any templates you wish to provide as a service. Lets not create any for now. This tutorial will explain how service templates are used by Liberty a little later on, and we will create one then. Creating Your Service Database TableIf you are creating a service, there probably will be some sort of data you want to store. Setting up your data table is the same for services as it is for packages. Since there is not that much specific about this for services, we will go over creating a data table quickly first to get it over with and then get into creating the service.In all bitweaver Packages we define our data tables in the schema_inc.php inside the package admin folder. This is what the Geo Package schema_inc.php file looks like:
In the $tables array we define each data table we want. Because Geo Package adds location data to all Liberty Content the table also includes a content_id value; this value is constrained to the same in the liberty_ccontent table. The rest of this file tells the installer to use this array to generate tables in our database and it also tells the installer some information about the package. The description and license information at the end is what is displayed in the installer and admin panel package listings so that others know what your package is all about. Now that we have a place to store our data, we can get on to the good stuff... Registering With Liberty ServicesGet a Liberty Service GUIDTo register our service we first need to define a Liberty Service GUID in Liberty for our particular service. You can check the master list of taken Liberty Service GUID's on the LibertyServices page, or look in the file LibertySystem.php in the liberty package directory. You can either create a new GUID or associate your package with an existing one. But be aware that existing Service GUID are used by other packages, and only ONE package can register with a service. You should only use an existing GUID if you are creating an alternate service to an existing one.For Geo Package a new GUID was added to LibertySystem.php:
Now that we have a GUID to register to, we can finally write some code in the package. Register Your Service FunctionsIn bit_setup_inc.php we will register our service to our Liberty Service GUID. We also need to add a few other things to this file. Lets look at bit_setup_inc.php from the Geo Package and walk through the parts we need to include:
Every package has a bit_setup_inc.php file, and it is used by bitweaver to get key information about installed packages every time a page on a bitweaver site is requested. So in the first part of the file we tell bitweaver what package this is and since we are creating a service we also tell it what Liberty Service GUID it is associated with:
Then we declare which functions in our package to associate with which Liberty Service methods we want to connect to:
There are several service options available to use. There are methods for loading data, for storing data, for deleting data, for displaying templates on different page types, etc. A list of available services you can connect to is also on the LibertyServices page. Here the geo package hooks into four of these Liberty Services:
The associated functions, such as geo_content_list_sql, we will define in our package class file. We will do that in just a minute. Geo Package does not register any templates with Liberty. But it could. Here are some template registration possibilities taken from the StarsPackage, which is used for rating content, and how those work:
The associated templates would be saved in the templates directory we created earlier. Creating Your Service ClassCreate The Class In Our Class FileAll package classes are built on the bitweaver kernel class. To do so we include a base class file. There are a few to choose from. For more complex packages it is good to use LibertyAttachable.php as a foundation, for a simple service like Geo Package all we need is BitBase.php. For which ever base file we want to use, we include it using the appropriate package path constant. In this case BitBase comes from the Kernel Package:
Now that we have a foundation we can declare our package class. The class file and class name are the same. So in Geo Package the class name is LibertyGeo. Here is how we set it up:
Add Class MethodsThere are several standard methods, found in almost all packages, you will probably want to add to your class. These methods are:
These do fundamental stuff like get data, store changes, or delete data. The details of how they work are beyond the scope of this tutorial. These are not our service functions, but some of our service functions are dependant on them, so here is what they look like in the Geo Package for easy reference and easy copying:
Add Service FunctionsOur service functions do not go in our class, they stand alone. For each function we registered with Liberty Services, we define it here.Recall that in our Geo example we registered four functions:
The first two, the sql functions, actually inject sql into the load() methods of other tables. We explicitly specify each data column we want returned and typically use a LEFT JOIN to attach the service sql. load_sql and list_sql are in many cases identical or nearly identical. Here is what they look like iin the Geo Package:
Our store and expunge (fancy word for delete) are slighly different, they actually receive a hash from the package using the service, and invoke the service class methods. This is very clear in the expunge example here. The store example is a little less clear, we check to see if it doesn't execute properly, and if there are errors we capture them. Look for this line in the geo_content_store function:
Thats the Geo class method store() being called. Here are the complete Geo store and expunge service functions:
And we are done! With these four functions in place, you can install your package and Liberty Services will automagically call these functions at the appropriate times. This is all you have to do to create a Liberty Service. It is quite easy! Remember, we didn't register or create any templates in this example, but if you want to you can. Just remember to add template files you register to your template directory. You will use smarty just the same as you would for any other template. For examples see the templates in the StarsPackage or PigeonholesPackage. Adding Liberty Services to an Existing PackageRegister The Package As Serviceto 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:
explaining the parameters of registerPackage:
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 ServicesThis is the cruicial bit. we register the service and when to display what and where.
You can see that the pigeonholes package first checks to see if it's active, if so, it adds the service specifications. Create Your Service Functions and tplsFor each function and tpl you register in bit_setup_inc.php you need create. Templates you will create and save in your template folder. Your service functions get defined in your class file, in Pigeonholes this is the Pigeonholes.php. But note that these functions are not IN the class, they reside outside. There are a variety of functions you can register, some add sql and some call on your package methods. Here is one example which extends all content getList methods:
Once you have defined all your functions you are done. Liberty Services automagically does the rest. </pkg> |