Embedding widgets in Service Catalog

In Service Catalog you have the ability to embed a UI Macro as a variable in your catalog items or record producers. UI Macros are based on Jelly and as such they will not render in Service Portal. To work around this, you can now embed a widget for your UI Macro variables when displaying your catalog in Service Portal. In this example, we're going to create three variables, and make the third variable a widget that will display the sum of the other variables. Create a catalog item with the following variables: Single Line Text: "value1" Single Line Text: "value2" Macro: "results" On the "results" variable record, you will see a "Default Value" tab, with a reference to the Widget. Create and select a new widget called "Embedded Results", and use the following values: HTML: [crayon-5dac41c9788cb997043421/] Client Script: [crayon-5dac41c9788d3353499194/] Now when you view this catalog item in the portal, the embedded widget will display the results of the two variables: Note, that the "field.change" event fires when the field loses focus, so you will have to tab or click out of the field to see the results.  

Using SCSS (SASS) Variables in Widgets

An issue I have come across in the past is keeping track of all the small CSS color changes etc. Fortunately, Service Portal supports the use of SCSS variables in the widget CSS. For example, instead of using CSS to define a color in every widget, set the dynamic Bootstrap variables in your Service Portal theme. You can also create your own custom variables to use in specific projects; i.e. $favorite-color. Here is an example of what it would look like in the Widget CSS: Now when a color needs to be changed across multiple widgets, you can change it in a single place. Service Portal also supports other SCSS features such as the use of Nesting, Mixins, and Operators. Note: The Service Portal SCSS implementation is a subset of the full SASS specification. To view a full list of default Bootstrap variables that you can customize, visit this link. If you would like to explore more, you can view the official ServiceNow documentation.

Modal Windows in Service Portal

Modal windows in Service Portal are based on the BootstrapUI directives. For further documentation see: https://angular-ui.github.io/bootstrap/#/modal Below is a simple example of how to open up a modal window: Controller: [crayon-5dac41c97a36a553943404/] HTML: [crayon-5dac41c97a373906778908/] Notes: Make sure the $uibModal service and $scope is included in the controller. In this example the modal template is just included in the HTML, but you could also set the "templateURL" property to an ng-template associated with this widget. You can manually pass in the scope to the template using the "scope" property.

Reference Fields with the snRecordPicker Directive

One of the very powerful directives available in Service Portal that we will be covering today is the snRecordPicker. This directive generates a field very similar to a reference field in the platform. This is very useful when creating custom widgets that will be interacting with tables and records in ServiceNow. The Directive: [crayon-5dac41c97ccc7426772915/] It supports the following properties: Property Description field a JavaScript object consisting of "displayValue", "value" and "name" table the table to pull records from default-query the query to apply to the table display-field (or display-fields) the display field value-field the value field (usually sys_id) search-fields the fields to search page-size number of records to display in dropdown   To use the snRecordPicker you will also need to create the "field" object in your controller as well as listen for the "field.change" event. The Controller: [crayon-5dac41c97cccf790088276/] The Widget: I've created a sample address picker widget that allows the user to select a location, and then retrieves the record from the server and populates several other fields with the information. The widget is available for download here: https://serviceportal.io/downloads/snrecordpicker-example/

Unofficial Service Portal Documentation Available

This week the Service Portal team has released it's own 'unofficial' documentation which covers a lot of the major topics that were not included in the official documentation. This github repo is being updated regularly so stay tuned for docs regarding the various API's and architecture around portals, themes, pages, and widgets. So if you haven't yet checked it out, head over to the Github account and check out the docs: https://github.com/service-portal/documentation

Service Portal in Geneva Overview

Service Portal was released as an opt-in technology preview in Geneva, but up until now not much has been posted about it. Over the next few weeks and leading up to Helsinki, I will be doing a series of posts with some basic information on the Service Portal in Geneva to help prepare you guys for the full release. NOTE: A lot is changing between Geneva and Helsinki. Any information provided will likely change by the time Helsinki is released. Service Portal is built with Angular.js and Bootstrap, but the real power is in the fact that it sits on top of ServiceNow's powerful server side scripting and GlideRecord. This makes for a very powerful combination that can integrate with any application or data across the platform. The 4 primary components of Service Portal is Portals, Themes, Pages, and Widgets. In this post I will provide a quick overview of each. Portals The portal record is what ties it all together. The portal is very similar to "sites" of CMS in that it has a URL suffix and a reference to theme. Themes Unlike themes in CMS, themes in Service Portal are not just limited to stylesheets. A theme is comprised of a header and footer (which are really just widgets), CSS variables (similar to LESS or SASS but with a slightly different syntax), CSS Includes, and JS Includes. Pages A page is made up of a layout which is comprised of containers, rows, and columns (based on the Bootstrap grid) which then reference widgets. The reference from a column to the widget is through a M2M table called "rectangle". Containers can be either fixed or fluid width and contain rows Rows only function is to contain columns Columns is where the responsiveness of the grid is defined. A column sets the size (out of 12) that it will occupy at various resolutions (mobile, tablet, desktop, large desktop). Rectangle has two functions: associate a widget with a column and also store the meta data for the instance of the widget. For example a "Carousel" widget could store "slides" on the rectangle record. Because the meta data for each widget might be different, the rectangle table can also be extended by additional tables. To see an example of how this all ties together, see the following diagram: Widgets Widgets is where the HTML and server & client side logic lives. All content on a page lives inside a widget. The properties of a widget are: HTML - the template for the widget JSON Data Producer - server side JavaScript evaluated through Rhino Client Script - the controller for the widget Data Table - the rectangle table the widget uses for storing meta data Fields - the fields on the rectangle table the widget uses Widgets use Angular.js for handling data bindings between the controller (client script) and view (HTML). Also any output from the server side JavaScript (JSON Data Producer) is also automatically available on scope. One of the most impressive features of a widget is how a controller can communicate with the server side. To see a good example of this, consider the following example widget, the Data Table. The important part to note is how the view has ng-click="go()" which is a call to a method on the controller, which then makes a call to the server side, fetches and returns the content to the controller which then updates the scope in view. This is amazing, it's a mini application all inside a widget with both server side fetching of data and client side logic. That's all I'm going to cover in this post, but hopefully that gives you guys a quick taste for what was in Geneva and the even more exciting full release of Service Portal that is coming in Helsinki. If you have any questions, please post them in the comments below.