Sometimes when making a view it may be useful to not include every element matching a pattern but only ones certain ones. This can be done statically in the pattern builder itself (via the property "is" or "in" filters) but often times a view builder might want these values to be changeable without having to edit the pattern each time. This is where parameters come in.
Setting a parameter in the the pattern builder allows a view builder to construct a view where these parameters can be used to filter the information being displayed. This can be useful if you want to highlight particular aspects of the data or if you want to set up a view that allows a user to filter down to an area of interest. It also allows for creating a view tailored to the individual viewing it using a custom "Me" parameter.
This guide will do through the basics of setting up a parameter in the pattern, using it in the view itself, and exposing it to users who only have view access. Parameters can also be set in a view via the URL query params, but that is an advanced topic for another article.
This article assumes that you are already familiar with the basics of creating a view. If not, we suggest starting with this article on the topic.
Setting a Parameter in the Pattern Builder
Parameters can be added to a view in the pattern builder using the "+ Add Parameter" button just above the default Query box. You must add a parameter here before it's available to use in the view.
That will bring up a small window asking you for a name and the element type of your parameter. Any name can be used; however, best practice is to use the element type name converted to lower case and, if more than one word, converted to camelCase or underscore_separated convention and removing any special characters. The element type dropdown is searchable if you have many element types in your city.
Once you click "Submit" the parameter is added and usable in queries. Parameters appear in their own section at the very bottom of the data source drop down. They are also searchable just like the other element types in the drop down. You can use them the same why you would use any element type in a query (this is one reason it is best practice to give the parameter a name similar to the element type it is for).
A notable difference once you create a parameterized view is that when you first visualize it it will likely be empty (unless you add additional queries without parameters). This is because it will only show elements of the query that match any selected parameters, of which there will be none to start.
The parameter selector is in the upper left hand side of the screen. By default it is only accessible from within view editing mode. You must begin typing to see the options.
If using a parameter for City Users you can also enter the keyword "Me" as a parameter. This will alway be the currently logged in user of the view (note: this will not work for public views, it will only work for logged in users).
As parameters are selected or removed the view will update to include the items chosen.
If the view is saved with parameters selected than those selections will be saved as well. If you do not wish for the view to load with parameters already selected, make sure to clear these before saving.
By default, the parameter selection box is not available while in viewer mode (and thus not available to non-admins). This can be particularly useful if you are creating a user-tailored view via the "Me" parameter and do not wish users to be able to change it, thereby seeing other users information.
If you wish your users to be able to see and change the parameter selections you can enable it under "Controls" by enabling the "Set Parameters" control (from the setting cog near the top left).
As mentioned earlier, these parameters can also be set by including element uuids in the URL query params. Another guide will be made in the future discussing this in greater detail, but you can inspect the URL of a view that was saved with parameters if you want to get started on it. The general format is to add ?param.param_name[]=<list of uuids> to the URL.
General best practices are to either A) leave the parameter box hidden and simply save the view with the parameter selection(s) you wish to highlight or B) show the parameter box and save the view with all choices pre-populated, allowing users of the view to filter the selections.
If you have any questions about the process or encounter any issues, you can always use the blue help button in the lower right corner of your screen to open a ticket with the Exaptive Support Team.