There is a detail in the way that the Seismic framework operates that makes switching the tab using script from within in the UI Builder (UIB) Tabs component a little more subtle than you might expect. There is also a major change for the Washington DC release and another quirk that comes into play when trying to control a Tabs set from within a Modal. I'll show you how to use code to switch tabs pre-W release (Vancouver) as well as how to do it within a Modal.
Use Case and Example
In this example of the behavior I am implementing the change of tabs with a button. You may need a scenario where you have to move to a previously selected tab upon form validation, or in the case of a modal you may wish to have the Tabs set always open to the first tab each time that you open the modal.
Reminder on Events and Binding to State Variables
I have to admit that even after approximately 3 years of working with UIB this one tripped me up at first. The way I set this up initially was basically correct (details to follow) with a client state parameter (CSP) of type holding the selected tab, then binding that value to the selectedTabIndex property on the tab set. Easy!
Then, when you clicked the button, the value changed and the tab changed as well. The first time. After selecting a different tab by clicking directly on it then returning to click the button nothing happened. This is because like any other data binding on the platform the control is only notified of a change when a change happens to the state parameter. Since the parameter doesn't change when clicking on the tab, the Tabs set has no idea to update itself.
NOTE: Those using a page created prior to the Washington DC release and upgraded will see both selectedTabIndex and the new selectedTab properties. In Vancouver you will only see selectedTabIndex. For this tutorial we're going to use the new string-based selectedTab, but the concept is the same for earlier versions using the index.
Basic Setup
Setup Page for Tutorial
Let's quickly set up our page and tabs for this tutorial.
1. Create a new UIB page.
2. Add a new Tabs component
3. Go to Configure > Tabs and add two more tabs, similar to this:
3. A. If using Washington DC make a note of the readable ID for each tab e.g. "tab_1", "tab_2" and "tab_3"
4. Add a new Client State Parameter (in the bottom left of the UI) call it selectedTab, type of String with a value of empty.
5. Add a button and change the label to Switch Tab.
6. Go to Events > Button clicked and add a new Update client state parameter event handler with the following parameters.
A. Client State Parameter: selectedTab
B. New value: "id=tab_2" (use the ID when you created the tab earlier)
Tab Selector
You may expect that to switch tabs you simply bind to a new value. In versions prior to Washington DC the select tab index is a simple integer. Washington DC introduces the concept of a Tab Selector. It is now a string, and that string is not simply the ID of the tab to select, but a special syntax to select a tab, similar to a query. Check out the docs for more details, but in our case we just need to the selected tab value on the Tabs set to "id=tab_name".
1. Return to the Tabs component and go to Properties > SelectedTab.
Note: If you are in Washington DC and working with an upgraded page from a prior release clear out the selectedTabIndex property. If you are on Vancouver simply bind to the selectedTabIndex property and skip the next step.
2. Use the little database icon to bind to the value of the selectedTab client state parameter set in the previous section.
Try it out
Save the page and click Preview to run it.
1. When you click the button it should switch to Tab 2. If not, work back through the previous steps and make sure that the tab name is correct and that you're binding to "id=tab_name" as expected.
2. Click on another tab, like tab 3.
Notice that it does not switch back to Tab 2. That's because when you selected tab 3 directly the CSP didn't get updated and therefore the platform has no idea that the tabs need to change. To solve that we need to set the CSP whenever the tab changes.
Set the Client State when the Tab Changes
Whenever the tab changes we want to make sure that tab is in the client state parameter. This will allow the framework to respond to changes regardless of where it originates from.
1. Return to the Tabs component and open Events > Add Event Mapping > Tab Item Selected.
2. Select Update client state parameter and set the following values:
A. Client state parameter name: selectedTab
B. New value (use database icon): CONCAT("id=", @payload.selectedTab)
3. Save the page and try it. Now when you change tabs then go back and use the button it should switch tabs.
Modals
A tab set within a modal dialog presents a subtle challenge. The Tabs set maintains its state, so when you first open the modal the tab will be on the default tab, usually the first one. If you open the modal, change tabs, close it then re-open, however, it will still be on the previously selected tab. If want it to reset you need to add an extra event to respond to the modal opening and make sure that the selected tab is reset.
1. Add a new modal to the page, choose "custom" and then go through the previous steps to recreate a Tabs set within its Body 1 container, binding to a new CSP called modalSelectedTab and bind the tab item selected event to update this value.
2. Select the modal and open Events > Add event mapping > Modal opened.
3. Choose Update client state parameter and set the following values:
A. Client State Parameter Name: modalSelectedTab
B. New Value: "id=tab_a" (Use the tab name created in the modal tab set).
Now open the tab, switch to a different tab, close the modal and re-open. It should return to the first tab!
Conclusion (and what to do in Vancouver and below)
In this article I have addressed the concepts of binding a client state parameter to change the selected tab with code. I have also covered the new "selectedTab" property in Washington DC+ and how to create a tab selector to control the tab set. If you are using the "selectedTabIndex" property in a sub-W release please use the concepts and event bindings presented here to instead bind the tab index number.
