Update: new docs, restructured plugins, and more in version 3.0.0

It’s been a few months since our last update to Loops & Logic and during that time, we’ve been hard at work adding new user-requested features to the plugin and laying the groundwork for some exciting long-term plans. Here’s what’s new in the latest version of Loops & Logic.

Plugin restructure

We have an ambitious vision for the future of Loops & Logic as well as its block-building sister plugin, Tangible Blocks. While many of the changes in version 3.0.0 won’t affect the experience of using the plugin for the time being, this update paves the way for many of the long-term features we’re cooking up. Some of these features include the ability to write data to the database with L&L, the ability to save and share your templates across your sites just using your Tangible account, and the ability to natively interact with data from third-party plugins like WooCommerce and others. This release of Loops & Logic restructures a lot of the plugin’s code to make it easier to develop those powerful features and also to simplify collaboration internally. This means that we’ll be able to have more developers work on the plugin leading to more frequent releases of new features. So while much of this update affects things behind the scenes, it means great things for the future of L&L.

Impact on Tangible Blocks users

While those using the free Loops & Logic plugin on its own likely won’t notice any difference in the interface of version 3.0.0, members of the Tangible Blocks beta should take note of a few important changes:

• Templates, Styles, Scripts, and Layouts will no longer exist natively when using Tangible Blocks Editor. In previous versions of the Tangible Blocks Editor plugin, the Tangible menu in the WordPress admin area contained four menu items called Templates, Styles, Scripts, and Layouts. This allowed users to create templates just like you can in the Loops & Logic plugin. The primary purpose of Tangible Blocks is to build blocks and not to act as a templating tool, so to help streamline our product offering and keep each plugin focused on its intended use, version 3.0.0 removes those four items from the menu. But don’t worry! Updating to 3.0.0 won’t cause you to lose any data! If you’ve created any template, style, script, or layout posts, all you need to do is install the latest version of Loops & Logic alongside Tangible Blocks to keep those menu items visible. If you haven’t created posts in those four menus, you’re free to continue using Tangible Blocks to build blocks and your menu will now be a bit less cluttered.
• License keys will not be required. We’re working on building a new platform to manage plugin license keys and until that’s set up, updating the plugin will not require having a valid license key. We’ll send an email to beta users when the new licensing process is launched.

New documentation

We’ve heard from many of our users that L&L’s documentation was great as reference material, but lacked explanations and examples that would be useful to a beginner. While we’re still working on moving some of the documentation pages over and adding more examples and explanations throughout, we wanted to get our revamped docs into users’ hands as soon as possible so we’re releasing them alongside version 3.0.0. Here are a few of the highlights that you’ll find in the new documentation, which now resides at docs.loopsandlogic.com:

• Easier ways to get started with L&L. For users looking for a thorough explanation of the ins and outs of the L&L templating language, there’s a getting started guide that will take you step-by-step through understanding, building, and displaying your first template. For users looking to get their hands dirty without wading through detailed explanations, we also have a two-minute quick-start guide that allows you to download a collection of premade templates that will work with the basic data structure of most WordPress blogs. These templates are annotated too, offering in-context explanations and suggestions about ways to modify the template to see the output change. We’re also working on an onboarding guide for Tangible Blocks users.
• How-to guides with practical template examples. These examples can be browsed at a glance here and we’ve also added links to relevant examples at the bottom of many of the pages pertaining to specific dynamic tags. As users share their templates and ideas on the L&L forum, we’ll continue to add more examples.
• The list of dynamic tags now includes a brief description of each tag. Often, we see users struggling to achieve certain functionality with their templates simply because they aren’t aware of all the tags available in the language. To help skim through all the available tags, we created this page with descriptions of what each tag can do.
• More examples of every core condition of the If tag. The documentation for the If tag not only has a more detailed explanation of its syntax but each of the core comparisons now has an example showing how you can use each one to create different kinds of conditional statements. The common comparisons on that page also include more detail about how each one works.
• More explanations about the Loop tag. The documentation for the Loop tag was also reworked to add more explanations about the different ways to filter a query.

Conditionally add boolean attributes to tags using tag-attributes

The L&L markup language makes it easy to add dynamic values to attributes with its curly brace syntax. For example, adding a dynamic image field to HTML’s img tag is as simple as writing <img src="{Field image}">. But what happens when you want to use the power of L&L to dynamically add an HTML boolean attribute (i.e. an attribute that doesn’t accept a value and is simply true or false based on its presence in the tag)? That’s now possible using the tag-attributes attribute. This attribute simply renders its value as an attribute. This attribute can be used to render multiple attributes, either as value-less keys or as key/value pairs. In the example below, the audio file will only autoplay and loop if the user visiting the page is logged in.

  <audio src="music.mp3" tag-attributes="{If user}autoplay loop{/If}"></audio>

If the user is logged in, the HTML output will be:

  <audio controls src="music.mp3" autoplay loop></audio>

To further illustrate how you can use this attribute in your L&L markup, let’s look at an example inspired by a post by forum user @markofapproval who wants to prefill a form based on a URL query parameter. Let’s say we’re sending a user to a form and one of the items on the form asks the user to select the industry they’re in. Imagine we’ve sent the user to this page with a URL query that looks like this https://example.com?industry=retail and based on that we want to output the following HTML where the “Retail” option of our industry selection field is marked as selected, as shown below.

  <select id="industry">
    <option value="manufacturing">Manufacturing</option>
    <option value="construction">Construction</option>
    <option value="retail" selected>Retail</option>
    <option value="agriculture">Agriculture</option>
  </select>

In version 3.0.0 of Loops & Logic, it’s now possible to use the tag-attributes attribute to dynamically add boolean attributes, like selected, to our markup. To achieve the functionality described above, here’s what the L&L markup might look like.

  <Switch check="{Url query=industry}">
    <When value=manufacturing />
    <Set manufacturing>selected</Set>
    <When value=construction />
    <Set construction>selected</Set>
    <When value=retail />
    <Set retail>selected</Set>
    <When value=agriculture />
    <Set agriculture>selected</Set>
  </Switch>

  <select id="industry">
    <option value="manufacturing" tag-attributes="{Get manufacturing}">Manufacturing</option>
    <option value="construction" tag-attributes="{Get construction}">Construction</option>
    <option value="retail" tag-attributes="{Get retail}">Retail</option>
    <option value="agriculture" tag-attributes="{Get agriculture}">Agriculture</option>
  </select>

Below is an example of what this looks like in practice. As you can see, the selection drop-down now has "Retail" selected because of the query in your current URL.

Manufacturing Construction Retail Agriculture

New diagramming language module

Ever wanted to dynamically generate diagrams using L&L? Now you can with the Mermaid diagramming library built into version 3.0.0. Using Mermaid’s simple markdown-inspired syntax within the new Mermaid tag will allow you to output a variety of nicely-structured diagrams. Since both the Mermaid diagramming language and L&L both use < > angle brackets for different purposes in their syntax, it’s not possible to write dynamic tags directly inside the Mermaid tag and all content within this tag needs to be written using Mermaid’s syntax. Luckily though, it is possible to render dynamic data outside of the Mermaid tag and then pass that data to Mermaid using the Format tag. Below is an example of a simple pie chart diagram listing all the different post categories on this site.

  <Set dynamic_diagram_content>
    <Loop type=taxonomy_term taxonomy=category hide_empty=true>
      "<Field title />" : <Field count />
    </Loop>
  </Set>

  <Format replace="this_will_be_replaced" with="{Get dynamic_diagram_content}">
    <Mermaid>
      pie showData title Distribution of posts by category on loopsandlogic.com
        this_will_be_replaced
    </Mermaid>
  </Format>

And here’s the output of the template above:

In the template above, we’re using L&L’s Loop and Field tags to dynamically render some markdown which is then saved to a variable that gets passed inside the Mermaid tag to be rendered as a pie chart. You can click here to see a static version of this markdown in Mermaid’s live editor and see how changing the data impacts the diagram.

Order a loop based on a custom date field

Version 3.0.0 now includes new ways of ordering the results of a loop based on a date field. For loop types that query WordPress data that are compatible with custom fields—such as post, attachment, and taxonomy term loops—the orderby_field_number query parameter can be used if the custom date field is ordered as a number, such as those that use a UNIX timestamp or a date format such as Ymd. When possible, using this parameter is the most efficient way to order items by date since it uses MySQL to order the results. In instances where the date format doesn’t allow using orderby_field_number, the sort_field and sort_type=date attributes can be used. While these loop attributes might not be as efficient, they are smarter because they’re able to automatically recognize a variety of common date formats and understand how to order posts based on the given date field. In instances where the date format is ambiguous (such as m/d/Y which can be difficult to differentiate from d/m/Y) there’s a new attribute called sort_date_format to specify the date format of the custom field. Here’s an example that sorts upcoming event posts based on a custom event_date field that uses the format m/d/Y.

  Here are a few of our upcoming events:
  <Loop type=event count=5 custom_date_field=event_date custom_date_field_compare="after" custom_date_field_value=current sort_type="date" sort_field="event_date" sort_date_format="m/d/Y">
    <Field event_date />: <Field title /><br />
  </Loop>

Create a list quickly with the new items attribute

The List tag makes it easy to build lists for various purposes in L&L. The latest release makes it even easier to create lists without needing to add Item tags within the inner content. Previously, the syntax for creating a list would have looked like this:

  <List name=colors>
    <Item>Red</Item>
    <Item>Green</Item>
    <Item>Blue</Item>
  </List>

The latest version of L&L allows you to simply create your list directly within the items attribute, like this:

  <List name=colors items="Red, Green, Blue" />

The Loop tag also accepts this attribute to loop through a list. Whereas before it would have been necessary to create a list with the List tag and the loop through it with <Loop list=my_list_name>, it’s now possible to loop through items using the items attribute like this: <Loop items="Cyan, Magenta, Yellow">. This new shortcut can cut down on unnecessary markup when you want to either quickly create a loop with a few items or if you already have a list stored in some field or variable and want to loop through its contents.

Set a custom query parameter

The L&L templating language is highly flexible, but sometimes third-party plugins require the use of specific query parameters to work with their data. While we’re working on building deep integrations with many plugins, the latest release of L&L provides a flexible solution that can be used on post and attachment loop types that allows users to pass custom data to the loop using the new custom_query parameter. The quickest way to pass a value to the query is using Hjson syntax. To see this in action, let’s look at an example inspired by forum user @elearningkings who was building a template that integrated with Search and Filter Pro. In order to display results in query results, Search and Filter Pro requires passing an ID to a WP_Query argument called search_filter_id. With the new custom query parameter, this can be done with the following syntax:

  <Loop type=post custom_query="{ search_filter_id: 123 }">  

In cases where more than one query parameter needs to be passed or the data needs to be generated and passed dynamically, it’s also possible to create a Map variable and pass that map to the custom_query parameter. The common data types that can be passed as a value are number, boolean, and string, which can be can be specified using the type attribute like this:

  <Map custom_query>
    <Key search_filter_id type=number>123</Key>
  </Map>
  
  <Loop type=post custom_query="{Get map=custom_query}">

New location rule to stop Style and Script template types from loading

While the Template post type in L&L is great for building dynamic pieces of site content, the Layout, Style, and Script allow users to use the templating language in specific locations on a site, essentially functioning as a powerful but lightweight theme builder. Layouts are designed to only load in specific locations defined in the Location tab of the template editor. In contrast, Scripts and Styles load everywhere by default when no location is specified, which makes it easy to add new sitewide styles and scripts to your site. To stop a style or script from loading anywhere on the site, it used to be necessary to change the post from published to draft. Now, there’s a simpler way to achieve that by simply setting the location rule to “Nowhere.”

Feature improvements

Here are a few changes we’ve made that don’t add any new functionality but improve the experience of using the plugin.

• Improved compatibility when using the If tag:
  • Automatically convert the subject to a list when the following comparisons are used: any_is, any_is_not, all_is, all_is_not, any_starts_with, all_starts_with, any_ends_with, all_ends_with
  • Automatically convert the value to a list when the following comparisons are used: in, not_in
  • For starts_with and ends_with, check first or last item if the subject is a list
  • Add support for all common comparisons to the list="..." core condition
• Improved compatibility for importing and exporting:
  • Clear any cached field values such as compiled CSS when overwriting an existing template
  • Export all template types with orderby=menu_order, to ensure that location rules are applied in the correct priority
• When rendering layouts, render the page content before head to support Meta tag in the Blocks Theme
• Make the code editor match the full height of the template
• Remove unused styles in page builder integrations
• Remember and restore the current tab in the template edit screen

Bug fixes

Here are some of the bugs we’ve fixed in this release.

• Allow the ACF image url field to support size attribute
• Display loop item text without spaces when using an acf_select field
• Support looping through an acf_select field when only a single value is selected
• Disable AJAX save until issues are resolved
• Fix fatal error thrown in is_extension function
• Fork HTML Lint library and wrap it in a unique namespace to improve compatibility with Customizer and other plugins that may load a different version
• Make the styles_compiled field update on import overwrite
• Address issues when using templates in a Custom Post Layout in Beaver Themer
• Make inline L&L code editor appear in Elementor
• Correctly apply the layout location rule for “Singular – All post types”
• Export textual description of layout location rules displayed in the archive screen
• Ensure the current post is used as the default loop context in dynamically loaded preview for page builder
• Solve issue with Beaver Builder preview and current post