=== Samba Booking Widgets ===
Contributors: sambahq
Tags: booking calendar, reservation calendar, booking system, travel, tours
Requires at least: 6.6
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add your Samba tour & activity booking widgets to WordPress — Book Now, calendar, departures, product grid. No HTML.

== Description ==

**Samba Booking Widgets** puts your [Samba](https://www.sambahq.com/)
tour and activity booking widgets on your WordPress site — no HTML, no hand-copied
iframes. Paste your workspace key once, then drop a **Book Now** button, an
**availability calendar**, an **upcoming departures** list, or a **product grid**
onto any page with a Gutenberg block or a shortcode. Widget types and options are
served live from your Samba account, with a real-time preview in the block editor.

It's built for **tour operators, activity providers and travel agencies** that take
bookings with Samba and want them on their own WordPress site in minutes.

= Booking widgets you can embed =

* **Book Now button** — opens Samba checkout in a modal, with an optional "from" price.
* **Upcoming Departures** — a live list of your next departures with seats and prices.
* **Calendar** — a month view showing availability, times and prices per day.
* **Product List** — a card grid of your trips with images and next departures.

= Why tour operators use it =

* **No code, no HTML** — pick a widget and a trip from dropdowns, and a live preview shows exactly what visitors will see.
* **Always up to date** — trips, prices and availability come straight from Samba, so your site never shows stale information.
* **Works everywhere** — a Gutenberg block, a native **Elementor** widget, and a `[samba_widget]` shortcode for classic themes and other page builders.
* **Secure** — your Samba key stays on your server and is never shown to visitors.
* **Fast** — the booking script loads only on pages that use a widget.

= Comparing Samba with FareHarbor, Bokun, Rezdy, Peek Pro, WeTravel or WP Travel Engine? =

Samba is a modern booking platform for tour and activity operators — an alternative
both to SaaS systems and to self-hosted WordPress booking plugins like WP Travel
Engine. If you're weighing it against another system, read the honest, side-by-side
breakdowns:

* [Samba vs FareHarbor](https://www.sambahq.com/alternatives/fareharbor)
* [Samba vs Peek Pro](https://www.sambahq.com/alternatives/peek-pro)
* [Samba vs Bókun](https://www.sambahq.com/alternatives/bokun)
* [Samba vs Rezdy](https://www.sambahq.com/alternatives/rezdy)
* [Samba vs WeTravel](https://www.sambahq.com/alternatives/wetravel)

Once you're on Samba, this plugin is how you put your booking widgets on WordPress.

= How it works =

1. Connect once in **Settings → Samba** with your workspace secret key.
2. Add the **Samba** block to any page or post, then pick a widget type and experience — or place `[samba_widget]` in your content.
3. Publish. The widget renders live from your Samba account.

A Samba account is required. Find your workspace secret key in the Samba dashboard
under Settings → Website Widgets → WordPress.

== Installation ==

1. Install the plugin from Plugins → Add New, or upload the plugin folder to
   `wp-content/plugins/`.
2. Activate the plugin through the Plugins screen.
3. Go to Settings → Samba and paste your Samba workspace secret key.
4. Add a "Samba" block to any page or post, choose a widget type and experience,
   and publish. (Or place `[samba_widget]` in your content.)

== Frequently Asked Questions ==

= Do I need a Samba account? =

Yes. The plugin embeds widgets from your Samba workspace, so you need a Samba
account and a workspace secret key. It does not create bookings on its own — it
displays and connects to your existing Samba booking platform.

= Where do I find my secret key? =

In your Samba dashboard, under Settings → Website Widgets → WordPress.

= Which booking widgets can I add? =

Book Now button, Upcoming Departures, Calendar, and Product List. New widget types
and options appear automatically as they are added to your Samba account.

= Do I need to write any HTML or code? =

No. You pick a widget and a trip from dropdowns in the block editor, with a live
preview so you can see the widget before you publish. The plugin handles the rest.

= Does it work with my theme and page builder? =

Yes. Use the Samba block in the block editor and block themes, the native **Samba
widget for Elementor**, or the `[samba_widget]` shortcode anywhere else (classic
themes, widget areas, and other page builders). It also coexists with WooCommerce.

= How do I use the [samba_widget] shortcode? =

Use `[samba_widget]` with a `type` and (where needed) an `experience` slug. Any other
attribute is passed to the widget as an option:

* `[samba_widget type="book-now" experience="your-experience" label="Book now"]`
* `[samba_widget type="upcoming-departures" experience="your-experience"]`
* `[samba_widget type="calendar" experience="your-experience"]`
* `[samba_widget type="product-list"]`

= Will it slow down my site? =

No. The booking script loads only on the pages that use a Samba widget, so the rest
of your site is unaffected.

= Is my Samba key safe? =

Yes. Your secret key is stored on your server and is never shown to visitors or
added to your pages — only the public information needed to display your widgets
reaches the browser.

= Do I have to update the plugin when new widget options are released? =

No. Widget types and their options are served live from the Samba API, so new
options appear automatically.

== External services ==

This plugin connects to [Samba](https://www.sambahq.com) to validate your account
and display live booking widgets. It requires a Samba account. It connects to two
Samba services:

1. Samba API — `https://api.sambahq.com`

   * What it does: validates your workspace secret key and loads your widget
     configuration, experiences, and booking data.
   * What is sent, and when: when you save your key in Settings → Samba, and when
     the block editor loads, your site makes server-side requests to the Samba API
     that include your secret key in an Authorization header. Your secret key is
     stored on your server and is never sent to the visitor's browser.
   * On the front end, widgets request public booking data (such as availability,
     departures, and prices) for the widget and experience you configured,
     identified only by your public workspace slug.

2. Samba embed script — `https://files.sambahq.com/widgets/embed.js`

   * What it does: loaded only on pages that contain a Samba widget, it renders
     the widget in the visitor's browser and fetches public booking data from the
     Samba API for the configured widget.

Your use of Samba is governed by Samba's [Terms of Service](https://www.sambahq.com/terms)
and [Privacy Policy](https://www.sambahq.com/privacy).

== Screenshots ==

1. Finding your workspace key in Samba, under Settings, Website Widgets, WordPress.
2. Connecting your workspace on the Samba settings screen in WordPress.
3. Choosing a widget type and experience from the Samba block in the editor.
4. Configuring widget options with a live preview in the block editor.
5. Book Now button on the front end.
6. Upcoming Departures list on the front end.
7. Calendar widget on the front end.
8. Product List widget on the front end.

== Development ==

The block's uncompiled source ships in `src/`; the files in `build/` are
generated from it with @wordpress/scripts (`npm run build`).

== Changelog ==

= 1.0.0 =
* Connect with a secret key; workspace and experiences resolved server-side.
* Gutenberg block and shortcode emit Samba widgets, with a live preview in the editor.
* Widget types and options are driven by the Samba API (no plugin update for new options).
* Widgets support wide and full alignment, so lists and calendars can break out of the content column.
* Native Elementor widget — drag "Samba" into any Elementor page and configure it from the panel (no shortcode needed).
