How To Implement PHP Tag Engine

Assumptions

  1. You are using PHP
  2. You are using the ADOdb database abstraction library
  3. Security (user logins, etc.) is handled outside of PHP Tag Engine
  4. You are familiar with PHP's OO syntax

Step 1. Download PHP Tag Engine

First off, you'll need to download PHP Tag Engine and put it in your project directory. I recommend using svn:externals, as this works well in my experience.

Step 2. Config Settings

The config settings are in the phptagengine.config.inc.php file. Edit this file as needed, the main things you need to do is make sure that your database settings and URLs are correct.

  • Set $pte->db = to the global variable that is your ADOdb instance.
  • Set $pte->table_tags to the name you want to use for your tags table (this table will be created by the install function).
  • Set $pte->table_tag_names to the name you want to use for your tag names table (this table will be created by the install function).
  • Set $pte->table_users to the name of your (existing) users table.
  • Set $pte->table_users_name to the name of "name" column in your (existing) users table.
  • Set $pte->base_url to the URL of your app.
  • Set $pte->ajax_handler to the URL of your AJAX request handler. If none exists, you will want to create a file for this.
  • Set $pte->tag_browse_url to the URL structure you want to use for browsing by tag. The tokens <tag> and <type> will be replaced by data values.
  • The $pte->default_type can be set to a default value. For example, in Tasks Pro and Tasks, I do not use this setting so I set the $pte->default_type to 'task' and never have to worry about it again.
  • The $pte->default_user can be set to a default value. If you are doing user-specific tagging, you won't be using this.

Step 3. Include in your codeline

To include PHP Tag Engine in your app, you'll want to include the phptagengine.inc.php file, like so:

require_once('phptagengine/phptagengine.inc.php');

Step 4. Add to Your Install Script

Assuming you have an install script that creates your database tables, you'll want to add a call to the $pte->install() method so that the PHP Tag Engine tables are created when your app is installed.

Step 5. Adding the tagging form to your app

PHP Tag Engine includes full front-end XHTML/CSS code for displaying tags and allowing them to be edited via the JS/AJAX interaction with the back-end code.

First you need to include the necessary CSS and JS files by putting this call in the head section of your HTML page:

$pte->html_head()

To add the tagging form to your app, you just use this method:

$pte->html_item_tags($item_id)

If you're showing a number of items at once, you'll probably want to use the built-in cache features to reduce the number of database queries to get tag data:

$pte->item_tags_cache

You can tell various methods to use the cache, as noted in the PHP Doc.

Step 6. AJAX Request Handling

If your app already has a file that handles AJAX requests, all you need to do is include phptagengine.inc.php in that file and set your $pte->ajax_handler to use that URL.

If you don't have a file that handles AJAX requests already, you can either create one or use your index.php file or similar, as long as it includes the phptagengine.inc.php file.

TODO for this page

More in depth, etc. Have a question - post it here or create a ticket and I'll try to clarify whatever is insufficiently documented.