Pre-release — content may change.

Widgets

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:

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:

  1. Universal Embed Script — Load the Wicket Widgets SDK
  2. Widget Initialization — Configure and render widgets in your page
  3. 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, editAdditionalInfo for 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-side

2. 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

On this page