README

Experience personalised shopping like never before. This Magento 2 / Hyvä-compatible module lets customers book one-on-one appointments with expert stylists directly from the storefront. Store administrators manage employees, departments, schedules, and appointment requests — all from the Magento Admin Panel.

Composer package: mhinspeya/mhinspeya-hyva-personal-shopping Module name: MHinspeya_AppointmentShopping Current version: 1.0.3 License: OSL-3.0

Table of Contents

• Features
• Requirements
• Installation
  • Via Composer (Recommended)
  • Manual Installation (app/code)
• Configuration
  • General Settings
  • Email Options
• Admin Panel Management
  • Manage Departments
  • Manage Employees
  • Manage Appointments
• Frontend Booking Flow
• How to Embed the Booking Form
• REST API Endpoints
• Database Schema
• ACL Permissions
• Hyvä Theme Compatibility
• Translations
• Uninstallation
• Support

Features

Storefront

• Interactive appointment booking — customers browse available employees per department and select a date/time slot
• Dynamic calendar & time-slot picker — available days and slots are computed from each employee's configured schedule (weekly availability, start/end time, break windows, appointment duration)
• Duplicate booking prevention — the system checks existing appointments to prevent double bookings for the same slot
• Automatic email notifications — confirmation emails are sent to both the customer and the assigned employee upon booking
• Hyvä Theme compatible — ships with Hyvä Tailwind templates, Alpine.js integration, and auto-registers via the Hyvä config observer
• Configurable age limit — enforce a minimum customer age at the form level
• Timezone-aware scheduling — supports configurable timezone for accurate slot calculations
• Customisable heading & sub-heading — admin-configurable page title and description text

Admin Panel

• Department management — create and manage store departments (e.g. Menswear, Womenswear, Childrenswear) with individual email contacts, sort order, and status toggle
• Employee management — add employee profiles with name, department assignment, email, profile image upload, bio/content, weekly schedule configuration (available days, time range, break slots, appointment duration), sort order, and status
• Appointment management — view, confirm, or reject customer appointment requests from a dedicated admin grid
• Approve / Reject workflow — one-click confirm or disapprove with automatic notification emails sent to the customer
• UI Component grids & forms — fully integrated Magento Admin UI Component listing grids with inline editing support for all three entities
• Mass actions — mass delete and mass status change on employee listings
• Image uploader — dedicated image upload handler for employee profile photos
• Seed data — ships with sample CSV data for departments, employees, and appointment forms, imported via a modern Magento data patch

Requirements

Installation

Via Composer (Recommended)

# 1. Require the package
composer require mhinspeya/mhinspeya-hyva-personal-shopping

# 2. Enable the module
bin/magento module:enable MHinspeya_AppointmentShopping

# 3. Run setup upgrade (runs data patches and creates DB tables)
bin/magento setup:upgrade

# 4. Compile DI
bin/magento setup:di:compile

# 5. Deploy static content (production mode)
bin/magento setup:static-content:deploy -f

# 6. Flush cache
bin/magento cache:flush

Manual Installation (app/code)

# 1. Create the module directory
mkdir -p app/code/MHinspeya/AppointmentShopping

# 2. Copy or clone the module files into the directory
cp -r <source-path>/* app/code/MHinspeya/AppointmentShopping/

# 3. Enable the module
bin/magento module:enable MHinspeya_AppointmentShopping

# 4. Run setup upgrade
bin/magento setup:upgrade

# 5. Compile DI
bin/magento setup:di:compile

# 6. Deploy static content (production mode)
bin/magento setup:static-content:deploy -f

# 7. Flush cache
bin/magento cache:flush

Configuration

Navigate to Stores → Configuration → Personal Shopping → Personal Shopping Configuration in the Magento Admin Panel.

General Settings

Email Options

Admin Panel Management

All management grids are accessible under MHinspeya → Personal Shopping in the admin sidebar.

Manage Departments

Path: MHinspeya → Personal Shopping → Manage Departments

Create and manage store departments. Each department has:

Manage Employees

Path: MHinspeya → Personal Shopping → Manage Employees

Add and configure employee/stylist profiles. Each employee has:

Schedule Configuration Fields:

Manage Appointments

Path: MHinspeya → Personal Shopping → Manage Appointments

View and manage all customer booking submissions:

Frontend Booking Flow

1. Customer visits the personal shopping page (/appointmentshopping/index/...)
2. Active departments and employees are displayed
3. Customer selects a department → available employees are shown
4. Customer selects an employee → the interactive calendar loads (AJAX call to /appointmentshopping/index/appointmentcalender)
5. Available dates and time slots are computed from the employee's schedule configuration
6. Customer fills in the booking form (name, email, phone, date of birth, preferred slot, optional message)
7. Form is submitted via AJAX to /appointmentshopping/index/appointmentbooking
8. System validates for duplicate bookings, saves the appointment, and sends confirmation emails to both the customer and the employee
9. Success/error message is displayed to the customer

How to Embed the Booking Form

You can display the booking form on any CMS page, block, layout XML file, or PHTML template using the following methods:

1. In a CMS Page or Block (CMS Content)

Insert the template block markup inside your CMS page content or block editor:

{{block class="Magento\Framework\View\Element\Template" template="MHinspeya_AppointmentShopping::appointment.phtml"}}

2. In Layout XML

Add the block definition to your layout XML file (e.g., cms_page_view.xml):

<block class="Magento\Framework\View\Element\Template" name="appointment.shopping.form" template="MHinspeya_AppointmentShopping::appointment.phtml" />

3. In a PHTML Template (PHP code)

Call the layout class dynamically inside another PHTML template:

<?= $block->getLayout()->createBlock(\Magento\Framework\View\Element\Template::class)
    ->setTemplate('MHinspeya_AppointmentShopping::appointment.phtml')
    ->toHtml() ?>

ACL Permissions

The module provides granular ACL resources under MHinspeya_AppointmentShopping:

REST API endpoints are protected by corresponding CRUD ACL resources (_save, _update, _delete, _view).

Hyvä Theme Compatibility

This module is fully compatible with the Hyvä theme. It includes:

• A Hyvä config observer (RegisterModuleForHyvaConfig) that auto-registers the module's frontend path with the Hyvä configuration system
• Tailwind CSS integration via the view/frontend/tailwind/ directory
• Alpine.js-ready .phtml templates in view/frontend/templates/
• No RequireJS or Knockout.js dependencies on the frontend

Translations

The module ships with a German (de_DE) translation file located at:

i18n/de_DE.csv

To add additional translations, create a new CSV file in the i18n/ directory following the Magento convention (e.g. en_US.csv, fr_FR.csv).

Uninstallation

Composer Installation

bin/magento module:disable MHinspeya_AppointmentShopping
composer remove mhinspeya/mhinspeya-hyva-personal-shopping
bin/magento setup:upgrade
bin/magento cache:flush

Manual Installation

bin/magento module:disable MHinspeya_AppointmentShopping
rm -rf app/code/MHinspeya/AppointmentShopping
bin/magento setup:upgrade
bin/magento cache:flush

Note: Uninstalling the module does not automatically drop the database tables. To remove them manually, drop mhinspeya_appointmentshopping_employeeappointment, mhinspeya_appointmentshopping_employeedepartment, and mhinspeya_appointmentshopping_employeeappointmentform.

Support

• Website: https://inspeya.com
• Author: MHinspeya — Magento 2 Extension Provider

For issues or feature requests, please contact us through our website.