[attribute] breakby

Destry · 2022-06-07 16:01:12

From the attributes page:

breakby. Used to group list items when separating by break. Possible values are lists of integers, like 2 (groups of 2 items) or 1,2 (alternate groups of 1 and 2 items). Default is 1 (actually unset).

I don’t really grok this without an example or three. Context is key. I know I’m using one in the glossary puzzle, but that’s just because I copied a snippet from the boards, not because I actually understand the function or potential.

Anyone want to take a stab at something short and sweet that would better inform the likes of me?

And what does it mean to use one without a value (i.e. breakby="")?

Put my vote in for adding attributes examples to that docs page, just like done in the individual tag pages. It would really help. We can start here. Help me understand and I’ll edit the file.

Oh, and I guess you can use the attribute by itself, without the empty value (i.e, breakby). An example is given here, and that does look like deep intel being laid down there, but it’s still too deep for some people. It seems we need writers who can take that gold info and turn it into even simpler layman’s terms. There is so much rich potential, I’m sensing, in what is possible, but no way to know it.

I am sad to say it, but I am not one of those people that easily sees through code abstraction, which makes me terrible for helping with this kind of documentation. Textpattern used to be so easy, and if you couldn’t do something you added a plugin, or just went without. No three ways about it. The good ol’ days of simplicity. Now… we have to map the genome.

Last edited by Destry (2022-06-07 16:25:53)

etc · 2022-06-07 16:36:17

Unfortunately, the only reliable/up-to-date txp docs is its code. You’ve done a huge docs rework (themes) few years ago, but every new version unavoidably obsoletes some parts of it. We (devs) keep traces of changes in History, but the docs get outdated faster than we update them, so any help is more than welcome.

So, breakby is now (4.8.8) empowered and extended to all tags. The link you cite describes its original behaviour for listing tags, like <txp:article />:

<txp:article break="hr">
    <txp:title />
</txp:article>

would output something like

Title 1
----------
Title 2
----------
Title 3
----------
...

But with breakby="2" it would be (see here for the motivation)

Title 1 Title 2
----------
Title 3 Title 4
----------
...

The next dev iteration has allowed breakby (still for listing tags) to evaluate a txp code and split the list when it changes. For example,

<txp:article breakby="<txp:posted format='%Y' />" sort="Posted" break="hr">
    <txp:posted format="%d-%m-%Y" />
</txp:article>

would output

02-07-2017 13-11-2017
--------------
11-05-2019 ...

splitting article list by year. Optionally, the breakby code (like <txp:posted format='%Y' /> above) can be put in a form and called via breakby="form_name". And a basic break can be replaced by a breakform, but it deserves a separate discussion.

Well, 4.8.8 has brought yet another lot of changes, TBC.

Destry · 2022-06-07 17:01:12

Thank you, etc.

I totally understand. Situation evolves, and docs are a thankless, time-consuming job, but you devs are often the ones having the knowledge to get the initial drafts out. I know others grasp knowledge quicker than some, too, but just don’t help log it in the docs, for whatever reason. (I like the forum, but you know, old gripe of mine about centralizing info where you expect it to be.)

I was just reading here, too. Somebody has done good work on that page. I was coming back to point out there’s a distinction between docs that explain and docs that demonstrate. The best docs will do both by whatever means. We’ve got pretty good docs that do the former, but less so the latter. What you’ve done above is more of the latter, and that really bridges it. Thank you.

A ton of work, I know.

Sorry to come across like an old crank.

Last edited by Destry (2022-06-07 17:04:24)

Destry · 2022-06-07 17:27:13

On the matter of like info in multiple docs locations… that is a potential issue for remedying. When someone does find the time to edit, the task is made more tedious when having to edit multiple locations and make those pages conceptually sync up.

Attributes, for example, might be at that point now where, like tag pages, each has its own dedicated page/url, where examples and demos can be fleshed out, however much or little. An index page like tags have too, so subcategories like ‘global attributes’ are quickly sorted/accessed.

etc · 2022-06-07 18:40:01

Destry wrote #333544:

Sorry to come across like an old crank.

You don’t have to be sorry, I perfectly understand and acknowledge your gripes. But what can I do — my name is bloatware.

A point we care about, however, is bw-compatibility. Almost everything that worked in 4.5 core still works in 4.8. Save for some old plugins, but that’s their nature.

Destry · 2022-06-08 10:56:57

Destry wrote #333545:

Attributes, for example, might be at that point now where, like tag pages, each has its own dedicated page/url, where examples and demos can be fleshed out, however much or little

The last thing anyone wants to hear is suggestions for docs work, and I know there is stuff in limbo with that already, but hear me out.

The tags reference has always been the meat and potatoes of docs, and while the ‘tags’ part of it is structured well enough, I think the attributes/values side of the tags docs is not. As one obvious example reflecting the greater problem: you cannot link to a given attribute to read up and learn about it; one has to click, click, hunt, scan, scrolldown to find the particulars. A straightforward restructuring of that information would really help users a lot; and docs maintainers, because it will be easier to update docs discrete topics and related examples are in one place.

Here’s the proposed model. Let’s start from the top — the docs homepage. Turn your attention to the Tags section and visualize the ‘Core tags’ list looking like this instead:

Core tags

Tags index (Tags use basics)
Attributes index (Attributes basics)
Tags in development

The parenthetical arrangement both keeps the same list length (layout considerations), and ties in the two basics docs to their respective topics (tags and attributes).

Then…

STEP 1 — Attributes basics page

The existing Tags use basics page (going by the title, ‘Learning about tags’), which is currently quite long, would be parsed into the two basics docs; i.e., attributes info would be extracted to its own doc page, Attributes basics, and the current doc would remain, a lot lighter.

Yes, a little editing will be needed to smooth out paragraph transitions, reestablish connections between the pages, … but overall a pretty simple task.

That results with:

Tags index (Tags use basics)
Attributes index (Attributes basics)
…

STEP 2 — Attributes index

This would be a conversion of the Tag attributes cross-reference into something more like the Tags index, having a subcategories section at top (e.g. for ‘Global attributes’), and alphabetized sections at bottom, where each attribute is listed and links to its own page.

Or keep the cross-reference and make a new index; though I think you’ll find the cross-reference is obsolete after the restructure. But whatever, backwards compatibility. Remember the idea is to make docs easier to edit, too, not just use. Legacy docs don’t help with that after restructures.

In relation, the info in the new ‘Attributes basics’ page would be further refined by extracting out what can be ported to the new ‘Attributes index’. A couple of examples off the top of my head:

The Global attributes list can be moved over and restructured accordingly:
- A Global attributes link added at top in the subcategories section that sorts those attributes.
- Each attribute alphabetized in the bottom sections, global and otherwise.
The large escape attribute section can be parsed out, going into its own ‘escape’ doc. That would be a meaty page for sure.

Which brings the third and last step.

STEP 3 — Attributes pages

All attribute doc pages would be modeled like tag pages, but instead of ‘Attributes’ sections you might have ‘Values’ sections.

Likewise, all relevant attribute/value examples that were currently in the Tags basic page could be parsed in with their respective attribute pages. And definitely new examples written in over time, like the one Oleg gave in this thread, that better demonstrate what a function does. And now it’s much easier to do in a dedicated page, no space confinements.

I think you see the plan at this point.

So now when someone is asking about ‘global attributes’, or the escape attribute itself, or, as in the case of this thread, the breakby attribute, we can easily give a link to that page where all the explanation and demonstration is provided on platter and cross-linked with the index and the other tag page contexts. A real tags ontology.

I forgot to mention, I could help with getting the architecture of this in place (least I could do for throwing the idea out there), but I wouldn’t be able to commit until after July.

Last edited by Destry (2022-06-08 14:21:25)

Bloke · 2022-06-08 12:06:34

Good idea in theory. And we had a cross-ref for atts before but it was too hard to maintain (I wanted to script it so it periodically pulled from the live tag docs one day).

Global atts would probably work, and definitely should be ‘write once and link’. That’s sort of been done already by pulling them out into separate include files.

The fly in the ointment is that attributes in some tags take different values compared to others. Or the attributes behave slightly differently. How would we reconcile that?

Destry · 2022-06-08 13:19:17

Bloke wrote #333548:

The fly in the ointment is that attributes in some tags take different values compared to others. Or the attributes behave slightly differently. How would we reconcile that?

You mean the same attribute has different value contexts in different tags?
What would be an example attribute having the most unique contexts?

I guess in that case you would account for the different contexts in the attribute’s dedicated page. I’m assuming that’s not unique contexts to every existing tag, so the group associations should be manageable?

This would require a new info design pattern different from tag pages, but that’s okay. Form fits the purpose, and all that.

Off the top of my head, theoretically:

=========

{Attribute}

The {attribute} attribute is a [global attribute] …

Value to tag association

This attribute has the following different key:value contexts depending on the tag in which it is used.

`Value-X`

The value-x value has {n} possible contexts of use in relation to the following sets of tags.

{A specific use context}

Elaboration paragraph about the context.

{inline, list, of, linked, tags, having, a, common, association, with {value} in this context}
- or -
{a single link to a repeating group of tags by a given group alias; e.g. ‘atomic tags’}

{another specific use context}

Elaboration para about the context.

{inline, list, of, linked, tags, having, a, common, association, with {value} in this other context}
- or -
{a single link to a repeating group of tags by a given group alias; e.g. ‘atomic tags’}

<pattern::repeating_sections_as_needed />

`Value-Y`

The value-y value has {n} possible contexts of use in relation to the following sets of tags.

<pattern::repeating_sections_as_needed />

======

That may not fit exactly. I’d have to get a clear idea of what the associations/contexts are, exactly, and if there’s too many to be feasible, but maybe you see what I am getting at; a way to group them out first per value then per context.

And if there’s any of that repetition stuff (e.g. common lists of tags for value context) that could be single-sourced from a single snippet file or something, all the better. But I can’t say at this juncture.

If those tag lists are quite long, we could give them alias associations, maybe — e.g. the ‘value-context list of tags’ — and instead of including the lists from another file, we simply put a link on that short alias and let people go see what that list is? Again, it’s hard to guess solutions without a better idea of how many contexts we’re talking about.

~~Or maybe we only describe where contexts are different between tag groups from a greater default situation? Describe the lesser delta situations, in other words.~~ Too abstract.

Last edited by Destry (2022-06-08 14:06:30)

etc · 2022-06-08 13:32:53

Bloke wrote #333548:

The fly in the ointment is that attributes in some tags take different values compared to others. Or the attributes behave slightly differently. How would we reconcile that?

Rather opportunely, breakby is a good example here. In txp 4.8.8 it has been extended to all tags, including the ‘atomic’ ones, that process a single item and not a list. For example, <txp:title /> outputs only the current article title and not a list of items (titles), like <txp:article /> could do. Hence, a construction like

<txp:title breakby="<txp:posted format='%Y' />" break="hr" />

would be meaningless, since there is no items to compare. So, breakby has a different function for ‘atomic’ tags – it is a string by which the tags output must be split. Jointly with break, limit and other attributes, this allows for processing plain strings as arrays. For example, to extract a random item from a comma-separated list, one could use

<txp:variable name="salad" value="apple+banana+cherry" breakby="+" sort="rand" limit="1" output />

To output the first character of a title, one could use

<txp:title breakby="" limit="1" />

Here breakby="" means ‘split the string into its characters’. Finally, a valueless breakby means splitting by comma and removing the surrounding spaces (the standard txp behaviour).

Destry · 2022-06-08 13:57:10

Thanks, Oleg. So we have, what, two or three contexts for breakby, for example, not including the ‘meaningless’ one. That seems very manageable.

breakby is a good example here. In txp 4.8.8 it has been extended to all tags, including the ‘atomic’ ones,

I like the term ‘atomic’ for delineating those tags.

That would be useful as a kind of alias I was talking about. Then you could talk about the atomic tags collectively that way. And instead of listing them all out each time you give a link to the Atomic tags page, and add the link in the subcategories section of the Tags index, for example.

If we had to come up with other aliases for varying tag groupings, why not. Surely there is a logic to the groups that would suggest a feasible alias in each case? I’m out on a branch now.

Last edited by Destry (2022-06-08 14:10:09)

Bloke · 2022-06-08 15:26:35

Destry wrote #333549:

You mean the same attribute has different value contexts in different tags?

Precisely. Most are fairly standard and take empty (valueless) or boolean options and they generally do the most logical thing. Although depending on the tag they might interpret values slightly differently – these are highlighted in each tag doc, which is good as they’re in context.

But think about a common attribute like sort. That takes on whatever values are in the database table, ~~plus specific construsts (in some tags) like FIELD(column, val1, val2, ...) to sort in a specific order~~ EDIT: that might not actually be the case – can’t recall.

So the linklist tag has:

category.
date.
description.
id (link id#).
linkname.
linksort.
rand() (random).
url.

But the article tag has:

AuthorID (author name).
Category1.
Category2.
comments_count.
custom_n where n is the number of your custom field – for numeric values use (custom_n+0).
Expires (expiry date).
ID (article id#).
Image (article image id#).
Keywords.
LastMod (date last modified).
LastModID (author name of last modification).
Posted (date posted).
rand() (random).
Section.
Status.
Title.
url_title.
Each field in the textpattern database table can be used as a sort key.

Each ‘listy’ tag that has the capability of sorting has its own set of field attribute values. There are about a dozen that use that 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.

Last edited by Bloke (2022-06-08 15:27:45)

Destry · 2022-06-08 17:42:00

Hmm… I see what you mean. No easy way to treat that one in a consistent way.

But maybe that section of that particular attribute page just uses a statement explaining the variable contexts and to see a given tag page for more specifics in that case; you know, without linking to every tag page.

That’s just one section of the attribute’s page, after all. Here’s the sections I’m playing around with, as it happens to be shaping, for a hypothetical breakby page. I would not consider any of it correct or final yet:

intro para (type of attribute, if applicable, and what its function is in general)
Syntax
- key (breakby): atomic tags and listing tags
- key:empty-value (breakby=""): atomic tags
- key:value (breakby="n"): listing tags
Values
- integers
- form name
Context of use
- Atomic tags context
- Listing tags context
Examples

I was just playing with idea at this point and had questions. For example if a tag is not an ‘atomic’ tag, does that make it a listing tag automatically? Does ‘listing tag’ even make sense? Are there other possible types that would not fit in the other two? What would a variable tag be?

In any case, I guess for the sort attribute you would just have a general statement, as mentioned, in the ‘Values’ section, and maybe you don’t have a ‘Context of use’ section at all. Don’t know, but I can see even just the intro, syntax, and examples sections being moderately beneficial as a URL landing spot.

I look at the cross-reference page and I see a section way down at the bottom for ‘sort’. It’s not big, and that’s okay, but man, it would be nice to have a link to that section, even. It seems to me a page fills that same objective without requiring a long-ass ToC. After that, what we put in the page can be simply whatever is deemed best needed.

But, hey, I am not looking for a lot of time to throw away. So, no worries if this ends here. :)

Last edited by Destry (2022-06-08 17:45:19)

Textpattern CMS

Textpattern CMS support forum

#1 2022-06-07 16:01:12