service-portal-pages

Service Portal Pages and Themes

widget-coherence covers the inside of one widget — server script, client controller and HTML staying in step. This covers everything around it: the page the widget sits on, and the theme the page renders in.

The hierarchy

sp_portal      one portal. Has a URL suffix ("sp"), a homepage, and a THEME.
  └── sp_page       a page, addressed by its stable `id` → /sp?id=<id>
       └── sp_row        a row in the page layout
            └── sp_column    a column in that row (12-column grid)
                 └── sp_instance   ONE PLACEMENT of one widget, with its options
                      └── sp_widget    the widget definition, shared by every instance

The two things to hold onto:

A page is not "in" a portal. sp_page has no portal reference. A page is reachable from any portal as /<portal-suffix>?id=<page-id>; what ties it to one is being that portal's homepage, or being linked from a menu. Listing pages "for a portal" is therefore a convenience filter, not a containment query.

id is the address, sys_id is the record. sp_page.id is the human-readable stable key that appears in the URL. Both are accepted by the management tool; the id is what a user will quote at you.

Creating and placing

await snow_create_sp_page({ id: "team_requests", title: "Team requests", public: false })

await snow_sp_page_manage({ action: "add_widget_instance", id: "team_requests",
                            widget_id: "widget-my-requests", column_sys_id: colSysId, order: 100 })

public: true means reachable without login — anonymous. It is the one field on this page worth a second look before setting it.

add_widget_instance prefers column_sys_id. Omitting it attaches the instance to the page directly, which renders but sits outside the grid; a page built that way cannot be laid out afterwards without recreating the instances. Build rows and columns first when the layout matters.

Widget options live on the instance