[wiki] Tag listings, attributes cross-reference

jsoo · 2010-10-05 10:43:54

I noticed article appearing in several places it shouldn’t in the attributes cross-reference. I duly removed “article” from the lists for:

excerpted
month
section
frontpage

because these are not, and never have been, available attributes in article.

Then I noticed “article” in the list for “id” and removed that too. Then, just for form, and as I had done with all the other attributes above, I tested it. To my surprise, you can use, say, article id="99". So I undid the last edit, but am left wondering why article allows this. From the code it’s obviously by intent.

That article and article_custom both support label and labeltag was missing from both the tag reference pages and the attribute cross-reference. Fixed those.

The order in which attributes are listed on tag reference pages varies from tag to tag. One senses a battle between alphabetization, grouping by function, prioritizing by usefulness, and just plain randomness (laziness?). I stuck label and labeltag down with wraptag et al. But there’s room for general improvement here.

Bloke · 2010-10-05 11:03:31

jsoo wrote:

To my surprise, you can use, say, article id="99"

Yes, I noticed that largely undocumented feature when I was developing smd_featured. Odd behaviour, which I chalked down to the fact <txp:article_custom /> and <txp:article /> use the same function under the hood (doArticles()) *shrug*. Interestingly, this behaviour led to this smd_featured bug because I was using article() internally which only honours the id attribute if you’re on a list page: put the site in an article context and you only get the current article out irrespective of id. Curious behaviour but half expected. I had to switch over to using article_custom() in the code to fix it.

Thanks for the other textbook fixes. The order of attributes does seem rather arbitrary. When I notice ones obviously out of logical sequence I tend to shuffle them about a bit, but perhaps I’m not helping here.

My approach has historically been to try to put most used/useful (or at least most impact) attributes first and defer the standard things like wraptag/break/class/html_id further down the list, otherwise you end up scrolling past attributes you know about as you become familiar with TXP. I also try and group the attributes by related functionality(ish) so if you can filter by id, category, section, status and time, then these go first. Perhaps the next ones might be offset and limit, then maybe sort because it affects the presentation. That then logically links to the wraptag, labeltag, break, class, etc attributes that also affect presentation. Right at the bottom I tend to put the ones you use rarely or can usually leave at default values: this avoids bombarding newbies with complicated options up top.

But I agree it’s far from an exact science so perhaps a more structured approach would be beneficial. Maybe if we could sub-categorize them with group headings it might help, so you can quickly hop to the section that appeals? No idea if that would work or confuse things further. I’ve tried it in my recent plugin docs but you know what they look like, so I’d best steer well clear :-)

Last edited by Bloke (2010-10-05 11:04:38)

jsoo · 2010-10-05 11:23:41

Bloke wrote:

Odd behaviour, which I chalked down to the fact <txp:article_custom /> and <txp:article /> use the same function under the hood (doArticles())

As I said it’s intentional:

// if an article ID is specified, treat it as a custom list
$iscustom = (!empty($theAtts['id'])) ? true : $iscustom;

Doesn’t make any sense to me.

My approach has historically been to try to put most used/useful (or at least most impact) attributes first and defer the standard things like wraptag/break/class/html_id further down the list

I agree with that approach.

Maybe if we could sub-categorize them with group headings it might help, so you can quickly hop to the section that appeals?

My preference would be to collapse the list to just show the attribute names, then expand to show individual definitions when clicked.

Bloke · 2010-10-05 11:32:15

jsoo wrote:

My preference would be to collapse the list to just show the attribute names, then expand to show individual definitions when clicked.

That might work. If you can pull it off then I guess it could be tried, although having to expand/collapse each might get tedious after a while. Unless there could be expand/collapse all too?

Tell you what, I’ll flip this Chilli Heatwave Dorito I have in my hand onto the desk and whichever way it lands will dictate what we’ll do…

*toss*

Damn, it broke and I ate it. You choose :-)

Last edited by Bloke (2010-10-05 11:33:11)

jsoo · 2010-10-05 14:06:54

Bloke wrote:

That might work. If you can pull it off then I guess it could be tried, although having to expand/collapse each might get tedious after a while. Unless there could be expand/collapse all too?

Sorry about the Dorito.

I think the simpler solution to satisfy both points is to add the attribute names to the TOC. That way experienced users get a quick scan of the available attribute names (and usually when I use the Tag Reference that is all I want to see) near the top of the page. (Speaking of which, it is strange to have the TOC below the summary.) For the rest, the full attribute def list is there to browse.

Edit: Or group the attributes, as you suggest. So the TOC would have:

Contents

Attributes
- Selection
  - id
  - category
- Presentation
  - label
  - labeltag

etc.

And of course you’d have the same sub-headings in the full attribute list.

Last edited by jsoo (2010-10-05 14:12:58)

Destry · 2010-10-05 14:15:23

One thought about attributes. If some represent a “set”, per se, that are common among many tags (thus wiki tag pages), it might be useful to put those attributes in a wiki template so it outputs to multiple pages rather than making the same edits multiple times. You could create as many of these templates as needed by whatever attribute groups you decide on.

Personally, I think expand/collapse functionality is getting a little gimmicky for a wiki. 2 cents.

els · 2010-10-05 14:21:31

Destry wrote:

Personally, I think expand/collapse functionality is getting a little gimmicky for a wiki. 2 cents.

FWIW, I think I agree with Destry here.

But I’d like to raise another question: what exactly is the use of the attributes cross-reference? Don’t misunderstand me, there may well be one or even more than one, I just haven’t been able to see one in all the time it exists.

jsoo · 2010-10-05 15:35:01

Destry wrote:

One thought about attributes. If some represent a “set”, per se, that are common among many tags (thus wiki tag pages), it might be useful to put those attributes in a wiki template so it outputs to multiple pages rather than making the same edits multiple times. You could create as many of these templates as needed by whatever attribute groups you decide on.

I had the same thought. There are maybe a few cases where the generic description would be missing some helpful information; what element does class apply to? But I was thinking to make one of the sub-groups “Common attributes”.

Personally, I think expand/collapse functionality is getting a little gimmicky for a wiki. 2 cents.

The TOC already does this, so I’m not suggesting anything new. At this point I’m only suggesting putting attributes into the TOC. Are there objections?

els · 2010-10-05 15:48:00

jsoo wrote:

At this point I’m only suggesting putting attributes into the TOC.

Then I probably misunderstood you :) Did you mean like this?

Attributes
- id
- section
- etc
Examples

jsoo · 2010-10-05 16:50:14

Els wrote:

Did you mean like this?

Yes. Possibly organized into sub-groups, at least for longer attribute lists.

However, this does mean getting the TOC to recognize the attribute term headings. They’re dt elements, not headers. I’m guessing it would be more trouble than it’s worth to convince the template to pick up dt elements, so it would mean redoing attribute lists as sub-headers and paragraphs instead of a definition list. Not sounding like such a good idea any more. It’s invalid HTML to put a header element inside a dt.

els · 2010-10-05 18:12:44

Jeff, that’s what I was thinking, such a lot of work… But have a look at what I just did on the variable page, would that be an acceptable alternative? Because I like your main idea.

Edit: here is a better example: screenshot. It wouldn’t require too many changes.

Last edited by els (2010-10-05 18:29:50)

rsilletti · 2010-10-05 18:39:19

Els

The attribute cross reference was originally devised as way of structuring and establishing not only a reference, but a guideline for encouraging standardization of attributes being used both in the core and in plugins. That was very early on in development and only marginally served that purpose then.
It also became clear very early on that in was a cumbersome setup and very difficult to maintain. IMHO the service it may have provided upon a time has long since passed and the work required to keep it current is probably greater than is worth the usage gotten from it. Removing it may resolve some confusion, however.

Textpattern CMS

Textpattern CMS support forum

#1 2010-10-05 10:43:54

[wiki] Tag listings, attributes cross-reference

#2 2010-10-05 11:03:31

Re: [wiki] Tag listings, attributes cross-reference

#3 2010-10-05 11:23:41

Re: [wiki] Tag listings, attributes cross-reference

#4 2010-10-05 11:32:15

Re: [wiki] Tag listings, attributes cross-reference

#5 2010-10-05 14:06:54

Re: [wiki] Tag listings, attributes cross-reference

#6 2010-10-05 14:15:23

Re: [wiki] Tag listings, attributes cross-reference

#7 2010-10-05 14:21:31

Re: [wiki] Tag listings, attributes cross-reference

#8 2010-10-05 15:35:01

Re: [wiki] Tag listings, attributes cross-reference

#9 2010-10-05 15:48:00

Re: [wiki] Tag listings, attributes cross-reference

#10 2010-10-05 16:50:14

Re: [wiki] Tag listings, attributes cross-reference

#11 2010-10-05 18:12:44

Re: [wiki] Tag listings, attributes cross-reference

#12 2010-10-05 18:39:19

Re: [wiki] Tag listings, attributes cross-reference

Board footer