Changeset 3458969

Timestamp:

02/11/2026 01:02:01 PM (7 weeks ago)

Author:

FreelanceDirectZA

Message:

Release version 1.5.0 - Added admin shortcode builder, awareness refactor, developer hook, builder integrations.

Location:

cancer-awareness-ribbon-shortcode

Files:

• assets/banner-1544x500.png (modified) (previous)
• assets/banner-772x250.png (modified) (previous)
• trunk/cancer-awareness-ribbon.php (modified) (17 diffs)
• trunk/readme.txt (modified) (12 diffs)

cancer-awareness-ribbon-shortcode/trunk/cancer-awareness-ribbon.php

@@ -3 +3 @@
 /**
  * Plugin Name: Cancer Awareness Ribbon Shortcode
- * Description: Adds a shortcode to display a cancer awareness ribbon whose colors change based on the current month (or by type override).
- * Version: 1.4.0
+ * Description: Adds a shortcode to display an awareness ribbon whose colors change based on the current month (or by type override).
+ * Version: 1.5.0
  * Author: Parallel Media
  * License: GPLv2 or later
@@ -19 +19 @@
         plugins_url('assets/css/cancer-awareness-ribbon.css', __FILE__),
         [],
-        '1.4.0'
+        '1.5.0'
     );
 }, 20);
 
 /**
- * Cancer list: type => [label, month, colors[], optional category]
+ * Default awareness types list (internal).
+ * Schema: type => [label, month, colors[], optional category]
  * Categories: Cancer, Medical, Social, Global
  */
-function car_get_cancers(): array
+function car_get_default_awareness_types(): array
 {
     return [
@@ -62 +63 @@
         'thyroid_cancer' => ['label' => 'Thyroid Cancer', 'month' => 9, 'colors' => ['#800080', '#00B3B3', '#FF69B4']],
 
-        // v1.1 - additional awareness ribbons (non-cancer)
+        // additional awareness ribbons (non-cancer)
         'hiv_aids_awareness' => ['label' => 'HIV / AIDS Awareness', 'month' => 12, 'colors' => ['#E10600'], 'category' => 'Global'],
         'autism_awareness' => ['label' => 'Autism Awareness', 'month' => 4, 'colors' => ['#1877F2'], 'category' => 'Medical'],
@@ -68 +69 @@
         'diabetes_awareness' => ['label' => 'Diabetes Awareness', 'month' => 11, 'colors' => ['#9E9E9E'], 'category' => 'Medical'],
         'heart_disease_awareness' => ['label' => 'Heart Disease Awareness', 'month' => 2, 'colors' => ['#C62828'], 'category' => 'Medical'],
-
-        // v1.2 - additional awareness ribbons (non-cancer)
         'domestic_violence_awareness' => ['label' => 'Domestic Violence Awareness', 'month' => 10, 'colors' => ['#800080'], 'category' => 'Social'],
         'prostate_health_awareness' => ['label' => 'Prostate Health Awareness', 'month' => 9, 'colors' => ['#7EC8E3'], 'category' => 'Medical'],
@@ -75 +74 @@
         'lung_health_awareness' => ['label' => 'Lung Health Awareness', 'month' => 11, 'colors' => ['#FFFFFF'], 'category' => 'Medical'],
         'alzheimers_awareness' => ['label' => 'Alzheimer’s Awareness', 'month' => 11, 'colors' => ['#5E2D79'], 'category' => 'Medical'],
-
-        // v1.3 - additional awareness ribbons (non-cancer)
         'pride_awareness' => ['label' => 'Pride Awareness', 'month' => 6, 'colors' => ['#E40303', '#FF8C00', '#FFED00', '#008026', '#004DFF', '#750787'], 'category' => 'Social'],
         'veterans_awareness' => ['label' => 'Veterans Awareness', 'month' => 11, 'colors' => ['#B22234', '#FFFFFF', '#3C3B6E'], 'category' => 'Social'],
@@ -83 +80 @@
         'organ_donation_awareness' => ['label' => 'Organ Donation Awareness', 'month' => 4, 'colors' => ['#4CAF50'], 'category' => 'Medical'],
     ];
+}
+
+/**
+ * Basic hex color validator (#RGB or #RRGGBB).
+ */
+function car_is_hex_color($c): bool
+{
+    $c = trim((string)$c);
+    if ($c === '') return false;
+    return (bool)preg_match('/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/', $c);
+}
+
+function car_clamp_int($v, int $min, int $max): int
+{
+    $v = (int)$v;
+    return max($min, min($max, $v));
+}
+
+function car_normalize_category($v): string
+{
+    $v = trim((string)$v);
+    if ($v === '') return '';
+    $v = strtolower($v);
+
+    if ($v === 'cancers') $v = 'cancer';
+    if ($v === 'med') $v = 'medical';
+
+    $map = [
+        'cancer'  => 'Cancer',
+        'medical' => 'Medical',
+        'social'  => 'Social',
+        'global'  => 'Global',
+    ];
+
+    return $map[$v] ?? '';
+}
+
+function car_sanitize_awareness_types($types): array
+{
+    if (!is_array($types)) return [];
+
+    $out = [];
+    foreach ($types as $raw_key => $raw_item) {
+        $key = sanitize_key((string)$raw_key);
+        if ($key === '') continue;
+        if (!is_array($raw_item)) continue;
+
+        $label = isset($raw_item['label']) ? trim((string)$raw_item['label']) : '';
+        if ($label === '') continue;
+
+        $month = isset($raw_item['month']) ? (int)$raw_item['month'] : 0;
+        if ($month !== 0) $month = car_clamp_int($month, 1, 12);
+
+        $colors_in = $raw_item['colors'] ?? [];
+        if (!is_array($colors_in)) $colors_in = [$colors_in];
+
+        $colors = [];
+        foreach ($colors_in as $c) {
+            $c = trim((string)$c);
+            if ($c === '') continue;
+            if (!car_is_hex_color($c)) continue;
+            $colors[] = $c;
+        }
+        if (!$colors) $colors = ['#999999'];
+
+        $category = '';
+        if (isset($raw_item['category'])) {
+            $category = car_normalize_category($raw_item['category']);
+        }
+
+        $item = [
+            'label'  => $label,
+            'month'  => $month,
+            'colors' => $colors,
+        ];
+        if ($category !== '') $item['category'] = $category;
+
+        $out[$key] = $item;
+    }
+
+    return $out;
+}
+
+/**
+ * Awareness Types Registry (v1.5)
+ *
+ * Developers can register/modify awareness ribbons via:
+ *   add_filter('car_awareness_types', function(array $types) { ...; return $types; });
+ */
+function car_get_awareness_types(): array
+{
+    $types = car_get_default_awareness_types();
+    $types = apply_filters('car_awareness_types', $types);
+    return car_sanitize_awareness_types($types);
+}
+
+/**
+ * Backwards compatibility wrapper (deprecated).
+ *
+ * @deprecated 1.5.0 Use car_get_awareness_types()
+ */
+function car_get_cancers(): array
+{
+    return car_get_awareness_types();
+}
+
+function car_item_category(array $item): string
+{
+    $cat = isset($item['category']) ? car_normalize_category($item['category']) : '';
+    return $cat !== '' ? $cat : 'Cancer';
+}
+
+function car_group_items_by_category(array $items): array
+{
+    $order = ['Cancer', 'Medical', 'Social', 'Global'];
+    $grouped = [
+        'Cancer' => [],
+        'Medical' => [],
+        'Social' => [],
+        'Global' => [],
+    ];
+
+    foreach ($items as $key => $item) {
+        $cat = car_item_category($item);
+        if (!isset($grouped[$cat])) $grouped[$cat] = [];
+        $grouped[$cat][$key] = $item;
+    }
+
+    $out = [];
+    foreach ($order as $cat) {
+        if (!empty($grouped[$cat])) $out[$cat] = $grouped[$cat];
+        unset($grouped[$cat]);
+    }
+    foreach ($grouped as $cat => $bucket) {
+        if (!empty($bucket)) $out[$cat] = $bucket;
+    }
+
+    return $out;
+}
+
+/**
+ * Helper for builder select options (flat).
+ * Elementor SELECT does not reliably support optgroups (nested arrays).
+ */
+function car_get_awareness_types_select_options_flat(): array
+{
+    $types = car_get_awareness_types();
+    $out = [];
+
+    foreach ($types as $key => $item) {
+        $label = (string)($item['label'] ?? $key);
+        $cat = car_item_category($item);
+        $out[$key] = $cat . ' | ' . $label;
+    }
+
+    // Optional: sort by label (keeps it tidy)
+    asort($out, SORT_NATURAL | SORT_FLAG_CASE);
+
+    return $out;
 }
 
@@ -103 +259 @@
 }
 
-function car_clamp_int($v, int $min, int $max): int
-{
-    $v = (int)$v;
-    return max($min, min($max, $v));
-}
-
-function car_normalize_category($v): string
-{
-    $v = trim((string)$v);
-    if ($v === '') return '';
-    $v = strtolower($v);
-
-    // allow a few friendly aliases
-    if ($v === 'cancers') $v = 'cancer';
-    if ($v === 'med') $v = 'medical';
-
-    $map = [
-        'cancer' => 'Cancer',
-        'medical' => 'Medical',
-        'social' => 'Social',
-        'global' => 'Global',
-    ];
-
-    return $map[$v] ?? '';
-}
-
-function car_item_category(array $item): string
-{
-    // Default: anything without explicit category is Cancer
-    $cat = isset($item['category']) ? car_normalize_category($item['category']) : '';
-    return $cat !== '' ? $cat : 'Cancer';
-}
-
-function car_group_items_by_category(array $items): array
-{
-    $order = ['Cancer', 'Medical', 'Social', 'Global'];
-    $grouped = [
-        'Cancer' => [],
-        'Medical' => [],
-        'Social' => [],
-        'Global' => [],
-    ];
-
-    foreach ($items as $key => $item) {
-        $cat = car_item_category($item);
-        if (!isset($grouped[$cat])) $grouped[$cat] = [];
-        $grouped[$cat][$key] = $item;
-    }
-
-    // return ordered + any extra categories (future-proof)
-    $out = [];
-    foreach ($order as $cat) {
-        if (!empty($grouped[$cat])) $out[$cat] = $grouped[$cat];
-        unset($grouped[$cat]);
-    }
-    foreach ($grouped as $cat => $bucket) {
-        if (!empty($bucket)) $out[$cat] = $bucket;
-    }
-
-    return $out;
-}
-
 function car_render_ribbon_svg(array $colors, int $size, string $label): string
 {
@@ -193 +287 @@
 c-33.208-21.358-88.518-46.819-163.426-46.819s-130.217,25.46-163.426,46.819c-25.382,16.325-41.878,32.54-49.703,41.068
 c-16.459-29.648-25.327-63.358-25.327-97.408C861.545,436.251,868.418,406.194,881.421,379.246z M826.783,1759.396
-l-157.379-336.675l255.586-332.444l168.38,259.026L826.783,1759.396z M1373.217,1759.396l-268.557-413.123l-0.042-0.064
+l-157.379-336.675l255.586-332.444l168.38,259.026L826.783,1759.396z M1373.217,1759.396
+l-268.557-413.123l-0.042-0.064
 c-0.007-0.01-0.013-0.02-0.02-0.03L770.167,831.709c-18.718-28.784-29.762-62.112-31.94-96.38s4.559-68.728,19.482-99.653
 l94.354-195.578c-1.086,8.654-1.637,17.37-1.637,26.073c0,38.495,10.741,76.575,30.562,109.42c0.135,0.271,0.29,0.533,0.47,0.782
@@ -213 +308 @@
 }
 
+/**
+ * Shared renderer so shortcode + builders can call the same logic.
+ */
+function car_render_awareness_ribbon(array $atts = []): string
+{
+    return car_shortcode_cancer_ribbon($atts);
+}
+
 function car_shortcode_cancer_ribbon($atts): string
 {
@@ -221 +324 @@
         'label'    => '0',
         'class'    => '',
-        'category' => '',   // v1.4: filter by category (Cancer, Medical, Social, Global)
-        'list'     => '0',  // v1.4: list all ribbons for a selected month
+        'category' => '',
+        'list'     => '0',
     ], $atts, 'cancer_ribbon');
 
     wp_enqueue_style('car-ribbon-style');
 
-    $cancers = car_get_cancers();
+    $types = car_get_awareness_types();
 
     $size = car_clamp_int($atts['size'], 16, 512);
@@ -244 +347 @@
     $extra_class = sanitize_html_class((string)$atts['class']);
 
-    // v1.4: list all awareness ribbons for the selected month (optionally filtered by category)
     if ($list_mode) {
         $matches = [];
 
-        foreach ($cancers as $key => $item) {
+        foreach ($types as $key => $item) {
             if ((int)($item['month'] ?? 0) !== (int)$month) continue;
 
@@ -262 +364 @@
         }
 
-        // Group by category (Cancer, Medical, Social, Global)
         $grouped = car_group_items_by_category($matches);
 
@@ -293 +394 @@
     }
 
-    // Single ribbon mode (existing behavior) + optional category filter when type is not forced
     $type = sanitize_key((string)$atts['type']);
     $selected = null;
 
-    // Type override always wins
-    if ($type && isset($cancers[$type])) {
-        $selected = $cancers[$type];
+    if ($type && isset($types[$type])) {
+        $selected = $types[$type];
     } else {
-        // If a category is provided and it's not Cancer, skip featured_by_month and pick first matching in that category for the month
         if ($category !== '' && $category !== 'Cancer') {
-            foreach ($cancers as $item) {
+            foreach ($types as $item) {
                 if ((int)($item['month'] ?? 0) === (int)$month && strcasecmp(car_item_category($item), $category) === 0) {
                     $selected = $item;
@@ -310 +408 @@
             }
         } else {
-            // Original featured-by-month logic
             $featured = car_featured_by_month();
-            if (isset($featured[$month]) && isset($cancers[$featured[$month]])) {
-                $candidate = $cancers[$featured[$month]];
-                // If category is set (Cancer) ensure it matches
+            if (isset($featured[$month]) && isset($types[$featured[$month]])) {
+                $candidate = $types[$featured[$month]];
                 if ($category === '' || strcasecmp(car_item_category($candidate), $category) === 0) {
                     $selected = $candidate;
@@ -321 +417 @@
         }
 
-        // Fallback: first item matching month (+ optional category)
         if (!$selected) {
-            foreach ($cancers as $item) {
+            foreach ($types as $item) {
                 if ((int)($item['month'] ?? 0) !== (int)$month) continue;
                 if ($category !== '' && strcasecmp(car_item_category($item), $category) !== 0) continue;
@@ -338 +433 @@
 
     $wrap_class = 'car-ribbon-wrap' . ($extra_class ? ' ' . $extra_class : '');
-
     $svg = car_render_ribbon_svg((array)$selected['colors'], $size, (string)$selected['label']);
 
@@ -355 +449 @@
     add_shortcode('cancer_ribbon', 'car_shortcode_cancer_ribbon');
 });
+
+/**
+ * Integrations loader
+ */
+function car_load_integrations(): void
+{
+    // Admin page
+    if (is_admin()) {
+        $admin_loader = __DIR__ . '/includes/admin/admin.php';
+        if (file_exists($admin_loader)) {
+            require_once $admin_loader;
+        }
+    }
+
+    // Elementor integration
+    $elementor_loader = __DIR__ . '/includes/integrations/elementor.php';
+    if (file_exists($elementor_loader)) {
+        require_once $elementor_loader;
+    }
+
+    // WPBakery / Visual Composer integration
+    $wpbakery_loader = __DIR__ . '/includes/integrations/wpbakery.php';
+    if (file_exists($wpbakery_loader)) {
+        require_once $wpbakery_loader;
+    }
+
+    // Divi integration
+    $divi_loader = __DIR__ . '/includes/integrations/divi.php';
+    if (file_exists($divi_loader)) {
+        require_once $divi_loader;
+    }
+
+    // Beaver Builder integration
+    $beaver_loader = __DIR__ . '/includes/integrations/beaver.php';
+    if (file_exists($beaver_loader)) {
+        require_once $beaver_loader;
+    }
+}
+add_action('plugins_loaded', 'car_load_integrations', 30);

cancer-awareness-ribbon-shortcode/trunk/readme.txt

@@ -1 +1 @@
 === Cancer Awareness Ribbon Shortcode ===
 Contributors: freelancedirectza
-Tags: cancer, awareness, shortcode, accessibility, charity
+Tags: cancer, nonprofit, ribbon, shortcode, accessibility
 Requires at least: 5.8
 Tested up to: 6.9
 Requires PHP: 7.4
-Stable tag: 1.4.0
-Version: 1.4.0
+Stable tag: 1.5.0
+Version: 1.5.0
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -16 +16 @@
 **Cancer Awareness Ribbon Shortcode** is a lightweight WordPress plugin that adds a shortcode for displaying a professionally designed awareness ribbon anywhere on your website.
 
-[Live Demo](https://www.parallelmedia.co.za/cancer-awareness-ribbon-demo)
+[Live Demo](https://www.parallelmedia.co.za/cancer-awareness-ribbon-demo/)
 
 The ribbon automatically adapts to the current awareness month and supports a wide range of awareness types including Cancer, Medical, Social, and Global causes.
@@ -24 +24 @@
 - Supports single-color and multi-color (gradient) ribbons
 - Uses a clean, scalable SVG with no background
-- Works seamlessly with Elementor, Gutenberg, headers, footers, and widgets
+- Works seamlessly with Elementor, Divi, WPBakery, Beaver Builder, Gutenberg, headers, footers, and widgets
+- Includes a built-in admin shortcode builder with live preview
 - Scales crisply at any size
 - Does not rely on external libraries or image files
@@ -37 +38 @@
 - Site-wide awareness displays
 
-Version 1.4.0 introduces:
-- Category grouping (Cancer, Medical, Social, Global)
-- Category filtering via shortcode
-- List mode to display all awareness ribbons for a selected month
-- Structured support for expanding awareness types
+Version 1.5.0 introduces:
+- Admin settings page with live shortcode preview
+- Default ribbon settings (size, type, month, category, label, list mode)
+- Internal data structure refactor from cancer-only to awareness types
+- Developer filter hook for registering custom awareness ribbons
+- Improved builder integrations (Elementor, Divi, WPBakery, Beaver Builder)
+- Foundation for future Pro features
 
 == Features ==
 
 * Automatic ribbon selection based on the current month
-* Supports many awareness types (Cancer, Medical, Social, Global)
+* Supports Cancer, Medical, Social, and Global awareness types
 * Multi-color gradient support for applicable ribbons
 * Fully responsive SVG (no images required)
-* Elementor Shortcode widget compatible
+* Admin shortcode builder with live preview
+* Save default ribbon display settings
+* Compatible with major page builders
 * Lightweight and fast (no external libraries)
 * Accessible SVG with ARIA labels
 * Customizable size, label, type, month, category filtering, and month listing via shortcode attributes
+* Developer hook to extend awareness ribbon library
 
 == Usage ==
@@ -66 +72 @@
 [cancer_ribbon type="breast_cancer"]
 [cancer_ribbon month="10"]
-
-New in 1.4.0:
 
 [cancer_ribbon category="Medical"]
@@ -80 +84 @@
 * `month` – Force a specific month (1–12)
 * `category` – Filter by category: Cancer, Medical, Social, Global (optional)
-* `list` – If set to 1/true, lists all ribbons for the selected month (optional, works great with `category`)
+* `list` – If set to 1/true, lists all ribbons for the selected month (optional)
+
+== Admin Shortcode Builder ==
+
+Version 1.5.0 adds a top-level **Awareness Ribbon** admin page where you can:
+
+- Select ribbon type
+- Choose month or auto-detect
+- Adjust ribbon size
+- Enable label display
+- Filter by category
+- Enable list mode
+- Add custom CSS class
+- View live preview instantly
+- Copy generated shortcode
+- Save global defaults
+
+== Developer Extensibility ==
+
+Developers can extend the ribbon library using a filter hook:
+
+
+
+    add_filter( 'car_awareness_types', 'my_custom_awareness_ribbon' );
+    function my_custom_awareness_ribbon( $types ) {
+        $types['my_custom_cause'] = array(
+            'label'    => 'My Custom Cause',
+            'month'    => 6,
+            'colors'   => array( '#123456', '#abcdef' ),
+            'category' => 'Global',
+        );
+        return $types;
+    }
+
+
+This allows plugins and themes to register custom awareness ribbons without modifying core plugin files.
 
 == Supported Awareness Types ==
@@ -97 +136 @@
 - Thyroid Cancer (September) – Purple, Teal & Pink
 
-Additional awareness ribbons added in later versions include (among others):
+Additional awareness ribbons include (among others):
+
 - HIV / AIDS Awareness
 - Autism Awareness
@@ -121 +161 @@
 == Frequently Asked Questions ==
 
-= Does this work with Elementor? =
-Yes. Use Elementor’s **Shortcode** widget and insert `[cancer_ribbon]`.
+= Does this work with page builders? =
+Yes. It works with Elementor, Divi, WPBakery, Beaver Builder, Gutenberg, and any builder that supports shortcodes.
 
 = Does it add any images or external files? =
@@ -147 +187 @@
 2. Breast cancer awareness ribbon (October)
 3. Multi-color gradient ribbon example
-4. Elementor Shortcode widget usage
-5. Month listing view (list mode) showing multiple ribbons
+4. Elementor module integration
+5. Admin shortcode builder with live preview
+6. Month listing view (list mode) showing multiple ribbons
 
 == Changelog ==
+
+= 1.5.0 =
+* Added admin shortcode builder with live preview
+* Added global default ribbon settings
+* Refactored internal data structure from cancer-only to awareness types
+* Added developer filter hook for registering custom awareness ribbons
+* Added full builder integrations (Elementor, Divi, WPBakery, Beaver Builder)
+* Improved internal structure for future Pro version expansion
 
 = 1.4.0 =
@@ -157 +206 @@
 * Added `list` shortcode attribute to display all ribbons for a selected month
 * Added grouped output by category when using list mode
-* Added categories to non-cancer awareness entries while keeping existing data structure intact
 
 = 1.3.0 =
-* Added Pride awareness ribbon (multi-color gradient)
+* Added Pride awareness ribbon
 * Added Veterans awareness ribbon
 * Added Child Protection awareness ribbon
@@ -180 +228 @@
 * Added Heart Disease awareness ribbon
 
-= 1.0.2 =
-* Fixed stylesheet loading to use proper WordPress enqueue functions
-* Updated contributor metadata for WordPress.org compliance
-* Minor internal cleanup and review-related improvements
-
-= 1.0.1 =
-* Added support for custom SVG ribbon
-* Improved Elementor compatibility
-* Fixed inline CSS loading issues
-* Removed background elements from SVG
-
 = 1.0.0 =
 * Initial release
@@ -196 +233 @@
 == Upgrade Notice ==
 
-= 1.4.0 =
-Adds category support, category filtering, and list mode to display all ribbons for a selected month.
-
-= 1.0.2 =
-Fixed stylesheet loading, updated contributor metadata, and minor internal cleanup.
+= 1.5.0 =
+Adds admin shortcode builder, default settings support, internal awareness refactor, developer extensibility hook, and builder integrations.
 
 == License ==