Initial commit: prestashop-entity-selector
Forked from prestashop-target-conditions Renamed all references from target-conditions to entity-selector
This commit is contained in:
574
README.md
Executable file
574
README.md
Executable file
@@ -0,0 +1,574 @@
|
||||
# PrestaShop Condition Traits
|
||||
|
||||
A collection of reusable PHP traits for PrestaShop admin controllers that provide powerful UI widgets for targeting and scheduling.
|
||||
|
||||
## Available Traits
|
||||
|
||||
| Trait | Purpose |
|
||||
|-------|---------|
|
||||
| **TargetConditions** | Multi-criteria targeting (countries, currencies, carriers, groups, languages) |
|
||||
| **ScheduleConditions** | Time-based scheduling (datetime range, weekly schedule, holiday exclusions) |
|
||||
|
||||
## Installation
|
||||
|
||||
### Via Composer
|
||||
|
||||
```bash
|
||||
composer require myprestarocks/prestashop-target-conditions
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
Copy the package to your module's vendor directory:
|
||||
```
|
||||
modules/your_module/vendor/myprestarocks/prestashop-target-conditions/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# TargetConditions Trait
|
||||
|
||||
A powerful multi-criteria targeting widget. Allows users to define conditions based on countries, currencies, carriers, customer groups, and languages.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### 1. Include the Trait in Your Admin Controller
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use MyPrestaRocks\TargetConditions\TargetConditions;
|
||||
|
||||
class AdminYourModuleController extends ModuleAdminController
|
||||
{
|
||||
use TargetConditions;
|
||||
|
||||
// Your controller code...
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Register Assets in setMedia()
|
||||
|
||||
```php
|
||||
public function setMedia($isNewTheme = false)
|
||||
{
|
||||
parent::setMedia($isNewTheme);
|
||||
|
||||
// Register the target conditions assets
|
||||
$this->registerTargetConditionsAssets();
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Add the Widget to Your Form
|
||||
|
||||
In your form rendering method (e.g., `renderForm()`), add the widget:
|
||||
|
||||
```php
|
||||
public function renderForm()
|
||||
{
|
||||
// Get existing restrictions from database (JSON string or array)
|
||||
$restrictions = $this->object->restrictions ?? '[]';
|
||||
|
||||
$this->fields_form = [
|
||||
'legend' => [
|
||||
'title' => $this->l('Configuration'),
|
||||
],
|
||||
'input' => [
|
||||
[
|
||||
'type' => 'free',
|
||||
'label' => $this->l('Target Conditions'),
|
||||
'name' => 'restrictions_widget',
|
||||
'desc' => $this->l('Define where this item should be available'),
|
||||
],
|
||||
],
|
||||
// ... other fields
|
||||
];
|
||||
|
||||
// Render the widget HTML
|
||||
$this->fields_value['restrictions_widget'] = $this->renderTargetConditionsHtml(
|
||||
'restrictions', // Field name for form submission
|
||||
$restrictions, // Current value (JSON or array)
|
||||
[
|
||||
// Configuration options (see below)
|
||||
]
|
||||
);
|
||||
|
||||
return parent::renderForm();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Process the Submitted Data
|
||||
|
||||
```php
|
||||
public function postProcess()
|
||||
{
|
||||
if (Tools::isSubmit('submitYourForm')) {
|
||||
$restrictions = Tools::getValue('restrictions');
|
||||
|
||||
// The value is already JSON-encoded from the widget
|
||||
// Store it in your database
|
||||
$this->object->restrictions = $restrictions;
|
||||
$this->object->save();
|
||||
}
|
||||
|
||||
return parent::postProcess();
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
The `renderTargetConditionsHtml()` method accepts a configuration array as the third parameter:
|
||||
|
||||
```php
|
||||
$this->renderTargetConditionsHtml('field_name', $value, [
|
||||
// Available condition groups to show
|
||||
// Default: all groups enabled
|
||||
'groups' => [
|
||||
'countries' => true, // Country selection
|
||||
'currencies' => true, // Currency selection
|
||||
'carriers' => true, // Carrier/shipping method selection
|
||||
'groups' => true, // Customer group selection
|
||||
'languages' => true, // Language selection
|
||||
],
|
||||
|
||||
// Empty selection behavior
|
||||
// true = empty means "all included" (available everywhere)
|
||||
// false = empty means "none selected" (not available anywhere)
|
||||
'empty_means_all' => true,
|
||||
|
||||
// Show "All X" toggle badges
|
||||
// When set, displays toggle buttons showing selection state
|
||||
'show_all_toggle' => [
|
||||
'empty' => $this->l('Available Everywhere'), // Label when nothing selected
|
||||
'selected' => $this->l('Restricted'), // Label when items selected
|
||||
],
|
||||
|
||||
// Show group modifiers (Limit/Sort controls)
|
||||
// true = show limit dropdown and sort controls per group
|
||||
// false = hide modifiers (cleaner UI for targeting contexts)
|
||||
'show_modifiers' => true,
|
||||
|
||||
// Pre-filter available options based on external restrictions
|
||||
// Useful when parent entity has its own restrictions
|
||||
'restrictions' => [
|
||||
'countries' => ['FR', 'DE', 'PL'], // Only show these countries
|
||||
'currencies' => ['EUR', 'PLN'], // Only show these currencies
|
||||
// ... etc
|
||||
],
|
||||
|
||||
// Custom labels for condition groups
|
||||
'labels' => [
|
||||
'countries' => $this->l('Countries'),
|
||||
'currencies' => $this->l('Currencies'),
|
||||
'carriers' => $this->l('Carriers'),
|
||||
'groups' => $this->l('Customer Groups'),
|
||||
'languages' => $this->l('Languages'),
|
||||
],
|
||||
]);
|
||||
```
|
||||
|
||||
## Use Case Examples
|
||||
|
||||
### Payment Method Targeting
|
||||
|
||||
Restrict payment methods to specific countries/currencies:
|
||||
|
||||
```php
|
||||
$this->renderTargetConditionsHtml('restrictions', $paymentOption->restrictions, [
|
||||
'groups' => [
|
||||
'countries' => true,
|
||||
'currencies' => true,
|
||||
'carriers' => false, // Not relevant for payments
|
||||
'groups' => true,
|
||||
'languages' => false,
|
||||
],
|
||||
'empty_means_all' => true,
|
||||
'show_modifiers' => false, // No need for limit/sort on targeting
|
||||
'show_all_toggle' => [
|
||||
'empty' => $this->l('Available Everywhere'),
|
||||
'selected' => $this->l('Restricted'),
|
||||
],
|
||||
]);
|
||||
```
|
||||
|
||||
### Product Selection Widget
|
||||
|
||||
Select products with quantity limits:
|
||||
|
||||
```php
|
||||
$this->renderTargetConditionsHtml('selected_products', $rule->products, [
|
||||
'groups' => [
|
||||
'products' => true,
|
||||
],
|
||||
'empty_means_all' => false, // Must explicitly select products
|
||||
'show_modifiers' => true, // Allow limiting quantity per selection
|
||||
]);
|
||||
```
|
||||
|
||||
### Shipping Rules
|
||||
|
||||
Define carrier availability by zone:
|
||||
|
||||
```php
|
||||
$this->renderTargetConditionsHtml('availability', $carrier->zones, [
|
||||
'groups' => [
|
||||
'countries' => true,
|
||||
'groups' => true, // Different rates for customer groups
|
||||
],
|
||||
'empty_means_all' => true,
|
||||
'show_all_toggle' => [
|
||||
'empty' => $this->l('Ships Everywhere'),
|
||||
'selected' => $this->l('Limited Zones'),
|
||||
],
|
||||
]);
|
||||
```
|
||||
|
||||
## Data Format
|
||||
|
||||
The widget stores data as a JSON object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"countries": {
|
||||
"items": ["FR", "DE", "PL"],
|
||||
"limit": 0,
|
||||
"sort": "default"
|
||||
},
|
||||
"currencies": {
|
||||
"items": ["EUR", "PLN"],
|
||||
"limit": 0,
|
||||
"sort": "default"
|
||||
},
|
||||
"carriers": {
|
||||
"items": [],
|
||||
"limit": 0,
|
||||
"sort": "default"
|
||||
},
|
||||
"groups": {
|
||||
"items": [1, 2, 3],
|
||||
"limit": 0,
|
||||
"sort": "default"
|
||||
},
|
||||
"languages": {
|
||||
"items": [],
|
||||
"limit": 0,
|
||||
"sort": "default"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Field Descriptions
|
||||
|
||||
- **items**: Array of selected IDs or ISO codes
|
||||
- **limit**: Maximum items to use (0 = no limit)
|
||||
- **sort**: Sort order for items ("default", "asc", "desc", "random")
|
||||
|
||||
## Selection Logic
|
||||
|
||||
### When `empty_means_all` is `true` (default):
|
||||
- Empty selection = item available for ALL values in that group
|
||||
- Selection made = item restricted to ONLY selected values
|
||||
|
||||
### When `empty_means_all` is `false`:
|
||||
- Empty selection = item NOT available (nothing selected)
|
||||
- Selection made = item available for selected values only
|
||||
|
||||
### Restriction Inheritance
|
||||
|
||||
When using the `restrictions` config option, the widget will only display options that match the parent restrictions. This is useful for hierarchical configurations where child items cannot exceed parent permissions.
|
||||
|
||||
Example: A payment method restricted to France and Germany cannot have a sub-option available in Poland.
|
||||
|
||||
---
|
||||
|
||||
# ScheduleConditions Trait
|
||||
|
||||
A time-based scheduling widget with visual timeline controls. Allows users to define when something should be active using datetime ranges, weekly schedules, and public holiday exclusions.
|
||||
|
||||
## Features
|
||||
|
||||
- **Datetime Range**: Specific start/end period with datetime pickers
|
||||
- **Weekly Schedule**: Per-day time ranges with visual timeline sliders
|
||||
- **Public Holiday Exclusions**: Optional integration with holiday providers
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### 1. Include the Trait
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use MyPrestaRocks\TargetConditions\ScheduleConditions;
|
||||
|
||||
class AdminYourModuleController extends ModuleAdminController
|
||||
{
|
||||
use ScheduleConditions;
|
||||
|
||||
// Your controller code...
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Initialize Assets in setMedia()
|
||||
|
||||
```php
|
||||
public function setMedia($isNewTheme = false)
|
||||
{
|
||||
parent::setMedia($isNewTheme);
|
||||
|
||||
// Initialize schedule conditions (loads CSS + JS)
|
||||
$this->initScheduleConditions();
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Render the Widget
|
||||
|
||||
```php
|
||||
public function renderForm()
|
||||
{
|
||||
// Get saved schedule data (JSON string from database)
|
||||
$scheduleJson = $this->object->schedule ?? '{}';
|
||||
$scheduleData = json_decode($scheduleJson, true) ?: [];
|
||||
|
||||
$this->fields_form = [
|
||||
'legend' => ['title' => $this->l('Configuration')],
|
||||
'input' => [
|
||||
[
|
||||
'type' => 'free',
|
||||
'label' => $this->l('Schedule'),
|
||||
'name' => 'schedule_widget',
|
||||
],
|
||||
],
|
||||
];
|
||||
|
||||
// Render schedule widget
|
||||
$this->fields_value['schedule_widget'] = $this->renderScheduleConditionsHtml(
|
||||
[
|
||||
'id' => 'my-schedule',
|
||||
'name_prefix' => 'schedule_',
|
||||
'title' => $this->l('Availability Schedule'),
|
||||
'subtitle' => $this->l('Define when this should be active'),
|
||||
'show_datetime_range' => true,
|
||||
'show_weekly_schedule' => true,
|
||||
'show_holiday_exclusions' => true,
|
||||
],
|
||||
$scheduleData
|
||||
);
|
||||
|
||||
return parent::renderForm();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Process Form Submission
|
||||
|
||||
```php
|
||||
public function postProcess()
|
||||
{
|
||||
if (Tools::isSubmit('submitYourForm')) {
|
||||
// Parse schedule data from form
|
||||
$scheduleData = $this->parseScheduleConditionsFromPost('schedule_');
|
||||
|
||||
// Serialize to JSON for storage
|
||||
$this->object->schedule = $this->serializeScheduleConditions($scheduleData);
|
||||
$this->object->save();
|
||||
}
|
||||
|
||||
return parent::postProcess();
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Evaluate Schedule at Runtime
|
||||
|
||||
```php
|
||||
// Check if current time matches the schedule
|
||||
$scheduleData = $this->parseScheduleConditions($object->schedule);
|
||||
|
||||
if ($this->evaluateScheduleConditions($scheduleData)) {
|
||||
// Schedule allows - item is active
|
||||
} else {
|
||||
// Schedule blocks - item is inactive
|
||||
}
|
||||
|
||||
// Or check against a specific timestamp
|
||||
$futureTimestamp = strtotime('+1 day');
|
||||
$willBeActive = $this->evaluateScheduleConditions($scheduleData, $futureTimestamp);
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
```php
|
||||
$this->renderScheduleConditionsHtml([
|
||||
// Unique ID for the widget
|
||||
'id' => 'schedule-conditions',
|
||||
|
||||
// Form field name prefix
|
||||
'name_prefix' => 'schedule_',
|
||||
|
||||
// Header text
|
||||
'title' => 'Schedule',
|
||||
'subtitle' => 'Define when this should be active',
|
||||
|
||||
// Which sections to show
|
||||
'show_datetime_range' => true, // Start/end datetime pickers
|
||||
'show_weekly_schedule' => true, // Per-day time range sliders
|
||||
'show_holiday_exclusions' => true, // Holiday exclusion controls
|
||||
], $savedData);
|
||||
```
|
||||
|
||||
## Data Format
|
||||
|
||||
The schedule data is stored as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabled": true,
|
||||
"datetime_start": "2024-12-24 08:00:00",
|
||||
"datetime_end": "2024-12-24 18:00:00",
|
||||
"weekly_schedule": {
|
||||
"0": {"enabled": false, "start": 0, "end": 1440},
|
||||
"1": {"enabled": true, "start": 540, "end": 1020},
|
||||
"2": {"enabled": true, "start": 540, "end": 1020},
|
||||
"3": {"enabled": true, "start": 540, "end": 1020},
|
||||
"4": {"enabled": true, "start": 540, "end": 1020},
|
||||
"5": {"enabled": true, "start": 540, "end": 1020},
|
||||
"6": {"enabled": false, "start": 0, "end": 1440}
|
||||
},
|
||||
"exclude_holidays": true,
|
||||
"holiday_countries": [1, 14, 17]
|
||||
}
|
||||
```
|
||||
|
||||
### Field Descriptions
|
||||
|
||||
- **enabled**: Whether scheduling is active (false = always active)
|
||||
- **datetime_start/end**: ISO datetime strings for absolute date range
|
||||
- **weekly_schedule**: Per-day configuration (0=Sunday, 1=Monday, etc.)
|
||||
- **enabled**: Whether this day is active
|
||||
- **start/end**: Minutes from midnight (0-1440, e.g., 540 = 09:00)
|
||||
- **exclude_holidays**: Whether to exclude public holidays
|
||||
- **holiday_countries**: Country IDs to check for holidays
|
||||
|
||||
## Public Holiday Integration
|
||||
|
||||
To enable holiday exclusions, implement the `HolidayProviderInterface`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use MyPrestaRocks\TargetConditions\HolidayProviderInterface;
|
||||
|
||||
class MyHolidayProvider implements HolidayProviderInterface
|
||||
{
|
||||
/**
|
||||
* Check if a date is a holiday for any of the given countries
|
||||
*/
|
||||
public static function isHoliday($date, array $countryIds)
|
||||
{
|
||||
// Your implementation
|
||||
return Db::getInstance()->getValue('
|
||||
SELECT 1 FROM ps_holidays
|
||||
WHERE holiday_date = "' . pSQL($date) . '"
|
||||
AND id_country IN (' . implode(',', array_map('intval', $countryIds)) . ')
|
||||
') ? true : false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get list of country IDs that have holidays configured
|
||||
*/
|
||||
public static function getCountriesWithHolidays()
|
||||
{
|
||||
return array_column(
|
||||
Db::getInstance()->executeS('SELECT DISTINCT id_country FROM ps_holidays'),
|
||||
'id_country'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get holidays within a date range
|
||||
*/
|
||||
public static function getHolidaysInRange(array $countryIds, $startDate, $endDate)
|
||||
{
|
||||
return Db::getInstance()->executeS('
|
||||
SELECT holiday_date, display_name, country_iso
|
||||
FROM ps_holidays h
|
||||
JOIN ps_country c ON c.id_country = h.id_country
|
||||
WHERE h.id_country IN (' . implode(',', array_map('intval', $countryIds)) . ')
|
||||
AND holiday_date BETWEEN "' . pSQL($startDate) . '" AND "' . pSQL($endDate) . '"
|
||||
');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then override the provider method in your controller:
|
||||
|
||||
```php
|
||||
protected function getScheduleHolidayProvider()
|
||||
{
|
||||
return 'MyHolidayProvider';
|
||||
}
|
||||
```
|
||||
|
||||
## Helper Methods
|
||||
|
||||
```php
|
||||
// Get human-readable description of schedule
|
||||
$description = $this->getScheduleDescription($scheduleData);
|
||||
// Returns: "Dec 24 08:00 to Dec 24 18:00 • Weekdays only • Excl. holidays (3 countries)"
|
||||
|
||||
// Format minutes to time string
|
||||
$time = $this->formatMinutesToTime(540); // Returns "09:00"
|
||||
|
||||
// Parse time string to minutes
|
||||
$minutes = $this->parseTimeToMinutes("09:00"); // Returns 540
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Assets
|
||||
|
||||
Both traits share a common CSS file with trait-specific styling:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `assets/css/admin/condition-traits.css` | Shared styling for both traits |
|
||||
| `assets/js/admin/target-conditions.js` | TargetConditions widget functionality |
|
||||
| `assets/js/admin/schedule-conditions.js` | ScheduleConditions widget functionality |
|
||||
|
||||
## CSS Classes Reference
|
||||
|
||||
### TargetConditions
|
||||
|
||||
```css
|
||||
.condition-trait { } /* Main wrapper */
|
||||
.condition-group { } /* Individual group container */
|
||||
.condition-group-header { } /* Group header with label */
|
||||
.condition-group-items { } /* Items container */
|
||||
.condition-item { } /* Individual selectable item */
|
||||
.condition-item.selected { } /* Selected state */
|
||||
.group-modifiers { } /* Limit/sort controls container */
|
||||
.condition-trait-toggle { } /* All/restricted toggle badge */
|
||||
```
|
||||
|
||||
### ScheduleConditions
|
||||
|
||||
```css
|
||||
.schedule-conditions { } /* Main wrapper */
|
||||
.schedule-section { } /* Section container */
|
||||
.schedule-datetime-range { } /* Datetime range section */
|
||||
.schedule-weekly { } /* Weekly schedule section */
|
||||
.schedule-holidays { } /* Holiday exclusions section */
|
||||
.day-timeline { } /* Individual day row */
|
||||
.timeline-track { } /* Time range slider track */
|
||||
.timeline-range { } /* Active time range bar */
|
||||
.timeline-handle { } /* Draggable handles */
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Requirements
|
||||
|
||||
- PrestaShop 1.7.x or 8.x
|
||||
- PHP 7.1+
|
||||
|
||||
# License
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user