=== Ramassio – Waste Collection Calendar ===
Contributors: verturin
Tags: waste, recycling, calendar, ical, town
Requires at least: 7.0
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Waste collection calendar for towns: bins, glass, garden waste, even/odd weeks, date changes, iCal feed and e-mail reminders.

== Description ==

Ramassio tells residents **which container to put out, and when**.

It is made for town halls and local councils: one screen to describe the collections, one form to post a last-minute change, and every display updates itself — the website, the residents' phone calendars and the e-mail reminders.

= Any kind of waste =

* Wheelie bins of any colour (general waste, packaging, food waste…), glass, paper, garden waste, bulky items, textiles, hazardous waste days…
* Kerbside collection (put the container out), drop-off on a date (mobile collection point), on appointment only, or a permanent site with opening hours such as a recycling centre (address, link to the opening hours, directions, "check before you go" notice).
* Add as many collection types as you need. Ready-made examples can be switched on in one click.
* Containers are drawn as scalable vector pictures in the colour you choose, so they stay sharp at any size. You can use your own photos instead.

= Flexible schedules =

* Every week, even weeks, odd weeks (ISO week number), every N weeks, once a month (e.g. the 2nd Tuesday), or only on listed dates.
* One or several days per week.
* Seasons (e.g. garden waste from April to November).
* Extra one-off dates.
* Areas for large towns (districts, arrondissements, villages): each collection type can have other days, other weeks or no collection in some areas, and date changes can concern one area only.
* Residents find their area by typing their postcode or street; their choice is remembered on their phone or computer.
* "Put it out the evening before" or "the same morning", collected in the morning, afternoon or evening.

= Last-minute changes =

* Move, cancel or add a collection in a few clicks (public holiday, snow, strike…), with a reason shown to residents.
* Built-in French public holidays: the plugin lists the collections falling on a holiday and applies "day before / day after / cancel" in one click. Other countries can be added with a filter.
* Every change is shown at once on the website, in the subscribed calendars and in the reminders.

= Everywhere residents look =

* `[ramassio_page]` — the complete page in one block: changes, next collections, calendar, subscription buttons and e-mail form. It looks the same with every theme. `[ramassio_page show="calendar"]` shows only the calendar.
* `[ramassio_next]` — next collection of each type: date, "in 2 days", and what to do ("Put it out on Wednesday evening — collected the next day in the morning").
* `[ramassio_calendar]` — modern monthly calendar with previous / next month buttons, even and odd weeks, public holidays and changed dates.
* `[ramassio_changes]` — upcoming changes, ideal for the home page.
* `[ramassio_ical]` — subscribe from an iPhone, Android, Google or Outlook calendar. The feed updates itself: a moved collection moves in the residents' calendars too.
* `[ramassio_send_links]` — residents choose iPhone, Android or computer and receive by e-mail the calendar subscription link and the home-screen link, with step-by-step instructions for their device.
* `[ramassio_app_link]` — a mobile page residents add to their home screen, like an app, with a proper icon: a drawn wheelie bin in your colour, the town logo, or your own image.
* `[ramassio_subscribe]` — e-mail reminder the day before (double opt-in, one-click unsubscribe), with the town logo.
* **Links to share** — an `<iframe>` code to embed the calendar on another website (community of communes, school, association), a direct link and the calendar feed address.
* A classic widget, and a public JSON API for phone widgets (an iPhone Scriptable widget is included in the `extras` folder).

= Made for the people who run it =

* A dashboard shows the next collection, the coming collections, the upcoming changes, the holidays to check and the number of subscribers.
* Backup and restore all the data as one JSON file, on the same or another site.
* Page caches (LiteSpeed Cache and LiteSpeed server cache, WP Rocket, W3 Total Cache, WP Super Cache, Autoptimize, Cloudflare plugin) are emptied automatically when the schedule changes.

= Clean and lightweight =

* All data lives in the plugin's own database tables. Uninstalling removes everything.
* No account, no external service, no tracking, no ads.
* Translation ready (text domain `ramassio`).

== Installation ==

1. In WordPress, go to **Plugins › Add New**, search for "Ramassio", then install and activate it. (Or upload the `ramassio` folder to `/wp-content/plugins/` and activate it.)
2. A **Ramassio** menu appears. Open **Collections** and adjust the collection types: name, colour, days, frequency, when to put the container out. Save.
3. Create a page and add the shortcodes you need, for example:
   `[ramassio_page]` for the complete page in one block, or separately `[ramassio_changes]`, `[ramassio_next]`, `[ramassio_calendar]`, `[ramassio_ical]`, `[ramassio_subscribe]`.
4. In **Settings**, set the town name, the town logo (e-mails, calendar page, mobile page) and the home-screen icon. The **Links to share** block gives, ready to copy: the `<iframe>` code, the direct link to the calendar page, the calendar feed address and the mobile page.

For reliable e-mail reminders, use an SMTP plugin, and on low-traffic sites a real server cron job calling `wp-cron.php`.

== Frequently Asked Questions ==

= How are even and odd weeks counted? =

With the ISO 8601 week number: weeks start on Monday and week 1 contains the first Thursday of the year. It is the number printed on most European calendars.

= A collection is moved because of a public holiday. What do residents see? =

The website shows the new date with the reason, the subscribed calendars move the event (it keeps the same identifier, so there is no duplicate), and the reminder e-mail is sent the day before the new date.

= Can residents choose only some collections? =

Yes. Every shortcode accepts `streams="black,yellow"` (the ids are listed in Ramassio › Display on the site), and the e-mail form lets residents tick the collections they want.

= My town is split into areas or districts with different days. =

In Settings › Areas / sectors, add your areas with their postcodes, streets or places. Then, in each collection type, the **By area** table lets you set other days, other weeks or no collection for some areas. Visitors choose their area or find it by postcode or street; tick "Ask visitors to choose their area" so that no one sees the dates of another area.

= How do I show a recycling centre? =

Add a collection type and choose "Permanent site with opening hours". Fill in the address and the link to the opening hours page. It is shown with the next collections, with "Opening hours" and "Directions" buttons, and never appears in the calendar or the reminders.

= The calendar looks different from the screenshots on my site. =

Open **Ramassio › Settings** and click **Check now** in "Display check", at the bottom of the page. It loads your pages as a visitor would and tells whether they come from an outdated cache (LiteSpeed, WP Rocket, Cloudflare…), from an old copy of the plugin, or whether another plugin removes the layout. A button empties the page caches.

If your theme changes the look of the calendar, use `[ramassio_page show="calendar"]` instead of `[ramassio_calendar]`: the calendar is then displayed in a frame of your own site that resizes itself, so the theme's styles cannot reach it. `[ramassio_page]` alone shows the complete page (changes, next collections, calendar, subscription buttons, e-mail form).

= I added a date but it does not show on my phone. =

Subscribed calendars are refreshed by the phone itself, on its own schedule (on iPhone: Settings › Calendar › Accounts › Fetch New Data). Also check that the calendar was added as a *subscription* ("Add Subscribed Calendar", or the webcal button) and not by opening the .ics link in a browser, which only imports a one-time copy.

= Which personal data does the plugin store? =

Only the e-mail addresses of the residents who subscribe to the reminders, with the collections and area they chose. Subscriptions need a confirmation; unconfirmed addresses are deleted after 7 days; every e-mail has an unsubscribe link that deletes the address. The WordPress personal data export and erase tools are supported. The "Get the links by e-mail" form does not store the address.

= Can editors (not only administrators) post changes? =

Yes, with the `ramassio_capability` filter, for example: `add_filter( 'ramassio_capability', fn() => 'edit_pages' );`

== External services ==

Ramassio does not send any data to an external service by itself: no API call, no tracking, no remote file.

It only displays links that residents may choose to open:

* **Google Calendar** — the "Add to Google Calendar" button opens `calendar.google.com` with the address of your own calendar feed, so the resident can subscribe to it. Nothing is sent until the resident clicks; Google then receives the feed address. [Google Terms of Service](https://policies.google.com/terms), [Google Privacy Policy](https://policies.google.com/privacy).
* **Google Maps** — for a recycling centre with an address, the "Directions" button opens `google.com/maps` with that address. Nothing is sent until the resident clicks. [Google Terms of Service](https://policies.google.com/terms), [Google Privacy Policy](https://policies.google.com/privacy).

== Screenshots ==

1. Next collections and the monthly calendar with even and odd weeks.
2. The calendar embedded on another website, with the calendar subscription buttons.
3. Mobile page residents add to their phone home screen.
4. "Get the links by e-mail": residents choose their device and receive the subscription links.
5. Dashboard in the administration.
6. Collection types: frequency, days, put-out time, recycling centre with address and opening hours.
7. Date changes, with one-click decisions for collections falling on a public holiday.
8. Settings and links to share: iframe code, direct link, calendar feed.
9. Reminder e-mail with the town logo.
10. Areas: each area with the postcodes, streets or places used to find it.
11. "By area" table of a collection type: other days, other weeks or no collection in some districts.
12. Residents find their area by postcode or street; the dates of their area are then shown and remembered.
13. Home-screen icon for iPhone, iPad and Android: drawn icon, town logo or your own image.

== Changelog ==

= 1.3.0 =
* First public release on WordPress.org.
* Collection types with any colour or photo; weekly, even/odd weeks, every N weeks, monthly, seasonal and one-off dates; areas; kerbside, drop-off, on-appointment and recycling-centre modes.
* Date changes (move, cancel, extra), for the whole town or one area, and French public holidays with one-click decisions.
* Areas / districts with their own days, found by postcode or street.
* `[ramassio_page]`: the complete calendar page in one block, unaffected by the theme.
* Next collections, modern monthly calendar, upcoming changes, widget, embeddable page, mobile home-screen page, JSON API.
* Calendar feed that updates itself in residents' calendars.
* E-mail reminders the day before (double opt-in, unsubscribe link, town logo) and "Get the links by e-mail" form.
* Town logo on the calendar and mobile pages; home-screen icon for iPhone, iPad and Android.
* Dashboard; display check in the settings (tells whether visitors get an outdated cached copy), backup / restore, automatic page cache purge.

== Upgrade Notice ==

= 1.3.0 =
First public release.
