Portalize Widget Embedding Guide

Welcome to the Portalize widget integration guide. This document provides step-by-step instructions for embedding the Portalize events widget on your website.

Pricing & Activation

The Portalize widget is a paid premium feature that requires manual activation. To get started:

Contact: jan@schafe-vorm-fenster.de
Request: Widget activation for your organization
Receive: Your unique organizer ID after approval

Note: The widget cannot be used without an activated organizer ID.

Prerequisites

Before embedding the widget, you need:

Organizer ID - A unique identifier provided after activation
Website Access - Ability to add JavaScript or iframe code to your site

Configuration Options

The widget supports the following configuration filters to customize the displayed events:

Filter	Type	Description	Example
`organizerId`	string	Your unique organizer identifier (required)	`"org-12345"`
`category`	string	Filter events by category	`"workshop"`, `"concert"`
`location`	string	Filter events by location	`"Berlin"`, `"Munich"`
`dateFrom`	string	Show events starting from this date (ISO 8601)	`"2025-01-01"`
`dateTo`	string	Show events up to this date (ISO 8601)	`"2025-12-31"`
`limit`	number	Maximum number of events to display	`10`, `25`, `50`

Integration Methods

Method 1: Script-Based Embed (Recommended)

The script-based approach provides the most seamless integration with automatic updates and responsive behavior.

Steps:

Add the widget script to your HTML page's <head> or just before </body>:

<script src="https://your-widget-host-domain.com/dist/widget.umd.js"></script>

Create a container element where you want the widget to appear:

<div id="portalize-widget"></div>

Initialize the widget with your configuration:

<script>
  const config = {
    organizerId: "YOUR_ORGANIZER_ID",
    category: "workshop",
    limit: 10
  };
  
  // Initialize the widget
  window.PortalizeWidget.init('#portalize-widget', config);
</script>

Complete Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Events</title>
  <script src="https://your-widget-host-domain.com/dist/widget.umd.js"></script>
</head>
<body>
  <h1>Upcoming Events</h1>
  <div id="portalize-widget"></div>
  
  <script>
    const config = {
      organizerId: "YOUR_ORGANIZER_ID",
      category: "workshop",
      dateFrom: "2025-01-01",
      limit: 25
    };
    
    window.PortalizeWidget.init('#portalize-widget', config);
  </script>
</body>
</html>

Method 2: Iframe Integration

The iframe approach provides complete isolation and is ideal when you want to prevent any CSS or JavaScript conflicts.

Steps:

Add an iframe element to your HTML:

<iframe 
  src="https://your-widget-host-domain.com/embed/YOUR_ORGANIZER_ID?config={}"
  width="100%"
  height="600"
  frameborder="0"
  title="Portalize Events Widget">
</iframe>

Customize the widget by URL-encoding your configuration as a JSON string in the config parameter:

<iframe 
  src="https://your-widget-host-domain.com/embed/YOUR_ORGANIZER_ID?config=%7B%22category%22%3A%22workshop%22%2C%22limit%22%3A10%7D"
  width="100%"
  height="600"
  frameborder="0"
  title="Portalize Events Widget">
</iframe>

Configuration with filters:

The config parameter accepts a URL-encoded JSON object. Here's how to build it:

// Your configuration object
const config = {
  category: "workshop",
  limit: 10,
  dateFrom: "2025-01-01"
};

// URL-encode it
const encodedConfig = encodeURIComponent(JSON.stringify(config));

// Use in iframe src
const iframeSrc = `https://your-widget-host-domain.com/embed/YOUR_ORGANIZER_ID?config=${encodedConfig}`;

Complete Iframe Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Events</title>
  <style>
    .widget-container {
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
    }
  </style>
</head>
<body>
  <div class="widget-container">
    <h1>Upcoming Events</h1>
    <iframe 
      src="https://your-widget-host-domain.com/embed/YOUR_ORGANIZER_ID?config=%7B%22category%22%3A%22workshop%22%2C%22limit%22%3A25%7D"
      width="100%"
      height="800"
      frameborder="0"
      title="Portalize Events Widget">
    </iframe>
  </div>
</body>
</html>

Responsive Design

Both integration methods support responsive design:

Script-based: The widget automatically adapts to its container width
Iframe: Set width="100%" and adjust height as needed, or use CSS to make it responsive:

.widget-container iframe {
  width: 100%;
  min-height: 600px;
  border: none;
}

Troubleshooting

Widget not appearing?

Check your organizer ID: Ensure it matches the ID provided during activation
Verify the script URL: Make sure the widget script is loading correctly (check browser console)
Check for JavaScript errors: Open browser developer tools and look for error messages

Events not loading?

Validate your configuration: Ensure date formats use ISO 8601 (YYYY-MM-DD)
Check filter values: Verify category and location values match available options
Contact support: If issues persist, reach out to jan@schafe-vorm-fenster.de

Support

For questions, issues, or feature requests:

Email: jan@schafe-vorm-fenster.de
Include: Your organizer ID and a description of the issue

Last updated: 2025