Overview
Embed self-serve member features directly into your website
Wicket Widgets allow you to embed interactive forms for managing resources like Person Profiles, Organization Profiles, and custom data fields directly within your website, providing a similar UI to what's available in the Wicket Admin.
What Are Wicket Widgets?
Wicket Widgets are JavaScript-based UI components that enable members to:
- Edit their profiles — Update personal information, contact details, and preferences
- Manage organizations — Modify organization profiles and details
- Complete onboarding — Guide new members through registration and setup flows
- Update preferences — Configure communication settings and language preferences
- Manage custom fields — Edit additional information using JSON schema-validated forms
These widgets serve as building blocks for developing richer user experiences such as member onboarding flows, account centers, and self-service portals.
Available Widgets
Wicket provides four main widget types for different use cases:
createPersonProfile
Edit person profile information including names, contact details, and demographic data
editPersonPreferences
Manage communication preferences, language settings, and notification options
editOrganizationProfile
Edit organization details such as legal name, addresses, and contact information
editAdditionalInfo
Edit custom data fields validated against JSON schemas for people and organizations
Note: Organization widgets (editOrganizationProfile and editAdditionalInfo for organizations) require special widget tokens for security. Person widgets use standard JWT API tokens.
Key Features
1. Consistent UI/UX
Widgets provide the same look and feel as the Wicket Admin interface, ensuring a consistent user experience across all touchpoints.
2. Real-time Validation
All widgets include built-in validation that matches the Wicket MDP API's validation rules, providing immediate feedback to users.
3. Event-Driven Architecture
Widgets emit events for key actions (saves, deletes, navigation) allowing you to respond to user interactions and integrate with your application logic.
4. Multi-language Support
Widgets support internationalization with configurable language settings.
5. Flexible Embedding
Embed widgets anywhere on your site using simple JavaScript initialization within any HTML container element.
Integration Approaches
CMS Integration
Wicket provides plugins and starter modules for popular CMS platforms:
- WordPress — Plugins for member portals, protected content, and widget integration
- Drupal — Modules for membership features and widget embedding
See the CMS Integration Guide for detailed setup instructions.
Custom Website Integration
For custom websites or applications, widgets can be embedded using:
- Universal Embed Script — Load the Wicket Widgets SDK
- Widget Initialization — Configure and render widgets in your page
- Event Handling — Respond to widget events and user actions
See the Embedding Guide for implementation details.
Authentication
Wicket Widgets use two authentication approaches depending on the widget type:
- Person widgets (
createPersonProfile,editPersonPreferences) use standard JWT API tokens - Organization widgets (
editOrganizationProfile,editAdditionalInfofor orgs) require special widget tokens
Widget tokens provide temporary, scoped access and allow your application to control permissions before granting access to organization data.
See the Widget Authentication Guide for implementation details and security best practices.
Security Considerations
1. Server-Side Token Generation
Always generate widget tokens server-side, never expose your API secret in client-side code:
// ✅ Good: Server-side token generation
app.post('/api/widget-token', async (req, res) => {
// Verify user has permission to edit this organization
if (!userCanEditOrg(req.user, req.body.orgId)) {
return res.status(403).send('Forbidden');
}
// Generate widget token server-side
const token = await createWidgetToken(req.user.id, req.body.orgId);
res.json({ token });
});
// ❌ Dangerous: Never do this
const token = generateJwt(apiSecret); // Don't expose secrets client-side2. Permission Checks
Implement your own permission logic before issuing widget tokens:
function userCanEditOrg(user, orgId) {
// Custom permission logic based on your business rules
return user.organizations.includes(orgId) &&
user.hasRole('organization_admin');
}3. Token Scoping
Widget tokens are scoped to specific resources (person + organization), limiting what can be modified.
Best Practices
1. Progressive Enhancement
Ensure your site works without JavaScript before adding widgets:
<!-- Fallback content for no-JS users -->
<div id="profile-container">
<noscript>
<p>Please enable JavaScript to edit your profile, or
<a href="/account/edit">use the basic form</a>.</p>
</noscript>
</div>2. Loading States
Show loading indicators while widgets initialize:
const container = document.getElementById('profile-container');
container.innerHTML = '<div class="loading">Loading profile editor...</div>';
Wicket.widgets.createPersonProfile({
accessToken: token,
personId: personId,
rootEl: container
}).then(function(widget) {
// Loading indicator automatically replaced by widget
});3. Error Handling
Handle widget initialization errors gracefully:
Wicket.widgets.createPersonProfile(config)
.then(function(widget) {
// Success
})
.catch(function(error) {
console.error('Widget failed to load:', error);
container.innerHTML = '<p class="error">Unable to load profile editor. Please try again later.</p>';
});4. Event Monitoring
Listen for save events to provide feedback:
widget.listen(widget.eventTypes.SAVE_SUCCESS, function(payload) {
showNotification('Changes saved successfully!');
});Common Use Cases
Member Account Center
Combine multiple widgets to create a complete account management experience:
<div id="profile-section">
<!-- Person profile editing -->
</div>
<div id="preferences-section">
<!-- Communication preferences -->
</div>
<div id="organizations-section">
<!-- Organization management (with widget tokens) -->
</div>Self-Service Organization Profiles
Allow organization administrators to update their company information:
// Server-side: Generate token with permission check
if (userIsOrgAdmin(userId, orgId)) {
const widgetToken = await createWidgetToken(userId, orgId);
res.json({ token: widgetToken });
}
// Client-side: Render widget
Wicket.widgets.editOrganizationProfile({
accessToken: widgetToken,
orgId: organizationId,
rootEl: document.getElementById('org-editor')
});Performance Considerations
1. Lazy Loading
Load widget script only when needed:
function loadWidgetScript() {
if (!document.getElementById('wicket-widgets')) {
const script = document.createElement('script');
script.id = 'wicket-widgets';
script.src = 'https://your-tenant-admin.wicketcloud.com/dist/widgets.js';
document.body.appendChild(script);
}
}
// Load on user interaction
document.getElementById('edit-profile-btn').addEventListener('click', function() {
loadWidgetScript();
// Initialize widget after script loads
});2. Widget Cleanup
Remove widgets when no longer needed:
const widget = await Wicket.widgets.createPersonProfile(config);
// Later, when navigating away or closing modal:
widget.clear(); // Removes widget from DOM and cleans up listeners