Hi all, I recently created a page that let users search a datasource via a form and return the results. There were a few steps, and some undocumented parts that I've put into the following tutorial:
How to create dynamic content using a CSV datasource
The purpose of this tutorial is to provide the details for you to generate a dynamic content area using a CSV datasource. By dynamic I mean the ability to isolate individual shadow assets and present these, exclusive of other assets in the datasource.
For example, say we have a CSV file containing a list of books you have available in your store. In the CSV you have a number of columns that store information about each book – Book title, Publish year, Publisher, Author, ISBN.
With this data we will create two different ways to generate dynamic content based on user interaction, in our example we’ll use a form to search for content in one of the columns.
Prepare and upload the CSV
- First prepare your CSV file ensuring you have clearly defined columns. Also check to make sure you don’t have extra spaces in the rows and columns. Extra spacing will cause PHP errors in Matrix when you upload the CSV file.
- Upload the CSV into Matrix using the CSV datasource
- Take note of the Available Keywords For the Data Source Record Set Asset in the Shadow Asset Name section of the details screen. You’ll need them later. For reference we want the following Keywords
- %ds__book_title%
- %ds__publish_year%
- %ds__publisher%
- %ds__author%
- %ds_isbn%
Create and prepare an Asset Listing Page
- Create a new Asset Listing Page asset
- In the Asset Selection section in the details screen, choose Data Source Record Set for the Asset Types to List.
- In the Asset Locations section on the details screen, choose the CSV datasource for the Root Nodes.
Prepare the CSV datasource to accept dynamic inputs
Before we follow these steps a little explanation of what we’re going to do here. In order to create dynamic content, what we’re essentially doing is filtering the CSV file and returning the values via the asset listing asset.
There are two parts that allow us to filter the CSV, first we need to create a filter with a range of conditions; then we need to create a dynamic input, that allows us to pass the value to the filter.
Creating the Record Filter
For our first example we want to create a form that searches the Publish year. To do this we’ll create the condition that allows us to search just this column.
- From the context menu of the CSV datasource select Record Filter
- Create a new condition by entering a name in the Add New Condition text input. This input needs to match the name of the datasource record set field name. So for our example, we’ll call ours publish_year. Click commit.
- Now set the remaining conditions:
- Value to match: %%year_search_value%%
- Match type: String match – Exact
- Match case: No
- Turn the filter on by adjusting the Filter Options section to:
- Filter status: On
- Logical Grouping: Match on ONE condition
- Filter Mode: Return the records matching the given conditions
You’ll notice the double %% signs being used in the Match type. This value is the name we’re going to use in our Dynamic Input, as per the notice at the bottom of the section:
Note: Dynamic variables added in "Dynamic Inputs" screen can be used here in the "Value to Match" field in the form %%VARIABLENAME%%.
Creating the Dynamic Input
Here we’ll create a dynamic input that grabs the value from our search form and store the value in the variable name we specified in the Record Filter.
- From the context menu of the CSV datasource select Dynamic Inputs
- In the Add New Variables Below text field in the Dynamic Variables section, add the variable name year_search_value and commit the change
- In the Data Mappings section, choose the parameter Variable: year_search_value and in the next selection list choose Set Variable, as we want to set the variable ‘year_serach_value’ with a value. Click commit to make the change.
- After the commit you’ll notice there is a blank field in the Data Mappings section that asks to Set Value. Here we’re going to use a Global Keyword Replacement to pull the value based on a URL parameter we’ll add to our form and link later. For now, enter the value %globals_get_year_query%
Building a search form
In this section we’ll create a form that asks generates a list of books published on a date given by the user.
- First create a standard page and create a form using the following HTML:
<form action=”./?a=1234” method="get">
<div class="form-actions">
<label for="year_query">Enter a year to search for:
<input type="text" name="year_query" /></label>
<button type="submit">Search</button>
</div>
</form>
You’ll notice we set the form action to another asset number. The number you enter here should be the number of the Asset Listing Page we created earlier. When we submit our form the value entered in the input named year_query will be appended to the URL, for example ?year_query=2012
- Next we need to setup the Asset Listing Page, so that the book information stored in the CSV is presented on the page. For our application we want to present all of our data in a table.
First in the Page Contents of our Asset listing Page we’ll create the table HTML. Enter:
<table>
<tr>
<td>Publish year</td>
<td>Title</td>
<td>Author</td>
<td>Publisher</td>
<td>ISBN</td>
</td>
%asset_listing%
</table>
- Now we need to put the datasource values into the table row. This is where we’ll need to reuse the datasource keywords we identified after uploading the CSV.
<tr>
<td>%ds__publish_year%</td>
<td>% ds__book_title %</td>
<td>% ds__author %</td>
<td>% ds__publisher %</td>
<td>% ds_isbn %</td>
</td>
That’s pretty much it. Now when we search for a year using our form, we’ll append the year_query variable tour the URL, which we’ll grab from the Global Keyword Replacement as a Dynamic Input which is then used to filter our results, returning only the book information that matches the publish date entered.
Returning results in alphabetical order
If you want to return the books in alphabetical order you can do so by making a small adjustment to the CSV Datasource. This change will mean that the results will always return in alphabetical order for the Asset Listing Page used. Otherwise, there is no other way to order CSV datasource records other than using a JavaScript solution.
- Open the Details screen of your CSV datasource
- In the section Shadow Asset Name enter the value %ds__book_title% in the Enter The Name Of The Shadow Assets text input
- Head over to your Asset Page Listing and open the Asset Sorting page
- On this page adjust the default is to sort by Name, so unless you’ve made a change the results should now be sorted alphabetically. Otherwise in the Default Sorting section, set the Default Sort-by Option to Name or Short Name
After thoughts
This method could easily be applied to search a second table in a faceted style list, where values from one table can be used to filter the results of a second table. For this we could use a standard Asset Page Listing and pull out the values, create a list of links and append a value to the link.
For example, <a href=”./?a=anotherassetlisting?query_var=%ds__first_table_var%”>Show these results</a>
