Ulmer Social Widget
Free floating social / contact widget for OpenCart 3.0.x and ocStore 3.0.x
by EmeraldWeb - https://emeraldweb.de

This archive contains:
  - ulmer-social-widget-1.4.14.ocmod.zip   the file you install
  - README_OC3_EN.txt / UK / RU              this guide (3 languages)
  - LICENSE.txt                                      license terms
  - NOTICE                                           author and attribution notice
  - DATENSCHUTZ.md                                   privacy notice

============================================================
BEFORE YOU START (IMPORTANT!)
============================================================
We highly recommend making a full backup of your store's files and database before installing or updating any extensions. As the saying goes, the world is divided into two types of people: those who already make backups, and those who spend half the night restoring their site! :)

============================================================
INSTALLATION (FOR NEW USERS)
============================================================
1. In the OpenCart admin: Extensions > Installer.
   Upload the file: ulmer-social-widget-1.4.14.ocmod.zip
2. Go to Extensions > Modifications and click the blue Refresh button (top-right).
3. Go to Dashboard, click the blue gear icon (Developer Settings) in the top-right corner, and refresh the Theme cache.
4. Go to Extensions > Extensions, choose "Modules" in the dropdown, find "Ulmer Social Widget" and click the green Install (+) button.
5. Still in Extensions > Extensions > Modules, click Edit (pencil) on "Ulmer Social Widget".
6. All channels are OFF by default. Turn on the 3-5 channels you actually use, fill in each link, and Save.
7. Open your storefront - the floating button appears in the corner!

If step 5 gives you a "Permission Denied" message: OpenCart grants the rights automatically to the user group of the administrator who installed the module, so this only happens if you administer the store under a different group. Go to System > Users > User Groups, edit your group, find "extension/module/ulmer_social_widget" and check the box in both the "Access Permission" and "Modify Permission" lists, then Save.

============================================================
UPDATING TO A NEW VERSION
============================================================
OpenCart's Extension Installer prevents overwriting files by default. To update the module via the admin panel, follow these steps:
1. Go to Extensions > Installer.
2. Find the old "Ulmer Social Widget" entry in the "Installed Extensions" list at the bottom of the page.
3. Click the RED Delete (Trash) button next to it. 
   (Don't worry: this only deletes the old files to allow uploading the new ones. Your module settings, links, and stats are safely stored in the database and will NOT be deleted!).
4. Upload the new ulmer-social-widget-1.4.14.ocmod.zip file.
5. Go to Extensions > Modifications and click Refresh.
6. Crucially, refresh the Theme cache via the blue gear icon on your Dashboard!
7. If you receive a "Permission Denied" error when editing the module, check System > Users > User Groups: your group needs "extension/module/ulmer_social_widget" ticked in both the Access and Modify lists. OpenCart normally sets this for you when the module is installed.

============================================================
MANUAL FTP INSTALLATION / UPDATING (if the Installer will not work)
============================================================
Use this if your hosting blocks the Extension Installer. It takes TWO steps - the first one on its own is not enough:

1. Open the .ocmod.zip, take the `upload` folder out of it, and copy its contents into your store's root directory (over the `admin` and `catalog` folders).
2. Take `install.xml` from the root of the .ocmod.zip, rename it to `ulmer.ocmod.xml`, and upload it into your store's `system/` folder.
   Do not skip step 2: this file is what adds the widget to your theme's footer. With only step 1 done, the module appears in the admin but the widget never shows up on the storefront.

Afterwards: click "Refresh" in Extensions > Modifications, then clear the Theme cache from Dashboard (blue gear icon, Developer Settings) - otherwise the admin serves a cached older template. Don't forget to grant User Group permissions (System > Users > User Groups) as well.

Good to know: installed this way, the module is not listed in Extensions > Modifications, and the module's own Diagnostics tab reports the modification as missing. That is expected for a manually placed file, and the widget still works.

============================================================
TROUBLESHOOTING COMMON OC3 ISSUES
============================================================
* "Permission Denied!" when opening module settings:
  OpenCart grants the rights automatically to the user group of the administrator who installed the module, so this only happens if you administer the store under a different group. Go to System > Users > User Groups, edit your admin group, and check the box for "extension/module/ulmer_social_widget" in both Access and Modify lists.

* "Directory Not Allowed to be Written To" during upload:
  This is a notorious OC3 security limitation restricting where the installer can write files. Use the Manual FTP Installation method above, or install the popular "Fix OC 3.x Extension Installer" module from the OpenCart marketplace.

* "File could not be uploaded" / Upload fails silently:
  Your hosting provider's PHP `upload_max_filesize` is likely set too low (e.g., 2MB). Increase it in your cPanel/php.ini, or use the Manual FTP Installation method.

* "Modification requires a unique ID code!" error:
  You are trying to upload an update over an existing installation. You must delete the old modification in Extensions > Installer FIRST (see Updating section step 3).

* Changes aren't applying / The widget doesn't appear:
  OC3 has a very stubborn Twig cache. Clicking refresh in Modifications is NOT ENOUGH! You must go to the main Dashboard, click the blue gear icon in the top-right corner, and clear the Theme cache. Also, ensure you clear any third-party caches (NitroPack, LiteSpeed, Cloudflare).

============================================================
SUPPORT & HELP
============================================================
Running into a problem or something went wrong? Reach out to us, and we will try our best to help!
Please note: this module is provided completely free of charge, so support is provided on a best-effort basis. Due to high workload, a response might occasionally take some time. Thank you for your understanding!

  Email:     support@emeraldweb.de
  Telegram:  @emeraldweb_support
  WhatsApp:  https://wa.me/message/SOTKVJT5H365N1
  Web:       https://emeraldweb.de
