soapKit

An Elementor-powered toolkit for WooCommerce shops and hotel / single-room sites.

• Header & footer positioning with sticky-header offset compensation
• A native Elementor Theme Builder with chip-based display conditions
• A managed Elements page where every shipped widget can be toggled on/off
• A complete Single Room widget suite (16 widgets) for hotel / room CPTs
• 12 free WooCommerce / header widgets (cart, wishlist, mini-cart, product grid, etc.)
• 23 PRO placeholders for future upsell (visual only, no class loaded)

Requirements

• WordPress 6.3+ (uses the bundled swiper script for carousels)
• PHP 7.4+
• Elementor 3.10+
• Advanced Custom Fields Pro 5.x+ — required to get the room UI in the post editor. The widgets still work without ACF (native post-meta fallback) but you'll have no admin screen for them.
• WooCommerce 7+ — only for the cart / wishlist / product widgets. Not required for the room widget suite.

Installation

1. Copy this whole folder to wp-content/plugins/ (or upload the zip via Plugins → Add New → Upload).
2. Activate soapKits in Plugins.
3. Open soapKits → Elements in the sidebar to confirm the plugin loaded.

Setup: import the ACF field group

This is the most important step for the room widgets.

1. Install & activate Advanced Custom Fields Pro.
2. In WP admin, go to Custom Fields → Field Groups (under "Custom Fields" in the sidebar).
3. Click the "Import Field Groups" button in the top toolbar.
4. Select the file docs/acf-room-field-group.json from this plugin folder and import.
5. Open the imported field group (named "SoapKits — Room Widget Fields").
6. In the Location Rules meta box, change Post Type is equal to room to your actual room CPT slug (e.g. hotel_room, soapkit_room, etc.).
7. Click Update.

You will now see 20 fields on every room post edit screen: Room Gallery, Room Price, Max Occupancy, Booking Link, Room Video, Room Location, Room Amenities (repeater), Room Features (repeater), Room Phone / WhatsApp / Email, Room Rating, Room Number / Floor / Type, Check-in / Check-out.

If you don't use ACF, every widget still works — it falls back to plain WordPress post meta using the same field keys. You just won't have a UI to edit them; use update_post_meta() from functions.php or a custom plugin.

Setup: room custom post type

The plugin does not register the room CPT for you (every property uses different slug/taxonomies). Make sure your existing CPT:

• Has supports => [ 'title', 'editor', 'thumbnail', 'comments', … ] (comments are required for the Reviews widget)
• Has a taxonomy registered (e.g. room_type or hotel_amenity). The Room Related Rooms widget uses the first taxonomy it finds that has terms on the current room.
• Is publicly queryable.

The room-context detection in the plugin looks for any post type whose slug or labels contain the word "room" (hotel_room, room, soapkit_room, etc.), so you don't have to whitelist a specific slug.

Setup: header & footer

The plugin ships its own Template Handler that injects header and footer templates. The simplest path:

1. In Elementor, open Templates → Theme Builder (or Templates → Saved Templates, depending on your Elementor version).
2. Add two new templates:
   • Header — design as you normally would, hit Publish.
   • Footer — same, hit Publish.
3. In the soapKits → Conditions meta box on each template, set where the template appears:
   • Add conditions like Entire Site, Singular: room, Singular: post, Singular: page, etc.
   • Use the "Display Across Entire Site" preset for a one-click global header/footer.
4. Hit Save Conditions. The plugin will register the wrapper IDs (soapkits-header, soapkits-footer), add the body classes (soapkits-has-header, soapkits-has-footer, plus the singular-{post-type} variants), and enqueue its tiny CSS/JS that hides the theme's default header/footer and compensates the page for the sticky-header height.

If your theme already supplies a header, add this CSS to silence it:

body.soapkits-has-header .site-header,
body.soapkits-has-header header#masthead { display: none !important; }

The plugin emits the same set of wrapper IDs and body classes in both spellings — soapkits-* and soapkit-* (singular) — so pick whichever your CSS targets.

Setup: enable / disable widgets

Go to soapKits → Elements in the sidebar. You'll see a card grid with every shipped widget, grouped by category (Header, WooCommerce, Products, Marketing, Single Room, …). Each card has an on/off toggle:

• Free widgets — toggle freely. State is stored in the soapkits_widgets_enabled option.
• PRO widgets — visual only, badge is shown but the toggle is locked to off.

Use the Enable All / Disable All buttons at the top of any category to mass-toggle. The state is saved via AJAX when you flip a switch.

Single Room widgets (16)

All under the Elementor category "Single Room" (soapkits-room). Every widget:

• Detects whether it's rendered in a single-room context. Off-room, it shows a friendly notice in the editor and renders nothing on the front-end.
• Reads its field via Room_Fields::get() — ACF first, then get_post_meta() fallback.
• Provides editor-only empty-state notices when the source field is empty.

Icon library

Amenities, Features, and Meta widgets share an inline SVG library (no external icon font, no font Awesome). Icons resolve from a name like wifi, pool, ac, tv, parking, breakfast, coffee, bath, shower, bed, safe, pet, smoke, no-smoke, phone, restaurant, gym, spa, fire, plus generic check and star. Any icon can also be a full URL or inline <svg>…</svg> markup.

WooCommerce / header widgets (12 free)

Plugin structure

soapkits/
├── soapkits.php                  (plugin header)
├── includes/
│   ├── class-plugin.php          (Elementor register hook, widget autoloader)
│   ├── class-assets.php          (style/script registry)
│   ├── class-template-handler.php(header/footer injection + body classes)
│   ├── class-theme-builder.php   (Conditions meta box, chip UI)
│   ├── class-conditions.php      (token matcher + filter hook)
│   ├── class-widget-registry.php(Elements page widget list)
│   ├── class-admin-menu.php      (Elements page UI + AJAX)
│   ├── class-nav-menu-widget.php(free widget)
│   ├── class-room-fields.php     (single source of truth for room field access)
│   └── …
├── widgets/
│   ├── *-widget.php              (free, non-room widgets)
│   └── room/
│       ├── class-room-base.php              (abstract base)
│       ├── class-room-title-widget.php      (16 room widgets)
│       └── …
├── assets/
│   ├── css/
│   │   ├── kit-global.css        (page-level flex layout, header offset)
│   │   ├── admin.css             (Elements page styles)
│   │   └── widgets/
│   │       ├── nav-menu.css
│   │       ├── room-featured-image.css
│   │       ├── room-gallery.css
│   │       └── …
│   └── js/
│       ├── kit-global.js         (header height measurement)
│       ├── admin.js              (Elements page toggle UI)
│       └── widgets/
│           ├── room-related.js   (Swiper carousel)
│           └── room-gallery.js   (Swiper carousel)
└── docs/
    ├── room-widgets-plan.md      (full design plan for the room suite)
    └── acf-room-field-group.json (20-field ACF export, ready to import)

Developer hooks

// Add your own widget to the "Single Room" category automatically:
add_action( 'soapkits_room_widgets_registered', function( $manager ) {
    $manager->register( new \My\My_Room_Widget() );
});

// Override the room context detection (e.g. force-enable on a CPT):
add_filter( 'soapkits_is_room_context', function( $is_room, $post_type ) {
    if ( $post_type === 'accommodation' ) {
        return true;
    }
    return $is_room;
}, 10, 2 );

// Add your own conditions token:
add_filter( 'soapkits_conditions_known_tokens', function( $tokens ) {
    $tokens['my-template'] = __( 'My Custom Template', 'soapkits' );
    return $tokens;
} );

// Match the token at runtime:
add_filter( 'soapkits_conditions_token_match', function( $matched, $token, $value ) {
    if ( $token === 'my-template' && is_page( 'special-offer' ) ) {
        return true;
    }
    return $matched;
}, 10, 3 );

Troubleshooting

Widgets don't appear in Elementor.

• Go to soapKits → Elements and confirm the widget is toggled on.
• Deactivate other Elementor addons that might be registering widgets with the same name (rare).
• Check wp-content/debug.log for fatal errors.

Carousel arrows don't navigate.

• Make sure nothing on the page is calling Swiper.destroy() or running multiple Swiper initializations.
• The plugin uses the swiper script shipped with WordPress 6.3+ as a dependency. Older WP versions need Elementor ≥ 3.11 (which bundles its own Swiper).

ACF fields are not showing on the room edit screen.

• You forgot to change the Location Rule in the imported field group to match your real room CPT slug.

The room widget shows an editor notice like "This post type does not have comments enabled".

• Add 'supports' => [ …, 'comments' ] to your register_post_type() call.

Sticky header doesn't offset the page correctly.

• The plugin measures the header height via JS and writes it to a CSS custom property --soapkits-header-height. Make sure the page has the soapkits-has-header body class. Check the body classes in your browser dev tools.

License

GPL v2 or later.

Author

soapKits Team.