├── decorated-form-screenshot.png ├── examples └── fdExampleStringField.md ├── styling.md └── README.md /decorated-form-screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/platform-experience/form-decoration/HEAD/decorated-form-screenshot.png -------------------------------------------------------------------------------- /examples/fdExampleStringField.md: -------------------------------------------------------------------------------- 1 | # `fdExampleStringField` 2 | 3 | #### Template 4 | ```html 5 |
8 | 10 | 15 |
16 | ``` 17 | #### Controller function 18 | ```javascript 19 | function fdExampleStringFieldCtrl ($scope, $timeout, $element) { 20 | 21 | $scope.focus = function () { 22 | $scope.hasFocus = true; 23 | $scope.$emit("sp.spFormField.focus", $element, $scope.inputField); 24 | }; 25 | 26 | $scope.blur = function () { 27 | $scope.hasFocus = false; 28 | $scope.fieldValue($scope.field.stagedValue); 29 | $scope.$emit("sp.spFormField.blur", $element, $scope.inputField); 30 | }; 31 | 32 | $timeout(function () { 33 | $scope.$emit("sp.spFormField.rendered", $element, $scope.inputField); 34 | }); 35 | 36 | } 37 | ``` 38 | #### CSS 39 | ```css 40 | .fd-ex-string input { 41 | box-sizing: border-box; 42 | border: 4px solid #C4D0D6; 43 | border-radius: 4px; 44 | background-color: #F9FDFF; 45 | padding: 5px 15px; 46 | width: 100%; 47 | } 48 | ``` 49 | -------------------------------------------------------------------------------- /styling.md: -------------------------------------------------------------------------------- 1 | # Styling 2 | The following SASS variables can be set to control the styling of the form itself. 3 | 4 | | Variable | Effect | Default | 5 | | ------------- | ------------- | ------------- | 6 | | `$fd-ff-margin` | Margin between each form field| `10px 10px 10px 10px` | 7 | | `$fd-ui-actions-margin` | Margin surrounding the UI Actions | `30px 0px` | 8 | | `$fd-ui-actions-text-align` | Text-alignment of the UI Actions | `center` | 9 | | `$fd-uia-margin` | Margin between individual UI Actions | `10px` | 10 | | `$fd-uia-border-radius` | Border radius of the UI Actions | `8px` | 11 | | `$fd-uia-border` | Border of the UI Actions | `3px solid #C4D0D6` | 12 | | `$fd-uia-background` | Background of the UI Actions | `#fff` | 13 | | `$fd-uia-padding` | Padding of the UI Actions | `5px 20px` | 14 | | `$fd-uia-color` | Color of the UI Actions | `#000` | 15 | | `$fd-uia-min-height` | Minimum height of the UI Actions | `40px` | 16 | | `$fd-uia-min-width` | Minimum width of the UI Actions | `40px` | 17 | | `$fd-uia-font-size` | Font size of the UI Actions | `18px` | 18 | | `$fd-uia-background-hover` | Background of UI Action when hovered | `#F9FDFF` | 19 | | `$fd-uia-background-border` | Border of UI Action when hovered | `#F9FDFF` | 20 | | `$fd-uia-background-color` | Color of UI Action when hovered | `#F9FDFF` | 21 | | `$fd-uia-primary-background` | Background of the primary UI Action | `#da1a40` | 22 | | `$fd-uia-primary-border` | Border of the primary UI Action | `#da1a40` | 23 | | `$fd-uia-primary-color` | Color of the primary UI Action | `#fff` | 24 | | `$fd-uia-primary-background-hover` | Background of the primary UI Action when hovered | `#fd3056` | 25 | | `$fd-uia-primary-border-hover` | Border of the primary UI Action when hovered | `#da1a40` | 26 | | `$fd-uia-primary-color-hover` | Color of the primary UI Action when hovered | `#fff` | 27 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Form Decoration 2 | 3 | This ServiceNow application offers added flexibility to the out-of-box form widget in Service Portal, all while retaining it's functionality including respect for form views, UI Policies, and Client Scripts. 4 | 5 | Some feature highlights of the app: 6 | 7 | - Ability to create your own new field types (e.g. "Address lookup"). 8 | - Apply them to all fields of a certain type, or specific fields on a specific table. 9 | - Apply to all portals, or a specific portal. 10 | - Put UI Actions anywhere on the page, in any widget, and style them in any way you want. 11 | - Only UI actions, fields, and associated elements are contained in the widget. There's no background colour, or surrounding "frame". 12 | 13 | The goal for this application is to be as unopinionated as possible, and allow **you** to control how your form displays. 14 | 15 | ![Decorated Form](decorated-form-screenshot.png) 16 | 17 | ## Why? 18 | 19 | The out-of-box form widget in Service Portal is extremely powerful, in that it leverages base-platform functionality so that forms can be designed by configuration rather than code. 20 | 21 | While it's very powerful, it has it's limitations as well. Specifically, there is no out-of-box way to style elements, or to add special functionality to fields on the form. This means that while a portal can look good, it's appearance is often brought down by the inclusion of the form widget on the page which doesn't conform to the styling of the portal. 22 | 23 | Prior to this application, the only way to create your own custom field types and styling was to create your own form from scratch, sacrificing all the base-platform functionality. This app offers a middle-ground. 24 | 25 | ## Installation 26 | 27 | To use this application, simply navigate to `System Applications` > `Studio` on your instance. In the dialog that opens, select `Import From Source Control` and point it at the following repository: 28 | 29 | ``` 30 | https://github.com/platform-experience/form-decoration-app.git 31 | ``` 32 | **NOTE:** Executing **Apply Remote Changes** from the **Source Control** menu of ServiceNow Studio will uninstall and reinstall the application, dropping all the tables and thus wiping your configuration data, thus it is suggested not to do this. It is aimed for this application to be published to a ServiceNow repo/the store eventually, which will allow you to receive updates to the app without wiping your data. 33 | ## Getting Started 34 | There are two widgets included in this application, with the primary one being **Form (Decorated)** (`pi-decorated-form`). This widget must be used for the form decoration functionality to work. For instructions on how to add it to a Service Portal page, refer to the [ServiceNow Documentation website](https://docs.servicenow.com/bundle/helsinki-servicenow-platform/page/build/service-portal/task/t_AddWidgetsToAPage.html). 35 | 36 | The application also comes with a Service Portal Page called `df_test` with the widget already on it. If you open the below URL on your instance you can see it in action. 37 | 38 | ``` 39 | /sp?id=df_test&table=sys_user 40 | ``` 41 | 42 | There is another widget called **Form (Decorated) Actions Example** (`pi-df-actions`) which shows an example of how one would use the API to move the UI actions off the form and into another completely different part of the page. 43 | 44 | ## Understanding 45 | 46 | The app works by leveraging the `template-url` attribute on the out-of-box `spModel` directive. `spModel` is the core directive from which the out-of-box form widget gets it's functionality. 47 | 48 | Instead of offering only a finite set of field types (around 20), the template that this app includes offers unlimited types as it's controlled by what is contained in the tables of the application: 49 | 50 | - Directive (`x_snc_formdec_directive`) - kind of like a "mini-widget". This is where you create your new field types. 51 | - Decorator (`x_snc_formdec_decorator`) - This is where you set the criteria for when a Directive will be used for a particular form field. 52 | 53 | Note that if there is no Decorator defined for a certain field, the out-of-box way of displaying the field will be used. 54 | 55 | 56 | ## Widget Options 57 | 58 | The **Form (Decorated)** widget can be controlled with the following options/parameters: 59 | 60 | | Option (Label) | Option (Name) | URL Parameter | Description | Mandatory | Default | 61 | | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | 62 | | Table | `table` | `table` | The table to show | Yes | 63 | | Sys ID | `sys_id` | `sys_id` | The Sys ID of the record in the table | No | `-1` | 64 | | View | `view` | `view` | The view to use | No | `service_portal` | 65 | | Show only primary UI action | `primary_only` | | Whether to only show the primary UI action | No | `false` | 66 | | Show section headings | `show_headings` | | Whether to show section headings | No | `true` | 67 | | Show UI actions | `show_actions` | | Whether to only show UI actions at all | No | `true` | 68 | 69 | If both and option and URL parameter are are supplied, the option will be used. 70 | 71 | ## Creating a custom field type 72 | To create your own field type, simply create a new record in the **Directive** table (`x_snc_formDec_directive`). 73 | 74 | | Field | Description | 75 | | ------------- | ------------- | 76 | | Name (camel-case) | The name of the directive in camel-case. | 77 | | Screenshot | An example screenshot of the directive. | 78 | | Description | A description of the directive, explaining functionality and anything that can't be conveyed in the screenshot. | 79 | | Template | HTML template of the field | 80 | | Link function | Link function of the field | 81 | | Controller function | Angular controller of the field | 82 | | CSS | CSS to style the field (not SASS compatible) | 83 | 84 | **NOTE:** 85 | 86 | - There are an additional two fields on the table which are read only: `spinal_case` and `snake_case`. These fields will be auto-populated based on the value entered in the **Name (camel-case)** field. 87 | - CSS will be parsed and scoped so it won't conflict with other fields, and the result of this parsing will be stored in the **CSS (parsed)** field (`css_parsed`). 88 | 89 | When creating your directive, you need to ensure it interacts with the form correctly so that when the form is submitted, the correct value gets sent to the server. 90 | 91 | - The value of your field should in most cases be bound to the `field.stagedValue` scope variable. 92 | - When the user focuses on the field, you should emit the Angular event `sp.spFormField.focus`. 93 | - When the user is no longer interacting with the field, you should emit the Angular event `sp.spFormField.blur` and pass the stagedValue into the FieldValue scope function (e.g. `$scope.fieldValue($scope.field.stagedValue);` 94 | 95 | **NOTE:** be careful when using [one-time bindings](https://toddmotto.com/angular-one-time-binding-syntax/), as if the field/form changes as a result of UI Policy/Client Script you want these updates to reflect on your field. 96 | 97 | ## Defining when the new field type will be used 98 | You must define a directive record which controlls when the field type will be used. You can do this within the **Decorators** table (`x_snc_formdec_decorator`). 99 | 100 | | Field | Description | 101 | | ------------- | ------------- | 102 | | Directive | A reference to the directive record created in step 2. | 103 | | Portal | The portal where this relationship should apply. | 104 | | Applies to | Whether the decorator applies to a field type, or a specific field. | 105 | | Field Type | The field for which the directive should be used. | 106 | | Field | The field for which the directive should be used. | 107 | 108 | ## Security 109 | The application has 4 roles which can be granted to users to allow them to configure the application. 110 | 111 | | Role | Description | Contains roles | 112 | | ------------- | ------------- | ------------- | 113 | | `x_snc_formDec.admin` | Administrative access | `x_snc_formDec.developer` `x_snc_formDec.manager ` | 114 | | `x_snc_formDec.developer` | Can manage directive records | `x_snc_formDec.user` | 115 | | `x_snc_formDec.manager` | Can manage decorator records | `x_snc_formDec.user` | 116 | | `x_snc_formDec.user` | | | 117 | 118 | No roles are required to be able to view the form widget or the custom fields. 119 | 120 | ## Configuration 121 | 122 | - [Styling](styling.md) 123 | 124 | ## Example Directives 125 | The application comes with 9 Directive records in it's demo data which you can use as inspiration for your own custom fields: 126 | 127 | - [fdExampleStringField](examples/fdExampleStringField.md) 128 | - fdExampleCheckboxField 129 | - fdExampleChoiceField 130 | - fdExampleEmailField 131 | - fdExamplePasswordField 132 | - fdExamplePhoneField 133 | - fdExamplePhotoField 134 | - fdExampleRefField 135 | - fdExampleYesNoField 136 | 137 | There are also 9 Decorator records which will ensure that these field types are used for the `sys_user` table. 138 | 139 | ## Get assistance 140 | 141 | For assistance or feature requests, please raise an issue within this GitHub repo (`platform-experience/form-decoration`). Best efforts will be made to resolve these. --------------------------------------------------------------------------------