When building websites, sometimes we need to display custom data in the database, which is not a post, page, or a custom post type. In this case, we will create a custom URL for users to access and see the information we want to display. This URL is usually called a virtual page because it is not managed in the WordPress admin area.
The example of virtual pages can be seen on e-commerce sites. After the customer places an order, the website will generate an invoice for customers to view order details. They also can pay or print the invoice to PDF and download it to their computer.
At Meta Box, we also use virtual pages to display the changelog of the plugins. For example, to view the Meta Box Builder changelog, visit the following URL:
https://metabox.io/plugins/meta-box-builder/changelog/
Apparently, invoice or changelog has custom content, but they are not a page or a custom post type in WordPress. They are created based on the specific needs of each website.
How to create a virtual page
There are a few ways to create a virtual page in WordPress, depending on how you want to generate the URL for that page. In this article, I will show you three ways to create virtual pages based on the permalink structure:
- A virtual page with a simple URL
domain.com/?invoice_id=123
. - A virtual page that appends to an existing link, such as the link to the changelog of the Meta Box plugins:
https://metabox.io/plugins/meta-box-builder/changelog/
. We will need to use the rewrite endpoint API. - A virtual page that has a custom link structure
domain.com/download/123/
. We will use custom rewrite rules.
Let’s see how to implement each method below.
Creating a virtual page with a simple URL
This is the simplest type of virtual page since you do not have to work with custom rewrite rules. You just need to get the value of the variable invoice_id
on the URL and display the template based on that value.
Note that the variable on the URL must not be the same as the existing WordPress query variables.
To get a template for that URL, we will hook into init
as follows:
add_filter( 'init', function( $template ) { if ( isset( $_GET['invoice_id'] ) ) { $invoice_id = $_GET['invoice_id']; include plugin_dir_path( __FILE__ ) . 'templates/invoice.php'; die; } } );
We use the init
hook instead of template_include
so that WordPress does not have to query the database to retrieve messages. Therefore, speed will be faster.
The template file is located in the templates
directory of the plugin. If you put it in another directory or in the add, change the path to that file.
After including the file, we must run die
so that WordPress does not execute queries and other tasks (which possibly output to the screen).
This method is very fast and convenient. However, its downside is that the URL is not pretty.
Creating a virtual page with rewrite endpoint API
The Rewrite endpoint API is a part of the rewrite rules API in WordPress, which helps us add a suffix (endpoint) into a link structure already available.
For example, at Meta Box, we create a custom post type product
for plugins and each plugin have the following URL structure:
https://metabox.io/plugins/meta-box-builder/
With the endpoint, we can create a URL for the changelog as follows:
https://metabox.io/plugins/meta-box-builder/changelog/
Here /changelog/
is added at the end of an existing URL and creates a custom URL.
This is very handy because it makes the URL structured and easy to understand. Besides, it is quite simple.
To add an endpoint, we use the add_rewrite_endpoint()
function as follows:
add_action( 'init', function() { add_rewrite_endpoint( 'changelog', EP_PERMALINK ); } );
And load the template as follows:
add_action( 'template_redirect', function() { global $wp_query; if ( ! is_singular( 'product' ) || ! isset( $wp_query->query_vars['changelog'] ) ) { return; } include plugin_dir_path( __FILE__ ) . 'templates/changelog.php'; die; } );
We use the template_redirect
hook instead of init
as we did before because we have to check whether the page being loaded is a single product page. Note that when we add an endpoint to a URL, all template tags of WordPress still work. This is very useful when checking the condition of the page.
Similar to the first method, we also include a template file from the templates
folder of the plugin and die
so that WordPress does not have to perform extra actions.
Using endpoint is quite convenient for content types that relate to the available content. However, it is limited to existing URL structures and cannot create custom URL structures. To do that, let’s see the third one below.
Creating a virtual page using custom rewrite rules
Suppose we need to create a page to download the invoice domain.com/download/123
, where 123
is the ID of the order. We will need to do the following steps:
Create a custom rewrite rules
add_filter( 'generate_rewrite_rules', function ( $wp_rewrite ){ $wp_rewrite->rules = array_merge( ['download/(\d+)/?$' => 'index.php?dl_id=$matches[1]'], $wp_rewrite->rules ); } );
The filter generate_rewrite_rules
is used to add a custom rewrite rule to the list of available WordPress rules (stored in $wp_rewrite->rules
). This list is an array, and to add a rule, we simply add an element to that array.
A rule is defined by two components:
- Rewrite rule: is declared as a regular expression
download/(\d+)/?$
- The parameters when the WordPress parse rule:
index.php?dl_id=$matches[1]
. WordPress uses the functionpreg_match()
so the parameters are parsed similar to this function. The parameter$matches[1]
is the value in the first bracket of the rewrite rule, ie the\d+
part. The value of this parameter is passed to the custom variabledl_id
.
Adding a custom query var to WordPress
After parsing the rewrite rule as above, the value of the invoice ID is stored in the dl_id
variable. To make WordPress understand this variable, we need to declare it as follows:
add_filter( 'query_vars', function( $query_vars ){ $query_vars[] = 'dl_id'; return $query_vars; } );
This code will add dl_id
to the list of WordPress query vars.
Load template
The final step is loading a template for the download page. This is the code:
add_action( 'template_redirect', function(){ $dl_id = intval( get_query_var( 'dl_id' ) ); if ( $dl_id ) { include plugin_dir_path( __FILE__ ) . 'templates/download.php'; die; } } );
We get the invoice ID by the function get_query_var()
. Since the dl_id
the variable was declared in the previous step, WordPress understands and derives it. If your URL is download.com/download/123
then the value of dl_id
is 123
.
Then we load the corresponding template file and die
so that WordPress does not handle the next actions.
Compared to the previous method, this last approach is more complex. However, this is the only way you can create your own URL.
You might ask: How do I create a custom URL like domain.com/my-custom-url
?
Well, it’s not hard to do that, try the code below:
add_filter( 'generate_rewrite_rules', function ( $wp_rewrite ){ $wp_rewrite->rules = array_merge( ['my-custom-url/?$' => 'index.php?custom=1'], $wp_rewrite->rules ); } ); add_filter( 'query_vars', function( $query_vars ){ $query_vars[] = 'custom'; return $query_vars; } ); add_action( 'template_redirect', function(){ $custom = intval( get_query_var( 'custom' ) ); if ( $custom ) { include plugin_dir_path( __FILE__ ) . 'templates/custom.php'; die; } } );
Conclusion
Creating a virtual page with a custom URL is a very common thing in plugins. With the 3 ways above, hopefully, you can create virtual pages of your choice. If you have other methods, please share them with us in the comments section.
Thank you for this article, this is very helpful. I want to mention one thing. According to the following post;
https://markjaquith.wordpress.com/2014/02/19/template_redirect-is-not-for-loading-templates/
template_redirect shouldn't use to 'include' template instead of template_include
what do you think?
That's partly correct. template_include runs *after* WordPress performed query for posts. So, if you don't need to use WordPress query, using template_redirect will have a better performance. In the article, I ran "die" to stop all further actions, which is for the exact purpose.
Thank you for reminder, i almost followed this tutorial.
Just read on official doc: https://codex.wordpress.org/Plugin_API/Action_Reference/template_redirect
There was a line with bold text: "Loading a different template is not a good use of this action hook"
It's not recommended to use this hook to load a template file that you can do in your theme. However, in this case, it's fine to load a template file for a virtual page, which does not exist in WordPress.
Having just tested the first example myself, I found that literally any URL containing "?invoice_id" will redirect to the specified template. I know you gave reasons for why that first example is "least desirable", but this effect makes it undesirable for completely different reasons, does it not?
Hello, did you add "die" or "exit" in the code? Without that, WordPress will continue parse other query vars and set the template. The code in the post is the code that I'm using for this website and it works.
I just realised my previous comment was confusing. Where I used the word "redirect", what I really meant was "include" - i.e. any URL will include the invoice.php template file regardless of the exact URL path. As long as it has "?invoice_id" at the end, it will redirect.
If I understand the code correctly, this behaviour is not surprising, because the template is beling included based solely on the condition "if ( isset( $_GET['invoice_id'] ) )". That would evaluate to true regardless of what the URL path was.
For clarity, I'm talking about the very first example, the one you suggest people NOT use because it does not have "pretty" URLs.
I used the word "redirect" in error again! Argh!
I tried the last snippet and got: 'I got Invalid argument supplied for foreach() in wp-includes/class-wp.php on line 289'
https://imgur.com/a/JdElg
WP 4.9.4 / PHP 7
@Marro: Yes, that's right! That's why this method is very simple and should be only used in some specific situations. To keep the URL non-public, you should create a secret query param that only you know it.
@pax: what query var did you use? Do not use preserved query vars by WP.
I didn't even get that far, I just copied the snippet in my functions.php and added the custom template in my theme, the error happens on plain front page, with now queries.
FYI, you have a typo in your code - where you return $public_query_vars, that variable isn't set - use return $query_vars instead.
Hi Jason, thanks! I've just updated the post.
Hi how can i do this like http://example.com/download/testing like this url please help me i am stuck in this
I am using the "Creating a virtual page using custom rewrite rules" technique for virtual pages, and it works. Elsewhere in my theme, I am trying to use "is_page_template('my-virtual-page-template.php')", and it does NOT work for my virtual pages, even though they definitely are using this template. Have you run into this issue and/or do you have a solution?
Hi, this is very helpful as I need to create custom print friendly pages with plain text ACF field for our news items, and ideally something like /site/name-of-story/print and then load custom temlpate that pulls in the custom clean text fields without the HTML bold/italics/links or images. So, I think one of your first couple of examples with the rewrite endpoint API would work for that. So, woo and hoo. Thanks ! 🙂
Oh, why don't you use our Meta Box plugin instead of ACF? 😉
I'm using the "Creating a virtual page with rewrite endpoint API" approach, but only want these virtual pages on child pages. Is that possible?
Example... fitness studio with studios as post type. Top level pages are the City, child pages are the locations, and we want /pricing and /schedule endpoints set up for those child pages.
So url might be domain.com/new-york/uptown/pricing
Any tips would be greatly appreciated!
This is excellent! For a modal, the first example worked great, and it kept everything simple. Much appreciated.
Any suggestion how to work within comment form and comments on virtual page? I'm using second example.
Everything working as expected, but when I send form, page reload to virtual "parent page".
Thanks
hi thanks
I use first way to show login form
if this safe? sample: my-site.com/?login=true
Hi, excellent article. One question I have is, how do you return a response code like 404 or 301 if the ID is invalid or doesn't exist? I'm not quite sure how to hook WP before the headers are written to the output stream.