webAppKit blog

Release 0.12 : interfaces, config editing

J.Ducastel — Wed, 12 Mar 2008 20:19:00 +0100

As you may have noticed, i dropped the big roadmap on the wiki. Instead, i try to relase a new version each time a feature is added / a big change occur. So what does bring the 0.12 release ?

Changes to the core: In order to ensure code quality, i started to define interfaces. iWakKit, iWakTool and iWakStorage are available.; Splitted Webappkit class into Webappkit (API, static methods only) and WakKit, kit instances.; some reorganisation into core library files; changes to WakStorage implementation, and new unit tests.
librairies: worked on webappkit.db (link, querytpl, mapper) which are database-related tools; started work on webappkit.fs (filesystem libraries) : filesystem libraries
admin interface: You can now edit tools and kits configuration from the web admin interface.

Release 0.11

J.Ducastel — Fri, 22 Feb 2008 14:38:00 +0100

Get it there. Changelog and screenshots below.

(PHP5) Lazy loading for library classes and Tools instances. Loaded weight counter (available as DjTpl tag)
Updated tutorials, including a unit tests page.
Admin interface improvements, including bread crumb while browsing kits, and icons.
Dysfunctional kits diagnostics on their page.

Kits list
Kit details and tests summary
Kit unit tests detailed report: *
Exception catched

Release 0.10.1

J.Ducastel — Fri, 08 Feb 2008 13:31:00 +0100

You can download it there. Here is the changelist :

Exceptions: The PHP5 version now brings its own set of exceptions, so it's easier to know what's wrong with a kit.
Admin web interface: HTTP authentication : you will have to create a config file in order to allow access to the web admin, but a sample is provided when it doesn't exist.; Kit diagnostics on non-functional kits page.; Better SimpleTest integration. A dedicated Tool can be added to your Kits. When done, tests run smoothly from the web admin.; Aesthetic improvements. Have a look at the screen shots below.

Kits List
Single Kit admin page
Kit unit tests running
Tutorials

0.10 Released

J.Ducastel — Tue, 29 Jan 2008 18:14:00 +0100

This is a solid intermediate release. Here is the file. It features :

A bilingual (english/french) admin interface including some tutorials, which will be featured on the home site too. The admin only lists available kits yet, but is protected by HTTP authentication.
Dot syntax has been implemented and is the new standard for kits id, although that slash is still supported.
The embedded framework is maturing. It's used for the admin interface and public web site.
PHP5 is now the reference development. Most changes are backported to PHP4 however.

The new web site is bilingual too and features the admin tutorials. Its update will be available within the next hours, as it's moving to a new host.

Update 2008-01-30 : Ouch, the new host offer si still beta... and does not provide url rewriting yet. Therefore, only the home page is available for the new web site. I hope it will be fixed soon, if not i will temporary get back to the old host.

0.9.1 released

J.Ducastel — Fri, 21 Dec 2007 12:48:00 +0100

Pretty everything is in the title. Here is the file. There is no big change in this release, most changes concern included libraries. To summary, i added unit tests, fixed some bugs, improved template engine, worked on a micro-framework for the admin interface. Here is the changelog :

added kit simpletest, with a temporary MySQL database tool
unit tests for kit webappkit
unit tests for kit datapath
unit tests for kits databeans/databean, databeans/datetime
PHP5 version for Databean
units tests for pathnode/common
pathnodes/common: filenode->move(), filenode->slugifyPath(), filenode->chmod()
renamed kit django/templates to dj/tpl
dj/tpl: added tag ifincollection
dj/tpl: added tags extends, block : template inheritance (uses storage mechanism)
webappkit: modifed WakTool constructor, replaced $name arg by optional $cfg arg, which is now loaded by owner kit.
some work on webappit/engine

For next release, i may change the syntax to access subkits from kit/subkit to kit.subkit. Not sure yet. What do you think ?

0.9 released

J.Ducastel — Wed, 31 Oct 2007 10:34:00 +0100

Everything is in the title. The home page tutorials have been updated. The root index.php will launch the helloworld kit, which is self-explanatory, and for the first time provides both english and french pages. Bonjour le monde !

From the roadmap :

Kits format stabilized.
allowing webappkit class inheritance for kits.
generic Tools (kits components) accessing as kits members using a factory pattern.
migrating existing library kits to new format.
Services and Storages redefined as Tools. (Services disappear, Tools are the new Services).
PHP versions compatibility range for kits.

Get it there.

Zero Dot Nine

J.Ducastel — Tue, 30 Oct 2007 14:10:00 +0100

If you take a look at the roadmap, you'll see some changes. A development branch has been started, numbered 0.9 (odd minor versions numbers will now be for development versions - even for stable ones). The 0.8 still live in the trunk for now. Milestones are set up to 0.14.

So what's new ?

Services have disapperead and are replaced by Tools, which are accessed as Kits members.
Storages are now Tools themselves, provided by webappkit/storages.
Kits API have changed a bit. Most methods are static ones. Kits metadata and libraries are now loaded before Kit instance building, to allow some kits to override the generic webappkit class.
PHP version range compatibility can be defined in Kits metadata.

The help file in the repository have been updated with new tutorials. I hope to release 0.10 rather quickly, has goals previously set for 0.9 have been sparsed over three milestones.

Here is the content of the updated help file :

Using a Kit

Unzip webappkit at the root of your web application. It's probably done as the file you're reading is part of it. It creates a webappkit/ folder. Before retrieving any Kit, put this line into your code :

/**
* getting webappkit core (only once call is necessary)
*/
include('webappkit/include-me.php');

When you need a Kit's resources, let's say ooxmlrpc, load it with :

/**
* loads a kit resources
*/
webappkit::getKit('ooxmlrpc');

If you need only a subkit, let's say http within databeans, get it with :

/**
* loads a subkit's resources
*/
webappkit::getKit('databeans/http');

In this exemple, databeans/http requires databeans/databean, but you don't have to take care about that.

webappkit::getkit($id) returns the kit instance. Always use this method to retrieve a kit, as Kits should be singletons.

Tools

Tools are named object instances taking their configuration data from the kit they belong to.

They are retrieved as kit members like this :

/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * calling the method "bar" of the kit's tool named "foo"
 */
$kit->foo->bar();

Storages

Storages are specific Tools. They build and retrieve object instances stored within kits files.

You use them just as any other Tool, as a kit's member. For example, let's get a template from our sample kit :

/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * getting the template from the storage, which is named "templates"
 */
$tpl=$kit->templates->getItem('help');
/**
* using the 
*/
echo $tpl->render();

Building a Kit

Let's build a Kit named mykit, which will contain a couple of class definition files.

Create a folder named mykit.wak within your webappkit/ folder.
Put your code files inside, let's say myclass.class.php and mychildclass.class.php which is extending it.

Create an INI file at its root named wak.ini and edit it :

[kit]
; kit-wide meta informations
version = "0.1"
; kit version. Will be used later.
desc = "This is my first kit. It will rocks !"
; a short description. Single line to be INI compliant !
phpversion = "4.3-5.*"
; define which PHP versions range compatibility (optional)
; you can use a single version string with jokers, as 4.*

[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "datapath"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php"
1 = "mychildclass.class.php"

This file describe Kit's resources and dependancies. Kits and files will be loaded in the order you defined.

Here we're done with the main kit.

Please note that Kits are singletons and won't be instanciated twice. Hopefully.

PHP version auto-switch

You can have a library file for each PHP versions, and tell the kit to load the appropriate one upon the current PHP version running.

To do this, we will name our files with the specific extensions : .php4 and .php5 , and then edit the kit's INI as this :

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php*"
1 = "mychildclass.class.php*"

Using * at the end of the file name will trigger the load of .php4 or .php5, upon the current running PHP version.

Building a subkit

Kits can contain subkits, which can be either optional or loaded by their parent kit.

It will also require another kit, webappkit/datapath, and provide an extension as an optional subkit named mysubkit.

Into mykit.wak/, create a folder named mysubkit.wak
Put its own code files into it, for example anotherclass.php4 and anotherclass.php5, which are PHP4 and PHP5 versions of the same class as seen before.

Create its wak.ini file at its root :

[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "mykit"
1 = "pathnodes"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "anotherclass.php*"

As you see, this subkit requires its parent kit and another kit, pathnodes. It also requires datapath, but this dependancy is already defined by parent kit.

A subkit may contain itself a subkit and so on.

Subkits auto-loading

If we want the parent kit mykit to load its subkit when loaded itself, we can add this into mykit's wak.ini file :

[load_subkits]
; subkits to load after self resources, order will be preserved
; n = "relative subkit id"
0 = "mysubkit"

The subkit will be loaded after paren'ts kit dependancies and own files.

Adding Tools

Tools have to be declared within kit's wak.ini file :

[load_files]
0 = "worker.class.php"

[tools]
; name = "class"
bob = "worker"

Here we have declared a tool wich will be named bob within the kit and will be an instance of the class worker.

Tools classes have to extends wakTool class. Their definition file can be included within the providing kit or one of its dependencies. Here it's an included one. Let's look at its class definition :

class worker extends wakTool {
        /**
        * a Factory function : every Tool has to declare it
        * @static
        * @param string $kit kit's id
        * @param string $name tool's name within kit
        * @return object worker's instance
        */
        function & factory($kit,$name) {
                return new worker($kit,$name);
        }
        
        /**
        * here is an useful function
        * @return string hairs color
        */
        function getHairs() {
                return $this->cfg['hairs'];
        }
        
        /**
        * @var array the default configuration values
        */
        var $cfg=array('hairs'=>'red');
}

Now, we can get tool bob from our kit and it will have its default config :

$kit=&webappkit::getkit('mykit');
/**
* this will print 'red'
*/
echo $kit->bob->getHairs();

Borrowing tools

But our worker class can now be used in another kit, by declaring it in the kit's wak.ini file :

[kit]
desc = "this is another kit, providing a worker tool borrowed from mykit"

[load_kits]
0 = "mykit"
; we need its "worker" class for alice service

[tools]
alice = "worker"

And let's override its config. Create a file named alice.tool.ini at the anotherkit's root :

; this is the alice tool config file for anotherkit
hairs = "blue"

Let's look at our second tool instance :

$kit2=webappkit::getkit('anotherkit');
/**
 * this will print "blue"
 */
echo $kit2->alice->getHairs();

And you can also have several instances of the same tool within the same kit, each with its own config.

Adding storages

Storages are just specific tools. Just like them, their definition file can be included within their providing kit, or they can just provide a config file for a tool class taken from an external kit dependancy.

They have to extend wakStorage class, which is provided by webappkit/storages kit.

Their function is to retrieve object instances stored in files within the kit.

Here we will get templates from our kit, using a storage class provided by djtpl template engine kit.

Here's our kit's wak.ini :

[load_kits]
; getting dependancies, including the storage class
0 = "djtpl"
; please note that djtpl kit itself require webappkit/storages

[tools]
; declaring storage, name = "class"
templates = "djtplstorage"

And now we override some storage config in templates.tool.ini :

; this is the templates storage config
search = "views/{{lang}}/{{id}}.{{type}}"
; here is the filename template for files search
[critera]
; the defaults values for search criteria
lang = "en"
type = "html"

This settings indicate that template files will be stored within a views/ folder within our kit, having languages subfolders, and that files are named by id.type. The default language is set to en, and default type to html.

Now, let's get a template from our kit. First, we will change the language default value to fr. Then, we want the template having the home id.

/**
 * changing a criteria's default value
 */
$kit->templates->setCriteria('lang','fr');
/**
 * getting a template
 * string criteria will be taken as 'id'
 * or you can provide an associative array for more criteria
 * missing criteria will be taken from current defaults
 * this will build a template instance from views/fr/home.html
 */
$tpl=$kit->templates->getItem('home');
/**
* rendering the template
*/
echo $tpl->render();

Changes for kits interface - requests for comments

J.Ducastel — Fri, 29 Jun 2007 17:20:00 +0200

I'm about to change the current kit interface (the webappkit class). The goal is to make it more agile and extensible. Please let me know how bad are this ideas.

First, i plan to allow inheritance / overriding of this class. Each kit may define its own kti class, and/or inherit from a specific kit class. To allow this, it will be required to read the metadata file before creating the kit instance (to resolve classe heritage). But heritage may go further than just class heritage, it may also concern kits components such as services and storages.

Second, i thought again about generic components, like services and storages. Rather than having specific kit methods to retrieve them, they would be public members of their kit instances. For example :

$foo=&$kit->getService('foo');
$foo->bar();
would become
$kit->services->foo->bar();

where $kit->services would be an instance of a ServiceFactory class. Each component type would have its factory / iterable class. Components would be loaded on kit->load(), not when creating kit instance.

In the same way, subkits instances would be available within their parent kit with $kit->subkits->subkit_name;.

On a side note, webappkit/appengine framework kit have been renamed to webappkit/evtengine. This is more meaningful, and it may not be the favorite framework for web admin. Rather, i plan to develop a framework based on the new webappkit paradigm rather than implement the old paradigm again. More about this later : one commit at a time ;)

0.8.1 (alpha 2) released !

J.Ducastel — Fri, 01 Jun 2007 17:44:00 +0200

You can download webappkit 0.8.1. Home page and code documentation have been updated.

Services and Storages are now available, see the homepage tutorials for more information.
webappkit/djtpl now includes a storage for templates.
webappkit/appengine is growing, although not used yet for webappkit admin.
admin page now dynamically lists available kits, and still include home page tutorials.

doc updated, 0.8.1 onwork

J.Ducastel — Tue, 29 May 2007 19:10:00 +0200

Almost everything is in the title.

Code documentation has been updated and is still available at code.webappkit.net.

Version 0.8.1 is onwork. Here's the news :

Kits resources loading is now separated from kit instance retrieval. Methods $webappkit->load() and webappkit::loadkit($id) have been added, which are not called by webappkit constructor.
webappkit::timecounter() and $webappkit->loadedWeight() have been added to help optimization.
Admin index (when calling url /webappkit from your app root) is not static anymore. It still includes micro tutorials, but provided kits list is now dynamically built from actual kits.
A new pathnodes subpackage is being worked on : webappkit/pathnodes/od which stands for Open Document.

0.8.0 Alpha released !

J.Ducastel — Wed, 16 May 2007 19:27:00 +0200

As quoted in the previous post : release early, release often. You can now download the first alpha release, saving you the pain of setting a subversion working copy.

Along with this release, the project home has been updated with three micro-tutorials, which you'll find too on the help.html file included with the release. :

Have fun !

Code documentation - alpha coming

J.Ducastel — Tue, 15 May 2007 18:39:00 +0200

Some code documentation has been generated and is online at code.webappkit.net. It covers the core kit and subkits code. It may be useful to people using provided generic libraries, such as databeans (data structures), pathnodes (filesystem) and Django templating engine php implementation.

I plan to release 0.8.0 as an alpha version sometime soon. The foundation is there, and work have been started on appEngine, the basic framework to be used by the web admin.

Release soon, release often. Any help is welcomed.

more big changes

J.Ducastel — Fri, 13 Apr 2007 23:09:00 +0200

(i'm evil)

As i was not happy with previous packages/resources system, i've trashed and recoded it - again. It was starting to be bloated and complex, and not that agile. So, to summary :

Packages are renamed to kits. A single class, webappkit, is used both as kit instances and global API (through its static methods). Kits can contain kits themselves, and kit names are made upon the physical tree (databeans/datetime for example).

A INI metadatafile, named wak.ini is required at the root of the kit. With this we take care of dependancies, both internal and external. For more flexibility, a wak.init.php may be included, if present, when the kit instance is built. A wak.run.php may also be present, and will be executed upon call of its run() method.

Services and non-code objects storage have to be implemented at this point. But various library packages have been converted to the new standard :

databeans
pathnodes
djangotpl
Spyc

Generic resources

J.Ducastel — Wed, 11 Apr 2007 20:38:00 +0200

The previously announced move has been started. Packages resources will be made generic, so their access and management will not be devoted to packages directly but to type-specific implementations of a generic resource class. Here's a changelist :

A new interface : wakResource, and a first, incomplete, implementation : wakResource_class. wakResource_service, wakResource_template to follow.
Changes have been made to wakPkg methods
The package metadata file format has also changed.
As a side note, the trunk compability will now include both PHP4 and PHP5, with an automatic switch between resource instances. Current move has still to be ported to php5, though.

0.7.0.1 released

J.Ducastel — Wed, 28 Mar 2007 13:53:00 +0200

Another minor release : 0.7.0.1 is available. It includes some bugs corrections for the 0.7 milestone.

Some (minor) work has been done on the wiki, too.

About 0.8 milestone, i'm thinking about having a generic interface for resources within packages rather than adding specific types later on. Resources are actually library classes and services (which are class singletons). Other types may be templates, static files such as images, css and javascript resources, documentation etc.

On the same topic, resources versions/flavours may be added, i.e. multiple files for a same resource. As an example, a package may provide libraries for both php4 and php5, and the appropriate version will be retrieved.

First download available, legacy

J.Ducastel — Sat, 13 Jan 2007 12:02:00 +0100

A first archive has been published for download on googlecode. It's a legacy archive and contains version 0.7.0, which is the last version using the microkernel paradigm.

It's currently being used by quizzgeek.net and is somewhat usable for production, although it doesn't include any administration interface. Configuration is entirely done by config files ( INI and YAML ), and there is no documentation available. Furthermore, it's considered as deprecated as the trunk is currently the 0.8 milestone and is seeing a major refactoring.

Sexy download, isn't it ?

Discussion group created

J.Ducastel — Thu, 11 Jan 2007 20:22:00 +0100

A google group has been created to discuss webappkit. You'll found it at groups.google.com/group/webappkit. Feel free to discuss the project, which is eagerly awaiting for contributors ! ;)

Some activity

J.Ducastel — Thu, 11 Jan 2007 13:19:00 +0100

In no particular order :

Home page has been updated, with links to googlecode pages.
Branch 0.5 has been added to subversion, for history purposes, and because some web apps are still using it.
Some minor work has been done to the source and wiki documentation.

svn moving to googlecode

J.Ducastel — Thu, 21 Dec 2006 14:31:00 +0100

As a good google slave, i've decided to move webappkit from sourceforge to googlecode, which has been recently improved. => webappkit on googlecode.

Google added a wiki and downloads to their open-source projects hosting offer. Coupled with their faster subversion server, issue tracking and neat web interface, it's now a good choice for project hosting.

I took the chance to change folders struture a bit. Legacy branches are now under branches/ as 0_7_php4 (the old php4, microkernel architecture) and 0_8_php4/ (the new packages architecture, but php4 version). Under trunk/ is the onwork php5, packages architecture, which may be released as 0.8 later.

Additionaly, some pages are available on the google-hosted webappkit wiki. The old, self-hosted one will be trashed soon.

first rebuilt version available

J.Ducastel — Thu, 14 Dec 2006 20:28:00 +0100

I've just added php5 to repository (revision 150). As announced, there are some huge changes in process. Basically, WAK is moving from a generic micro-kernel for web apps, to a packages architecture for web apps.

Packages are the new central interface. A package is a folder containing an index/metadata file (wakpkg.yml) describing provided resources. Thoses resources will be accessed through a wakpkg instance. Resources can be :

class definition files
services (named singleton within the package namespace, extending from wakservice class)

Class dependancies will be handled provided they are described within the metadata file.