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).
Creating an Angular Directive in Service Portal
Directives are one of the many important components available in Service Portal thanks to Angular.js. You've probably already used many of Angular's built-in directives without knowing it, such as: ng-repeat, ng-model or ng-class. But did you know you can also develop and use your own directives in your Service Portal widgets? To illustrate a very basic example, let's navigate to the "Angular Providers" module, and start by creating a new record with the following: Name: "spButton" Type: "Directive" Client Script: [crayon-66289cd97f0d4633118904/] To use your Angular Provider you will need to associate it with a widget by linking the two together using the "Angular Providers" related list on the widget form. Now you can use the directive within any of the HTML of that widget. For example: [crayon-66289cd97f0e4141767609/] Note: The name of the directive is camel-case "spButton," however when used in HTML, it needs to be hyphenated (e.g. spButton -> sp-button). Now when that widget is rendered, you will see the following button any time that directive is used: When this button is pressed, it will bring up an alert with the message, "Hello World".
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-66289cd980821600438669/] Client Script: [crayon-66289cd98082f342823593/] 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.
Service Portal Developers Wanted!!!
We're hiring! NewRocket is seeking an experienced front-end web developer who is an expert in Javascript, HTML5 and CSS3. We're passionate about creating amazing user experiences for self-service portals and custom applications on the ServiceNow platform. If you have a passion for pushing the boundaries of design and development, then we invite you to help us continue our mission. The selected candidate can expect to work with a talented team of developers and designers who are creating best of class mobile and web applications for some of the top companies in the world. This is an in-house position at our offices in Vista, CA. What You’ll Do: Create mobile and web applications based on site maps, wireframes and visual designs using standards/compliant JavaScript, HTML5 and CSS3 Participate in design review and client requirements sessions Collaborate with engagement managers and other developers to understand, estimate, prioritize and implement requests for development and maintenance Requirements: Minimum of 3-5 years front-end web development experience Proven, thorough knowledge of JavaScript, HTML5, CSS3, cross-browser compatibility issues, Adobe Photoshop, CSS grids & frameworks Ability to write JavaScript from scratch Experience with JavaScript frameworks such as Angular.js, jQuery, React.js Expert in Responsive Web Design To apply, please email us your resume and portfolio to: careers@newrocket.com
Widget Options Schema & Instance Options
One of the very powerful features of the Service Portal is the "Widget Options Schema" which enables developers to create a set of dynamic options on the widget. This allows for the widget to pull dynamic data from the instance without needing to modify the actual form of the instance. You can define the options schema by either: In the portal, hold [CTRL] + right click on the widget, and select "Widget Options Schema" In the Widget Editor, click the hamburger menu and select "Edit options schema" In the options schema modal, you can create the options by clicking the "+" button and setting the field name, label, and field type. The following types are currently supported: String Boolean Integer Reference Choice Field_name Field_list Once the schema has been defined, you can set the values to be used on the instance by holding down [CTRL] and right clicking the widget in the portal and selecting "Instance Options". Once the Instance Options have been set, you can now access the option values using the "options" object in the widget, which is automatically made available in the Server Script, Client Controller, and HTML. See the following examples: Client Controller: [crayon-66289cd982d78268339896/] Server Script: [crayon-66289cd982d8c633668200/] HTML: [crayon-66289cd982d90591711455/] A good example of this could be as simple as a Title Widget where now the widget can be used all throughout your portal, but the title is different each time it is used since the title is being pulled from the instance. This allows your widgets to be very configurable and reusable. I highly suggest you start using it with your portals and custom widgets today.
Using Custom Fonts In Service Portal
A question that I get asked a lot is how to use custom fonts in Service Portal. Here are the three primary ways: Option 1: The easiest option is through Google Fonts. Select the Google font you want to use. Copy the font's style sheet URL. Go to your theme and add a new CSS Include. Make sure the "Source" is selected to URL and then paste the CSS URL. Click save. Now you can reference the font in your CSS. [crayon-66289cd985553927228670/] Option 2: You'll need to encode your fonts using base64 and then include them in the CSS Includes of your theme. You can use this free tool by Transfonter: transfonter.org. Use the "expert" option, then you will see an option for base64 encoding in the CSS section. Select "Base64 Encode." Once exported, add the generated code as a CSS include on your theme. For more information see: Learn how to create custom CSS in your theme here. Option 3: Another approach is to upload your font files as attachments to the CSS Includes record and then reference them with "sys_attachment.do?" and passing in the sys_id as a parameter. See the following example: For additional information on CSS fonts, here's an article that I have found to be very helpful. If you find this useful, let me know in the comments below.
Shopping Cart Available for Service Portal
We have been hard at work developing tons of new Widget functionality, and as some of you noticed in the recent "Gothenburg Theme" video, that we have developed the shopping cart functionality that has been missing from Service Portal. The good news is that we have now released this as an update set that can be applied to any portal. The cart includes the following functionality: Multiple quantity support for both "Buy Now" and "Add to Cart" Cart preview dropdown in the theme header Customizable URL's for "continue shopping" and "successful order" Ability to save and load a previously saved cart Order on behalf of another user Generate "Deliver to" from requested for users location Many "Instance Options" to customize the widgets Mobile cart icon when viewed on mobile devices Check out some of the screen captures below. If anyone is interested, please email us at info@newrocket.com for more information and pricing.
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-66289cd9884f5235125104/] HTML: [crayon-66289cd988502570989312/] 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.
Founder of 