Pre-release — content may change.

Widgets

Embedding Guide

Step-by-step guide to integrating Wicket Widgets into your website

This guide covers how to embed Wicket Widgets into your website, from initial setup to advanced configuration and event handling.

Prerequisites

Before embedding widgets, ensure you have:

  1. API Access — Valid JWT token for authentication (Authentication Guide)
  2. Tenant URL — Your Wicket admin URL (e.g., https://your-org-admin.wicketcloud.com)
  3. Resource IDs — UUIDs for people, organizations, or other resources the widget will manage

Installation

Step 1: Add the Universal Embed Script

Add the Wicket Widgets loader script to your HTML page:

<!DOCTYPE html>
<html>
<head>
  <title>My Member Portal</title>
</head>
<body>
  <!-- Your page content -->
  <div id="widget-container"></div>

  <!-- Wicket Widgets Loader Script -->
  <script type="text/javascript">
    window.Wicket = function(doc, tag, id, script) {
      var w = window.Wicket || {};
      if (doc.getElementById(id)) return w;
      var ref = doc.getElementsByTagName(tag)[0];
      var js = doc.createElement(tag);
      js.id = id;
      js.src = script;
      ref.parentNode.insertBefore(js, ref);
      w._q = [];
      w.ready = function(f) { w._q.push(f); };
      return w;
    }(document, "script", "wicket-widgets", "https://your-org-admin.wicketcloud.com/dist/widgets.js");
  </script>
</body>
</html>

Important: Replace your-org-admin.wicketcloud.com with your actual Wicket admin URL.

Step 2: Initialize Widgets

All widget initialization must happen inside the Wicket.ready() callback:

<script>
  Wicket.ready(function() {
    // All widget code goes here
    console.log('Wicket Widgets SDK loaded and ready');
  });
</script>

The Wicket.ready() callback ensures the SDK is fully loaded before you try to create widgets.

Creating Your First Widget

Example: Person Profile Editor

<div id="profile-editor"></div>

<script>
  Wicket.ready(function() {
    Wicket.widgets.createPersonProfile({
      accessToken: 'YOUR_JWT_TOKEN',
      personId: 'person-uuid-here',
      apiRoot: 'https://your-org-api.wicketcloud.com',
      rootEl: document.getElementById('profile-editor'),
      lang: 'en'
    }).then(function(widget) {
      console.log('Profile editor loaded successfully');

      // Listen for save events
      widget.listen(widget.eventTypes.SAVE_SUCCESS, function(payload) {
        console.log('Profile saved:', payload);
      });
    }).catch(function(error) {
      console.error('Failed to load profile editor:', error);
    });
  });
</script>

Widget Configuration

Common Configuration Options

All widgets accept these standard parameters:

ParameterTypeRequiredDescription
accessTokenstringYesJWT token or widget token for authentication
rootElHTMLElementYesContainer element where widget will render
apiRootstringYesBase URL for Wicket MDP API (e.g., https://your-org-api.wicketcloud.com)
langstringNoLanguage code (en, fr, etc.). Default: en

Widget-Specific Parameters

Different widgets require additional parameters:

Person Widgets

// createPersonProfile
{
  personId: 'person-uuid', // UUID of person to edit
  // ... common options
}

// editPersonPreferences
{
  personId: 'person-uuid',
  // ... common options
}

Organization Widgets

// editOrganizationProfile
{
  orgId: 'org-uuid',      // UUID of organization to edit
  accessToken: widgetToken, // Must be a widget token, not regular JWT
  // ... common options
}

Additional Info (Custom Fields)

// editAdditionalInfo (for person)
{
  personId: 'person-uuid',
  // ... common options
}

// editAdditionalInfo (for organization)
{
  orgId: 'org-uuid',
  accessToken: widgetToken, // Widget token required for orgs
  // ... common options
}

Complete Examples

Example 1: Person Profile with Event Handling

<!DOCTYPE html>
<html>
<head>
  <title>Edit My Profile</title>
  <style>
    #profile-container {
      max-width: 800px;
      margin: 40px auto;
      padding: 20px;
    }
    .notification {
      padding: 15px;
      margin-bottom: 20px;
      border-radius: 4px;
      display: none;
    }
    .notification.success {
      background: #d4edda;
      color: #155724;
      display: block;
    }
  </style>
</head>
<body>
  <div id="notification" class="notification"></div>
  <div id="profile-container"></div>

  <script>
    window.Wicket = function(doc, tag, id, script) {
      var w = window.Wicket || {};
      if (doc.getElementById(id)) return w;
      var ref = doc.getElementsByTagName(tag)[0];
      var js = doc.createElement(tag);
      js.id = id;
      js.src = script;
      ref.parentNode.insertBefore(js, ref);
      w._q = [];
      w.ready = function(f) { w._q.push(f); };
      return w;
    }(document, "script", "wicket-widgets", "https://your-org-admin.wicketcloud.com/dist/widgets.js");
  </script>

  <script>
    Wicket.ready(function() {
      // Configuration
      const config = {
        accessToken: 'YOUR_JWT_TOKEN',
        personId: 'YOUR_PERSON_UUID',
        apiRoot: 'https://your-org-api.wicketcloud.com',
        rootEl: document.getElementById('profile-container'),
        lang: 'en'
      };

      // Create widget
      Wicket.widgets.createPersonProfile(config)
        .then(function(widget) {
          console.log('Widget loaded');

          // Show notification on successful save
          widget.listen(widget.eventTypes.SAVE_SUCCESS, function(payload) {
            const notification = document.getElementById('notification');
            notification.className = 'notification success';
            notification.textContent = 'Your profile has been saved successfully!';

            // Hide notification after 5 seconds
            setTimeout(function() {
              notification.className = 'notification';
            }, 5000);
          });

          // Log errors
          widget.listen(widget.eventTypes.ERROR, function(error) {
            console.error('Widget error:', error);
          });
        })
        .catch(function(error) {
          console.error('Failed to initialize widget:', error);
          document.getElementById('profile-container').innerHTML =
            '<p style="color: red;">Unable to load profile editor. Please refresh the page.</p>';
        });
    });
  </script>
</body>
</html>

Example 2: Organization Profile with Server-Side Token

<div id="org-editor"></div>

<script>
  Wicket.ready(function() {
    // Fetch widget token from your server
    fetch('/api/get-widget-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        personId: 'YOUR_PERSON_UUID',
        orgId: 'YOUR_ORG_UUID'
      })
    })
    .then(response => response.json())
    .then(data => {
      // Initialize widget with token from server
      return Wicket.widgets.editOrganizationProfile({
        accessToken: data.widgetToken,
        orgId: 'YOUR_ORG_UUID',
        apiRoot: 'https://your-org-api.wicketcloud.com',
        rootEl: document.getElementById('org-editor'),
        lang: 'en'
      });
    })
    .then(function(widget) {
      widget.listen(widget.eventTypes.SAVE_SUCCESS, function() {
        alert('Organization profile updated!');
      });
    })
    .catch(function(error) {
      console.error('Error:', error);
    });
  });
</script>

Event Handling

Available Events

Widgets emit events for key lifecycle moments:

Event TypeDescriptionWidgets
WIDGET_LOADEDWidget initialized and renderedAll
SAVE_SUCCESSData saved successfullyProfile, Additional Info
DELETE_SUCCESSResource deletedProfile
ERRORAn error occurredAll

Listening to Events

Use widget.listen() for ongoing event monitoring:

widget.listen(widget.eventTypes.SAVE_SUCCESS, function(payload) {
  console.log('Saved:', payload);
});

Use widget.listenOnce() for one-time events:

widget.listenOnce(widget.eventTypes.WIDGET_LOADED, function() {
  console.log('Widget is ready');
  // This callback will only fire once
});

Event Payload Examples

// SAVE_SUCCESS
{
  type: 'people',
  id: 'person-uuid',
  attributes: { /* updated person data */ }
}

// ERROR
{
  message: 'Failed to save profile',
  code: 'VALIDATION_ERROR',
  details: { /* error details */ }
}

Widget Lifecycle Management

Cleaning Up Widgets

Remove widgets when no longer needed:

const widget = await Wicket.widgets.createPersonProfile(config);

// Later, when done:
widget.clear(); // Removes widget from DOM and cleans up event listeners

Replacing Widgets

To replace a widget with another:

// Clear existing widget
existingWidget.clear();

// Create new widget in same container
const newWidget = await Wicket.widgets.createPersonProfile({
  personId: differentPersonId,
  rootEl: sameContainer,
  // ... other config
});

Multi-Language Support

Setting Language

Specify language via the lang parameter:

Wicket.widgets.createPersonProfile({
  lang: 'fr', // French
  // ... other config
});

Supported Languages

Check with your Wicket administrator for available language codes. Common options:

  • en — English
  • fr — French
  • es — Spanish

Dynamic Language Switching

let currentWidget = null;
const container = document.getElementById('profile-container');

function loadWidget(language) {
  // Clear existing widget
  if (currentWidget) {
    currentWidget.clear();
  }

  // Load widget in selected language
  Wicket.widgets.createPersonProfile({
    accessToken: token,
    personId: personId,
    apiRoot: apiRoot,
    rootEl: container,
    lang: language
  }).then(function(widget) {
    currentWidget = widget;
  });
}

// Language selector
document.getElementById('lang-selector').addEventListener('change', function(e) {
  loadWidget(e.target.value);
});

Styling and Customization

Default Styling

Widgets come with built-in styling that matches the Wicket Admin interface. No additional CSS is required.

Container Sizing

The widget adapts to its container's width. Control widget size via the container element:

<style>
  #profile-container {
    max-width: 800px;  /* Limit widget width */
    margin: 0 auto;    /* Center widget */
  }
</style>

<div id="profile-container"></div>

Responsive Design

Widgets are responsive and work on mobile devices:

#widget-container {
  max-width: 100%;
  padding: 20px;
}

@media (min-width: 768px) {
  #widget-container {
    max-width: 800px;
    margin: 40px auto;
  }
}

Error Handling

Initialization Errors

Handle widget creation failures:

Wicket.widgets.createPersonProfile(config)
  .then(function(widget) {
    // Success
  })
  .catch(function(error) {
    console.error('Widget initialization failed:', error);

    // Show user-friendly error message
    container.innerHTML =
      '<div class="error">' +
      '  <p>Unable to load the profile editor.</p>' +
      '  <button onclick="location.reload()">Retry</button>' +
      '</div>';
  });

Runtime Errors

Listen for errors during widget operation:

widget.listen(widget.eventTypes.ERROR, function(error) {
  if (error.code === 'VALIDATION_ERROR') {
    // Widget will show validation errors inline
    console.log('Validation failed:', error.details);
  } else if (error.code === 'NETWORK_ERROR') {
    alert('Network error. Please check your connection and try again.');
  } else {
    console.error('Widget error:', error);
  }
});

Common Errors

Error CodeCauseSolution
INVALID_TOKENToken expired or invalidRefresh authentication token
PERMISSION_DENIEDUser lacks permissionVerify user has access to resource
NETWORK_ERRORAPI request failedCheck network connection and API URL
VALIDATION_ERRORInvalid data submittedReview validation messages in widget
RESOURCE_NOT_FOUNDPerson/Org UUID doesn't existVerify UUID is correct

Performance Optimization

Lazy Loading

Load widgets only when needed:

// Load widget on button click
document.getElementById('edit-profile-btn').addEventListener('click', function() {
  // Check if script is loaded
  if (typeof Wicket === 'undefined') {
    // Load script first
    const script = document.createElement('script');
    script.src = 'https://your-org-admin.wicketcloud.com/dist/widgets.js';
    script.onload = function() {
      Wicket.ready(function() {
        createWidget();
      });
    };
    document.body.appendChild(script);
  } else {
    Wicket.ready(function() {
      createWidget();
    });
  }
});

function createWidget() {
  Wicket.widgets.createPersonProfile({
    // ... config
  });
}

Caching Tokens

Cache authentication tokens to avoid repeated API calls:

let cachedToken = null;
let tokenExpiry = null;

async function getToken() {
  // Return cached token if still valid
  if (cachedToken && Date.now() < tokenExpiry) {
    return cachedToken;
  }

  // Fetch new token
  const response = await fetch('/api/auth/token');
  const data = await response.json();

  cachedToken = data.token;
  tokenExpiry = Date.now() + (data.expiresIn * 1000);

  return cachedToken;
}

Debugging

Enable Console Logging

Check browser console for widget debug information:

Wicket.ready(function() {
  console.log('Wicket SDK version:', Wicket.version);

  Wicket.widgets.createPersonProfile(config)
    .then(function(widget) {
      console.log('Widget instance:', widget);
      console.log('Available event types:', widget.eventTypes);
    });
});

Common Issues

Widget doesn't render:

  • Check that container element exists: document.getElementById('container-id')
  • Verify Wicket.ready() callback is executing
  • Check browser console for JavaScript errors

Widget shows authentication error:

  • Verify token is valid and not expired
  • Check API URL is correct
  • Ensure token has proper permissions for the resource

Events not firing:

  • Confirm you're listening for correct event types
  • Check that event listeners are registered after widget creation

On this page