Skip to content

Commit

Permalink
add template argument
Browse files Browse the repository at this point in the history
  • Loading branch information
@jbrinley
jbrinley committed May 24, 2011
1 parent 20e5595 commit ed2a0c5
Show file tree
Hide file tree
Showing 4 changed files with 120 additions and 19 deletions.
52 changes: 49 additions & 3 deletions WP_Route.class.php
View file
Expand Up @@ -17,7 +17,7 @@ class WP_Route extends WP_Router_Utility {
private $page_arguments = array();
private $access_callback = TRUE;
private $access_arguments = array();
private $template = '';
private $template = array();
private $properties = array();

/**
Expand Down Expand Up @@ -109,9 +109,9 @@ public function execute( WP $query ) {

$title = $this->get_title($query);

$page = new WP_Router_Page($page_contents, $title);
$template = $this->choose_template();

// TODO: do something with the template
$page = new WP_Router_Page($page_contents, $title, $template);
}

/**
Expand Down Expand Up @@ -271,4 +271,50 @@ protected function preg_index( $int ) {
$wp_rewrite->matches = 'matches'; // because it may not be set, yet
return $wp_rewrite->preg_index($int);
}

private function choose_template() {
$template = '';
$extra = array(
'route-$id.php',
'route.php',
'page-$id.php',
'page.php',
);
if ( $this->template ) {
foreach ( (array) $this->template as $path ) {
$path = str_replace('$id', $this->id, $path);
if ( $this->is_absolute_path($path) ) {
if ( file_exists($path) ) {
$template = $path;
break;
}
} else { // relative path, look in the theme
$template = locate_template(array($path));
if ( $template ) {
break;
}
}
}
}
foreach ( $extra as $key => $path ) {
$extra[$key] = str_replace('$id', $this->id, $path);
}
if ( !$template ) {
$template = locate_template($extra);
}
return $template;
}

private function is_absolute_path( $filename ) {
$char_1 = substr($filename, 0, 1);
if ( $char_1 == '/' || $char_1 == '\\' ) {
return TRUE; // unix absolute path
}
$char_2 = substr($filename, 1, 1);
$char_3 = substr($filename, 2, 1);
if ( ctype_alpha($char_1) && $char_2 == ':' && ( $char_3 == '/' || $char_3 == '\\') ) {
return TRUE; // windows absolute path
}
return FALSE;
}
}
17 changes: 16 additions & 1 deletion WP_Router_Page.class.php
View file
Expand Up @@ -13,6 +13,7 @@ class WP_Router_Page extends WP_Router_Utility {

protected $contents = '';
protected $title = '';
protected $template = '';

public static function init() {
self::register_post_type();
Expand Down Expand Up @@ -85,14 +86,21 @@ private static function make_post() {
return $id;
}

public function __construct( $contents, $title ) {
public function __construct( $contents, $title, $template = '' ) {
$this->contents = $contents;
$this->title = $title;
$this->template = $template;
$this->add_hooks();
}

protected function add_hooks() {
add_action('pre_get_posts', array($this, 'edit_query'), 10, 1);
add_action('the_post', array($this, 'set_post_contents'), 10, 1);
add_filter('the_title', array($this, 'get_title'), 10, 2);
add_filter('single_post_title', array($this, 'get_single_post_title'), 10, 2);
if ( $this->template ) {
add_filter('template_include', array($this, 'override_template'), 10, 1);
}
}

/**
Expand Down Expand Up @@ -144,4 +152,11 @@ public function get_title( $title, $post_id ) {
public function get_single_post_title( $title, $post ) {
return $this->get_title($title, $post->ID);
}

public function override_template( $template ) {
if ( $this->template && file_exists($template) ) { // these checks shouldn't be necessary, but no harm
return $this->template;
}
return $template;
}
}
68 changes: 54 additions & 14 deletions readme.txt
View file
Expand Up @@ -36,20 +36,45 @@ Created by [Adelie Design](http://www.AdelieDesign.com)

= Creating Routes =

* Your plugin should hook into the `wp_router_generate_routes` action. The callback should take one argument, a `WP_Router` object.
* Your plugin should hook into the `wp_router_generate_routes` action.
The callback should take one argument, a `WP_Router` object.
* Register a route and its callback using `WP_Router::add_route( $id, $args )`
* `$id` is a unique string your plugin should use to identify the route
* `$args` is an associative array, that sets the following properties for your route. Any omitted argument will use the default value.
* `path` (required) - A regular expression to match against the request path. This corresponds to the array key you would use when creating rewrite rules for WordPress.
* `query_vars` - An associative array, with the keys being query vars, and the values being explicit strings or integers corresponding to matches in the path regexp. Any query variables included here will be automatically registered.
* `$args` is an associative array, that sets the following properties for your route.
Any omitted argument will use the default value.
* `path` (required) - A regular expression to match against the request path.
This corresponds to the array key you would use when creating rewrite rules for WordPress.
* `query_vars` - An associative array, with the keys being query vars, and the
values being explicit strings or integers corresponding to matches in the path regexp. Any query variables included here will be automatically registered.
* `title` - The title of the page.
* `title_callback` - A callback to use for dynamically generating the title. Defaults to `__()`. If `NULL`, the `title` argument will be used as-is. if `page_callback` or `access_callback` returns `FALSE`, `title_callback` will not be called.
* `title_arguments` - An array of query variables whose values will be passed as arguments to `title_callback`. Defaults to the value of `title`. If an argument is not a registered query variable, it will be passed as-is.
* `page_callback` (required) - A callback to use for dynamically generating the contents of the page. The callback should either echo or return the contents of the page (if both, the returned value will be appended to the echoed value). If `FALSE` is returned, nothing will be output, and control of the page contents will be handed back to WordPress. The callback will be called during the `parse_request` phase of WordPress's page load. If `access_callback` returns `FALSE`, `page_callback` will not be called.
* `page_arguments` - An array of query variables whose values will be passed as arguments to `page_callback`. If an argument is not a registered query variable, it will be passed as-is.
* `access_callback` - A callback to determine if the user has permission to access this page. If `access_arguments` is provided, default is `current_user_can`, otherwise default is `TRUE`. If the callback returns `FALSE`, anonymous users are redirected to the login page, authenticated users get a 403 error.
* `access_arguments` - An array of query variables whose values will be passed as arguments to `access_callback`. If an argument is not a registered query variable, it will be passed as-is.
* `template` - Reserved, but not yet implemented.
* `title_callback` - A callback to use for dynamically generating the title.
Defaults to `__()`. If `NULL`, the `title` argument will be used as-is. if
`page_callback` or `access_callback` returns `FALSE`, `title_callback` will not be called.
* `title_arguments` - An array of query variables whose values will be passed
as arguments to `title_callback`. Defaults to the value of `title`. If an argument
is not a registered query variable, it will be passed as-is.
* `page_callback` (required) - A callback to use for dynamically generating the
contents of the page. The callback should either echo or return the contents of
the page (if both, the returned value will be appended to the echoed value). If
`FALSE` is returned, nothing will be output, and control of the page contents will
be handed back to WordPress. The callback will be called during the `parse_request`
phase of WordPress's page load. If `access_callback` returns `FALSE`, `page_callback`
will not be called.
* `page_arguments` - An array of query variables whose values will be passed as
arguments to `page_callback`. If an argument is not a registered query variable,
it will be passed as-is.
* `access_callback` - A callback to determine if the user has permission to access
this page. If `access_arguments` is provided, default is `current_user_can`, otherwise
default is `TRUE`. If the callback returns `FALSE`, anonymous users are redirected to
the login page, authenticated users get a 403 error.
* `access_arguments` - An array of query variables whose values will be passed
as arguments to `access_callback`. If an argument is not a registered query variable,
it will be passed as-is.
* `template` - An array of templates that can be used to display the page. If a path
is absolute, it will be used as-is; relative paths allow for overrides by the theme.
The string `$id` will be replaced with the ID of the route. If no template is found,
fallback templates are (in this order): `route-$id.php`, `route.php`, `page-$id.php`,
`page.php`, `index.php`.

Example:
`$router->add_route('wp-router-sample', array(
Expand All @@ -61,8 +86,16 @@ Example:
'page_arguments' => array('sample_argument'),
'access_callback' => TRUE,
'title' => 'WP Router Sample Page',
'template' => array('sample-page.php', dirname(__FILE__).DIRECTORY_SEPARATOR.'sample-page.php')
));`

In this example, the path `http://example.com/wp_router/my_sample_path/` will call
the function `sample_callback` in the calling class. The value of the `sample_argument`
query variable, in this case "my_sample_path", will be provided as the first and only
argument to the callback function. If the file `sample-page.php` is found in the theme,
it will be used as the template, otherwise `sample-page.php` in your plugin directory will
be used (if that's not found either, fall back to `route-wp-router-sample.php`, etc.).

= Editing Routes =

* You can hook into the `wp_router_alter_routes` action to modify routes created by other plugins. The callback should take one argument, a `WP_Router` object.
Expand All @@ -71,13 +104,20 @@ Example:

Creating or changing routes should always occur in the context of the `wp_router_generate_routes` or `wp_router_alter_routes` actions, using the `WP_Router` object supplied to your callback function.

* `WP_Router::edit_route( string $id, array $changes )` - update each property given in `$changes` for the route with the given ID. Any properties not given in `$changes` will be left unaltered.
* `WP_Router::edit_route( string $id, array $changes )` - update each
property given in `$changes` for the route with the given ID. Any properties
not given in `$changes` will be left unaltered.
* `WP_Router::remove_route( string $id )` - delete the route with the given ID
* `WP_Router::get_route( string $id )` - get the `WP_Route` object for the given ID
* `WP_Route::get( string $property )` - get the value of the specified property for the `WP_Route` instance
* `WP_Route::get( string $property )` - get the value of the specified property for
the `WP_Route` instance

== Changelog ==

= 0.1 =

*Initial version
* Initial version

= 0.2 =

* Added the `template` argument
2 changes: 1 addition & 1 deletion wp-router.php
View file
Expand Up @@ -5,7 +5,7 @@
Description: Provides a simple API for mapping requests to callback functions.
Author: Adelie Design
Author URI: http://www.adeliedesign.com/
Version: 0.1.1
Version: 0.2
*/
/*
Copyright (c) 2011 Adelie Design, Inc. http://www.AdelieDesign.com/
Expand Down

0 comments on commit ed2a0c5

Please sign in to comment.