- Using your favorite browser, navigate to the PCI demo homepage. If you installed the PCI locally and chose the default set up, that URL would be http://localhost:8080. If you changed any of the defaults, or installed to a different domain or port that URL will be slightly different. If you have any trouble finding the PCI home page, consult the Getting Started with the BI Platform documentation.
- From the PCI home page upper right corner, select Go | Solutions | Reporting Samples | Dependent Parameter Examples .
- From this page, select Dynamic Dependent Parameter Page. You should see a prompt for parameters, similar to the following screenshot:
Open the dep-param Solution in the Design Studio
- Open the Pentaho Design Studio. From the main menu, choose File | New Project | Simple Project.
- The wizard walks you through setting up your project. When prompted for the location of your project files, uncheck the "use default" checkbox, and enter the path to the PCI sample solutions directory, usually located at <pentaho-pci-root>/pentaho-solutions. Name your project something you like; I named mine param_solutions.
- Click the Finish button, and you are all set. You can now work with the solution files that we installed in the previous step.
- Using the Java Perspective, and the Navigator view, navigate to the dep-param folder, under <solution-root>\samples\reporting\dep-param. You should see the following files:
Explaining the dep-param Files
Before we delve into the technical detail of the action sequences, let me first explain the purpose of each solution file, to help give you a better perspective of how this solution works as a whole.
There are several files in our dep-param directory, but the only ones that contribute to the workings of this feature (and that we will concern ourselves with here) are DependentParameterExample.xaction, PositionTitlesForDept.xaction, and DependentParameterTemplate.html. The rest of the files in the directory (if you aren't already familiar with Pentaho solutions) support externalizing your solution's strings for localization, and support the appearance of the solution within the PCI demo. To learn more about these support files in detail, you can browse some of our early tech tips, as well as the Internationalization documentation.
The DependentParameterExample.xaction is the main action sequence. In this action sequence, we set up the Secure Filter Component that will request a region and department from the user. Once the user has chosen the department, we will submit a request to the server to get the list of position titles for that department. Retrieving the department specific position titles happens via the PositionTitlesForDept.xaction. I will get in to details on how the second action sequence gets executed in a minute, but for right now its useful to understand that there is no reloading of the page or the Secure Filter Component when we retrieve the position titles,as that function is an AJAX call.
The way we enable AJAX and the dynamic loading of the dependent parameter, position title, is by using a custom DHTML file as the template for the page that the Secure Filter Component (in our first action sequence) generates. That file is DependentParameterTemplate.html.
That's alot to digest in a very compressed fashion, so let's walk through the action sequences and the DHTML template in the Design Studio. Step by step, we will put the bits together and help you understand how Mike came up with this solution.
The DependentParameterExample Action Sequence
The DependentParameterExample action sequence controls our solution. Let's dig in and see what's in there.
- Open the DependentParameterExample.xaction in the Pentaho Design Studio. You can do this by navigating to the dep-param directory in our solution's project, and double-clicking on the DependentParameterExample.xaction file.
- In the Process Inputs box at the top of the page, you should see an inputs folder. Expand that folder using the plus sign next to the folder. In the inputs folder are the six inputs needed for our simple solution. We need three String inputs to hold the three selections that the user will specify: REGION, DEPARTMENT and POSITIONTITLE. Then we also need a String-list input to hold the available values for each of the three selections: that would be the REGION_FILTER, DEPARTMENT_FILTER and POSITIONTITLE_FILTER.
- Click on the REGION_FILTER String-list input. Notice that the Default Value checkbox is checked, and there are 4 hard coded values in the defaults list. We have hard coded the region values for the REGION selection, ONLY for the sake of simplicity. We could have used a SQL Lookup Rule to populate the REGION_FILTER values, but instead wanted to keep the example as simple as possible.
- The DEPARTMENT_FILTER values are also hard coded, in order to keep things simple. Click the DEPARTMENT_FILTER String-list input, and you will see it too has several default values.
- We start the action sequence by running a query to populate the POSITIONTITLE_FILTER String-list. Click on the first action in the Process Actions box, labeled "Perform SQL Query". You can examine the details of this action, and see that the query is retrieving all position titles from the database, and the resultset is being stored in the POSITIONTITLE_FILTER input.