Add Help text to Custom Liquid Section + Block

[nicklepine]

Relates to: #42

Describe the enhancement you'd like

We have an opportunity to better inform merchants on the usecases in which they add an custom liquid section:

• Add your own Liquid
• Add an app's liquid snippet

@gretchen-willenberg Could you help come up with copy for this?

[gretchen-willenberg]

Support copy drafts

v1 longer explanation; upgrade path more insider/jargony
Add app snippets or other Liquid code to create advanced customizations without taking your theme off the upgrade path. Learn more [offsite icon]

v2 shorter, upgrade path explained more simply
Add app snippets or other Liquid code without affecting automatic theme updates. Learn more [offsite icon]

v3 a combination
Add app snippets or other Liquid code to create advanced customizations without affecting theme updates. Learn more [offsite icon]

Additional copy changes

• Leave custom field empty to emphasize it’s open to the merchant and flexible
• Remove Learn about Liquid link above custom field. It can end support text, like we do with metafields. Or, we may decide we don't need it with the addition of the support text.

[nicklepine]

Thanks @gretchen-willenberg. I think introducing the concept of the upgrade path might be a bit TMI in this context so I would stick to a spin off version of your V1:

Add app snippets or other Liquid code to create advanced customizations. Learn about Liquid [offsite icon]

What do you think?

[gretchen-willenberg]

True. Cool with the first sentence.

Can I stubbornly hang onto Learn more vs Learn about Liquid to be consistent with our other education links in support copy (including metafields)? Since it's generic, it gives us the most freedom to link out. Might be about Liquid, might eventually be a bit more app-centric with Liquid?

Add app snippets or other Liquid code to create advanced customizations. Learn more [offsite icon]

[nicklepine]

Aligned on
Add app snippets or other Liquid code to create advanced customizations. Learn more [offsite icon]

[PaulNewton]

Can I stubbornly hang onto Learn more vs Learn about Liquid

@gretchen-willenberg Neither are currently good Learn more or Learn about liquid pointing to just the top level liquid reference is not suitable to inform merchants about how to use this liquid setting type and it's limitations.
The official docs definitely need a supporting doc explaining the context of liquid settings, it's limitations, noting how this helps prevent upgrade problems unlike standard theme code editing, THEN pointing non-basic needs to the liquid reference.
It is not like editing a custom text setting, or themes code file , and will be confusing to new merchants who have never done anything like embed codes or shortcodes. Sending merchants to the liquid ref for this setting is kicking kids into the deep end of a pool that's also very wide and keeping them from the edges with the skimmer pole.

Merchants looking to add a little flexibility just need an understandable resource to give them context of what this thing can do , like adding themselves as vendor* or showing another feature image to pages before they get punted to the much broader and complex areas of the liquid ref , the customization tutorials, or try to use code from places like partners code snippets and not understand why some code errors out (it has {% schema %}).

The findable resources on the topic of liquid settings leave much to be desired as well
Searching merchant help just has deadends

• https://help.shopify.com/en/search?#/?page=1&q=liquid%20setting
• https://help.shopify.com/en/search?#/?page=1&q=liquid%20setting%20type%20theme&suggested=0
• https://help.shopify.com/en/manual/online-store/themes/os/customize/theme-settings
  google search is worse

And the main doc about this new setting type is for implementers not end users : https://shopify.dev/themes/architecture/settings/input-settings#liquid

*{% if product.vendor = shop.name %}{{vendor.name }}{% endif %}

[PaulNewton]

@nicklepine
Nit Add app snippets or other Liquid code to create advanced customizations. Learn about Liquid [offsite icon]
for:
Add Liquid code or snippets from apps and other sources to create advanced customizations. Learn about Liquid [offsite icon]
#1 steers clear of confusing app sections for app snippets and as as thing of copy&paste code vs a theme architecture concept(defunt or not ),
#2 reprioritizes Liquid code as the context
#3 implies other sources: forums, help groups, theme dev KB's , shopify support mails,etc.

Future - Down the line IF shopify support resources grow for this , such as a premade list of snippets, will probably want to swap "advanced" to be "basic or advanced" aligning with support policy 🤷

[PaulNewton]

Leave custom field empty to emphasize it’s open to the merchant and flexible

Doesn't this create a UX exception, which other keyboard entry settings have a behavior of not having a placeholder? (pickers don't count)
If we apply that reasoning to RTE, title texts, etc it doesn't work. I don't know the underlying behavior name of the effect but having something to poke gets more reaction than an empty space 🤷.
At minimum leaving this blank needs to be supported by a reference link with examples, and clearly documented in the repo why it's an exception in more concrete terms.

Looking at things like RTE text settings we get:

"Share information about your brand with your customers. Describe a product, make announcements, or welcome customers to your store."

In the above the placeholder text explains some general usages and importantly makes it a pain point if the user DOESN'T edit it , getting users to either delete all the text or start editing the text more immediately seeing results on the page.

Also placeholders make it clearer visually where an output will be.

I think the issue is finding a general case placeholder that is short, explanatory and contains text&liquid&html code that instantly encourages change and exploration because it's undesirable to leave it alone. 😫

It should be some short overally generally usable liquid code so it's more explanatory insitu regardless of page|resource context.
I think a liquid placeholder should at minimum, and maximum, have 1 conditional tag(or iteration tag but not both ), and 1 output tag, and 1 attribute used to make it clearer that logic is the name of the game and through that business rules can be applied:

<p>Use custom logic to display information or add features to your theme such the store description.</p>
{% if shop.description != blank %}
<p>{{ shop.description }}</p>
{% else %}
Tell customers about your store or your story.
{% endif %}

And probably should try to avoid objects that may not exist during a store setup like description 🤷 , though it could be argued request.design_mode could be used to link the merchant to the admin to edit that field probably best not to encourage that route logic in sections.

In this context I think the two below examples are actually bad because they immediately fulfill a too specific need.
For reference updating nicklepine's original to have liquid

<div class="ba-trust-wrapper">
<h3>Checkout Securely With</h3>
<ul>
{% for type in shop.enabled_payment_types %}
<li>{{ type | payment_type_svg_tag  }}</li>
{% endfor %}
</ul>
<div>

and updating the policies snippet from the liquid docs to have links

<ul>
{% for policy in shop.policies %}
  <li>{{ policy.title | link_to:policy.url }}</li>
{% endfor %}
</ul>

💣 Both are broken when a store doesn't have those things available yet, in others not having payment methods or no polices entered in the admin results in bad placeholder output. So placeholders like that would need guards {% if shop.policies.size > 0 %} overcomplicating things for a liquid placeholder by having conditions AND loops.

Liquid setting is a lowkey gamechanger for the theme customizations part of the ecosystem and probably will be my favorite feature of OS2 even though it basically loses me work! And I'd wager it will be a merchant favorite too once it's capability is more well known.. soooo getting the first touch experience tuned of the liquid-setting-type in the reference theme seems important for longterm merchant pedagogy making themes even more flexible.

Aside: policies example code also points out a problem that snippets in the liquid ref will get used for this feature but not all of them are functionally complete i.e. the shop.policies snippet does not generate urls_

[ludoboludo]

There is an existing link that, from what I can see, is there by default based on the type of the setting (liquid). So if we want to change the link I will have to get in touch with another team.

As for the text to add, we could link to different resource or ommit the Learn more. Screenshot

[nicklepine]

Good flag @ludoboludo Then let's keep the existing Liquid link coming from the liquid setting in editor, and ditch the learn more in the additional help text ( was intended to link to the same place).

So the paragraph to add is simply: Add Liquid code or snippets from apps and other sources to create advanced customizations.

cc: @gretchen-willenberg I think Paul's suggestion is a good one, to put emphasis on the Liquid code rather than apps - given we also have the separate concept of app blocks in the theme.