Let me start by warning you that this blog gets nerdy quick and has the potential to put you to sleep. If you don’t want to read through it and just want the solution, scroll to the bottom and I’ve got instructions on how to quickly implement this demo. In the end, you can just drop these files in a directory on your portal server and it should work. Be warned, you may miss me giving away a FREE pat on the back somewhere in this post.
When you install our Portal, there is a section within the Dashboards Menu for Calendars. We have an article in our Knowledge Base that will walk you through the process. Creating additional calendars is a little tricky and can get confusing quickly. There is another way to create a Calendar that I’d like to walk you through that may be a bit easier and offers more options (think COLORS).
I’m going to pick on Change Management in this example. If your company is using the Change Management module, more than likely there is some sort of a weekly CAB (Change Advisory Board) meeting. At the very least, they meet to discuss and approve/deny any changes in the next week. We could create a view in the Console and then promote that view to the Portal or even through our Page Builder. There is something about a calendar that makes more sense in this scenario and offers a better perspective to the CAB and Analysts when planning for changes. I’m going to break this down into 4 steps:
- Creating a New Page in the Portal
- Adding a Kendo Scheduler to the Page
- Adding Data to the Kendo Scheduler
- The fun stuff (COLORS!!!)
Create a New Page
I’m going to start off by dropping a few folders and files in the CustomSpace folder on a Portal Server (these will be included in a ZIP file). The folders are “CustomCalendar” and “views”.
We will start with the Calender.js file in the views folder. The name of this file ends up playing a part in the URL used to get to this page. We will see it in action at the end of this section. For now, let’s look at the contents of the file. The file uses JSON to define some basic information about the layout of the page and where to look for additional information. The Page Title is used to control what name shows up on the tab within the browser (Line 4). You can add several View Panels to a page to load different things and control how they layout on the page. In this example we are only loading one View Panel and it points to “CalendarViewPanel” (Line 14).
Next, we will open the viewpanels folder within the views folder. There is a file here called…you guessed it…CalenderViewPanel.js. This file is also in JSON format and contains a definition section that is essentially loading a few more files for us. You can see that it is referencing a CustomCalendar.css file and a CustomCalendar.js file (Line 5). Notice we have also set <div id=’calendarstart’> at the end of the block on Line 5. You can add an “id” attribute to any tag on a page so that you can reference it for later use. The value must be unique within an HTML document. We will circle back to this in a bit.
Lastly, we will look in the “CustomCalendar” folder to inspect these files.
CustomCalendar.css can be used to apply styling to just this page. CustomCalendar.js is used to load the CustomCalendar.html file which is what will end up containing the logic behind the Calendar widget (Line 2-3). One other thing to point out is the containerId (Line 4) which lines up with the id we just defined in the View Panel (“calendarstart”).
For now, we just want to get our Calendar HTML page to show. The CustomCalendar.html file contains some basic html that is loading on the page. One key thing to point out here is Line 9 that is setting “id=mycalendar”. This is the same functionality we just used. It is just a placeholder on the page that allows us to reference later.
So here is what we have so far.
At this point you should be able to go to the following URL to load this calendar: http://{yourportalserver}/view/Calendar. The important thing here is that it will look in that views folder for whatever comes after view in the URL. So, in this example it looks for a file called Calendar.js. If you changed the URL to http://{yourportalserver}/view/thisisboring, it would look for a file called thisisboring.js in the CustomSpace\views\ directory. This is the linear progression of how it is loading:
Calendar.js –> CalendarViewPanel.js –> CustomCalendar.js –> CustomCalendar.html
One thing I skipped is that I’ve also added a New Link under Navigation Settings that points to this URL so it can be clicked from the Navigation Node.
Adding a Kendo Scheduler to the Page
So we have our page loading when the Steve Calendar navigation node is clicked. Next we want to actually add a calendar onto the page. Our portal uses Kendo UI widgets to load certain things on pages. All of the Grids you see for My Work, My Requests, Team Work are loading the data into a Kendo Grid. The Dashboards use different variations of the Kendo Chart. For this demo, we will be adding a Kendo Scheduler.
You have a bunch of different configuration options for the Scheduler widget. I’m just going to add a few basic things here so we don’t over complicate it. I’ve added new content on Lines 9-28.
The first thing I did was add a script tag (Line 9) to let the page know that we will be loading some JavaScript on the page. Line 11 is just telling it that when the page has loaded and is ready, run the code within the function. Line 12 is used to set a variable for the URL of the portal server. This helps when you are moving this from environment to environment where the URL may change. Line 13 is calling a function called loadCalendar and sending it the variable we just set. Once the loadCalendar function is called, it adds a kendoScheduler widget on the page right after the “mycalendar” id we set earlier (Line 16). As you can see all I am doing is telling it what today’s date is and what views I want to see in the widget.
Just like that you already have a calendar loading in the portal.
Adding data to the Kendo Scheduler
Now that we have a calendar loading on the page we want to have it load our Change Requests. When gathering data to be used in a view, you will be using one of the Portal API’s to get that information. There are 2 options to get the dataset, the GetProjectionByCriteria API and the GetDashboardQueryData API. The GetDashboardQueryData API is what is used when you create a SQL Table or Chart Widget in the Page Builder in the Portal. This API queries the ServiceManagement directly versus the GetProjectionByCriteria API which queries the Service Manger SDK. The GetDashboardQueryData API will load your dataset a LOT quicker and is much easier to understand. I’m going to use that API in this example but must give the caveat that it isn’t made available via our API documentation. This means that it could change at some point. I really don’t think it will because it is the driving force behind the Page Builder. Worst case the name would change or something minor that would require you to update a portion of what I’m about to walk through.
All you need to do is determine the correct SQL Query that will bring back your dataset. In this case I just want all Change Requests that are In Progress.
The GetDashboardQueryData API needs your SQL Query to be encoded in a format that it understands. Just search anywhere online for “url encoder” and just copy and paste your Query. The output should looks something like this:
Back to the CustomCalendar.html file. I’ve added a block of code to the beginning of the script that sets this formatted query to a variable and then sends it to the API (Line 15 and 17). Once it gets the results, it now calls the loadCalendar function and also sends the data it got back (Line 22).
Now in the loadCalendar function we want to receive this data and use it for our datasource (Line 41 – 55). Line 43 is where we actually pass in our data. The schema (Line 44-54) is a predefined set of fields that you map to your data. By default it will use the title as the name of the item on the calendar and then start and end for the date range.
For more information on your options around the schema and the scheduler in general go to the following site: http://docs.telerik.com/kendo-ui/api/javascript/ui/scheduler
After adding this logic this is what we have now:
With this in place all you really need is to get your query correct and then update that query variable so it brings in what you want. In this example we are only bringing in Change Requests but you could easily write a query that brings in different types of work items and shows them on the calendar.
One quick note, I added some additional logic that allows you to click on the CR and it will open it in a new window. Line 57-66 adds a click event to the scheduler that when clicked will call the openWI function (Line 67-69).
Adding COLOR to the Kendo Scheduler
Alright so I know this is the only reason you are even reading this. Colors make the calendar look sooooo much better.
All I have to do is add a resources section and tell it that the risk field will determine the color. You just have to make sure that the values you set are actually coming through (The Risk Enumeration out of the box contains Low, Medium, High. If you have changed these, you would need to change the values to your new ones). You can change the colors to whatever you like.
I also added some HTML at the beginning of the file to load a color key on the page.
And here is what it should look like:
Most of the logic you need for a custom Calendar is already included in these files. All you would really need to change is your SQL Query and then just update which field will drive the colors and what color you want. There is also a lot of things you do within the Calendar that I didn’t talk through. Once again the information can be found here: http://docs.telerik.com/kendo-ui/api/javascript/ui/scheduler
The files are available here: https://community.cireson.com/discussion/1826/calendar-colors-in-the-cireson-portal
You just need to unzip the file and then copy the folders into your CustomSpace directory on your Portal Server. Go to the following URL to load the calendar: http://{yourportalserver}/view/Calendar
NOTE: If you just skipped to the bottom, this assumes that you have Change Requests with Risk Values of Low, Medium, High.
