This article describes how to add a Month Picker control to a page during the page design process. For details on how to use the Month Picker during run time, see: Using Time Pickers.
Overview
The Month Picker allows a user select a monthly time period. This is usually used to provide a time period for other components on the page, such as a chart. The component publishes the start and end of the month period for use by other components.
The following diagram shows a Month Picker component being configured:
| Start Time: | The start of the month that is initially displayed when the page first loads. This must be created as an event with a type of Datetime. You can choose a date and time using the date picker. You can choose the date and time separately, however it’s normally used to specify a time period starting from midnight. |
| End Time | The end of the time range that is initially displayed when the page first loads. This must also be created as an event with a type of Datetime. This should be no later than the end of the month specified as the start date. If this is past the end of the month from the start date, the end date is ignored and defaults to the end of the month. |
| Month | The month that is selected by default when the page first loads. This must be created as an event with a type of Number, with the number corresponding to the month. |
| Year | The year that is selected by default when the page first loads. If no year is specified, the current year is used. This must be created as an event with a type of Number. |
Tutorial
The Month Picker is a useful component that enables users to change the type of data that is returned to other components on a page.
In this tutorial, we'll look at adding a Month Picker that will change what is displayed on a chart as the user selects different months.
Let's go through this process, step-by-step.
Step by Step: Creating a Month Picker that Drives a Stacked Chart
Before you start, open a new tab in Explorer and click the “Create a New Page in Studio Mode” thumbnail. Choose the grid layout - you can adjust the rows and columns if you like but it's not important for this exercise.
If you have access to the training environment, you can follow the steps exactly as outlined here. Otherwise, you will need to adjust the configuration to suit your data.
Step 1. Add the Month Picker to the page
Drag and drop the Month Picker component onto a grid cell.
Step 2. Configure the Month Picker
The Month Picker uses events to configure all its options. In fact, you'll notice that the events all come preconfigured with event names. This is because these events are so often used, and by other components on the page, that it's often unnecessary to bother changing the names. It's best to leave the names as is, but you can change them if you want. If you do change them, you'll need to remember this for the next steps.
Step 3. Create the events
This step provides the hooks for the Month Picker to send signals to other components on the page.
- Click the Set Defaults button on the far right of the Studio toolbar.
- Create an event called "startTime" with a date set to 1 January 2014.
- Create an event called "endTime" with a date set to 31 December 2014.
- Create an event called "selectedMonth" with a number value of 1.
- Create an event called "selectedYear" with a number value of 2014.
You can create an event at any time. In creating these events, we make them available not only to the Month Picker, but also to any other components we may want to place on the page.
Step 4. Add and configure data
Month Pickers don't normally do anything by themselves - you use them to drive other components. Ultimately, we want the Month Picker to change the returned data depending on what time period the user selects. Let's add some data that we will use to return data to a chart.
- Add the AccountingAmountbyProduct dataset, and configure it as follows:
- periodEndedYear: (Event) selectedYear
- periodEndedMonth: (Event) selectedMonth
- PeriodType: (Text) Accounting
- amountType: (Text) Net
- accountMultiple: (Number) -1
- reportingLevel: (Text) AREA
- currencyCode: (Text) CAD
- accountType: (Text) RV
- entitySelectedFlag: (Text) N
- selectedHierarchyId: (Text) All
- selectedEntities: (List) FIREBAG, GARDEN, GLACIER, BADGER, KIRBY, KAYBOB
As you can see, you need a degree of familiarity with the dataset to know what the parameters mean. In this dataset, we have 2 parameters that can listen to events published by the Month Picker: periodEndedYear and periodEndedMonth. This is what ultimately causes the chart to change when the user selects different months.
Step 5. Add and configure the chart
Let's add a chart that will make use of the Month Picker. Drag and drop a Chart onto another cell on the page. Configure a stacked bar chart as follows:
- Source Data: AccountingAmountbyProduct1
- For the chart series:
- Type: Stacked Bar series
- Add 3 Bar Series, configured the first as follows:
- Y Field: (Text) OIL
- Name: (Text) Oil Sales
- Colour: (Text) #9BBB59
- Configure the 2nd bar series as follows:
- Y Field: (Text) GAS
- Name: (Text) Gas Sales
- Colour: (Text) #C0504D
- Configure the 3rd bar series as follows:
- Y Field: (Text) NGL
- Name: (Text) NGL Sales
- Colour: (Text) #8064A2
- For the X Axis:
- Field: (Text) DISPLAY_MONTH
Step 6. All done!
Congratulations! You now have a fully functioning Month Picker that drives a stacked bar chart.
- Click the preview
button on the Studio toolbar to see what your page will look like in run-time. - When the Month Picker first loads, the chart displays data for the corresponding default period.
Don't forget to save your page!