custom subpages

if your widget needs more than the built-in settings form, you can add your own dashboard tabs. go to the subpages tab and add one or more subpages with a name and an iframe URL.

when someone opens your widget's instance page, those tabs will load your page in an iframe.

WidgetStar appends a token query parameter to your iframe URL. you can verify it by sending a request to /api/verify-token:

const token = new URLSearchParams(location.search).get('token'); // req.query.token
const res = await fetch('https://widget.st/api/verify-owner', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }),
});
const data = await res.json();
// data.instance_id, data.widget_id, data.user_id
// data.username and data.email only if you asked for them

by default the token only gives information about the instance and the owner's user id. if your dashboard needs their username and email, check ask for username and email on that subpage. they'll see a prompt before the iframe loads, and /api/verify-owner will include username and email.

this is how your dashboard knows which instance is being configured and who's the owner. always verify the token on the server!

iframe height

the dashboard iframe starts at a default height. to make it fit your page, include this script:

<script src="https://widget.st/js/subpage.js"></script>

it measures your page and tells WidgetStar so the iframe can resize to the content.

styling the dashboard

if you want your custom subpage to fit WidgetStar's style, we prepared a CSS file you can use that gives you common WidgetStar styles:

<link rel="stylesheet" href="https://widget.st/styles/subpage.css">

List of styled elements:

• h3 - header
• .box - dashboard box div
• .primary-btn - big purple primary button. add small or short classes for a smaller variants
• .secondary-btn - big blue secondary button. add small or short classes for a smaller variants
• .tiny-btn - common small button in dashboard elements. add danger class to make it red
• table, thead, tbody - table styled by default
• input, textarea, select - styled by default