sgb_url_handler
Mar 5, 01:13 PM • txp
Configuration | Download | Changelog | To Do
Update 2005-06-21: If you're having problems with sgb_url_handler (e.g. your site goes blank after starting it) follow these instructions
This plugin adds a number of features to TxP, increasing it's ability to respond to different URL schemes. All configuration options are set in the function sgb_url_handler_config(). The plugin will only send proper HTTP errors (404 and 301) if sgb_error_documents is active (version 0.1.2.2+).
Configuration
Match Mode
This option is configured using $config['match'] in the configuration function (config).
When set to 'best' the plugin uses whatever information is available in a URL to match an article, e.g. example.com/validSection/validID/invalidTitle, example.com/invalidSection/validID/invalidTitle, and example.com/invalidSection/invalidID/validTitle would match an article and example.com/validSection/invalidID/invalidTitle would match the secion.
When set to 'exact' the plugin must match all information in the URL to make a valid request, e.g. example.com/validSection/validID/invalidTitle, example.com/invalidSection/validID/invalidTitle, and example.com/invalidSection/invalidID/validTitle would all generate a 404. Only example.com/validSection/validID/validTitle would return an article.
Additionally in this mode the plugin can send 301/Redirection headers (actually in either mode the plugin can send 301s, it's unlikely that a 301 will be sent in "best" mode). A 301 header is sent when an article is matched using a scheme different from the scheme specified in the TxP Permlink Mode or the $sections array of the config.
The default value for this option is $config['match'] = 'best';
Send Errors
This option is configured using $config['send_errors'] in the configuration function (config).
Errors are only available if sgb_error_documents is active, this option allows you to enable or disable error sending.
The default value for this option is $config['send_errors'] = 1;
Send 301
This option is configured using $config['send_301'] in the configuration function (config).
Sends 301/Redirect if set to true when an article is requested by a URL scheme different from the permlink mode (or from the scheme set in $sections).
The default value for this option is $config['send_301'] = 0;
Send 404
This option is configured using $config['send_404'] in the configuration function (config).
Sends 404/Not Found errors when an article is not found at the specified URL.
The default value for this option is $config['send_404'] = 1;
Schemes
This array in the config contains all URL Schemes the plugin will be able to recognize. URL Schemes should be listed in the order you want them satisfied, once the plugin matches a URL it will attempt to satisfy it. URL Schemes are defined in the follow format:
$schemes['scheme_name'] = "scheme/format";
$schemes['section_category_title'] = "/%section%/%category%/%title%";
$schemes['section_title'] = "/%section%/%title%";
$schemes['section'] = "/%section%";
$schemes['title_only'] = "/%title%";
As displayed above, URL Schemes are not "flattened" so you'll need to specify a distinct scheme for each step. The scheme_name must be unique, and is only used to identify schemes. Keywords in the scheme/format are surrounded by % symbols. The basic keywords are as follows: %section%, %category%, %id%, %title%, %year%, %month%, %day%, %sring%, and %number%. The last two are used as place holders and don't figure into the article retreval.
In addition to the basic keywords there are several locale specific keywords, these begin with an underscore: %_author%, %_section%, %_category%, and %_file%. These translate into the locale specific words, e.g. on an EN-US install of TxP %_section% translates to 'section'.
Schemes can also have literal strings in them, e.g. $schemes['some_scheme'] = "superblog/%title%" would only match for URLs that started with "superblog" and contained a title.
It is not necessary to put a leading or trailing slash.
Sections
This option is configured using the $sections array in the configuration function (config).
This allows you to specify which sections should use which URL Scheme. When using this option the Permlink Mode set in the TxP admin is the default URL Scheme. To fully utilize the plugin you'll need to use the <txp:sgb_url_handler_permlink></txp:sgb_url_handler_permlink> tag in your forms. This tag will correctly generate the permlink of an article based on the information in $sections. This information is also used when sending 301/Redirect headers.
There are no sections predefined, to define a section add a line like this $sections['section_name'] = 'some_scheme'; in the config. some_scheme must match a URL Scheme defined in $schemes and section_name must be a valid section.
Triggers
This option is configured using the $triggers array in the configuration function (config).
Triggers are actions that can be executed by the plugin when a specific URL Scheme is matched. Triggers allow the plugin to step out of the normal article matching routine and execute other plugins/code. There are six triggers: AUTHOR, FILE, ATOM, RSS, REDIRECT, NOTHING. Style-wise triggers are in uppercase (but are ultimately treated case-insenstive).
Some triggers accept an optional paramter this is done by adding ::paramter to the end of the trigger definition, e.g. REDIRECT::http://www.google.com would be the trigger to redirect a URL to google. As of now only the REDIRECT accepts optional paramaters.
Download
Changelog
- 0.1.8.4 - Current
- Updated code so "notices" weren't generated by sgb_url_handler (r463 added the error handling stuff)
- 0.1.8.3
- Now include sgb_error_documents via
include_plugin()-- now requires a recent (r430+) version of TxP
- Now include sgb_error_documents via
- 0.1.8.2
- Cleaned up some code related 301s
- 0.1.8.1
- Fixed a bug with issuing 301s and articles with no section/category
- 0.1.8 - Has a bug
- Refactored the entire plugin (all the good parts anyway)
- Rewrote URL scheme assembling code
- Reduced server load (processor/memory)
- Crushed some annoying bugs with regards to 301s and 404s
- 0.1.7 - Unreleased
- Rewrote error handling code
- Updated 301 support
- Added initial support for an
<txp:sgb_url_handler_permlink>tag - Added per-section URL scheme preference
- 0.1.6 - Unreleased
- Added initial support for sending 301s and redirecting users to the proper location
- Added initial support for custom URL schemes
- 0.1.5
- Added trigger for file_downloads.
- Fixed a bug where requests to other TxP resources (textpattern/css.php) were incorrectly assigned 404s.
- 0.1.4
- Articles are resolved using Titles and Sections when appropreiate.
- Added 404 support. See documentation for more information.
- 0.1.3
- Fixed an error with /Section/Category/Title parsing
- Fixed version numbering
- 0.1.2
- Added help
- 0.1.1
- Released
To Do
- Add an admin interface?
Add support for 301 redirections(added in 0.1.7)Add support for custom URL schemes(added in 0.1.7)Add an elegant way to disable specific URL formats.(added in 0.1.7)I want to make /Section/Category/Title parsing a bit more robust. I'd like to have it look up based on title & category (if valid) in case there are multiple posts with the same title. This will probably make it into 0.1.4.(added in 0.1.4)
Supplemental Instructions
Install sgb_url_handlers 0.1.8.4
Install sgb_error_documents 0.1.2.2
Configure each plugin per normal
Edit sgb_error_documents and copy all the code (you don't need to save after copying)
Return to the plugins page
Edit sgb_url_handler, delete or comment out the line that says
include_plugin('sgb_error_documents');Paste all the code you copied from sgb_error_documents above the line you just commented out (or deleted)
Save the changes and return to the plugins page
Activate sgb_url_handler -- you don't need to activate sgb_error_documents.