search

textpattern / textpattern.github.io

Textpattern CMS user documentation.
https://docs.textpattern.com
GNU General Public License v2.0
15 stars 17 forks source link

page: tag page changes to common presentational elements #155

Open Bloke opened 4 years ago

Bloke commented 4 years ago

Absolute URL of front-end page

(e.g.) https://docs.textpattern.com/tags/images

The question/problem

We now have the notion of 'global' attributes that all tags can take. Instead of repeating the definition of these ad nauseum in each tag page, can we use includes?

Option A

Write a whole bunch of includes for each set of things we use often, e.g. a doc that has the heading, intro text, plus class, wraptag, break, escape in it. And a doc that has heading, intro text, plus class, wraptag, break, escape, breakby, label, labeltag. And so on.

Option B (better)

Write a bunch of individual includes, one for each attribute such as escape, break, label, labeltag, breakby, wraptag, class. Then, on each tag page under the 'Common attributes' heading, call them into the doc one by one on a tag-by-tag basis.

Option C (better still?)

Write a single common presentational attributes header include file with the header text, introductory paragraph and then a bunch of conditionals in it, one for each attribute. When you call in the include, you pass in the attributes you want to display and the include only displays the ones you give it in the parameter list.

e.g. if using:

{% include common_atts.html class breakby wraptag %}

the include only displays those three under the heading and intro text.

I'm not sure how capable includes and parameters are in Liquid/Jekyll. I've not seen any examples yet where you can pass in valueless attributes so we might have to do something stupid like:

{% include common_atts.html class="1" breakby="1" wraptag="1" %}

and then check to see if each common attribute is equal to 1 in order to display it or not. But the general idea is that we write a single template with a bunch of conditionals and then just render bits of it based on the way that file is included and the params we give it.

Worth pursuing?

Checklist

Need to:

  1. Remove all links to any 'panel' pages (they will be gone).
  2. For links -- page-templates-explained.md and form-templates-explained.md -- assuming such links are still needed; change them to the following locations, respectively:
    • [page templates](/build/site-structures#page-templates)
    • [form markup](/build/site-structures#form-markup)
  3. . . .

Currenty 168 tags (pages)

Bloke commented 4 years ago

Another avenue for Option C might be to pass in something like this:

{% include common_atts.html atts="class, breakby, wraptag" %}

and then iterate over them in the include file:

### Common presentational attributes

These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.

{% for att in include.atts %}
   {% if {{att}} == "class" %}
      // display class attribute info
   {% endif %}
   {% if {{att}} == "breakby" %}
      // display breakby attribute info
   {% endif %}
   ...
{% endfor %}
wion commented 4 years ago

I think anytime you can eliminate overhead editing by single-sourcing... Do it. And the tag pages seem to be prime candidates for simplified editing wins wherever they can be gained. Especially as there are so damn many of them.

As for understanding the liquid options and whatnot, thus what is the best course, I'll have to defer to your and Phil's better judgement on how to proceed there. I get lost when anything is too deeply woven around conditionals, and liquid has always been a bit abstract to me.

At any rate, I'm licking my wounds and directing my attention away from tags pages now, back to the other site sections and needed materials, and the various guidelines I still need to finish.

philwareham commented 4 years ago

Yes we should always try to utilise reusable code wherever possible to make everyones life easier. So I'm in favour of includes wherever we can.

Bloke commented 4 years ago

I'll see what I can do.

Bloke commented 4 years ago

Okay, it works. I've added an '_includes/common-atts.html' file and have coded in entries so far for:

We can add more entries, plus the additional global attributes, as and when we need them.

To use it in a tag page, call the include file and pass it a list of attributes, using the attribute name and then its default value as the argument. That value will be used verbatim in the tag default text, which means we can get rid of the silly 'see exceptions' thing, as we can put the exact defaults in per tag.

So, for the section_list tag:

{% include common-atts.html break="br" breakby="unset" class="tag name or unset" escape="html" label="unset" labeltag="unset" wraptag="unset" %}

That's live for that tag now. I've added automatic links to the cross-reference pages for each one, noted if an attribute is global or not, and also (for escape) linked to the tag-escaping doc, which will move when the tag basics area is consolidated. But once all tag pages are converted to use this, we'll only need to update the link once in the include file. Woohoo!

Any amendments, improvements and help converting the tag pages over to use it welcome.

Bloke commented 4 years ago

Made some more tweaks to the include file so you don't need to specify the default value if it's the most common default we use. Unfortunately, Liquid doesn't accept valueless attributes so if you want to use the default value, you have to specify ="". The defaults are:

So the above mentioned include for section_list could now be:

{% include common-atts.html break="" breakby="" class="tag name or unset" escape="" label="" labeltag="" wraptag="" %}
Bloke commented 4 years ago

Moved the global atts out of the common-atts.html file into their own global-atts include file.

So for the above mentioned section_list tag page, the include now becomes:

{% include common-atts.html break="" breakby="" %}
wion commented 4 years ago

Any amendments, improvements and help converting the tag pages over to use it welcome.

I've moved the tag pages checklist from #153 to head post here, to help keep track. You might want to add to the 'what to change' list just above it, as needed.

wion commented 4 years ago

127

wion commented 4 years ago

118

Bloke commented 4 years ago

For completeness, I've renamed the include file so it is grouped better in the file list with the global attributes include:

{% include atts-common.html %}