Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: [attribute] breakby
Bloke wrote #333552:
Each ‘listy’ tag that has the capability of sorting has its own set of field attribute values.
Ah, listy. I see what you did there. It’s not the same as list tags, but conceptually too similar and needs a differing alias, as it were. I like listy, but…
If we have atomic tags, meaning tags that output a single content element, or something like that, then what would be a decent alias for the tags that output multiple elements by some repeating way? ‘Pattern’ tags? ‘Grouping’ tags? ‘Rolling’ tags (as in list rolls)? I’m shooting for the listing concept but it’s a hard one to synonymize in this case.
Sticking with listy for now: how would the listy tags and the existing ‘list tags’ match up? Some overlap, probably, but any significant difference? (It’s a bit of a cloud to me at the moment.)
What would something like else fall into? Neither group, I guess. So we’d need another referring alias group in context of attributes discussion, say ‘neutral’ tags? Meaning tags that have no attributes of their own but can use global attributes.
There are about a dozen [tags] that use that [sort] attribute and they’re all unique. So yes, it could be done in the way you specified, listing out each tag after the generic attribute definition. As long as it’s only defined in one place (to make updating it easy), and it’s clear for people to find, then I’m happy with slicing and dicing content however makes most sense.
To be sure, I am still just trying to get my head around whether or not such an evolution of the tag docs is logical. My intuition as an often confused Txp user trying to understand tag logic says, yes! But by that fact of often being confused, the user side of me might be wrong. (I was not the best person to write the Theme’s doc, perhaps, because I never use that functionality. It probably needs a rewrite now?)
Another ‘issue’ (besides convenient links to individual attribute docs/examples) that stands out for me as a troubled ‘learner’ (the new user scenario) is that on the surface (the docs homepage) there is no trailhead pointer leading people down the path to attributes nirvana; one just sees Tags, Tags, Tags. That makes sense in one frame of mind, but other minds might think to want to come at it from another direction. For example, what started me on this campaign was having this on my plate (and it’s not the first time for such scenarios):
<txp:article sort="UPPER(Title)" class="glossary_terms" limit="0"
breakby="glossary_sublists"
breakform="glossary_blocks"
listform="glossary_terms_alphabetical" />I can’t even remember where that originally came from, but it was in my page template, and in one of those late-night, tired, and slightly-frustrated moods, I was like ‘what the hell does breakby="glossary_sublists" and breakform="glossary_blocks" even mean and do?’ Right then and there I was wishing for breakby and breakform links in a index page, equal to the tags index page, that took me directly to every possible thing I needed to know about those attributes, with sufficient real use-case examples, such as the one just given.
But that does not currently exist. You have to come at it from other docs breadcrumbs, and by the end of that sleuthing you still arrive at rather brief explainer paragraphs without demonstration or real context examples; not the kind you would get from the forum, but which nuggets of gold may or not exist after dubious forum searching, scrolling, and scanning attempts.
I hear what you’re saying, though, about the potential increase in docs files. On one hand it’s archived in a repo, which is based on a folder/file system, so that’s not really an issue (if but an energy issue). On the other hand, if the architecture is not sensibly conceived, editor’s have to edit more files than necessary. So, yes, we’d want to ensure that even though we parse attributes out into their own docs pages to gain the benefit of indexable URLs (thus easier to point to), we’d also want to make sure content is edited in such a way that—for the most part—the redundancy is minimized to the max, to lessen the long-term maintenance burden.
I know you were thinking of ways to use include pages and related logic, much like can be done in Txp, and I don’t want to trip up your progress there.
Let us stew on it for the summer. We can revisit in the colder months. Maybe others would be kind enough to pipe in here and give their opinion. The repo, being it is one, could always have an experimental tags branch setup. If it goes no where, it goes no where, and easy to snip off again.
Last edited by Destry (2022-06-09 12:17:45)
Offline
Re: [attribute] breakby
Back to the thread’s topic (and I don’t mind the docs discussion detouring, keep at it)…
Here is the block taken directly from the ‘Global attributes’ list in the Learning about tags page:
breakby="integer(s)"
Used to group list items when separating bybreak. Possible values are lists of integers, like2(groups of 2 items) or1,2(alternate groups of 1 and 2 items). Otherwise, the value is evaluated on each loop and `break` happens as soon as it changes. Note that `string` must be enclosed in double quotes.
Default: 1 (unset) (see breakby cross-reference).
(Ah-ha! So there is a buried link to that specific anchor in the cross-reference.)
I don’t see any mention here of the ability to use a Form name as a value, as I did in that code example in the previous post. Is there a reason it lacks here? (So, as an example, I’d expect all possible use-cases to be explained in a dedicated breakby page.)
Also, ‘Default: 1 (unset)’…
- ‘Default’ means default tag behaviour, without use of this attribute at all?
- ‘1’ means an integer value of
1? - ‘unset’ means the same as not using the attribute at all in a tag (versus not including a value), no matter what syntactical form (i.e. it does not mean
breakbyorbreakby="")?
If so, then maybe all that can be stated more plainly as something like this:
Default behaviour equals
breakyby="1". This is equal to not using the attribute at all in any syntactical manner, whether key (breakby) , key:empty-value (breakby=""), or key:value (breakby="n", wherenis an integer).
Ditto in the cross-reference page block, which is pretty much redundant text to the block in the global attributes list.
If this was all written into a single page, which would include a section on the syntactical pattern’s possible (as I was drafting), the reference to ‘any syntactical manner’ would be clear in context and it would not be necessary to add those parenthetical clarifications.
Last edited by Destry (2022-06-09 12:16:18)
Offline
Re: [attribute] breakby
I don’t see any mention here of the ability to use a Form name as a value, as I did in that code example in the previous post.
Well your form name is actually a “string“ , although cognitively the jump to “use a form” is a little difficult for me. But I have more than once had problems with understanding exactly what “string” is – e.g what I thought was a “keyword” in an example Bloke (stef) gave was actually a “string”…
IOW my humble understanding, “string” = “a series of alphanumerical characters”. I am sure I will now be send to a reeducation camp for this explanation…
Where is that emoji for a solar powered submarine when you need it ?
Sand space – admin theme for Textpattern
Offline
Re: [attribute] breakby
Hehe. Yeah, we could do with demystifying some of the terminology. ‘string’ – while technically accurate – doesn’t really cover what you can do with it. Although a form name is a string, it triggers different behaviour because it goes and fetches a form and uses its contents rather than just using the (string) contents of the attribute verbatim.
Now that the docs repo is self-hosted (yay, Pete) we have more scope to run Jekyll and other shell scripts which weren’t available to us when hosted on GitHub. That might be helpful for us to think about this in a more program-oriented way, e.g. define tags and their attributes in some terse markup language such as YAML and run a script to generate the tags doc pages and attribute cross ref pages. Then we only ever update in one place and rerun the script to spit out the docs.
Food for thought. It’s just code. And code is pottery.
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: [attribute] breakby
phiw13 wrote #333560:
your form name is actually a “string“
Good point.
cognitively the jump to “use a form” is a little difficult for me.
Me too. But apparently it is needed for what I am trying to do.
But, again, good point on the string thing, that brought that use context out a bit for me there.
my humble understanding, “string” = “a series of alphanumerical characters”.
Yes, I think that’s correct. I just saw that explained somewhere in context of using <txp:title breakby="" yield="1" /> to give the first letter of a title, for example.
Last edited by Destry (2022-06-09 12:29:34)
Offline
Re: [attribute] breakby
breakform is not in the tags attributes cross-reference, btw.
Offline
Re: [attribute] breakby
Well, we’ve got (currently) 3 contexts for breakby.
- Breaking by txp tags (inline or in a form) as described here concerns only content listing tags:
<txp:article />and its derivatives,<txp:images />,<txp:linklist />and<txp:file_download_list />. This could change, but is technically not trivial. - Breaking by numbers works for all tags (4.8.9)
- Breaking by character(s) works for ‘atomic’ tags, i.e. those that can not loop over a collection of items (articles, categories, etc) and thus previously had no
break,limitand other ‘list’ attributes.
It’s probably too early for a definitive guide to these freshly modified attributes.
Offline