The Tokenize Request Parameters module (TRP) provides the following:

• Converts parameters passed in the URL of a Drupal node into tokens: e.g. /node/451/&order=12345 will be converted into the token [get-param:order] or [get-param-order]
• Converts parameters from a form post to a Drupal node: e.g. a form with <input type="hidden" name="order" value="12345"> will be converted into the token [post-param:order] or [post-param-order]
• Configuration page to configure which request parameters can be tokenized on which pages and which methods (i.e. URL or Form parameters).
• Secure filtering of parameters before they are tokenized

Do I need this module?

This is a very specialized module. Chances are you don't need it. You will find this module of value if you have the following requirements:

• You have a script that needs to send one or more values to one of your Drupal content pages
• You need to be able to take the sent value 'as-is' and place it in arbitrary places to display embedded in your content
• A content editor without PHP privileges needs the freedom to place the passed value anywhere within their authored content

Some example use cases where this module will help you, include:

• You have a non-Drupal application that processes a transaction for you and then redirects the user to your Drupal page with a confirmation number or some other value calculated and passed by your external application.
• You have a custom payment processor that needs to send the user to a 'thank you' page that will display the order number
• You have an issue ticketing system that passes back a ticket number and other details that will be displayed on your Drupal site

This module is a token provider only - it needs to be used by some other module that will use or 'consume' the tokens. In the above use cases the consumer module would be Token Filter. However, it will work with any other module that consumes tokens. For example, it could be used to provide tokens to a Menu Token filter, to have the path to menu items change dynamically. Though, you would need to be VERY cautious about doing such a thing!

Getting Started

Assuming that you want to embed tokens into your content pages you will need to install and enable the following modules:

• Token
• Token Filter
• Tokenize Request Parameters

Once all modules are enabled you need to start planning how to produce your tokens and where to expose them, then configure the modules.

Preparation & Planning

Before configuring your site there are a few things you will need to prepare to ensure that you are securely and efficiently exposing the right tokens that you will need.

1. How will your application pass the parameter? Will it be in the URL, or is it a form post?
2. What are the names of the parameters that you will expose as tokens? In a URL request parameters passed as key/value pairs: key=value. The parameter name will be the same as the name of the key. In form posts the parameter name is the 'name' attribute in the form field.
3. On what page or pages will you need to have parameters passed to and displayed?
4. What is the maximum number of characters that you expect to be passed to your content page? For example, if you are accepting a parameter for an order number, how many digits are your order numbers typically?
5. If parameters sent to your content page exceed the maximum expected how should that be handled? You have two options: either truncate the passed value so that any value that exceeds the maximum expected will be chopped off after the maximum characters have been used, or discard the parameter completely.

This information will be needed before configuring Token Request Parameters.

Setup: Token Filter

The first thing you will need to do is to enable the Token Filter module. Again this assumes you are exposing parameter tokens for use in node content pages:

• Go to Administer / Site configuration / Input formats
• Create or modify an existing Input Format that you will use when editing your content page
• You will see a list of Input filters, some enabled and others not enabled. One of the disabled filters will be the Token Filter. Enable that filter in your chosen input format.
• While still in the input filter configuration page click on the local navigation tab at the top of the page labeled: 'Rearrange'. Reorder the sequence in which the input filters are applied to make sure that the 'Token Filter' is BEFORE the HTML Filter to ensure that tokenized parameters cannot inject arbitrary HTML after the HTML filter has cleaned code. TRP module does apply internal filters to protect against XSS attacks, but this is a recommended extra precaution

Configuration: Tokenize Request Parameters (TRP)

Once you have your token consumer module (Token Filter) setup and enabled you can now configure TRP to tokenize the parameters that you expect to receive and expose as tokens. Make sure that you have answered the preparation questions in the Preparation & Planning section above before you configure TRP - it will help remove any confusion about what it is you are configuring.

These configuration options are provided so that you can lock down the behavior of your parameter tokens to very specific contexts. This makes sure the performance of your site is not compromised and is also an important part of using this module in a secure manner.
Ideally, you will configure specific pages that can receive parameters, using only the method you expect to use (POST or GET) to pass values and handling any parameters a malicious user might try to pass: for example, trying to write spoof text to display on your site, to look like it is a message from your site. If you are displaying a 10 digit number, then you should configure TRP to only display a token 10 characters in size and either discard any values that exceed that or truncate it.

• Go to Administer / Site configuration / Token Request Parameters
• Select what method your parameter will be passed by: GET or POST. If you might have both methods used to pass the parameter then you can select both methods - ideally you have only one method. This should be determined in Step #1 of your preparation & planning
• In the text area labeled 'Tokenize the following parameters'. List each parameter name that you identified in Step #2 of your preparation & planning. Each parameter name should go on it's own line. NOTE: the parameter name is case sensitive. It should be listed exactly as it will be written in the URL or post form input name
• In the text area labeled 'Allow parameter tokens for the following pages' list the pages that you will be sending parameters to (Step #3 in preparation). This uses the same page matching format that is used for configuring the visibility of blocks. Add the path to each page that you want to enable parameters to be tokenized. If you want to enable all pages under a a specific path use the * wildcard. For example: "node/*/list" will enable tokenization on every node page that has a content list page
• In the text area labeled 'How many characters should be allowed in the token?' - put the expected maximum number of characters as an integer (whole number) value. The default is 50 characters, so if the maximum of your parameter will be 60, you will need to set this value at '60'. See Step #4 of the prep & planning section above
• Finally, select the handling preference identified in Step #5 of prep and planning by selecting the appropriate radio button under 'How should values exceeding the maximum characters allowed be handled?'

How do I pass the parameters to my page?

If you are using the form post method, then you simply have the parameter you want to pass as a form input element. The 'name' attribute of the input element will be the name of the parameter matched by TRP.

If you are passing values on the URL then you can add the parameter to the internal path used by Drupal:

E.g. For the Drupal URL, '/index.php?q=node/5' you will add the parameter as '/index.php?q=node/5&myparam=myvalue. It is important to use the & sign to separate key/value parameter pairs in a URL.

If you are using Clean URLs then most likely your URLs look something like '/node/5'. Although the URL looks different internally to Drupal is still looks like '/index.php?q=node/5' and so the '?' is implicitly already included. This means you need to construct your URL on Clean URLs like this: '/node/5/&myparam=myvalue. You should use the ampersand, not the '?' query mark.

Also, you do not have to include the final slash: '/node/5&myparam=myvalue', works just as well.

Can't I just enable the core PHP filter and display $_GET and $_POST values?

You are not prevented from doing this, but it is a strongly discouraged practice. For one thing, enabling the PHP filter will expose the whole of PHP to a content editor on every page of your site and there are many reasons why you might not want to do that.

The main reason that you should avoid using PHP filter to embed something like:
print $_GET['my_url_param']; is that it introduces the risk of cross site scripting (XSS) attacks: because you are accepting unfiltered values from an untrusted source. The purpose of TRP is to add a layer of protection from these sorts of vulnerabilities using the Drupal best practices for security. That is essentially the whole purpose for this module's existence.

A basic rule of thumb here is that if you don't know how to modify the code above to make it secure then you definitely need to use TRP instead. If you do know how to secure that code, you will already appreciate the value of using TRP.