PHP Kemu Gradiented Progress Renderer v 1.0

This is main documentation file for Kemu Gradiented Progress Renderer v 1.0.

Introduction

This is advanced progress bar renderer for PHP. It renders some nice-looking gradiented progress bars into PNG.
For example this:

is 100x11 sized dynamically rendered progress bar.

Samples

Here are few samples of what "PHP Kemu Gradiented Progress Renderer" renders:

No text

The "badGood" skin, size 100x11 pixels, rendered 11 times with progress values 0%, 10%, 20%, ..., 100% without of text:

Default text

The "badGood" skin, size 100x11 pixels, rendered 11 times with progress values 0%, 10%, 20%, ..., 100% with the default text:

Skins

Predefined skins dump #1:

Predefined skins dump #2:

Predefined skins dump #3:

Full skin charts (big pictures !) here: base skins, white skins,

Defining width and custom text

The "badGood" skin, defining horizontal size (height is constant: 11px) and some custom text:

Notice how the text is auto-aligned in the progress bar.

Defining border size

The "badGood" skin, defining different border size:

Defining height

The "badGood" skin, defining different height:

Description

Rendered progress bar consists of border, the progress bar itself and some aligned text - however this may vary for different skins.

Rendering is based on configuration provided to the rendering module by a calling PHP script. Configuration includes size (width and height) of an image, the name of the skin, border size, progress value, text to display etc.
Detailed description of usage is provided in examples section and in source code.

Dependencies

GD: PHP with GD library support is needed (99% you have it - it's common on 99% of servers).

k_cache: Image rendering in PHP takes some precious server CPU time, so caching progress bar images is supported through included PHP Kemu Linear Cache (k_cache) module.

k_log: Rendering needs some logging/debugging, so the default k_log API is supported inside renderer. You can attach "PHP Log2Files Advanced Logger" as the logger. Also some dummy logger implementation ("k_log_dummyFileWriter.php") is available in the package. It is used by examples, it can be used for testing, but DO NOT use that in production environment, as this is not locking/threads aware. Read about "PHP Log2Files Advanced Logger" for more info.

Features

19 skins included
customizable width, height, border size and text
no additional dependencies - only standard GD in PHP
unique caching engine with file locking
usage explained by examples
well commented source code - easy to customize or to learn from
apache mod_rewrite compatible

How to

The usage of this module is so simple, that we decided to show it by few useful examples included in a release pack, instead of providing the "API-like" documentation.
There is no "big installing instruction", as there is simply no need to install anything - just unpack.
You can even use the examples directly in your productive server - just modify the configuration passed to the renderers in example files and change the file names according to your needs.
Of course, if you want to go into details of API calls, the documentation is provided as comments inside PHP files.

Package

After you unpack the release package into your server, you will find:

examples.php - start here, this file groups all examples on one page
ex01.php, ex02.php etc. - php files for displaying the example progress bars,
ex01renderer.php, ex02renderer.php etc. - renderer example calls. These files are used for rendering progress bars in examples.
cache - empty directory for storing cached rendered progress files.
doc - documentation
libs - the renderer and all its dependencies,
- k_progressGradiented.php - the core file for rendering progress bars
- k_cache.php - k_cache module for caching rendered files
- k_log_dummyFileWriter.php - very simple log implementation for helping in the development process
- some internal dependency files

Examples - start here

After unpacking, run the http://yourserver/examples.php script. This will display the list of examples - you can click on any example to start it.

Also there is a "click" for clean up the caches - it just removes all files from "cache" directory.

Examples - short way

You can just use ex02_renderer.php or ex03_renderer.php in your production environment. Of course you may change name of scripts according to your needs :)
Do not use directly ex01 nor ex04 scripts, as those are made as feature demos, and do not use cache (running this without cache can simply eat too much of your CPU power).

Example #1 - very simple config (non-productive, cache disabled)

This example contains 7 different sub-examples. It just calls files: ex01_1renderer.php, ex01_2renderer.php, ex01_3renderer.php, ... in row as images.
Each file simply calls K_PROGRESS_GRADIENTED_emitGradient($config) function, giving slightly different config.

There is no log usage, there is no cache usage. Those examples are just for experimenting a little bit.
You can adjust each of those scripts to experiment with your configs.

WARNING: This is example only, never use this code directly on production server. The cache is disabled here !!

Example 1.1:

- 100 x 20 PNG, skin: badGood, progressValue: 50 - very simple example
Example 1.2:

- 500 x 11 PNG, skin: badGood, progressValue: 90 - example of changing size and progress value
Example 1.3:

- 200 x 30 PNG, skin: badGood, progressValue: 120 - example of what happen if you put over-maxed progress value (120%)
Example 1.4:

- 200 x 30 PNG, skin: badGood, progressValue: 60, borderSize: 5 - example of borderSize change
Example 1.5:

- 200 x 30 PNG, skin: badGood, progressValue: 25, progressText: "only 25 percent !" - how to set the custom text
Example 1.6:

- 200 x 30 PNG, skin: badGood, progressValue: 75, progressText: "" - how to disable text
Example 1.7:

- 200 x 30 PNG, skin: grass, progressValue: 75 - how to change the skin

Example #2 - progress passed by PHP param (productive, cache enabled)

This example shows how exactly you may use the K_PROGRESS_GRADIENTED_emitGradient() in your scripts.

There is proper log and cache configuration.
The script just takes the input parameter "p" (which should be a number) and uses it as progress value.
There is also k_cache_id which is an unique id for the k_cache system.

Example #3 - progress and skin passed by PHP param (productive, cache enabled)

This is very similar to example #2 - it just additionally takes the skin name from PHP params calls.

Example #4 - display internal parameters (productive, cache enabled)

This example displays internal parameters instead of those passed by param.

It displays:
- gradient bar of your real HDD usage (disk_total_space() and disk_free_space() functions used),
- the fancy clock, made of 3 gradients (hours, minutes, seconds) - just refresh the page to see how it moves,

Other

FAQ

Ask your questions to ss@ke.mu

License

All copyrights reserved by Kemu Studio, Pietrzak 'yosh' Roman (visit yosh.ke.mu).
Source code and documentation available from CodeCanyon