Update Doc with the current Plugin Feature Changes

[ghen-arvesu]

Hi @eliot-akira ,

We are working on creating blog posts on the changelogs as well as updating the documentation for Loops and Logic and we are wondering if you can give us some insights about what new features from your plugin updates that we should add on the documentation.

[eliot-akira]

Hi @ghen-arvesu Thank you for helping with this.

The L&L plugin has a file called readme.txt, at the bottom of which is the change log for each version.

• https://github.com/TangibleInc/loops-and-logic/blob/main/readme.txt#L154-L189

All plugins have this file, and the change log section is used by the WordPress plugin update process to inform users of what's included in a new version. (A link called "What's New" opens a popup to show it.)

As you can see it's only a summary of additions and changes. It's not enough information to write documentation or an announcement post. For the future it would help if I (and others) get in the habit of writing more detailed change logs.

---

Also, the change log for older versions (before 4.2.1) has been moved to a History page in this docs site.

• https://github.com/TangibleInc/loops-and-logic-docs/blob/main/docs/reference/40%20-%20history/index.md

The reason for moving it is that the entire change log section is sent (between update server and all sites where the plugin is installed) for every plugin update check, which can be frequent.

---

I will copy the list here and go through the points to identify what needs documentation. I'll use the :tomato: emoji to highlight them.

• 🍅 ACF Repeater: Improve support for sort/filter by field
  • Translate internal keys used by ACF to actual field names
  • For field value comparison, ACF Date field is in format "Y-m-d" and DateTime field is "Y-m-d H:i:s"
• Atomic CSS: Utility classes and variables compatible with Tailwind v4
• 🍅 Attachment loop type
  • Add field "audio" for audio file metadata from ID3 tags
  • Add field "filepath" for path to file
• Editor: Improve passing language definition of closed tags to formatter
• Elandel (template language in TypeScript): Start Expression and Interactivity modules
• Enable by default new features that reached stability; Can be deactivated in settings page
  • Elementor integration: Use new code editor based on CodeMirror 6
  • 🍅 Object cache for parsed and pre-processed templates
• Export page: Improve select template types for L&L and Blocks
• 🍅 Field tag: Support "." dot syntax for subfields (object/array/loop)
• Gutenberg integration: Improve enqueue editor assets in iframe
• 🍅 Improve compatibility with PHP 8.4
• Improve development setup and tests for supported PHP versions with Docker and wp-env; end-to-end tests with Playwright; and running tests on plugin zip archive before publish
• 🍅 Layout template type: Improve loading logic to pass through redirects
• REST API: Improve compatibility with Checkview
• Start new features
  • 🍅 Content Structure templates
  • Form templates
  • ACF Extended integration
  • Tangible Fields integration
• 🍅 WP Grid Builder facet integration with support for pagination

From an older change log (4.2.1) in history, this is a good one:

• Improve plugin zip package build/test/release workflow
  • 🍅 File size ~42% smaller
  • Remove source maps for production

This is about the release process of creating a zip package and a final pre-release test run on the plugin extracted from the generated package. It's the kind of changes that improve things behind the scenes without the user needing to know about it. Similarly with some of the bug fixes above.

---

So, many of the points above need further explanation. I'm going to write about them in subsequent comments, as a rough draft for the docs. We can create sub-issues for bigger points, if that might help to manage them better.

[ghen-arvesu]

Thank so much @eliot-akira! yeah for management I think thats sounds good as well and pls feel free to tag me on those sub-issues so I could have visibility. Quick question though why a 🍅 hahhaha

[eliot-akira]

🍅 ACF Repeater: Improve support for sort/filter by field

• Translate internal keys used by ACF to actual field names
• For field value comparison, ACF Date field is in format "Y-m-d" and DateTime field is "Y-m-d H:i:s"

This is related to:

• https://tangibletalk.com/t/acf-repeater-order-rows/618/5

It's about the ACF Repeater loop type and its sort_field attribute (documented here) and the field attribute (docs). Particularly there was improvement in comparing date field values.

[eliot-akira]

Oh the 🍅 was the most visible emoji I could find to use as a marker. I first used a flag 🚩 but it was too small to stand out in the list. It works, no? (:

I have a list of "Gitmoji", emoji shortcuts in Markdown supported by GitHub.

https://github.com/eliot-akira/gitmoji?tab=readme-ov-file#gitmoji-markdown

[eliot-akira]

🍅 Attachment loop type: Media file metadata

• Add field "audio" for audio file metadata from ID3 tags
• Add field "filepath" for path to file

ID3 is a standard for metadata associated with audio and video file formats. WordPress bundles a library for this purpose:

• https://github.com/WordPress/WordPress/tree/master/wp-includes/ID3

Theoretically L&L should already support all file formats listed in the above library, but so far I've only tested with MP3 audio files.

Example template with ACF File field.

<Loop acf_file=example_file_field>
  File name: <Field filename /><br>
  File path: <Field filepath /><br>

  Artist: <Field audio.artist /><br>
  Album: <Field audio.album /><br>

  All audio metadata:<br>
  <Loop field_keys=audio>
    <Field key /> = <Field value /><br>
  </Loop>
</Loop>

Since the field is named audio, for now we can document that it supports audio files. In the future we can expand support for all formats supported by ID3, and provide the metadata under a different field name like video or id3.

Example list of metadata fields:

album = Romance del Diablo
artist = Luz y Sombra
bitrate = 128000
bitrate_mode = cbr
channelmode = stereo
channels = 2
codec = LAME
compression_ratio = 0.09070294784580499
dataformat = mp3
encoder = LAME3.98r
encoder_options = CBR128
fileformat = mp3
filesize = 963930
length = 60
length_formatted = 1:00
lossless =
mime_type = audio/mpeg
sample_rate = 44100
text = 196301
title = Fracanapa
track_number = 5

[eliot-akira]

🍅 Object cache for parsed and pre-processed templates

This is a feature to boost performance of template rendering. It pre-processes the template at the time when it's edited and saved, storing the result in cache, also known as Transients API.

Depending on the site setup, it takes advantage of any additionally installed cache plugins, such as Redis, Memcached, SQLite, LiteSpeed. See: Persistent Caching.

This is an optional feature in plugin settings, now enabled by default.

[eliot-akira]

🍅 Field tag: Support dot syntax for subfields

This feature was demonstrated in the audio metadata example above. It enables "reaching into" a field value (array, object, or loop instance) to get a subfield, without having to create loops for each level.

<Field audio.artist />

This will get the audio field, which is an object, then the artist subfield.

The subfield can be a number, to get an item from an array/list. The index starts from 0 (zero) as the first item. (I considered starting from 1 but it's simpler to use the index unchanged, rather than convert to actual zero-based index used internally.)

The dots can be chained:

<Field attached_files.0.audio.album />

[eliot-akira]

🍅 Improve compatibility with PHP 8.4

The improvement includes running the plugin tests on PHP 7.4 and 8.4.

This is an ongoing effort in L&L and in WordPress itself.

• PHP Compatibility and WordPress Versions

As you can see in the page above, PHP 8.4 is only partially supported by the latest version of WP 6.8.

One of these days we're going to drop support for PHP 7.4, but currently about 30% of WordPress sites are still running that version (or below).

• WordPress usage satistics

[eliot-akira]

🍅 Layout template type: Improve loading logic to pass through redirects

This is related to:

• Conflict with Gravity Forms login form in Layout template

The main benefit of this improvement is that form redirects are supported when using a Layout template.

[eliot-akira]

🍅 Content Structure templates

This is a newly started feature for building content structure using L&L templates: custom post types, fields, taxonomies.

So far the ACF integration is fairly comprehensive, let's say "beta stage" for people to start using.

There's a lot to document here, so I'll make a sub-issue for it.

• Content Structure: Document ACF integration #11

The next planned task for this feature is to integrate with the Tangible Fields module. There will likely be some differences with how ACF works, particularly the field definition schema. I'll probably ask @nicolas-jaussaud for help with this, since he's the expert of the Fields library.

[eliot-akira]

🍅 WP Grid Builder facet integration with support for pagination

This feature was a community contribution:

• Add support for WPGB Pagination Facet template-system#151

And they were kind to update the docs as well:

• Add WP Grid Builder Facet Doc #8

I imagine the above two links include useful information for the blog post.

[eliot-akira]

So, that's the bottom of the list of changes in recent versions of L&L. I think I got all the main points.

@ghen-arvesu Please let me know if you have any questions.

I'll do the "content structure" one, but the other points are hopefully suitable for other people to participate in the documentation process. I'm trying to not do everything myself, but instead provide notes and information so we can do it as a team effort.

[ghen-arvesu]

Looks awesome!

Will parse through your comments and send you any questions if I have some!

Thanks so much!