===== Entrylist =====
Author: [[https://www.pierov.org/|Piero VDFN]]

==== Description ====
The plugin adds the BBCode tag ''entrylist''. It requires the [[doc:plugins:standard#bbcode|BBCode]] plugin and allows you to list blog entries grouped by their **entry date** (year → month → day → entries).

<WRAP right round tip 350px>
**Tip:**\\
The plugin does not include a widget. However, you can create a static page and then use the BlockParser plugin to place it as a widget in the menu column.
</WRAP>

==== Usage ====
Basic syntax:
  [entrylist <options>]

You can filter by year/month/day:
  * ''y'' filters by year
  * ''m'' filters by month (requires ''y'')
  * ''d'' filters by day (requires ''y'' and ''m'')

If no filter is given, the plugin outputs a hierarchical archive list (years → months → days → entries).

==== Parameters ====
^ Parameter ^ Values ^ Description ^
| ''y'' | ''YY'' or ''YYYY'' | List entries for a year. ''YY'' means 2000–2099 (e.g. ''23'' = 2023). ''YYYY'' is accepted for convenience in the range 2001–2099 (e.g. ''2025''). |
| ''m'' | ''MM'' or ''M'' | List entries for a month. Requires ''y''. Values 1–12 (''1'' will be treated as ''01''). |
| ''d'' | ''DD'' or ''D'' | List entries for a day. Requires ''y'' and ''m''. Values 1–31 (''2'' will be treated as ''02''). Invalid dates (e.g. 31/02) return “no entries”. |
| ''yformat'' | date format | Output format for year headings (strftime-style tokens). Overrides default. |
| ''mformat'' | date format | Output format for month headings (strftime-style tokens). Overrides default. |
| ''dformat'' | date format | Output format for day headings (strftime-style tokens). Overrides default. |
| ''link'' | ''on/off'' (also ''false'') | Whether entry titles should link to the entry. Default: ''on''. Use ''off'' or ''false'' to disable. |
| ''sort'' | ''asc/desc'' | Sorting order. Default: ''asc''. Applies to years/months/days and also to entries within a day (by entry id / time). |
| ''noentries'' | text | If the resulting list is empty, output this text instead. |
| ''+FORMAT''   | time format             | Output format for time (strftime-style tokens). Override the entry time (e.g. ''[entrylist=+%H:%M y=23]'').                                  |

==== Date & time formats (important) ====
FlatPress allows admins to configure the site short date format under:\\
''Administration → Configuration → International settings''.

**Default behaviour (version 1.0.4):**
  * Day headings use the configured admin date format (''locale.dateformatshort'') **as-is**.
  * Month and year headings are automatically derived from that admin short date format.
  * You can override these defaults per tag with ''yformat/mformat/dformat''.
  * The default time format comes from the admin setting ''locale.timeformat''.
  * You can override the entry time format for a single ''[entrylist]'' tag.

This means the Entrylist headings follow the admin-configured formats for many locales (e.g. German, English, Spanish, French, Italian, Greek, Dutch, Danish, Czech, Japanese, Portuguese/Brazil, Russian, Turkish, …), including formats with literal characters like ''年/月/日''.

==== Examples ====
**Entrylist for the whole year 2023**
<code>
[entrylist y=23]
</code>

**Same year, using a 4-digit year**
<code>
[entrylist y=2023]
</code>

**If there is no entry in the whole year 2024, output “none at home”**
<code>
[entrylist y=24 noentries="none at home"]
</code>

**Entrylist only for January 2023**
<code>
[entrylist m=01 y=23]
</code>

**Entrylist only for day 12 of January 2023**
<code>
[entrylist d=12 m=01 y=23]
</code>

**Same day, but without links to the posts**
<code>
[entrylist d=12 m=01 y=23 link=off]
</code>

**Descending order**
<code>
[entrylist y=23 sort=desc]
</code>

**Override heading formats**
<code>
[entrylist y=23 yformat="%Y" mformat="%B %Y" dformat="%A, %e. %B %Y"]
</code>

**Override the entry time format (per tag)**
<code>
[entrylist=+%H:%M y=23]
</code>

**Overwrite heading and entry time (v1.0.3 like)**
<code>
[entrylist=+%H:%M y=23 yformat="%Y" mformat="%B" dformat="%d."]
</code>
==== Notes ====
  * The list is built from FlatPress entries and grouped by their entry date (the date stored in the entry id).
  * The plugin uses a cache file (''plugin_entrylist_tag.txt'' in FlatPress' cache directory) and automatically invalidates it when entries are published or deleted.
  * The entry time is wrapped in a span you can style via CSS:
<code html>
  <span class="entrylist-time">14:30</span>
</code>
==== Screenshots ====
| {{:res:plugins:pierovdfn:entrylist1_0_3.png?400|}} | {{:res:plugins:pierovdfn:entrylist1_0_4.png?400|}} | \\
|Preview version 1.0.3| Preview version 1.0.4 |
==== License ====
GNU GPLv2

==== Download ====
{{ res:plugins:pierovdfn:entrylist1_0_4.zip |}}

{{ res:plugins:entrylist_1_0_3.zip |}}

{{ res:plugins:pierovdfn:entrylist1_0_2.zip |}}


==== Git Repo ====

[[https://github.com/flatpressblog/flatpress-extras/tree/master/thirdparty/plugins/entrylist | github repo]] of Entrylist plugin
==== Changelog ====
== 2026-01-05: Version 1.0.4 ==
  * Respects the admin-configured short date and time format
  * Accepts 4-digit years (2001–2099) in addition to ''YY''
  * Per-tag state reset: multiple ''[entrylist]'' tags on one page no longer affect each other

== 2026-01-03: Version 1.0.3 ==
  * With time of creation of the post

== 2025-02-26: Version 1.0.2 ==
  * Compatibility with PHP 8.0+ established

**Support**\\
Please ask for help on the [[https://forum.flatpress.org/viewtopic.php?t=848|FlatPress Forum]].