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:
- API Access — Valid JWT token for authentication (Authentication Guide)
- Tenant URL — Your Wicket admin URL (e.g.,
https://your-org-admin.wicketcloud.com) - 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
accessToken | string | Yes | JWT token or widget token for authentication |
rootEl | HTMLElement | Yes | Container element where widget will render |
apiRoot | string | Yes | Base URL for Wicket MDP API (e.g., https://your-org-api.wicketcloud.com) |
lang | string | No | Language 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 Type | Description | Widgets |
|---|---|---|
WIDGET_LOADED | Widget initialized and rendered | All |
SAVE_SUCCESS | Data saved successfully | Profile, Additional Info |
DELETE_SUCCESS | Resource deleted | Profile |
ERROR | An error occurred | All |
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 listenersReplacing 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— Englishfr— Frenches— 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 Code | Cause | Solution |
|---|---|---|
INVALID_TOKEN | Token expired or invalid | Refresh authentication token |
PERMISSION_DENIED | User lacks permission | Verify user has access to resource |
NETWORK_ERROR | API request failed | Check network connection and API URL |
VALIDATION_ERROR | Invalid data submitted | Review validation messages in widget |
RESOURCE_NOT_FOUND | Person/Org UUID doesn't exist | Verify 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