Included with Service Portal are a variety of different CSS utility classes loosely based on some of Bootstraps utility classes. For many of the classes below, you will see a format similar to: "m-t-lg", this stands for "margin top large". As I'm sure you can guess, there is also a classes for bottom, left, right, small (sm), medium (md), etc. and all the various combinations thereof. This allows you to easily add consistent margins, padding, colors, etc. without creating custom styles within the widget. Here is a list we've compiled of some of the most common utility classes: Padding: wrapper, wrapper-xs, wrapper-sm, wrapper-md, wrapper-lg, wrapper-xl Horizontal Padding: padder, padder-xs, padder-md, padder-lg, padder-xl Vertical Padding: padder-v, padder-v-md, padder-v-lg, padder-v-xl Top Padding: padder-t, padding-top-s, padding-top-m, padding-top-lg, padder-t-lg, padder-t-xl Right Padding: pad-right Bottom Padding: padder-b-none, padder-b, padder-b-md, padder-b-lg, padder-b-xl Left Padding: N/A Top Margin: m-t, m-t-none, m-t-xxs, m-t-xs, m-t-sm, m-t-lg, m-t-xl, m-t-n-xs, m-t-n-lg Right Margin: m-r, m-r-none, m-r-xs, m-r-sm, m-r-lg, m-r-n Bottom Margin: m-b, m-b-none, m-b-xs, m-b-sm, m-b-lg, m-b-xl, m-b-n Left Margin: m-l, m-l-none, m-l-xs, m-l-sm, m-l-lg, m-l-n Text Color: text-muted, text-primary, text-success, text-info, text-warning, text-danger Background Color: bg-primary, bg-success, bg-info, bg-warning, bg-danger Float Elements pull-left - Floats an element to the left pull-right - Floats an element to the right Clearing Floats clearfix - Clears floats Display & Margin center-block - Sets an element to display:block with margin-right:auto and margin-left:auto Visibility show - Forces an element to be shown (display:block) hidden - Forces an element to be hidden (display:none) invisible - Forces an element to be invisible (visibility:hidden). Will take up space on page even though it is invisible sr-only - Hides an element to all devices except screen readers sr-only-focusable - Combine with "sr-only" to show the element again when it is focused (e.g. by a keyboard-only user) text-hide - Helps replace an element's text content with a background image close - Indicates a close icon caret - Indicates dropdown functionality (will reverse automatically in dropup menus) Hide visible-xs, visible-sm, visible-md, visible-lg Show hidden-xs, hidden-sm, hidden-md, hidden-lg For more details on CSS in Service Portal, you can check out the unofficial documentation on Github: https://github.com/service-portal/documentation/blob/master/documentation/css.md#page
New Features of Istanbul
Istanbul is the next release of ServiceNow and with it many new fixes and additions are being included for ServicePortal, including more than 200 bug fixes, localization improvements, and widget editor improvements. But the most exciting thing in Istanbul are some of the new Service Portal features: Search Sources The search has been greatly improved with the new "search sources" feature which adds greater flexibility and extensibility to the search widgets. A search source will describe the behavior and source data Ability to configure the behavior of search in portals without having to write, edit or clone any widgets SC Shopping Cart The shopping cart has been one of the most highly anticipated new features, and greatly enhances the shopping capabilities of the Service Catalog in Service Portal. Support for ordering quantities of items (where permitted) Adding ordered items to a cart (stored in the sc_cart table) Setting "Requested For" field and order details Ability to edit the variables of a cart item after it has been added to the cart Support for saved carts with the ability for later use Respects most Service Catalog properties Omit cart Omit quantity Catalog variable 2-column layouts This is another huge improvement over Helsinki, adding support for 2-column layouts for variables in Service Catalog. Improvements to the Widget Editor New hotkey bindings Dependencies are able to be viewed and edited alongside a widget Localization Improvements All strings have been translated Extended translation to the widget client script Use of ${My key} Widget Options Schema Improvements Declare parameters for widget Users can now have hints Default values are able to be provided Bug Fixes Istanbul also includes some notable bug fixes, including: The variables max_length being inconsistent with normal Catalog UI Certain $sp api's don't work in scoped applications Order guide variables don't cascade Cannot redirect to the correct location after login Help and Tooltips don't appear on forms Branding editor unable to load without a default portal specified Unable to hide "Label" variables in Service Catalog using UI Policy Actions Service catalog doesn't nest categories - page takes long time to show when there are a lot of categories Forms not displaying -- NONE -- in dependent choice list field Simple support for catalog item variable 2-column layouts
Using Events to Communicate Between Widgets
Following the principle of “separation of concerns”, it is good practice for your portal or application to be made up of self contained functional components, also known as widgets in Service Portal. However sometimes these widgets need to communicate with one another. Thanks to Angular.js this can be accomplished through the use of $broadcast, $emit, and $on methods. $broadcast and $emit allow you to raise an event in your widget. The difference between $broadcast and $emit is that the former sends the event downwards from parent to child controllers, while $emit sends an event upwards from the current controller to all of its parent controllers. Both methods are available on $scope and $rootScope. You can subscribe to an event using the “$on” event handler. In this example we will create two widgets that interact using $broadcast and $on. Widget #1: Create two buttons that upon click, will $broadcast an event called "customEvent" and pass an object. HTML: [crayon-6623cb46a8a34053869176/] Client Script: [crayon-6623cb46a8a46598110985/] Widget #2: Listen for the "customEvent" event, and when triggered, the callback function will update the text. HTML: [crayon-6623cb46a8a4a206269420/] Client Script: [crayon-6623cb46a8a4e911390185/] The final results should look like this:
Understanding Instances
Widget Instances are a vital component of Service Portal, and although at first glance they seem simple, they can be quite powerful when utilized correctly. In simple terms, the widget instance record stores the location of the widget (which column) and the context needed for it to render. The context of the widget is comprised of the fields on the instance table as well as the "Additional options" field in JSON format. The additional options get generated based on the fields defined in the "Options Schema" on the widget, documented here. Each widget defines which instance table it will use along with which fields from that table. To set the "table" and "fields" variables on the widget, you must open the widget record in the standard ServiceNow UI form. See the example below from the "Icon Link" widget which uses the "sp_instance_link" table. The following is the out-of-box instance tables available: Instance (sp_instance) Base instance table with the following fields: color, css, glyph, short_description, size, title, url Instance of Carousel (sp_instance_carousel) Instance primarily used by the carousel widget, has a related list of slides Instance of Simple List (sp_instance_vlist) Used by list widgets such as "Simple List" and "Unordered List" and contain fields specific to setting Tables and Filters Instance with Link (sp_instance_link) Used for creating widgets that act as hyperlinks, e.g. "Icon Link", with fields such as URL and references to commonly used tables Instance with Menu (sp_instance_menu) This is the instance used by the Header Menu (referenced from the Portal), but can also be used for any widget displaying a menu. It has a "Menu Items" related list. Instance with Table (sp_instance_table) The instances behind the Data Table and Count widgets, with fields for setting the Table and Filter You can also create your own Widget Instance table by extending "sp_instance" and referencing the new table and fields in a widget. If the table referenced on the widget is changed, it will NOT automatically update the existing instances, so you will need to remove the old instances and generate the new instances via the Service Portal Designer. Once completed, you will now see your custom instance fields when you view the widget Instance Options (CTRL + Click > Instance Options).
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-6623cb46ac9a4971922408/] Client Script: [crayon-6623cb46ac9b3528687640/] 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-6623cb46ae499047190011/] HTML: [crayon-6623cb46ae4a8408331360/] 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-6623cb46b12c8505820204/] 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-6623cb46b12d7026669462/] 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
Founder of 