{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":614,"path":"api-reference/scripts/c_UIMacros.md","title":"UI macros","bundle":null,"doc_type":null,"release":"australia","body":"\n# UI macros\n\nUI macros are discrete scripted components administrators can add to the user interface.\n\nUI macros are typically controls that provide inputs or information not provided by existing field types. By default, the system provides UI macros for a variety of user interface elements such as:\n\n- All formatters\n- The Service Catalog cart\n- The action icons next to fields\n- The action icons on forms and lists\n- The widgets of a content management system\n- The Orchestration activity designer\n\nAdministrators can create their own UI macros to provide custom controls or interfaces. Creating UI macros requires knowledge of [Jelly script](http://commons.apache.org/proper/commons-jelly/). Review the existing UI macros for examples and suggested approaches. Those who want to build custom interfaces with JavaScript technologies should consider Service Portal as an alternative.\n\n**Note:** To view available UI macros, navigate to **All** > **System UI** > **UI Macros**.\n\n**Parent Topic:**[Creating custom UI Pages and UI macros](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/create-custom-ui-pages.md)\n\n**Related topics** \n\n\n[Service Portal](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/c_ServicePortal.md)\n\n[Create a UI macro for a formatter](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/t_CreateAUIMacro.md)\n\n## UI macro basics\n\nUI macros can be used to build solutions that can’t be built using the available catalog variable types.\n\n### Accessible UI macros\n\nSeveral UI macros are available in the UI macros \\[ui\\_macros\\] table. These UI macros have names starting with `ui_` and emulate the behavior of a subset of standard form field types for use in UI pages. For example, the ui\\_date\\_time UI macro can act like a glide\\_date\\_time field in a UI page, providing a type-able input field with a date/time selector.\n\nA UI macro can be included in a UI page with the <g:> Jelly tag. The following example includes the ui\\_date\\_time UI Macro, providing two optional attributes to the UI Macro:\n\n```\n\n```\n\nThe attribute values in the <g:> Jelly tag are provided to the UI macro as jvar-prefixed variables. The UI macro can use the jvar-prefixed variables in its XML.\n\n|Attributes|jvar-prefixed variables|\n|----------|-----------------------|\n|name|jvar\\_name|\n|value|jvar\\_value|\n|onchange|jvar\\_onchange|\n\n**Note:** These UI macros aren’t intended to support all features of their corresponding form field type. In many cases, the macros are only intended for specific ServiceNow application use cases.\n\nThe `ui_`-prefixed UI macros include descriptions specifying supported attributes that can \\(or must\\) be provided in the UI page's <g:> Jelly tag. To view available UI macros, navigate to **All** > **System UI** > **UI macros**.\n\n/\n\n### Custom UI macros\n\nThe ui\\_example UI macro uses three jvar-prefixed variables: jvar\\_name, jvar\\_test\\_attribute and jvar\\_laptop\\_type. These variables can be provided to the UI macro as name, test\\_attribute and laptop\\_type attributes in a <g:> Jelly tag in a UI page.\n\n- **Creating the ui\\_example UI macro**\n\n Navigate to **All** > **System UI** > **UI Macros** and select **New**.\n\n Name the macro `ui_example` and add the following script to the **XML** field:\n\n ```\n \n \n
name jvar: ${jvar_name}
\n
test_attribute jvar: ${jvar_test_attribute}
\n
laptop_type jvar: ${jvar_laptop_type}
\n \n ```\n\n- **Using the macro in a UI page**\n\n Navigate to **All** > **System UI** > **UI Pages** and select **New**. You will be asked to select an administrator role.\n\n Name the UI page and add the following script to the **HTML** field:\n\n ```\n \n \n
Template include one:
\n \n \n
Template include two:
\n \n \n ```\n\n- **Checking output**\n\n In the UI page, you can click **Try It** to view the results.\n\n\n**Note:** If you create a macro and it doesn’t display as expected in the UI page, clearing the cache might help. To clear the cache of your instance, in your browser, enter `/cache.do`.\n\n**Related topics** \n\n\n[UI pages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/r_UIPages.md)\n\n[Jelly tags](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/r_JellyTags.md)\n\n[<g:ui\\_form/>](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ExtensionsToJellySyntax.md)\n\n[<g:ui\\_input\\_field />](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ExtensionsToJellySyntax.md)\n\n[<g:ui\\_checkbox/>](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ExtensionsToJellySyntax.md)\n\n## Calling UI macros\n\nAdministrators can call UI macros from certain record types associated with the user interface.\n\n
\n\nRecord type\n\n
\n\nExample\n\n
\n\nDictionary attribute\n\n
\n\nDisplay an icon for a reference field:\n\n ```\nref_contributions=ui_macro_name\n```\n\n
\n\nUI page\n\n
\n\nDisplay something on a UI page:\n\n ```\n\n```\n\n
\n\nUI macro\n\n
\n\nCall a UI macro from another UI macro:\n\n ```\n\n\n \n \n\n```\n\n
\n
## UI macro form\n\nEach UI macro record consists of a name and an XML document written in Jelly code.\n\n|Field|Description|\n|-----|-----------|\n|Name|A unique and descriptive name for this macro.|\n|Active|Select the check box to render the element as defined. Clear the check box to disable the element without deleting the code. For example, the **email\\_reply** macro is inactive by default.|\n|Description|Describe the purpose of the macro and parameters passed to it.|\n|XML|Jelly script that defines the macro.|\n\n## Custom approval UI macro\n\nThis section describes how to create a custom approval UI macro.\n\n**Warning:** The customization described here was developed for use in specific instances, and is not supported by Now Support. This method is provided as-is and should be tested thoroughly before implementation. Post all questions and comments regarding this customization to our community [forum](http://community.service-now.com/).\n\n**Script Name**: Custom Approval UI Macro\n\n**Type**: UI Macro\n\n**Description**: Here is an option to get more detail out of the My Approvals view of an Execution Plan. This can be done by creating a new UI macro. Navigate to **System UI** and click **UI Macros**. First, rename the existing `approval_summarizer_sc_task` to something like `approval_summarizer_sc_task_old` and deactivate it. Then create a new one using the same name \\(`approval_summarizer_sc_task`\\). The name should basically tell you what the macro does and what it applies to. In this case, we're replacing an existing one so we decided to re-use the existing name.\n\nCopy the XML script at the bottom of this article into the XML code window in the new UI macro. This is great way to give some detail to an approver when you are making line item approvals via approval tasks within the Service Catalog Execution Plans.\n\nThe following example script has a link into the item ordered, a short description \\(which contains the ability to expand the variables from the item\\), price, quantity and the total price. This helps the approver in that it shows more detail. They can now see what they are actually approving.\n\n```\n\n \n