Sparse - Linking to Templates

Let's say you have two pages: one listing a bunch of employees, and a second page listing employee details. You want to make it so clicking an employee brings you to the second page. And, of course, you want both pages to be done in Sparse. How do we do it? Well, you can muck around with $_REQUEST, but there's a simpler way. You can change the URL to "feed" data into a Sparse template, allowing you to dynamically change what's being displayed without having to worry about it in the template itself.

A quick primer on URLs for those who are rusty. Your regular run-of-the-mill URL looks something like this:

http://www.sparse.com/docs/linking.html

However, you can also use the query portion of the URL to pass data to the page you're aiming for. Queries consist of a set of variables and the values associated with them. For example,

http://www.sparse.com/docs/linking.html?name=Daniel&gender=male&intelligence=very%20high

The query starts after the ?. The set of "variable=value" pairs are separated by & signs. Note the %20 in the last value; because URLs aren't very smart at handling funny characters, you'll need to URL-Encode them. Try this page to encode your value.

Now that that's out of the way: Sparse allows you to use special variables in your URL to affect a Sparse template. Here are the variables you can stick in there.

Name	Explanation
sparse_id	This is the index of the template on the page. Because Sparse allows more than one template per page, this is necessary to tell it which template we're dealing with. If you only have one template, you can leave this out. Otherwise, set this to 0 for the first template on the page, 1 for the second template, etc.
sparse_page	The page to display (page 1, 2, 3, etc.) You can only use this if you have "Next" or "Previous" buttons or an sqlnavigation tag in your template.
sparse_search[name]	The search terms to execute. "Name" is the name of the field you want to search. You can include multiple search terms in a single URL, e.g. sparse_search[field1]=value1&sparse_search[field2]=value2...
sparse_limit	The number of items to display at once.
sparse_sort[]	The name of a field to sort by.
sparse_sort_order[]	ASC or DESC (for ascending or descending). By default this is ASC, so you can ignore it if that's what you want. This goes along with sparse_sort, and again, you can include any number of sparse_sort and sparse_sort_order variables, and the data will be sorted by the first one it sees, then the second one, etc.

So, for example:

http://www.sparse.com/mytemplate.phtml?sparse_search[managerID]=56&sparse_limit=5&sparse_sort[]=employeeName

will list those employees whose manager ID is 56, show 5 per page, and sort by the employee's name.

A nice use of this is to make "sortable headers":

<tr>
<th><a href="?sparse_sort[]=name">Name</a></th>
<th><a href="?sparse_sort[]=address">Address</a></th>...
</tr>

Note that there is no URL in there at all, just a query string. That's a shortcut for saying "this page, with the following query".

External Forms

In addition to plain links, you can have the user execute the search himself from a separate page (e.g. from another window or frame). You can use the same variables above, but in a form context:

<form action="mySparsePage.phtml" method="POST">
<input type="hidden" name="sparse_id" value="1">
Search for name: <input type="text" name="sparse_search[name]">
Rows to display: <input type="text" name="sparse_limit">
<input type="submit"></form>

Previous: Errors | Configuring Sparse | Next: Advanced PHP Usage