For advanced use cases, a JavaScript API is made available via the global zPortal object. Typically, an HTML Block is used to run JavaScript that utilizes this API. The System API provides access to data about the Portal, as well as providing methods for displaying modals, interacting with Tableau visualizations, and hiding and showing Blocks.

Accessing the API

The System API is defined on the global window object as zPortal. For most use cases, code that uses the System API is put into an HTML block inside a <script> tag. See example uses below.

Properties

page

Object. Information about the current page.

Example

{
	name: "My Page",
	user_id: null,
	order: 1000,
	icon: null,
	screenshot: "data:image/png;base64,...",
	id: "aabb0011-1234-5678-ccdd-aabbcc001122",
	updated_at: "2020-03-30T17:02:05.906350+00:00",
	created_at: "2020-03-30T17:02:05.906362+00:00",
	data: {theme: {…}, grid: {…}}
	datasources: []
}

pageList

Array. List of each page in the portal.

siteConfig

Object. The Custom Portal Site Configuration object.

Example

{
	system: {
		theme_id: "aabb0011-1234-5678-ccdd-aabbcc001122",
		default_dashboard: "aabb0011-1234-5678-ccdd-aabbcc001122", 
		Name: "Value"
	},
	openapi_url: "/openapi.json",
	openapi_prefix: "/api",
	debug: true,
	database_url: "URL('postgresql://admin:********@172.17.0.1/portal')",
	target_database_url: "URL('postgresql://admin:********@stage.zuarbase.net/analytics')",
	partials: {
		sidebar: {…},
		rightSidebar: {…},
		footer: {…},
		header: {…},
		leftSidebar: {…}
	},
	payload: {},
	permissions: ["*"],
	admin: true,
	theme: {
		id: "aabb0011-1234-5678-ccdd-aabbcc001122",
		user_id: null,
		name: "Light",
		json_data: {…},
		updated_at: "2020-03-23T10:35:05.543129+00:00"
	},
	tableau_server: {
		url: "https://tableau.company.com",
		site_name: "default",
		product_version: "2020.1.1",
		rest_api_version: "3.7",
		build_number: "20201.20.0305.1738"
	},
	token_expiry: 15552000
}

theme

Object. The current page's theme.

Example

customProperties: {},
template: {
	header: true,
	leftSidebar: true,
	rightSidebar: true,
	footer: false
}

Methods

Methods on the System API are scoped to properties for the type of object they interact with. For instance, the call to show a block is scoped to the block object and can be accessed like zPortal.block.show().

block.show(blockId)

Shows the block with the given block id.

Example

<button onclick="zPortal.block.show('aabb0011-1234-5678-ccdd-aabbcc001122');>Show block</button>

Parameters

blockId

The id of the block to show.

block.hide(blockId)

Hides the block with the given block id.

Example

<button onclick="zPortal.block.hide('aabb0011-1234-5678-ccdd-aabbcc001122');>Hide block</button>

Parameters

blockId

The id of the block to hide.

modal.show(modalConfig)

Displays a modal window to the user.

Example

<!-- Contents of an HTML block -->
<div>
	<!-- A button to click that will trigger our modal -->
	<button onclick="showPoll()">Take Poll</button>

	<!-- Using the System API to show the modal -->
	<script type="javascript/text">
		(function () {
			window.showPoll = function () {
				zPortal.modal.show({
					title: 'Portal Poll',
					body: '<p>Did you find this article useful?</p>',
					dismissButton: 'No',
					confirmButton: 'Yes',
					size: 'md'
				})
				.then(() => {
					// Confirm button clicked
					vote('yes');
				})
				.catch(() =>{
					// Dismiss button clicked
					vote('no');
				});
			}

			function vote (v) {
				// Save vote in external API
				console.log('Vote logged:', v);
			}
		})(); // Wrap block JavaScript in IIFE
	</script>
</div>

Parameters

modalConfig

The method takes one parameter, an object with the following properties and default values:

{
    title = 'Modal',
    body = '<strong>Hello, World</strong>',
    dismissButton = false,
    confirmButton = false,
    size = 'md'
}

modalConfig.title

The text to display in the header of the modal.

modalConfig.body

The text or HTML to display in the body of the modal.

modalConfig.dismissButton

The text to display in the dismiss button or set to false to hide the dismiss button.

modalConfig.confirmButton

The text to display in the confirmation button or set to false to hide the confirmation button.

modalConfig.size

Controls the size of the modal. Accepted values are sm, md, lg.

tableau.setUrl(blockId, dashboardUrl, dashboardUrl)

Changes the Tableau dashboard URL that a Tabeau block is displaying.

Example

<button onclick="zPortal.tableau.setUrl('aabb0011-1234-5678-ccdd-aabbcc001122', 'https://company.tableau.com/r/my-tableau-dashbaord')">Change dashboard</button>