Small notifier examples, what's new, 2.0.1

content/dev/code/notifiers.md

@@ -35,6 +35,7 @@ Here are some 'quick links' to various sections of this documentation:
 
 5. [Additional Information](#additional-information).  This section has references to additional documentation on the observer/notifier system.
 
+6. [Complete Examples](#complete-examples) This section shows examples of using notifiers and observers.
 
 ## Triggering Event Notifications
 
@@ -378,3 +379,8 @@ Some plugins which can be helpful during development when using notifiers includ
 * The [output of the Zen Cart Notifier Report](/dev/code/notifier_report/) run against the current release is provided on the docs site for easy reference by developers.  
 * You may also install the [Notifier Report](https://github.com/lat9/notifier_report) on your own site to get the list of notifiers for your version, which could differ from the official list if you have made changes or are not running the current version. 
 
+## Complete Examples 
+
+- [Creating an exception list for a shipping module](/user/shipping/exceptions/)
+- [Adding a link to the Information, More Information or EZ-Page Sidebox](/user/sideboxes/add_link_information_sidebox/#using-an-observer)
+

content/release/changed_files-v2-0-0.html

@@ -175,6 +175,7 @@ <h1>CHANGED Files in v2.0.0</h1>
                <li>admin/includes/css/attributes_controller.css</li>
                <li>admin/includes/css/developers_tool_kit.css</li>
                <li>admin/includes/css/stylesheet.css</li>
+               <li>admin/index_dashboard.php</li>
                <li>admin/includes/extra_datafiles/dist-site_specific_admin_overrides.php</li>
                <li>admin/includes/functions/admin_access.php</li>
                <li>admin/includes/functions/functions_help.php</li>

content/release/whatsnew_2.0.0.html

@@ -189,10 +189,12 @@ <h2>
                 <li>(Note: no database changes between 2.0.0/2.0.1, so no need to run zc_install again if 2.0.0 is already installed.)</li>
                 <li>Admin: NOTIFY_ADMIN_CUSTOMERS_LISTING_ELEMENT notifier enhanced to pass entire customer query result.</li>
                 <li>Admin: For stores with large numbers of coupons, selecting coupons on page 2+ can wind up showing a blank infoBox and the wrong coupon records.</li>
+                <li>Admin: Allow customization of dashboard widget display.</li>
                 <li>Core: Many PHP8 logs have been fixed.</li>
                 <li>Storefront: New Products listing now shows new products as configured.</li>
                 <li>Storefront: Shopping Cart class in_cart_check() function fixed.</li>
                 <li>Storefront: notifiers added to shipping modules so storeowners can implement their own exception rules.</li>
+                <li>Storefront: notifiers added so storeowners can add to Information, More Information and EZ-Pages sideboxes.  See <a href="/user/sideboxes/add_link_information_sidebox/#using-an-observer">this page</a>.</li>
             </ul>
 
             <h2>

content/release/work_in_progress.html

@@ -51,14 +51,15 @@ <h1>
                 What's Next ... Upcoming changes to Zen Cart
             </h1>
 
-            <h2>v2.1.x</h2>
-                The improvements targeted for v2.1.x include:  
+            <h2>v2.1.0</h2>
+                The improvements targeted for v2.1.0 include:  
                 <br><br>
             <ul>
                 <li>New Feature: The <a href="https://vinosdefrutastropicales.com/product_extra_files/options_stock/readme.html">Products Options Stock</a> plugin will be integrated with Zen Cart. </li>
                 <li>New Feature: <a href="https://github.com/zencart/zencart/discussions/6428">Child Templates</a> will be supported, so that storeowners can more easily determine what has been changed from the base release of a template. (This may slip to a follow on release depending on schedules.)</li>
                 <li>New Feature: The Zen Cart admin will be secured with <a href="https://github.com/zencart/zencart/pull/6350">Multi Factor Authentication</a>. </li>
                 <li>Admin: The <a href="/dev/code/template_settings/">template settings file</a> may now be viewed from your admin page.</li>
+                <li>Admin: The date of last password change is now shown on the Users page in admin.</li>
                 <li>Core: Shipping modules now inherit from ZenShipping base class to reduce code duplication and ensure consistency.</li>
             </ul>
             <br><br>

content/user/about_us/whats_new.md

@@ -7,7 +7,7 @@ weight: 10
 
 > Note: If you want to see What's **Next** for Zen Cart instead, please [click here](/release/work_in_progress.html).
 
-- April 2024: [Zen Cart v2.0.0 Released](https://www.zen-cart.com/showthread.php?230040-Zen-Cart-2-0-0-Released).
+- April 2024: [Zen Cart 2.0.0 Released](https://www.zen-cart.com/showthread.php?230040-Zen-Cart-2-0-0-Released).
 - April 2024: [1.5.7/1.5.8 Address Security Patch](https://www.zen-cart.com/showthread.php?230032-Security-patch-for-Zen-Cart-v1-5-7-series-and-v1-5-8-series) released.  All users running Zen Cart 1.5.7x and 1.5.8x should apply these patches as soon as possible. 
 - March 2024: [Reminder to migrate off the old UPS API](https://www.zen-cart.com/showthread.php?229812-UPS-XML-will-stop-working-June-2024-(here-s-new-OAUTH-module)&p=1399614#post1399614) posted on forum.  Two months left to upgrade to [UPS Shipping RESTful API](https://www.zen-cart.com/downloads.php?do=file&id=2374) or update your custom code.  The old API will stop working on  **June 3, 2024**.
 - March 2024: Release Candidate 1 for 2.0.0 was built; here's the [2.0.0 RC 1 Feedback](https://www.zen-cart.com/showthread.php?229991-Feedback-on-2-0-0-rc1) forum thread. 
@@ -24,5 +24,5 @@ weight: 10
 - September 2023: We updated the [FedEx Integration for Zen Cart](/user/shipping/fedex/) to use the more recent FedEx REST API.  The newer [FedEx Shipping REST API](https://www.zen-cart.com/downloads.php?do=file&id=2375) plugin replaces the older FedEx Web Services integration. 
 - August 2023: We have updated the recommended process for updating your database from latin1/iso-8859 to UTF8MB4.  Please see [Converting to utf8mb4](/user/upgrading/convert_to_utf8/) for more information.
 - June 2023: We have updated the [UPS Integration for Zen Cart](/user/shipping/ups/) to use the more recent UPS REST API.  The newer [UPS Shipping RESTful API](https://www.zen-cart.com/downloads.php?do=file&id=2374) plugin replaces all older UPS Integrations for Zen Cart. 
-- March 2023: Zen Cart 1.5.8 released!  [Release announcement for 1.5.8a](https://www.zen-cart.com/showthread.php?229371-Zen-Cart-1-5-8a-Released).
+- March 2023: Zen Cart 1.5.8a released!  [Release announcement for 1.5.8a](https://www.zen-cart.com/showthread.php?229371-Zen-Cart-1-5-8a-Released).
 - February 2023: We updated the [USPS Integration](https://www.zen-cart.com/downloads.php?do=file&id=1292) for Zen Cart to use the newest service names from USPS.  

content/user/shipping/exceptions.md

@@ -0,0 +1,76 @@
+---
+title: Shipping Exceptions
+description: How to disable shipping modules based on conditions
+category: shipping 
+weight: 10
+---
+
+Most shipping modules have a zone configuration setting, which allows you to 
+disable the shipping module if the customer is not in the specified zone.
+
+What if instead, you want to disable a shipping module based on the cart contents? 
+
+Starting with Zen Cart 2.0.1, most shipping modules include a notifier in the `update_status` method (or a subordinate method) that allows you to set the `enabled` status. 
+
+If you are running an earlier version of Zen Cart, this change is [easily backported](#backporting).
+
+
+Here's an example observer that disables this module for product id 27.  (Obviously you will want to customize this for your specifications.)
+
+Create the file `includes/classes/observers/auto.freeoptions.php` as follows: 
+
+
+```
+
+<?php
+class zcObserverFreeoptions extends base
+{
+    public function __construct()
+    {
+        global $current_page_base;
+        $this->attach(
+            $this,
+            [
+                'NOTIFY_SHIPPING_FREEOPTIONS_UPDATE_STATUS',
+            ]
+        );
+    }
+
+    protected function update(&$class, $eventID, $not_used, &$enabled)
+    {
+        $products = $_SESSION['cart']->get_products();
+        foreach($products as $product) {
+            if ($product['id'] == 27) {
+
+                $enabled = false; 
+                return; 
+            }
+        }
+    }
+}
+```
+
+## Backporting
+
+If you are running an earlier version of Zen Cart than 2.0.1, this change is easily backported.
+
+In the shipping method you want to update, copy the notification from the version of that file in 2.0.1. (The notifiers are distinct for each shipping module, and contain the shipping module's name.)
+
+For example, in the `freeoptions` module, the notifier is `NOTIFY_SHIPPING_FREEOPTIONS_UPDATE_STATUS`.  To backport, modify `includes/modules/shipping/freeoptions.php` and copy this call to the end of the `checkForFreeOptions` function in Zen Cart 1.5.8 and Zen Cart 2.0.0, or the end of the `update_status` function in Zen Cart 1.5.7 and prior.
+
+The notifier looks like this: 
+
+```
+   if ($this->enabled) { 
+       // -----
+       // Give a watching observer the opportunity to disable the overall shipping module.
+       //
+       $this->notify('NOTIFY_SHIPPING_FREEOPTIONS_UPDATE_STATUS', [], $this->enabled);
+   }
+```
+
+And be sure the shipping module `extends base` - some earlier versions of some shipping modules do not:
+
+```
+  class freeoptions extends base {
+```

content/user/sideboxes/add_link_information_sidebox.md

@@ -11,11 +11,9 @@ There are three techniques that can be used to add links to the "Information", [
 
 1. [Using a Template Override](#using-a-template-override)
 2. [Using a Sidebox Module Override](#using-a-sidebox-module-override)
-3. [Using an Observer](#using-an-observer).  Available for Zen Cart versions 2.0.1 and later.
+3. [Using an Observer](#using-an-observer).  Available for Zen Cart versions 2.0.1 and later, but [easily backported](#backporting).
 
-### Techniques
-
-#### Using a Template Override
+## Using a Template Override
 
 To add a link to the Information Sidebox, we create the [override file](/user/first_steps/overrides/) `includes/templates/YOURTEMPLATE/sideboxes/tpl_information.php`.  
 
@@ -49,7 +47,7 @@ $content .= '<li><a href="' . zen_href_link(FILENAME_EZPAGES,'id=9') . '">' . "M
 
 or if you don't want to modify code, you can just use the [EZ-Pages sidebox](/user/sideboxes/ezpages_sidebox/), which displays EZ-Pages with sidebox display on and a positive sort order.  
 
-#### Using a Sidebox Module Override 
+## Using a Sidebox Module Override 
 
 Purists would argue that it's not a good practice to update the template to add links, and that instead, the relevant module file should be updated. The approach used above is more beginner friendly and lends itself to copy-and-paste ready examples for all three sideboxes, which is why it was chosen. 
 
@@ -64,7 +62,7 @@ The same process could be used to add a link to the More Information sidebox, us
 
 However, adding a link to the EZ-Pages sidebox using this technique would be more involved, since the entries in `$var_linksList` are arrays, not simple strings.
 
-#### Using an Observer
+## Using an Observer
 
 Starting with Zen Cart 2.0.1, these sideboxes include a notification to enable the insertion of additional links in the sideboxes' displays.  Each notification enables a watching observer to insert additional links into those sideboxes' display, making the template-override techniques above obsolete. 
 
@@ -74,7 +72,7 @@ Starting with Zen Cart 2.0.1, these sideboxes include a notification to enable t
 
 Each sidebox's notification provides a numerically-indexed array of links (as HTML anchor tags) to be included in the sidebox's display.
 
-##### Information Sidebox
+### Information Sidebox
 
 The "Information" sidebox now includes the following notification:
 
@@ -88,7 +86,7 @@ An observer can `attach` to that notification to insert additional links seamles
 $link_class = (isset($information_classes)) ? ('class="' . $information_classes . '"') : '';
 ```
 
-##### More Information Sidebox
+### More Information Sidebox
 
 The "More Information" sidebox now includes the following notification:
 
@@ -102,7 +100,7 @@ An observer can `attach` to that notification to insert additional links seamles
 $link_class = (isset($more_information_classes)) ? ('class="' . $more_information_classes . '"') : '';
 ```
 
-##### Important Links Sidebox
+### Important Links Sidebox
 
 The "Important Links" sidebox now includes the following notification:
 
@@ -112,7 +110,37 @@ $zco_notifier->notify('NOTIFY_EZPAGES_SIDEBOX_ADDITIONS', [], $var_linksList);
 
 An observer can `attach` to that notification to insert additional links seamlessly into that sidebox.
 
-##### Common Observer Processing
+### Example Observer
+
+Create the file `includes/classes/observers/auto.information_sidebox.php` as follows, using your own new links of course: 
+
+
+```
+<?php
+class zcObserverInformationSidebox extends base
+{
+    public function __construct()
+    {
+        global $current_page_base;
+        $this->attach(
+            $this,
+            [
+                'NOTIFY_INFORMATION_SIDEBOX_ADDITIONS',
+            ]
+        );
+    }
+
+    protected function update(&$class, $eventID, $not_used, &$information)
+    {
+
+       // Your links would be appended like this: 
+       $information[] = '<a class="list-group-item list-group-item-action" href="' . zen_href_link('forms') . '">' . 'Forms'. '</a>'; 
+
+    }
+}
+```
+
+### Common Observer Processing
 
 For each of the above notifications, an observer processes the array of links provided in a similar manner.  Let's say that you want to insert the following link into one of the sideboxes:
 
@@ -138,9 +166,20 @@ where
 - `$link_position` is the ***zero-based** position* at which you want to insert that link.  Use a value of `0` to insert the link as the first, `1` for the second and a large number, say `100` to insert that link at the end.
 - `$the_link` is the anchor-link described above.
 
-### General Information
+### Backporting 
+
+To backport these notifiers to an earlier versions of Zen Cart, simply modify the relevant file in `includes/modules/sideboxes` (or the override folder if the file is overridden).  For example, to add the Information sidebox notifier, update `includes/modules/sideboxes/YOURTEMPLATE/information.php` and after the last link is appended to the `information` array, add: 
+
+```
+$zco_notifier->notify('NOTIFY_INFORMATION_SIDEBOX_ADDITIONS', [], $information);
+```
+
+- To backport for the EZ-Pages sidebox, modify `includes/modules/sideboxes/ezpages.php` (or the override), and add the `notify` call for `NOTIFY_EZPAGES_SIDEBOX_ADDITIONS`.
+- To backport for the More Information sidebox, modify `includes/modules/sideboxes/more_information.php` (or the override), and add the `notify` call for `NOTIFY_MORE_INFORMATION_SIDEBOX_ADDITIONS`.
+
+## General Information
 
-#### Specification of URLs 
+### Specification of URLs 
 
 It's a good practice not to hardcode non-relative URLs, in case your site moves or you want to reconstruct a test instance of it.  So don't do this: 
 
@@ -156,9 +195,9 @@ $content .= '<li><a href="index.php?main_page=page&id=25">Important information<
 You can read more about [the importance of relative URLs](/user/first_steps/relative_urls/) to explore this topic in greater depth. 
 
 
-#### Mobile
+### Mobile
 
 You may need to make [additional edits to control the link on mobile displays](/user/template/sideboxes/#controlling-sideboxes-on-mobile-menu).
 
-#### More Examples 
+### More Examples 
 See [creating links to other pages](/user/customizing/creating_links/).