` will be rendered as HTML. 24 | 25 | So, for example, suppose you have a Service Catalog variable with it's Question field written as this: 26 | 27 | ``` HTML 28 |
29 | For remote employees:
30 | Please go to CDW to order headsets, USBs, etc.
31 | CDW Link 32 |
33 | 34 | ``` 35 | 36 | That field will be rendered like this on the Service Catalog page: 37 |  38 | -------------------------------------------------------------------------------- /documentation/service_portal.md: -------------------------------------------------------------------------------- 1 | # Service Portal 2 | Service Portal contains of two parts: 3 | 4 | - *Framework*: a set of APIs, [Angular](https://angularjs.org/) services, directives and tools that help to build portals. 5 | 6 |  7 | 8 | - [*Portals*](portal.md): a group of pages linked by their `page id`. For example: `[your instance]/sp` is the Default Service Portal. 9 | 10 |  11 | 12 | ***Learn more:*** 13 | 14 | + [Portal](portal.md) 15 | + [Widget](widget.md) 16 | -------------------------------------------------------------------------------- /documentation/spModal.md: -------------------------------------------------------------------------------- 1 | # spModal api 2 | _Available in Helsinki Patch 5_ 3 | 4 | spModal provides an alternative way to show alerts, prompts, and confirmation dialogs. Additionally you can use spModal.open() to display a widget in a modal dialog. spModal is a lightweight wrapper for angular UI bootstrap's $uibModal. See here for more info: https://angular-ui.github.io/bootstrap/#/modal 5 | 6 | | Method | Description | 7 | | :------ | :----------- | 8 | | [alert](#alert)(message).then(fn) | Alert a message. The promise contains a single argument that returns true/false. | 9 | | [confirm](#confirm)(message).then(fn) | Display a confirmation message. The promise contains a boolean of the user's response. | 10 | | [prompt](#prompt)(message, *defaultValue*).then(fn) | Prompt the user for input. Provide a message and an optional default value for the input field. The promise contains the user's response as a string. | 11 | | [open](#open)(object options).then(fn) | Open a modal with a customized set of options. See the options table below. | 12 | 13 | **Options** object definition 14 | 15 | | Option | type | Default | Description | 16 | | :------ | :------ | :------ | :----------- | 17 | | title | string | empty | goes in header - can be HTML | 18 | | message | string | empty | goes in the body - can be HTML | 19 | | buttons | array | Cancel & OK | buttons to show on the dialog | 20 | | input | bool | false | if true, shows an input field on the dialog | 21 | | value | string | empty | The value of the input field | 22 | | widget | string | empty | The Widget Id or sys_id to embed in the modal | 23 | | widgetInput | object | null | An object to send to the embedded widget as input | 24 | | shared | object | null | A client-side object to share data with the embedded widget client script | 25 | | size | string | empty | 'sm' or 'lg' | 26 | 27 | ## Examples 28 | 29 | Alert 30 | ------ 31 | 32 |  33 | 34 | **Html Template** 35 | ```html 36 | 39 | ``` 40 | 41 | **Client Script** 42 | ```javascript 43 | function(spModal) { 44 | var c = this; 45 | c.onAlert = function () { 46 | spModal.alert('How do you feel today?').then(function (answer) { 47 | c.simple = answer; 48 | }); 49 | } 50 | } 51 | ``` 52 |
53 | 54 | Confirm 55 | ------ 56 | 57 |  58 | 59 | **Html Template** 60 | ```html 61 | 64 | {{c.confirmed}} 65 | ``` 66 | 67 | **Client Script** 68 | ```javascript 69 | function(spModal) { 70 | var c = this; 71 | c.onConfirm = function() { 72 | c.confirmed = "asking"; 73 | spModal.confirm("Can you confirm or deny this?").then(function(confirmed) { 74 | c.confirmed = confirmed; // true or false 75 | }) 76 | } 77 | } 78 | ``` 79 |
80 | 81 | Confirm with HTML message 82 | ------ 83 | 84 |  85 | 86 | **Html Template** 87 | ```html 88 | 91 | {{c.confirmed}} 92 | ``` 93 | 94 | **Client Script** 95 | ```javascript 96 | function(spModal) { 97 | var c = this; 98 | // more control, passing options 99 | c.onConfirmEx = function() { 100 | c.confirmed = "asking"; 101 | var warn = ''; 102 | spModal.open({ 103 | title: 'Delete this Thing?', 104 | message: warn + ' Are you sure you want to do that?' 105 | }).then(function(confirmed) { 106 | c.confirmed = confirmed; 107 | }) 108 | } 109 | } 110 | ``` 111 | 112 | 113 |
114 | 115 | Prompt 116 | ------ 117 | 118 |  119 | 120 | **Html Template** 121 | ```html 122 | 125 |
126 | You answered {{c.name}}
127 |
128 | ```
129 |
130 | **Client Script**
131 | ```javascript
132 | function(spModal) {
133 | var c = this;
134 | c.onPrompt = function() {
135 | spModal.prompt("Your name please", c.name).then(function(name) {
136 | c.name = name;
137 | })
138 | }
139 | }
140 | ```
141 |
142 |
143 | 144 | 145 | Open 146 | ------ 147 | 148 | ### Example 1: Prompt with label 149 | 150 |  151 | 152 | **Html Template** 153 | ```html 154 | 157 |
158 | You answered {{c.name}}
159 |
160 | ```
161 |
162 | **Client Script**
163 | ```javascript
164 | function(spModal) {
165 | var c = this;
166 | c.onOpen = function() {
167 | //ask the user for a string
168 | spModal.open({
169 | title: 'Give me a name',
170 | message: 'What would you like to name it?',
171 | input: true,
172 | value: c.name
173 | }).then(function(name) {
174 | c.name = name;
175 | })
176 | }
177 | }
178 | ```
179 |
180 |
181 | 182 | 183 | ### Example 2: Agree with custom buttons 184 | 185 |  186 | 187 | **Html Template** 188 | ```html 189 | 192 |
193 | You answered {{c.agree}}
194 |
195 | ```
196 |
197 | **Client Script**
198 | ```javascript
199 | function(spModal) {
200 | var c = this;
201 | c.onAgree = function() {
202 | // ask the user for a string
203 | // note embedded html in message
204 | var h = 'Apple likes people to agree to lots of stuff
' 205 | var m = 'Your use of Apple software or hardware products is based on the software license and other terms and conditions in effect for the product at the time of purchase. Your agreement to these terms is required to install or use the product. ' 206 | spModal.open({ 207 | title: 'Do you agree?', 208 | message: h + m, 209 | buttons: [ 210 | {label:'✘ ${No}', cancel: true}, 211 | {label:'✔ ${Yes}', primary: true} 212 | ] 213 | }).then(function() { 214 | c.agree = 'yes'; 215 | }, function() { 216 | c.agree = 'no'; 217 | }) 218 | } 219 | } 220 | ``` 221 | 222 | 223 |224 | 225 | ### Example 3: Embedded widget 226 | 227 |  228 | 229 | **Html Template** 230 | ```html 231 | 234 | ``` 235 | 236 | **Client Script** 237 | ```javascript 238 | function(spModal) { 239 | var c = this; 240 | c.onWidget = function(widgetId, widgetInput) { 241 | spModal.open({ 242 | title: 'Displaying widget ' + widgetId, 243 | widget: widgetId, 244 | widgetInput: widgetInput || {} 245 | }).then(function(){ 246 | console.log('widget dismissed'); 247 | }) 248 | } 249 | } 250 | ``` 251 | 252 |
253 | 254 | ### Example 4: Modal sizes 255 | 256 |  257 |  258 |  259 | 260 | **Html Template** 261 | ```html 262 | 265 | 268 | 271 | ``` 272 | 273 | **Client Script** 274 | ```javascript 275 | function(spModal) { 276 | var c = this; 277 | c.onSize = function(size) { 278 | spModal.open({ 279 | title: 'Bootstrap modal sizes, sm, lg', 280 | size: size, 281 | message: 'Size set to ' + size 282 | }) 283 | } 284 | } 285 | ``` 286 | 287 | 288 |
289 | 290 | ### Example 5: Embedded widget with shared data 291 | 292 |  293 | 294 | This example requires 2 widgets. 295 | 296 | #### Parent Widget 297 | 298 | **Html Template** 299 | ```html 300 |
301 |
304 |
305 |
309 | ```
310 |
311 | **Client Script**
312 | ```javascript
313 | function ($scope,spModal) {
314 | var c = this;
315 | var shared = {};
316 | c.onChangeSchedule = function(){
317 | spModal.open({
318 | title: 'Select a value',
319 | widget: 'bec1438bdbf276009ed8f81d0f96193e',
320 | widgetInput: { hint: "Soup or Nuts?" },
321 | shared: shared
322 | }).then(function() {
323 | // Shared object was updated
324 | c.selectedValue = shared.selection;
325 | });
326 | }
327 | }
328 | ```
329 |
330 | #### Embedded Widget
331 |
332 | Name: **bec1438bdbf276009ed8f81d0f96193e**
333 |
334 | **Html Template**
335 | ```html
336 |
306 | You picked: {{c.selectedValue.text}}
307 |
308 |
337 |
340 |
341 | ```
342 |
343 | **Client Script**
344 | ```javascript
345 | function() {
346 | var c = this;
347 |
348 | var shared = c.widget.options.shared;
349 | c.selection = function selection(newVal) {
350 | return angular.isDefined(newVal) ? (shared.selection = newVal) : shared.selection;
351 | }
352 | }
353 | ```
354 |
355 | **Server Script**
356 | ```javascript
357 | (function() {
358 | data.hint = input.hint;
359 | data.questions=[];
360 | data.questions.push({text: 'Soup', value: 'soup'});
361 | data.questions.push({text: 'Nuts', value: 'nuts'});
362 | })();
363 | ```
364 |
--------------------------------------------------------------------------------
/documentation/sso_configuration.md:
--------------------------------------------------------------------------------
1 | # SSO, Login & Redirect
2 |
3 | _Working since Helsinki Patch 2_
4 |
5 | #### A few words on SSO
6 | If you use SSO, Service Portal should just work like you would expect. If you are using the system property to automatically redirect to your primary IDP, then Service Portal will automatically redirect to that IDP. If you have multiple identity providers, Service Portal shows a link on the login page to "Use external login". You can conditionally redirect users to Service Portal after login by following the steps in this guide.
7 |
8 | * Require authentication for every Service Portal
9 | * Make Service Portal your default login page
10 | * Conditionally redirect to Service Portal after login
11 |
12 | ### Require authentication for every Service Portal
13 |
14 | Some companies want their portal content available to only authenticated users. To do this, create a record in the sys_public table with the following values:
15 |
16 | Page: $sp
17 | Active: false
18 |
19 | Now when you go to [instance]/sp or [instance]/$sp.do you will be redirected to the platform configured login page if you're unauthenticated. This may be useful for companies with more complex SSO environments.
20 |
21 | ### Make Service Portal your login page
22 |
23 | To make Service Portal the login page for your instance
24 | set the system property glide.entry.page.script = "new SPEntryPage().getLoginURL()"
25 |
26 | #### Configuring SPEntryPage
27 |
28 | **Setting the portal**
29 |
30 | SPEntryPage uses /sp/ as the portal path to redirect to. If you must, edit the SPEntryPage Script Include and change the assigned portal to any portal_suffix you want. (Once you make changes to this script include it won't be upgraded with future updates)
31 |
32 | 
33 |
34 |
35 | ### Conditionally redirect to Service Portal after login
36 |
37 | To conditionally redirect a user to Service Portal after login, set the system property glide.entry.first.page.script = "new SPEntryPage().getFirstPageURL()"
38 |
39 | getFirstPageURL does 2 primary things:
40 |
41 | 1. Redirects to login_redirect.do in order to break out of the frameset (if there is one).
42 | 2. Redirects to Service Portal if the user has no roles, or the full platform for everyone else.
43 |
44 | You can customize this behavior within the "SPEntryPage" script include. (Once you make changes to this script include it won't be upgraded with future updates)
45 |
46 | ### Debugging
47 |
48 | To view debug output from SPEntryPage and see the session variables it redirects based on:
49 |
50 | 1. Make sure the system property "glide.entry.first.page.script" has the value: new SPEntryPage().getFirstPageURL()
51 |
52 | 2. Open the SPEntryPage script include and find and set "this.logVariables = true"
53 |
54 | 3. In a different browser, log in.
55 |
56 | 4. The log output can be viewed by going to "System Logs > System Log > All" in the navigator.
57 |
58 | Or by going directly to: /syslog_list.do?sysparm_query=level%3D0%5EORDERBYDESCsys_created_on&sysparm_first_row=1&sysparm_view=
59 |
--------------------------------------------------------------------------------
/documentation/widget.md:
--------------------------------------------------------------------------------
1 | ### Widget
2 |
3 | A widget is a superset of an [Angular directive](https://docs.angularjs.org/guide/directive) that is tightly coupled to a server-side JavaScript code block powered by the Rhino engine under the ServiceNow platform.
4 |
5 | Since widgets are `read-only` to benefit from future updates, you can't update their code. If you need to make major changes,
6 | *clone* the widget and give it another `name` and `id`.
7 |
8 | ### Widget Instance
9 | Once you drop a widget into a column using the Service Portal Designer it will create a widget instance.
10 | A widget instace is a reference to a widget that contains: location, properties and CSS especific for that instance. A widget used multiple times in the same page, will use multiple instances.
11 |
12 | 
13 |
14 |
15 | ***Learn more:***
16 |
17 | - [HTML](widget_html.md)
18 | - [Client Script](widget_client_script.md)
19 | - [Server Script](widget_server_script.md)
20 | - [Dependencies](widget_dependencies.md)
21 | - [CSS/SCSS](css.md)
22 | - [Embedded Widgets](widget_embedded.md)
23 | - [Server Script APIs](widget_server_script_apis.md)
24 | - [Instances](widget_instances.md)
25 | - [Options](widget_options.md)
26 |
--------------------------------------------------------------------------------
/documentation/widget_client_script.md:
--------------------------------------------------------------------------------
1 | #### Client Script
2 | This is the controller already linked to the widget. Consider every widget to be an Angular directive – you define the controller for that directive here. This is where you handle all the client-side logic and template binding for your widget.
3 | ```javascript
4 | function() {
5 | var c = this;
6 | c.update = function() {
7 | c.data.price = false;
8 | c.server.get({symbol: c.data.symbol}).then(function(r) {
9 | c.data.price = r.data.price;
10 | });
11 | }
12 | }
13 | ```
14 |
15 | | Property | Description |
16 | | :------ | :----------- |
17 | | `this.server.get([Object])` | Calls the server and sends custom `input`. Returns `Promise`. |
18 | | `this.server.update()` | Calls the server and `this.data` is automatically send to server side. Returns `Promise`. |
19 | | `this.server.refresh() ` | Calls the server and automatically replaces the current options and data from the server response. Returns `Promise` |
20 |
--------------------------------------------------------------------------------
/documentation/widget_client_script_apis.md:
--------------------------------------------------------------------------------
1 | # spUtil
2 |
3 | Set of methods that perform common, often re-used functions.
4 |
5 | | Method | Description|
6 | | :------ | :----------- |
7 | | addErrorMessage(String message)| Displays a notification error message |
8 |
9 | ```javascript
10 | spUtil.addErrorMessage("There has been an error processing your request")
11 | ```
12 |
13 | 14 | 15 | | Method | Description| 16 | | :------ | :----------- | 17 | | addInfoMessage(String message) | Displays a notification info message | 18 | 19 | ```javascript 20 | spUtil.addInfoMessage("Your order has been placed") 21 | ``` 22 | 23 |
24 | 25 | | Method | Description| 26 | | :------ | :----------- | 27 | | addTrivialMessage(String message)| Displays a notification trivial message | 28 | 29 | ```javascript 30 | spUtil.addTrivialMessage("Thanks for your order") 31 | ``` 32 | 33 |
34 | 35 | | Method | Description| 36 | | :------ | :----------- | 37 | | get(String widgetId) | Gets a widget model by id or sys_id. Returns Promise. | 38 | 39 | ```javascript 40 | spUtil.get("widget-cool-clock").then(function(response) { 41 | c.coolClock = response; 42 | }); 43 | ``` 44 | 45 |
46 | 47 | 48 | | Method | Description| 49 | | :------ | :----------- | 50 | | format(String, Object) | Alternative to string concatenation | 51 | 52 | Let's say you want to build a string with variables: `'An error occurred: ' + error + ' when loading ' + widget` 53 | instead of doing string concatenation you can use `format()`. 54 | ```javascript 55 | spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'}) 56 | ``` 57 | 58 |
59 | 60 | | Method | Description| 61 | | :------ | :----------- | 62 | | refresh(Object $scope) | Calls the server and automatically replaces the current options and data from the server response. Returns Promise | 63 | 64 | Same as `server.refresh()` The diference is that you can define what $scope to pass over. 65 | 66 |
67 | 68 | | Method | Description| 69 | | :------ | :----------- | 70 | | recordWatch(Object $scope, String table, String filter, Function callback)| watch for a table / filter update - callback when it happens | 71 | 72 | ```javascript 73 | spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId); 74 | ``` 75 | More documentation on recordWatch can be found [here](./widget_record_watch.md). 76 | 77 |
78 | 79 | | Method | Description| 80 | | :------ | :----------- | 81 | | update(Object $scope) | Calls the server and `this.data` is automatically send to server side. Returns Promise. | 82 | 83 | Same as `server.update()`. The diference is that you can define what $scope to pass over. 84 | 85 | `Do not try to use any other methods from spUtil() that are not listed here` 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /documentation/widget_css.md: -------------------------------------------------------------------------------- 1 | # Widget CSS 2 | -------------------------------------------------------------------------------- /documentation/widget_dependencies.md: -------------------------------------------------------------------------------- 1 | ## Widget Dependencies 2 | In Service Portal, it is possible to link Javascript and CSS files to widgets. This allows developers to create dependencies between their widgets and third party libraries, external style sheets, and angular modules. Dependencies are loaded asynchronous from the server at the time that they are needed. 3 | 4 | Following is a step-by-step guide on creating new dependency packages and associating them with widgets. 5 | 6 | ### Creating a Dependency Package 7 | A dependency package is a collection of Javascript and CSS files that can be then connected to a widget. Dependencies can be found in the table `sp_dependency`, or by navigating to the Service Portal module in the navigator and selecting the Dependencies submodule. 8 | 9 | In a dependency record, you will define the following: 10 | 11 | 1. Name - The name that your dependency will be referred to by (Useful for selecting a dependency from a dropdown list) 12 | 13 | 2. Include on page load - Select if you want your dependency to be loaded onto the page on initial page load of Service Portal, or leave unchecked to load the dependency only when the linked widget is loaded onto a page. 14 | 15 | 3. Angular module name - Only necessary if the linked Javascript is an Angular module. Provide the name of the Angular module name that you are loading in, so that it can be injected into the Service Portal angular application. Leave blank if not applicable. 16 | 17 | Once these fields are defined, you can start creating records in the `sp_js_include` and `sp_css_include` table and adding them to the JS Includes and CSS Includes related lists in a dependency record. 18 | 19 | ### Adding Files to a Dependency Package 20 | Here, we will quickly go over how to add files to a dependency package. Individual JS and CSS files can be found in the tables `sp_js_include` and `sp_css_include`, respectively. 21 | 22 | In a include record, you will define the following: 23 | 24 | 1. Display Name - The name of the include (Useful for selecting includes from a dropdown list). 25 | 26 | 2. Source - Your options here are going to depend on whether you are making a new JS include or a CSS include. 27 | 28 | Both JS and CSS includes have URL as an option, which is a way to provide a simple URL path to the file you want to include. ex. https://code.highcharts.com/highcharts.js 29 | 30 | The second option will depend on the file type. JS includes allow you to reference a UI Script record. CSS includes allow you to reference a SP CSS record, found in the table `sp_css`. 31 | 32 | Once you have created your include records, you can add them to your dependency package. Navigate back to your dependency record that you created earlier, and open up the related lists. In both the JS Includes and the CSS Includes related lists, you will do the following: 33 | 34 | 1. Select the tab for the related list 35 | 2. Click the Edit button 36 | 3. Using the slushbucket that has appeared on your screen, move any includes you with to add to your dependency package into the column on the right hand side of the screen. 37 | 4. Press Save 38 | 5. From the Related List on the Dependency record, update the Order field on each included file to specify what order the files should be loaded into the page. Files with lower Order values are loaded first. This is important if your fields depend on one another to be on the page to load correctly. 39 | 40 | ### Adding a Dependency Package to a Widget 41 | Finally, we can create a relationship between our new Dependency and a widget. To do this, follow these steps: 42 | 43 | 1. Navigate to the widget record you wish to update 44 | 2. Scroll to the bottom of the record, and open the Dependencies related list 45 | 3. Select the Edit button on the list 46 | 4. Find the dependency you want to add to the widget in the left column of the slushbucket, and move it to the right column. 47 | 5. Press Save 48 | 49 | That's it! Remember - a widget can have as many or as few dependencies as you want it to have, but the more you add, the more content your widget will need to download to render on the page. Keep the dependencies as small as possible for fast load times. 50 | -------------------------------------------------------------------------------- /documentation/widget_embedded.md: -------------------------------------------------------------------------------- 1 | 2 | # Embedded Widgets 3 | In Service Portal, widgets can be embedded inside other widgets. This technique is useful for creating more powerful widgets through the composition of other widgets. 4 | 5 | For a direct example of this, see the Social QA Question widget, which embeds a login widget next to the Answer Question section for an easy way to prompt users to login to answer questions. 6 | 7 | --- 8 | 9 | ## Widget Directive Syntax 10 | You can embed any widget inside of your widget’s [HTML template](widget_html.md) using the custom `
16 |
18 | ```
19 | _The `id` parameter is simply the id of the widget you're trying to embed._
20 |
21 | ## Widget Options
22 |
23 | Widgets might have [options](widget_options.md) that you can setup. You can define their values in JSON format:
24 |
25 |
26 | ### Providing options in the HTML template
27 |
28 | ###### HTML Template
29 | ```html
30 |
83 |
92 | ```
93 |
94 | ###### CSS
95 | ```css
96 | .panel {
97 | margin-top: 10px;
98 | }
99 | ```
100 |
101 | ###### Client Script
102 | ```javascript
103 | function() {
104 | // nothing to do here...
105 | }
106 | ```
107 |
108 | ###### Server Script
109 | ```javascript
110 | (function() {
111 | var options = [
112 | {zone: "America/Los_Angeles", title: "San Diego"},
113 | {zone: "America/Denver", title: "Denver"},
114 | {zone: "America/Chicago", title: "Chicago"},
115 | {zone: "America/New_York", title: "New York"}
116 | ];
117 |
118 | data.clocks = [];
119 | for (var i in options) {
120 | data.clocks.push($sp.getWidget("widget-cool-clock", options[i]));
121 | }
122 | })();
123 | ```
124 | ### Result
125 | Each instance of the clock widget has a different timezone and title.
126 |
127 | 
128 |
129 | ---
130 |
131 | ## API Reference
132 |
133 | ### Client Side
134 | ##### spUtil.get() - Get a widget model via client script
135 |
136 | ```javascript
137 | spUtil.get("widget-sc-cat-item", {sys_id: "your_catalog_item_sys_id"}).then(function(response) {
138 | c.catalogItemWidget = response;
139 | });
140 | ```
141 | **Parameters**
142 |
143 | - (_string_) widget\_id
144 | Can be a widget_id or widget sys_id.
145 | - (_object_) data
146 | An object to post to the widget's server script. Refer to this object as **input** in your server script.
147 |
148 | **Callback**
149 |
150 | The callback function is called when the widget model is ready. The response object contains the full widget model.
151 |
152 |
153 | ### Server Side
154 | ##### $sp.getWidget() - Get a widget model via server script
155 |
156 | ```javascript
157 | data.catalogItemWidget = $sp.getWidget("widget-sc-cat-item", {sys_id: "your_catalog_item_sys_id"});
158 | ```
159 | **Parameters**
160 |
161 | - (*string*) widget\_id
162 | Can be a widget_id or widget sys_id.
163 | - (*object*) options
164 | An object to pass to the widget's server script. Refer to this object as **options** in your server script.
165 |
166 | **Note:** As of all versions of Helsinki, any options passed into this function will only be available in the embedded widget's server script on the **first execution** of that script. Any subsequent calls into the server script from the embedded widget will not contain the object properties passed in. This is something we are investigating for a future version of Helisinki or Istanbul.
167 |
168 | ## Widget Model in depth
169 |
170 | The widget model contains all of the client-side parts of a widget needed to create an angular directive. The HTML template, client script, and link function are loaded just as they are in the sp_widget record. The data property is the result of the widget's server script execution. Anything that you put on the data object on the server is available in the data object on the client.
171 |
172 | Here is a detailed look at some of the fields in the widget model:
173 |
174 | | Property name | Type | Description |
175 | | ------------- | ---- | ----------- |
176 | | client_script | string | The widget's client script field |
177 | | css | string | The compiled css output from the widget's sass field |
178 | | data | object | The data object containing all of the keys and values added to it in the widget's server script |
179 | | dependencies | array | A collection of javascript libraries to load before the widget executes |
180 | | options | object | The options used to initialize the widget |
181 | | template | string | The widget's HTML Template field |
182 |
--------------------------------------------------------------------------------
/documentation/widget_html.md:
--------------------------------------------------------------------------------
1 | #### Widget HTML
2 | This is where the HTML markup for your widget goes. Inside the template , you can leverage AngularJS’s two-way binding to bind your controller variables to your markup. It uses the `controllerAs c` syntax for basic binding.
3 | ```html
4 | Time across the US
84 |
85 |
91 |
86 |
90 |
87 |
89 |
5 | ${Symbol Lookup}:
6 |
8 |
15 | ```
16 |
--------------------------------------------------------------------------------
/documentation/widget_instances.md:
--------------------------------------------------------------------------------
1 | ## Configuring Widgets with Instances
2 | In Service Portal, widgets are modular, configurable blocks of functionality and UI that are designed to be reusable.
3 |
4 | Whenever you embed a widget in a page, you are automatically creating an `sp_instance` record which contains three important things.
5 |
6 | 1. Reference to a column (where a widget is located)
7 | 2. Reference to a widget
8 | 3. Configuration for a widget in the form of pre-defined form fields and an Additional Options field in JSON format
9 |
10 | There are a number of ways that you can configure a widget, so we'll go through an example to get started with the basics.
11 |
12 | For information on working with instance options, read [Widget Options](widget_options.md) after you're done with this section.
13 |
14 | ### Configuring a Simple List Widget
15 | Let's try configuring a Simple List widget to show a list of problems from the `problem` table, and we will make each list entry link to a Form page. Start by embedding the Simple List widget in the index page, then navigate to that page URL either through a portal or by navigating to /$sp.do?id=index
16 |
17 | Now, let's start configuring the widget. Hold the CTRL button and right-click the widget from the page. If you are logged in as a SP Admin, you should see a context menu appear with a list of links, one of which should say **Instance Options**. Click that link, and you will see a modal appear on the screen containing all of the configuration options that the Simple List widget exposes to you.
18 |
19 | Now, from this modal, we will fill in the following fields:
20 |
21 | * Table - **Problem**
22 | * Display field - **Short description**
23 | * Link to this page - **form**
24 | * Secondary fields - **number**, **sys_updated_on**
25 |
26 | Hit **Save**, and the page will refresh with your newly-configured widget. Click on one of the List entries, and notice that you will be taken to a Form page for that record.
27 |
28 | ### The 'Link to this page' field is missing from my instance - what do I do? (Issue Fixed in Helsinki Patch 1)
29 | If you click on a record from the list and it does not open, type `sp_instance.list` in the left navigator, then find the instance of your Simple List widget. After you open the Widget Instance form, right click the header and select `Configure > Form Layout` from the context menu. Now find the 'Link to this page' field and add it to the Instance of Simple List view of the form. Click 'Save'. Go back to the Widget Instance form and select the page, that your Simple List needs to open records, by finding the page in the 'Link to this page' reference field.
30 |
--------------------------------------------------------------------------------
/documentation/widget_internationalization.md:
--------------------------------------------------------------------------------
1 | # Internationalization
2 |
3 | To internationalize strings in a widget, use `${string}` or `gs.getMessage("message")`. See when to use one form or another below:
4 |
5 | [Translating strings in the HTML template](#translating-strings-in-the-html-template)
6 |
7 | [Translating strings in the Client Script](#translating-strings-in-the-client-script)
8 |
9 | [Translating strings in the Server Script](#translating-strings-in-the-server-script)
10 |
11 | [Safe translations](#safe-translations)
12 |
13 | [Language Switch Widget](#language-switch-widget)
14 |
15 |
16 | ### Translating strings in the HTML template
17 | #### HTML Template
18 | ```html
19 |
9 | ![]()
13 |
14 | ${Stock Price}: 10 | ${Requesting stock price}{{c.data.price | currency:"$"}} 11 |
12 |
20 |
23 | ```
24 | Writing text as ``${message}`` is the equivalent of writing ``${gs.getMessage("message")}`` in other parts of the system, but written as a more legible shorthand.
25 |
26 | ${This message will be internationalized.}
21 |However, this will NOT be.
22 |27 | 28 | ### Translating strings in the Client Script 29 | #### Client Script 30 | Text can be internationalized the same way inside a client script. 31 | ```javascript 32 | function() { 33 | var c = this; 34 | c.message = "${This message will be internationalized}"; 35 | } 36 | ``` 37 | #### HTML Template 38 | ```html 39 |
40 |
41 |
43 | ```
44 |
45 | {{c.message}}
42 |46 | 47 | ### Translating strings in the Server Script 48 | 49 | Great for translating schema options and other values fetch during server-side runtime. 50 | 51 | #### Server Script 52 | ```javascript 53 | function() { 54 | data.message = gs.getMessage("this message contains 'quotes'"); 55 | } 56 | ``` 57 | 58 | ##### HTML Template 59 | ```html 60 |
61 |
63 | ```
64 |
65 | {{c.data.message}}
62 |66 | 67 | ### Safe translations 68 | In some cases, the translation might have quotes or double quotes on it. That could lead to JavasScript errors if you are using the ${} syntax in the client script. 69 | The safest way to fetch a translated message is to do it in the server script. 70 | Then, assign the value to a client-side angular binding. 71 | 72 |
73 | 74 | ### Language Switch Widget 75 | 76 | Users might want to change the language on the portal. The following Widget can be used as template to implement a customized language switch: 77 | 78 | ##### HTML Template: 79 | ```html 80 |
81 | ${Change Language}:
82 |
90 | ```
91 |
92 | ##### Client Script:
93 | ```javascript
94 | function($window) {
95 | var c = this;
96 | c.language = {value: 'en', displayValue: 'English'};
97 | c.changed = function(a) {
98 | c.server.get(c.language).then(function() {
99 | $window.location.reload();
100 | })
101 | }
102 | }
103 | ```
104 |
105 | ##### Server Script:
106 | ```javascript
107 | (function() {
108 | if (input) {
109 | var user = gs.getUser();
110 | user.setPreference("user.language", input.value);
111 | user.savePreferences();
112 | }
113 | })();
114 | ```
115 |
--------------------------------------------------------------------------------
/documentation/widget_link.md:
--------------------------------------------------------------------------------
1 | # Link Function (Advanced)
2 | Since widgets are basically augmented Angular directives, the Link function is used in exactly the same way that Link functions on directives are used in Angular: http://stackoverflow.com/questions/20018507/angularjs-what-is-the-need-of-the-directives-link-function-when-we-already-had
3 |
4 | We don't do any additional things with them, and they aren't necessary for 99% of what you probably want to do in your widget. Sometimes, it makes sense to do direct DOM manipulation in a Link function instead of your controller. See the Angular docs for more info!
5 |
--------------------------------------------------------------------------------
/documentation/widget_options.md:
--------------------------------------------------------------------------------
1 | # Widget Options
2 | In Service Portal, users can configure widgets embedded on pages through the power of **Widget Instances** (for more on this topic, read [Widget Instances](widget_instances.md) and return here for more).
3 |
4 | Now, let's go over how a Widget Developer could define an option schema within their own widgets to enable this level of configurability.
5 |
6 | ### Defining Option Schemas
7 | An **option schema** is a way of defining what properties users of your widgets can define. Any properties declared here will be surfaced when a user is editing the instance of a widget. Here, you can enable users to declare many types of fields, from primitive String and Numbers to reference fields.
8 |
9 | To do this, you will need to navigate to the Widget Editor and select the widget you wish to edit. In the top-right corner of the screen, select the hamburger icon and click the item called **Edit Option Schema**.
10 |
11 | You should be presented with something that looks like this:
12 |
13 | 
14 |
15 | This is where you can add and subtract widget options, along with types and hints. From here, press the + icon and give it a label, a name (snakecase, like_this), a type, and a hint. Depending on the type you select, you may be prompted to provide additional fields.
16 |
17 | Once you have provided your option(s), you can click the **Save** button and begin using them.
18 |
19 | To see your options in action, navigate to an instance of the widget on a page, hold CTRL and right-click the widget. Select the option titled **Instance Options**. In the modal popover, you will see your new option.
20 |
21 | ### Using Options in a Widget
22 | Now, let's go over how to access options in a widget, as well as some best practices.
23 |
24 | When developing a widget, you can access options from both the Server Script and the Client Script in the following way:
25 |
26 | ##### Client Script
27 | ```javascript
28 | function() {
29 | /* widget controller */
30 | var c = this;
31 | console.log(c.options.text_color) //Outputs the text_color option for this instance
32 | }
33 | ```
34 |
35 | ##### Server Script
36 | ```javascript
37 | (function() {
38 | $sp.log(options.text_color) //Logs the value of the text_color option to the browser console.
39 | })();
40 | ```
41 |
42 | #### Default Options
43 |
44 | Before an option value is set on an instance, it will appear as an undefined value when you access that option variable. Therefore, it's a good idea to specify default values for your options in the server script of a widget (to handle the situation where those option values haven't been provided yet).
45 |
46 | Luckily, in Javascript, that's easy:
47 |
48 | ##### Server Script
49 | ```javascript
50 | (function() {
51 | options.text_color = options.text_color || "blue";
52 | options.maximum_entry_count = options.maximum_entry_count || 5;
53 | })
54 | ```
55 |
--------------------------------------------------------------------------------
/documentation/widget_record_watch.md:
--------------------------------------------------------------------------------
1 | # Record Watch
2 | Record Watch is a tool that allows a widget developer to respond to table updates in real-time. For instance, by using Record Watch, the Simple List widget can listen for changes to its data table and if new records are added, removed, or updated, the widget can update itself in real-time.
3 |
4 | Below is an example of how to use Record Watch in a widget's Client Script.
5 |
6 | ##### Client Script
7 | ```javascript
8 | function(spUtil, $scope) {
9 | /* widget controller */
10 | var c = this;
11 |
12 | spUtil.recordWatch($scope, "incident", "active=true", function(name, data) {
13 | console.log(name); //Returns information about the event that has occurred
14 | console.log(data); //Returns the data inserted or updated on the table
15 | });
16 | }
17 | ```
18 |
19 | The above code is registering a listener on the incident table with the filter "active=true", meaning that whenever something changes on that table with that filter, our callback function will be executed.
20 |
21 | The callback function takes two parameters:
22 | * `name` - An object which contains information about the scope of the update.
23 | * `data` - An object containing information about the operation that has taken place ('insert', 'update', or 'delete'), as well as the data for the record itself and, if applicable, a list of the changes that have occurred on that record.
24 |
25 | ### Usage Notes
26 | * When passing the `$scope` argument into the `spUtil.recordWatch` function, be sure to inject `$scope` into the parameters of your Client Script function. For details, see the code snippet above.
27 | * For a real example of using Record Watch, see the **Simple List Widget**.
28 | * Tables that are (periodically) subject to a high frequency of database events are blacklisted from Record Watcher to prevent event storms.
29 |
--------------------------------------------------------------------------------
/documentation/widget_server_script.md:
--------------------------------------------------------------------------------
1 | ## Widget Server Script
2 | This is where you put the server-side logic for your widget. This is helpful primarily with interacting with the Glide platform through ServiceNow [server-side APIs](https://developer.servicenow.com/app.do#!/api_doc?id=server).
3 |
4 | ```javascript
5 | if (input) {
6 | var r = new RESTMessage('Yahoo Finance', 'get');
7 | r.setStringParameter('symbol', input.symbol);
8 | var response = r.execute();
9 | data.price = response.getBody();
10 | }
11 | ```
12 |
13 | This code will be executed within the context of the widget instance related to it.
14 |
15 | ### Server-side properties and helpers
16 |
17 | | Property | Description |
18 | | :------ | :----------- |
19 | | `input` | An object containing client-side properties set under `c.data`. It will have an `undefined` value until the client-side controller calls `c.server.update()` |
20 | | `data` | An object containing properties set during server-side execution |
21 | | `options` | An object containing the schema option properties |
22 | | [`$sp`](widget_server_script_apis.md#sp-api) | Helper class used to access server script API |
23 |
--------------------------------------------------------------------------------
/documentation/widget_server_script_apis.md:
--------------------------------------------------------------------------------
1 | ### $sp API
2 | Service Portal provides a set of convenience methods found on the global `$sp` object, which is available in any widget server script.
3 |
4 | | Method | Description |
5 | | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
6 | | [canReadRecord](#canReadRecord)(Mixed, *opt String*): boolean | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-canReadRecord_GR) Returns true if the user can read the specified GlideRecord. |
7 | | [getCatalogItem](#getCatalogItem)(String): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getCatalogItem_S) Returns a model and view model for a sc_cat_item or sc_cat_item_guide. |
8 | | [getDisplayValue](#getDisplayValue)(String): String | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getDisplayValue_S) Returns a display value from a field on a record in this order: 1. The widget's sp_instance* record
2. 9 | | [getField](#getField)(GlideRecord, String): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getField_GR_S) Returns {display_value, label, type, value} for a given field on a GlideRecord. | 10 | | [getFields](#getFields)(GlideRecord, String): Array | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getFields_GR_S) Like getField Checks the specified field names, and returns a comma seperated list of valid names. | 11 | | [getFieldsObject](#getFieldsObject)(GlideRecord, String) | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getFieldsObject_GR_S) Checks the specified field names, and returns an object containing the valid names. | 12 | | [getForm](#getForm)(String table, String sys_id, /*Optional String*/ encodedQuery, /*Optional String*/ view) | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getForm_S_S) Returns the form| 13 | | [getListColumns](#getListColumns)(String tableName, String view): | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getListColumns_S_S) Returns a list of the specified table's columns in the specified view| 14 | | [getMenuHREF](#getMenuHREF)(GlideRecord): String | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getMenuHREF_GR) Returns the (?id=) portion of the URL based on the sp_menu type. | 15 | | [getMenuItems](#getMenuItems)(String sys_id): Array | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getMenuItems_S) Returns the menu items for the specified instance | 16 | | [getParameter](#getParameter)(String): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getParameter_S) Returns the value of a given key from the query string or post body. | 17 | | [getPortalRecord](#getPortalRecord)(): GlideRecord | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getPortalRecord) Returns the portal's GlideRecord. | 18 | | [getRecord](#getRecord)(): Glide | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getRecord) Returns the GlideRecord for the current sp_instance\*. Returns null if the widget is embedded by another widget. | 19 | | [getRecordDisplayValues](#getRecordDisplayValues) (Object, GlideRecord, String): void | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getRecordDispValues_O_GR_S) Copies display values for the specified field names from a GlideRecord into the data parameter. | 20 | | [getRecordElements](#getRecordElements)(Object, GlideRecord, String): void | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getRecordElements_O_GR_S) Copies the value and display value for the specified field names from a GlideRecord into the data parameter. | 21 | | [getRecordValues](#getRecordValues) (Object, GlideRecord, String): void | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getRecordValues_O_GR_S) Copies values for the specified field names from a GlideRecord into the data parameter. | 22 | | getStream(String, String): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getStream_S_S) Get the activity stream for a record. | 23 | | getUserInitials() | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getUserInitials) Returns the user's initials as a string. | 24 | | [getValue](#getValue)(String): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getValue_S) Like [getDisplayValue](#getDisplayValue) except that it returns the value instead of the display value. | 25 | | [getValues](#getValues)(Object, String): void | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getValues_O_S) Copies values from the request or instance into the data parameter. | 26 | | [getValues](#getValues)(Object): void | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getValues_O_S) Copies values from the widget's sp_instance GlideRecord into the data parameter. | 27 | | [getWidget](#getWidget)(String, Object): Object | [Official Documentation](https://developer.servicenow.com/app.do#!/api_doc?v=jakarta&id=r_GSPS-getWidget_S__O) Returns a widget model for embedding a widget inside another widget. | 28 | | getKBRecord(): Unknown | Not documented - Returns the portal's KB record where the workflow state is published. | 29 | | getKBCount(): Unknown | Not documented - Returns the number of Knowledge Base articles. | 30 | | getKBCategoryArticles(): Unknown | Not documented - Returns KB articles in the specified category and its subcategories. Pass 'limit' to limit the number of articles returned. | 31 | | getKBTopicArticles(): Unknown | Not documented | 32 | | getKBTopCategoryID(): Unknown | Not documented - Returns the top category in the hierarchy containing the specified category. | 33 | | getKBSiblingCategories(): Unknown | Not documented - Returns KB categories with same parent as the specified category.| 34 | | getSCRecord(): Object | Returns sc_cat_item record for the portal's catalog with sys_class_name != sc_cat_item_wizard and active = true in the query. GlideRecord returned has not yet triggered the query. | 35 | | showCatalogPrices(): Unknown | Not documented - Is an object| 36 | | saveVariables(): Unknown | Not documented | 37 | | buildThemeVariableModel(): Unknown | Not documented | 38 | | getVariablesArray(): Unknown | Not documented - Returns the tables variables as an object. | 39 | | getWidgetFromInstance(): Unknown | Not documented - Returns a widget from the specified widget instance. | 40 | | getRecordVariablesArray(): Unknown | Not documented - Returns the records variables. | 41 | | getFilterBreadcrumbs(): Unknown | Not documented - Returns an array of objects where each object contains the breadcrumb label, value, and flags for if fixed and if removed| 42 | | logStat(String type, String table, String id, *opt String comments*): void | Create a new entry in the `sp_log` table with a table name, a record sys_id from that name, and some type and optional comments. Handy for doing things like logging searches or visits to pages, etc. | 43 | | getInstanceRecord(): Unknown | Not documented - Returns the widget instances GlideRecord| 44 | | log(): Unknown | Not documented - Sends the specified message to the log console. | 45 | | saveRecord(): Unknown | Not documented - Saves or updates the current record. | 46 | | logSearch(): Unknown | Not documented - Adds a record to the Service Portal Statistics logs. | 47 | 48 | 49 | 50 | $sp.getPortalRecord() 51 | ------ 52 | Useful for getting the current portal context. It returns the sp_portal GlideRecord if there is one. 53 | 54 | - $sp.getPortalRecord( ) 55 | - **Parameters** 56 | - None 57 | - **Returns** 58 | - (*GlideRecord*) The sp_portal record of the current portal context or null. 59 | 60 | Server Script 61 | 62 | ```javascript 63 | (function() { 64 | var portalGr = $sp.getPortalRecord(); 65 | data.logo = portalGr.getDisplayValue("logo"); 66 | data.homepage = portalGr.getDisplayValue("homepage.id"); 67 | })(); 68 | ``` 69 |
70 | HTML Template 71 | 72 | ```html 73 |
74 | ![]()
75 | Click here to go home
76 |
77 | ```
78 | 79 | Result 80 |  81 | 82 | $sp.getWidget() 83 | ----- 84 | Gets a widget by id or sys_id, executes that widget's server script using the provided options, then returns the widget model. 85 | 86 | - $sp.getWidget( widget_id, options ): Object 87 | - **Parameters** 88 | - (*String*) widget\_id 89 | Can be a widget_id or widget sys_id. 90 | - (*Object*) options 91 | An object to pass to the widget's server script. Refer to this object as **options** in your server script. 92 | - **Returns** 93 | - (*Object*) A widget model to be used with \
101 | HTML Template 102 | 103 | ```html 104 |
107 | For more information and examples refer to the [Embedded Widgets guide](widget_embedded.md). 108 | 109 | $sp.canReadRecord() 110 | ----- 111 | Useful for quickly determining if a record is valid and if the logged-in user has access to it. 112 | 113 | > If the record type is kb_knowledge, sc_cat_item, or sc_category it also checks if the user can view that item. 114 | 115 | - $sp.canReadRecord( gr ): Boolean 116 | - **Parameters** 117 | - (*GlideRecord*) gr 118 | A glide record 119 | - **Returns** 120 | - (*Boolean*) True if the record is valid and readable 121 | - $sp.canReadRecord( table, sys_id ): Boolean 122 | - **Parameters** 123 | - (*String*) table 124 | A table name to query. 125 | - (*String*) sys_id 126 | The record sys_id to query. 127 | - **Returns** 128 | - (*Boolean*) True if the record is valid and readable 129 | 130 | Server Script 131 | 132 | ```javascript 133 | data.items = []; 134 | data.userName = gs.getUserDisplayName(); 135 | var gr = new GlideRecord("sc_cat_item"); 136 | gr.query(); 137 | while(gr.next() && data.items.length < 10) { 138 | if ($sp.canReadRecord(gr)) { 139 | data.items.push(gr.getDisplayValue("name")); 140 | } 141 | } 142 | ``` 143 |
144 | HTML Template 145 | 146 | ```html 147 |
148 |
154 | ```
155 | Hi, {{c.data.userName}}!
149 |
150 | Here are some things you can order:
151 |
153 | - {{item}}
156 | Result 157 |  158 | 159 | > Notice how the list of items is different based on the logged in user 160 | 161 | $sp.getCatalogItem() 162 | ----- 163 | A quick way to get all of the data necessary to render and order a catalog item using \
183 | Client Script 184 | 185 | ```javascript 186 | function($http, spUtil) { 187 | var c = this; 188 | var submitting = false; 189 | c.getIt = function() { 190 | if (submitting) return; 191 | $http.post(spUtil.getURL('sc_cat_item'), c.data.catItem).success(function(response) { 192 | if (response.answer) { 193 | c.req = response.answer; 194 | c.req.page = c.req.table == 'sc_request' ? 'sc_request' : 'ticket'; 195 | } 196 | }); 197 | } 198 | } 199 | ``` 200 | 201 |
202 | SCSS 203 | 204 | ```css 205 | 206 | .img-bg { 207 | padding: 5px; 208 | background-color: $brand-primary; 209 | } 210 | 211 | .img-responsive { 212 | margin: 0 auto; 213 | } 214 | 215 | .cat-icon { 216 | display: block; 217 | margin: -40px auto 0; 218 | } 219 | ``` 220 |
221 | 222 | HTML Template 223 | 224 | ```html 225 |
226 |
247 | ```
248 |
249 |
227 |
246 |
228 | ![]()
229 |
230 |
234 |
235 |
245 | {{::data.catItem.name}}
236 |-
237 |
- ${Price}: {{::data.catItem.price}} 238 |
241 | ${Request created!} {{c.req.number}} 242 |
243 | 244 |250 | 251 | Result 252 | 253 |  254 | 255 | 256 | $sp.getDisplayValue() 257 | ----- 258 | Returns the display value of a given field (if it exists and has a value) from either the widget's sp_instance or the sp_portal record. Refer to the following diagram: 259 | 260 |  261 | 262 | This map visualizes a service portal page with one widget on it. Calling $sp.getDisplayValue("title") would return the display value of the title field on the widget's sp_instance record. If the title field didn't exist or was empty, then it would try the same operation on the the sp_portal record for the current portal context. 263 | 264 | > Note - Embedded widgets do not have sp_instance records. 265 | 266 |
267 | 268 | - $sp.getDisplayValue( fieldName ): String 269 | - **Parameters** 270 | - (*String*) fieldName 271 | The field name to get the display value of. 272 | - **Returns** 273 | - (*String*) A display value from either the sp_instance record or sp_portal record. 274 | 275 |
276 | Server Script 277 | 278 | ```javascript 279 | (function() { 280 | data.title = $sp.getDisplayValue("title"); 281 | data.catalog = $sp.getDisplayValue("sc_catalog"); 282 | })(); 283 | ``` 284 | 285 |
286 | HTML Template 287 | 288 | ```html 289 |
290 |
293 | ```
294 |
295 | sp_instance.title: {{::data.title}}
291 |sp_portal.sc_catalog: {{::data.catalog}}
292 |296 | Result 297 | 298 |  299 | 300 | $sp.getRecordElements() 301 | ----- 302 | Copies display values for the specified field names from a GlideRecord into the data parameter. 303 | 304 | 305 | - $sp.getRecordElements( Object, GlideRecord, String ): void 306 | - **Parameters** 307 | - (*Object*) data 308 | Must pass data object instantiated by the server. 309 | - (*GlideRecord*) GlideRecord 310 | Any GlideRecord of data 311 | - (*String*) String 312 | Comma-delimited string of fieldnames 313 | 314 | - **Returns** 315 | - (*Void*) 316 | Field objects will be added to data 317 |
318 | Server Script 319 | 320 | ```javascript 321 | (function($sp) { 322 | var gr = new GlideRecord("tablename"); 323 | var fieldnames = "sys_id,field_name"; 324 | $sp.getRecordElements(data, gr, fieldnames); 325 | })($sp); 326 | ``` 327 | 328 | $sp.getValue() 329 | ----- 330 | Returns the value of a given field (if it exists and has a value) from either the widget's sp_instance or the sp_portal record. See [getDisplayValue](#getDisplayValue) for more info. 331 | 332 | 333 | - $sp.getValue( fieldName ): Object 334 | - **Parameters** 335 | - (*String*) fieldName 336 | The field name to get the value of. 337 | - **Returns** 338 | - (*Object*) A value from either the sp_instance record or sp_portal record. 339 | 340 |
341 | Server Script 342 | 343 | ```javascript 344 | (function() { 345 | data.title = $sp.getValue("title"); 346 | data.catalog = $sp.getValue("sc_catalog"); 347 | })(); 348 | ``` 349 | 350 |
351 | HTML Template 352 | 353 | ```html 354 |
355 |
358 | ```
359 |
360 | sp_instance.title: {{::data.title}}
356 |sp_portal.sc_catalog: {{::data.catalog}}
357 |361 | Result 362 | 363 |  364 | -------------------------------------------------------------------------------- /release-notes/helsinki.md: -------------------------------------------------------------------------------- 1 | # Helsinki change log 2 | 3 | 4 | ## Helsinki Patch 6 Changes 5 | 6 | * The Variable type checkbox value needs to be string "true"||"false" so glideform apis and ui policy conditions can work 7 | * External content item should open in a new tab from SC category page 8 | * g_form.setValue to empty is broken for reference fields in Service Portal 9 | * evaluate order guide rule base condition from database, not client 10 | * Formatter type variables like container_start would cause order guide eval fail 11 | 12 |
13 | 14 | ## Helsinki Patch 5 Changes 15 | * Added a limit to typeahead search (defaults to 15) 16 | * Several fixes for permissions and element access on search results page 17 | * URL routing fix. When the path or portal changes, redirect to that new page 18 | * KB article attachments moved to bottom for consistency w/ platform UI 19 | * Clicking on links from the sc-category widget can now be intercepted and changed by a parent widget. Added the event name to the widget options schema. 20 | * KB category article count might show -1, it shouldn't; $sp.getKBCount now only counts published articles 21 | * Check_can_view widget option for SC Categories widget wasn't evaluated correctly after being set from true to false 22 | * sp_admin role should be able to CRUD sp_ng_template records 23 | * List widget did not honor glide.security.ui.filter system property or Dictionary attribute for table to force use of FilteredGlideRecord in lists 24 | * Added spModal api for a nicer alert, confirm, prompt: 25 | * spModel.alert(title) 26 | * spModel.confirm(title) 27 | * spModel.prompt(title, defaultValue) 28 | * **Form Widget** 29 | * In the activity stream, added a color bar to distinguish journal fields. Uses the accompanying system property (e.g., glide.ui.activity_stream.style.work_notes) 30 | * Support for journal stream for non-tasks 31 | * Pick the first choice in a choice list if none are selected 32 | * Don't expose short_description in ticket_conversation widget if user can't read that field 33 | * Don't show attachment icon or Edit link if user can't do attachments 34 | * Dont show 'record not found' once the form loads a record that DOES exist 35 | * Choice list now sets the value & displayValue 36 | * long, unbroken title is not wrapped in ticket conversation widget header 37 | * At mobile device width, the activity stream was unusable 38 | * Fixing some edge cases while using g_form.setValue() and the glide_list element. Like setting multiple display values at the same time. 39 | * Making the variable editor show display values for reference fields and list collector fields 40 | * Prevent duplicate --None-- in choice list 41 | * **Catalog support** 42 | * Order Guide description isn't being shown 43 | * Fixing reference qualifiers for list collector variable types 44 | * Quantity picker wasn't wide enough 45 | * For SP catalog item requests, Attachments are now attached to the sc_req_item instead of the sc_request 46 | * Order Guide didn't show images for guide or included items 47 | * Adding support for catalog item variable and variable set layouts: 2down, 2across. 48 | 49 | 50 |
51 | 52 | ## Helsinki Patch 4 Changes 53 | 54 | * Every out-of-box widget translated 55 | * Service Portal Designer translated 56 | * spPanel directive failed if title attribute had a single quote 57 | * Fixing JS error on toolip close 58 | * Fix to make sure a utc date is passed into the
105 | 106 | ## Helsinki Patch 3 Changes 107 | 108 | * Dozens of translations added 109 | * Don't base64 encode record values when saving a form 110 | * Removed spnavto processor 111 | * Honor glide.sc.price.display when set to "never" (search results) 112 | * My Requests widget should show same query as Requests in header 113 | * Services Status page shows wrong/missing dates with custom date format 114 | * link-button widget didn't let you set color in Widget Options 115 | * Setting glide.spform.log_sql to false by default 116 | * CSS class names were not being set on nested rows 117 | * Typeahead search wrongly shows no_search=true and visible_standalone=false catalog items 118 | * /sp portal homepage has no search input in mobile (xs) view 119 | * data table widget might fail to show column label 120 | * New portal should have out of the box Bootstrap colors and settings 121 | * g_user_date_time_format and other globals were not available 122 | * **Catalog support** 123 | * Bringing variable type "label" into the form field model so you can show/hide it using g_form.setDisplay() or ui policy actions 124 | * Don't show price/submit/attachments footer for Content Item catalog item, it's HTML only 125 | * Conversation stream didn't show image attachments added before insert (e.g., from the Create a New Incident catalog item) 126 | * If a catalog item has no short description it wouldn't show up on an order guide 127 | * Catalog variable Help Text isn't shown when specified 128 | * Catalog variable tooltip isn't shown 129 | * Fix for cascading variables. Reference field display values were using the wrong model property 130 | * Cleaning up the mandatory field processing in order guides 131 | * Update Price/Recurring when checkbox variable is unchecked 132 | * Firing submitted events from "SC Order Guide" and "SC Cat Item" 133 | * $sp.sc_order_guide.submitted 134 | * $sp.sc_cat_item.submitted 135 | * **Service Portal Designer** 136 | * Fix: When you drag and drop a widget to another location it will copy the widget instead of moving it 137 | * Fix: Widget code is running twice 138 | --------------------------------------------------------------------------------