Arkon Event Manager releasesself-updates

=== Arkon Event Manager === Contributors: arkon Tags: events, event calendar, calendar, venue, ical Requires at least: 6.4 Tested up to: 7.1 Requires PHP: 8.0 Stable tag: 2.17.1 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html

An events calendar for venues. Post your shows with a flyer, times and cover charge, and let visitors add any date to their own calendar.

== Description ==

Arkon Event Manager is an events calendar for venues. Add a show with its flyer, times, cover charge and category, then put the calendar on any page with one shortcode.

It suits places with a regular programme: music venues, bars, theatres and community halls, where the same nights come round every week.

= Enter a weekly night once =

Set a night to repeat and it shows up on every date it runs. You enter it once instead of creating a new event every week, and your admin does not fill up with fifty copies of the same show.

Events can repeat daily, weekly, monthly on a date, or monthly on a weekday. Set an interval, give it an end date, or list the dates to skip for holidays.

= Add a month at a time =

Bulk Add takes a whole month of shows in one go. Paste the booking list you were sent, upload a spreadsheet, or type rows straight into the table. However it arrives, you get the same table of events to check and correct, and nothing is saved until you press Create.

Pasted lists do not need a format. A line like Sept 4 - Old Codger, Pickled - 8pm is read as a date, a time and a title, and lines that belong to the entry above become its description, so a festival day with a running order keeps it.

Booking lists usually mix new shows in with corrections, so anything asking for something to be deleted or moved is set aside and shown to you rather than acted on. A line that says to delete a show never creates one.

Flyers are attached for you. Upload the folder to the Media Library and Bulk Add pairs each row with the artwork whose filename starts with that date, so 8-29.jpg finds the show on the 29th. Where a night has two shows and two flyers, the words after the date decide which is which, and anything still uncertain is left for you to pick rather than guessed at.

= Visitors can save the whole run =

Every event has "Add to Google Calendar" and "Download iCal" buttons. On a repeating night those save the entire series rather than the single date being viewed, so a regular adds your Tuesday open mic once and has it every week.

= Late nights display correctly =

A show from 8pm to 1am stays on the night it starts and reads "8:00 PM - 1:00 AM" instead of splitting across two days. Nights that run until closing can simply say "Close".

= Features =

• Flyer, date, start and end time, cover charge, category and description
• Bulk Add: paste a booking list, upload a spreadsheet, or fill in a table, and create a month of shows at once
• Repeating events, with holiday dates skipped
• [abm_calendar] shortcode: a month by month list with a Load More button
• A page for every event, showing its other upcoming dates
• Category pages
• Google Calendar and iCal export on every event
• Import from Modern Events Calendar with every date intact
• Old event links keep working after you switch
• Works with any theme, with extra support for Themeco Pro and Cornerstone

= Who it is for =

• Music venues and bars listing shows, residencies and weekly nights
• Theatres and cinemas with a rolling programme
• Community halls, clubs and societies with regular meetings
• Anyone who wants a listings page rather than a full event management suite

= Moving from another calendar =

If you are on Modern Events Calendar, the built in importer reads its data directly and brings every event across with all of its dates, its flyers and its categories. Your existing event links carry on working, so nothing you have posted or linked to breaks.

= Works with your theme =

Add the shortcode to a page and you have a calendar. Events get their own pages too, and if your theme has its own event template the plugin steps aside and lets it render.

Building with Themeco Pro or Cornerstone? Every field is available to Dynamic Content, and the plugin adds a Looper Provider so you can design your own listing layout without writing any code.

== Installation ==

1. Upload the plugin to wp-content/plugins/ and activate it, or install the zip through Plugins > Add Plugin > Upload Plugin.
2. An Events menu appears in the admin. Add an event: title, date, start and end time, cost, category, and a Featured Image for the flyer.
3. Create a page for your calendar and put [abm_calendar] on it.
4. Visit Events > Settings to set the currency symbol, the date format, the default "Close" time used by exports, a global flyer placeholder, how far ahead open-ended repeats generate, and how many events the calendar loads per batch.
5. Moving from another calendar? Go to Events > Migrate & Tools and run the preview before importing.

The post type registers its pages under /music-and-events/, and the category archives under /event-category/. Flush permalinks (Settings > Permalinks > Save) if event pages 404 immediately after activating.

== Frequently Asked Questions ==

= Do I need Cornerstone or Themeco Pro? =

No. [abm_calendar] and the single event template work on any theme. The Looper Provider and the Dynamic Content meta keys are there if you use Cornerstone, and inert if you do not.

= I changed an imported event's date and the calendar did not move. Why? =

Because its dates are locked, and that is deliberate.

An event imported from another calendar holds its dates verbatim and has no recurrence rule, so regenerating it would collapse hundreds of real dates down to the single date in the date field. The plugin refuses to do that. Editing the date field on such an event succeeds and changes the displayed date, but the calendar keeps showing the imported dates.

To take over from an import, give the event a recurrence rule -- which replaces the imported dates with the rule's -- or delete and recreate it. Everything other than the dates edits normally. Over REST, check abm_occurrences.locked before writing a date.

= My booking list says to delete some shows. What happens to those? =

Nothing, deliberately. Bulk Add only creates events. Any line asking for something to be deleted, cancelled or moved is listed back to you under "these ask for changes to events that already exist" and left for you to handle.

That is worth being firm about: a line reading "Delete July 23rd UniS" contains a date and a name, so a parser that treats every dated line as a new show would create the very event the list is asking to be rid of.

A line that asks to move a show between two dates is set aside for the same reason. It names the date being left and the date being moved to, and reading the wrong one puts a show on a night you are not open.

= What if a line in my list is not read correctly? =

You will see it. Every row lands in an editable table before anything is written, rows the parser had to guess at are highlighted with a note saying what it assumed, and lines it could not read at all are printed back to you so you can check whether one of them was a real show.

= Should I use the CSV importer or Migrate & Tools? =

Migrate & Tools, whenever the old install is in the same database.

A Modern Events Calendar CSV export carries one row per event, keyed on the event ID. Every date of a repeating event therefore collapses onto a single record, and a weekly night arrives with one date instead of hundreds. Migrate & Tools reads the occurrence table directly and copies every date.

= What happens to my old event URLs? =

Imported events keep their original slug, and requests to the previous single-event base (/event-archive/<slug>/ by default) are 301 redirected to the new permalink, including any trailing /ical/ and any query string. Unknown slugs are left to 404 rather than guessed at.

= How do shows that run past midnight work? =

Enter the real times. A show from 8:00 PM to 1:00 AM is one listing on the night it starts, reading "8:00 PM - 1:00 AM", and it exports with the correct finish time. There is no need for the same-day-midnight workaround other calendars require, because a date here carries a time range rather than a second date.

= What does "End time is approximate" do? =

It affects the exports only, never the listing, and it is off by default. Turn it on when the end time is a placeholder or the night is genuinely open-ended: the export then stops at the end of the start day instead of claiming a finish time. Leave it off when the end time is real.

= Can I change the calendar's accent colour? =

Yes, with one CSS variable:

.abm-calendar { --abm-accent: #d6006e; }

= What does uninstalling remove? =

The plugin's settings, the date table and the scheduled task that extends it. Your events, their meta and your categories are preserved -- delete them in the admin first if you want them gone.

== Reference ==

= Bulk Add =

Events > Bulk Add. Three ways in, all landing on the same editable table:

• Paste a list. One event per line. The date and the time are picked out of the line and the rest becomes the title, so commas in a lineup are safe. Lines beneath an entry become its description. Lines opening with an instruction ("Add", "Update") have it removed; lines asking for a deletion or a move are set aside instead of created.
• Upload a CSV. A header row naming any of title, date, start, end, cost, category, description. Common alternatives are accepted too -- artist for the title, cover for the cost, time for the start. Dates and times may be written plainly (Sept 4, 8pm) rather than as ISO values.
• Type rows. Add and remove rows directly; the table is the same one the other two fill in.

Match flyers by date pairs rows with images already in the Media Library. A filename beginning with the row's date matches it -- 8-29.jpg, 08-29.jpg and 8-29 Ascension.jpg all belong to the 29th of August. Where several share a date, the words after the date are compared with the event title; where that settles all but one row and one flyer, the last pair is matched by elimination; anything still uncertain is left empty and labelled. Runs automatically after reading a list, and on demand once dates have been corrected or the folder has been uploaded.

Dates written without a year are read as the next time that date comes round, and the row says so. Categories are matched to existing terms by name and never created. An event whose title and date already exist is skipped, so pressing Create twice does not double the calendar.

= Calendar shortcode =

[abm_calendar]

A month-grouped list of upcoming events -- flyer, title, short description, date, time, category and cost -- with a Load More button that pulls the next batch over AJAX. The description is the event's excerpt, or its trimmed content when there is no excerpt, and is omitted for events with neither.

Batch sizes are set under Settings > Calendar Shortcode and can be overridden per placement:

[abm_calendar initial="8" more="6"]

Filter to one category:

[abm_calendar category="music"]

Category tags in the list follow a global toggle (Settings > Calendar Shortcode > Category Tags). Each event can override it under Event Details > Category Tag: Default, Show, or Hide.

= Field shortcodes =

Use inside a Looper Consumer, where they read the current event, or pass id="123":

• [abm_event_date] -- formatted with the global Date Format
• [abm_event_date format="l, F jS"] -- per-tag override
• [abm_event_time] -- "8:00 PM - Close"
• [abm_event_category sep=", "] -- category names
• [abm_cost] -- formatted door cost
• [abm_flyer_url size="large"] -- flyer or placeholder URL
• [abm_flyer size="large"] -- flyer as an <img>
• [abm_ical] -- .ics URL
• [abm_gcal] -- Google Calendar URL
• [abm_event_export] -- both export buttons

= Meta keys for Dynamic Content =

Reference these inside a Looper Consumer with {{dc:post:meta key="..."}}:

• abm_date_display -- "26 Jun", using the global Date Format
• abm_time_display -- "8:00 PM - Close"
• abm_cost_display -- "$10", empty when free or unset
• abm_flyer_url -- flyer URL, falling back to the placeholder
• abm_ical -- per-event .ics link
• abm_gcal -- Google Calendar link
• abm_event_date -- Y-m-d, raw; use for Looper sorting and upcoming filters
• abm_event_time_start -- H:i, raw
• abm_event_time_end -- H:i or "close", raw
• abm_flyer_id -- flyer attachment ID, mirroring the Featured Image

Display values are generated on save. Do not write to them.

= Cornerstone Looper setup =

1. Add a Looper Provider element. Either choose the plugin's own provider, which loops over dates, or use Query Builder with:
   • Post Type: Event (abm_event)
   • Order By: Meta Value, Meta Key: abm_event_date, Order: ASC
   • Upcoming only: Meta Query, key abm_event_date, compare >=, value {{dc:date format="Y-m-d"}}, type DATE
2. Inside the Consumer, bind elements through Dynamic Content:
   • Image source: {{dc:post:meta key="abm_flyer_url"}}
   • Heading: {{dc:post:title}}
   • Date: {{dc:post:meta key="abm_date_display"}}
   • Time: {{dc:post:meta key="abm_time_display"}}
   • Category: {{dc:post:terms taxonomy="abm_category"}}
   • Link: {{dc:post:permalink}}

Query Builder loops over posts, so a repeating event appears once. Use the plugin's provider, or [abm_calendar], for a listing that shows every date.

= REST API =

Event meta is exposed on wp/v2/abm_event, so a whole event including its recurrence rule can be created or edited in one authenticated call.

Each event also carries a read-only abm_occurrences object:

• count -- how many dates the event currently has
• next -- its next upcoming date (Y-m-d), o