Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#11 2020-12-23 14:38:34

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,663
Website

Re: soo_toc table of contents generator

I love the simplicity of this plugin, and it is still the best solution for in-article content lists.*

Being Soo is a bit scarce these days, I’m wondering how future-proof the plugin may be as is, but also whether it might ever see an evolution.

Here’s why I’m wondering… I want to optimize my CSS around using content lists. The plugin hard-codes ul.toc, if I’m not mistaken. But for content lists like on my policies page (and in the Txp docs now, as another example), they clearly demand using an ol list. I would even go so far as to argue that all contents lists should be ordered in web markup because whether content is a 1-2-3 process or narrative storytelling, the ideas and concepts, represented by document sections, are still conceived to following a logical flow to a desired end. Nothing random about it. Of course, in print material, the worry about structural markup is non-existing, but I don’t think it was ever really thought through for the same elements in web content; not that I’ve ever found any discussions on. Also, ‘Table of Contents’ is a rather technical label for what most of the publishing world just calls ‘Contents’, logically. While ‘toc’ make for a nice and short selector, the content element I’m labeling on the surface is ‘Contents’, so I’d like to optimize my CSS to that conceptual match.

Which brings me to the question… Can I safely modify the plugin to use ol.contents, thereby aiding my objective of tightening CSS, and forget about the plugin after that, or should I worry about plugin upgrades that would break what I undoubtedly will forget that I changed?

* Content lists for documents composed of collated articles via a pageless section are handled with etc_query.

Side

Not that I’m asking for this, but musing on the desire for the functionality to appease more tastes than my own.

I can imagine a core tag — contents or contents_list — that makes use of existing attributes and adds one more for indicating desired depth of contents list:

 <txp:contents wraptag="" class="" levels="" />

The levels="" attribute being the new one and meaning the same as the level="" attribute in soo_toc; the depth based on however the article body is structured. I typically use an h1 on titles then begin all ‘first-level’ sections in the body with h2. So a declaration of levels="3" would list headings from h2 to h4.

I currently use soo_toc as a shortcode tag this way:

<section class="contents">
  <hr class="startrule">
  <h2>Contents</h2>
  <txp:soo_toc level='<txp:if_yield name="levels"><txp:yield name="levels" /></txp:if_yield>' />
  <hr class="endrule">
</section>

And the resulting short tag:

<txp::contents levels="" />

But without the benefit of wraptag="" class="", unfortunately.

Remembering wraptag="" is optional, it’s easy to target the list with .contents ol or .contents ul, as needed, and ignore the plugin class altogether. Maybe I’ll do that at least and everyone can forget my self waste of time here. ;)

Last edited by Destry (2020-12-23 14:49:12)

Offline

#12 2020-12-23 16:26:31

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,792
Website

Re: soo_toc table of contents generator

Hi Destry!

The soo_toc tag supports wraptag and class attributes, so you can use an ordered list with any class name you prefer.

The tag also has a level attribute for assigning the upper bound (i.e., maximum of 6) of heading depth. There is no corresponding attribute for assigning a lower bound, but the plugin only looks in the article body. So if your first-level sections in the body are h2, that is what soo_toc will find, and it will render these as h2 tags.

So, to list only headings from h2 to h4, make h2 your first-level heading within the body, then set limit to 3 (correction : set limit to 4. limit matches the actual designated heading number, not the number relative to the top-level header found in the body).

Hope this helps.

Last edited by jsoo (2020-12-23 20:35:55)


Code is topiary

Offline

#13 2020-12-23 20:13:58

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,663
Website

Re: soo_toc table of contents generator

Hi Jeff! Nice to see you around. I’ve been using the plugin so long a certain way, I guess I started assuming that was the only way. Never mind me. Everything I need is there. /goes back to dunce corner /

Offline

#14 2020-12-23 20:36:03

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,792
Website

Re: soo_toc table of contents generator

Well, I’ll join you there. What I said above about the limit attribute isn’t quite correct; it will match the actual h-tag number. I’ve corrected my example in my last post above.


Code is topiary

Offline

#15 2020-12-25 14:23:51

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,663
Website

Re: soo_toc table of contents generator

Merry xmas, everyone. I’m sitting around at the in-laws doing squat so, you know, ironing out web problems.

This is to anyone, but I suspect it’s a situation with how the plugin works. Not being a dev, I can’t say. This is only local dev for the time being, but…

I’ve managed to refactor my CSS so that soo_toc now powers both the ordered and unordered contents lists; e.g. my policies page using <txp:soo_toc wraptag="ol" />, and any ‘default style’ contents lists elsewhere using the plugin’s default ul (no wraptag needing declared).

My contents lists are all marked up consistently within a section element like this:

<section id="contents">
  <hr class="startrule">
  <h2>Contents</h2>
  <txp:soo_toc  />
  <hr class="endrule">
</section>

That works and looks as designed when the markup is added to the top of the body field.

Naturally, I want to minimize that eyesore by using an easier to remember shortcode instead (called contents). The one I showed before without the wraptag="" attribute incorporated works fine, rendering output as expected.

But as I just discovered, if I add the wraptag attribute to the shortcode to account for all list type situations in my newly refactored CSS:

<section id="contents">
  <hr class="startrule">
  <h2<txp:if_article_id id="3"> class="nosync"</txp:if_article_id>>Contents</h2>

  <txp:soo_toc level='<txp:if_yield name="levels"><txp:yield name="levels" /></txp:if_yield>' 
               wraptag='<txp:if_yield name="wrap"><txp:yield name="wrap" /></txp:if_yield>' />

  <hr class="endrule">
</section>

…the shortcode won’t work.

That is, if I declare ol (<txp::contents wraptag="ol" levels="4" />), the ol elements wraps the entire section block:

<ol>
<section id="contents">
  <hr class="startrule">
  <h2>Contents</h2>
  <li><a href="#idselector">Heading</a></li>
  <li><a href="#contents">Contents Items</a></li>
  <li><a href="#contents-l1">Test h3</a></li>
  <li><a href="#contents-l2-1">Test h4</a></li>
  <li><a href="#contents-l2-2">Test h4</a></li>
  <li><a href="#table">Table Tester</a></li>
  <li><a href="#form">Form Tester</a></li>
  <hr class="endrule">
</section>
</ol>

If I leave out that attribute to use a default ul list (<txp::contents levels="3" />), no ul elements is added at all:

<section id="contents">
  <hr class="startrule">
  <h2>Contents</h2>
  <li><a href="#idselector">Heading</a></li>
  <li><a href="#contents">Contents Items</a></li>
  <li><a href="#contents-l1">Test h3</a></li>
  <li><a href="#contents-l2-1">Test h4</a></li>
  <li><a href="#contents-l2-2">Test h4</a></li>
  <li><a href="#table">Table Tester</a></li>
  <li><a href="#form">Form Tester</a></li>
  <hr class="endrule">
</section>

How to fix?

Last edited by Destry (2020-12-25 14:31:27)

Offline

#16 2020-12-25 16:07:28

colak
Admin
From: Cyprus
Registered: 2004-11-20
Posts: 8,469
Website

Re: soo_toc table of contents generator

Hi Destry,
Did you try using the labeltag and label attributes? I also sightly amended your yields.

<section id="contents">
  <hr class="startrule">
  <txp:soo_toc <txp:if_yield name="levels">level='<txp:yield name="levels" />'</txp:if_yield> 
               <txp:if_yield name="wrap">wraptag='<txp:yield name="wrap" />'</txp:if_yield>
               label="Contents"
               labeltag="h2"
 />
  <hr class="endrule">
</section>

Yiannis
——————————
neme.org | hblack.net | State Machines | NeMe @ github
I do my best editing after I click on the submit button.

Offline

#17 2020-12-25 16:27:36

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,996
Website

Re: soo_toc table of contents generator

Slightly confused. Your short code yield is looking for the wrap attribute but you’re passing in wraptag. Might this work better? …

<txp::contents wrap="ol" levels="4" />

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

#18 2020-12-25 16:35:09

colak
Admin
From: Cyprus
Registered: 2004-11-20
Posts: 8,469
Website

Re: soo_toc table of contents generator

Bloke wrote #327854:

Slightly confused. Your short code yield is looking for the wrap attribute but you’re passing in wraptag. Might this work better? …

I took it that Destry used a shorthand for wraptag in his yield name.


Yiannis
——————————
neme.org | hblack.net | State Machines | NeMe @ github
I do my best editing after I click on the submit button.

Offline

#19 2020-12-25 16:37:04

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,792
Website

Re: soo_toc table of contents generator

I’ll have to think about this one a bit. Currently, if soo_toc has a wraptag other than ul (the default) or ol, it returns a simple (i.e., non-nested) listing of all h# elements, using the wraptag and break as usual for Txp. So that’s what’s happening here.

So maybe a quick-and-dirty solution would be something like this:

<section id="contents">
  <hr class="startrule">
  <h2<txp:if_article_id id="3"> class="nosync"</txp:if_article_id>>Contents</h2>

  <txp:if_yield name="wrap"><txp:yield name="wrap" />
    <txp:soo_toc level='<txp:if_yield name="levels"><txp:yield name="levels" /></txp:if_yield>' wraptag="ol" />
  <txp:else />
    <txp:soo_toc level='<txp:if_yield name="levels"><txp:yield name="levels" /></txp:if_yield>' />
  </txp:if_yield>

  <hr class="endrule">
</section>

assuming that ol is always the wraptag you want in this case. Not pretty, but perhaps it will work?


Code is topiary

Offline

#20 2020-12-25 17:09:32

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,663
Website

Re: soo_toc table of contents generator

A lot of people at the in-laws, apparently. ;)

colak wrote #327855:

I took it that Destry used a shorthand for wraptag in his yield name.

Correct. I was just naming the yield tag, but using the plugin’s wraptag attribute and passing in a value of ol.

But, Colak’s code works!

I don’t know why, but using the plugin’s label and labeltag attributes instead of straight markup made the problem go away.

(I also changed the h2 to h1 to be consistent with similar section headers (back matter sections), and that allowed me to remove three ugly CSS lines. But that’s a different thing.)

Thanks, gents. Back to your nog.

Last edited by Destry (2020-12-25 17:15:23)

Offline

Board footer

Powered by FluxBB