Glossary architecture

Bloke · 2020-06-07 18:57:01

Destry wrote #323594:

your resulting list example does not separate terms by alphabetical sections, which I might want to do.

If it was a native Txp solution, you would do that with <txp:if_different> comparing the first character of the term. If the xsl stylesheet can be teased into returning the first letter of the term, you may be able to do something similar there. I’m not an XSLT guru, unfortunately, but it does have a substring function.

That said, things have moved on a lot since 2016. I wonder if this can be realised in a core solution now with some <txp:article_custom> cleverness, iterating over the synonyms to build up the variable containing the entire list. Then maybe a custom shortcode to reorder the list and stuff it on the page wherever you need it: <txp::glossary />.

Not sure how easy that would be. I’d have to grok your setup a little better to figure out if we could do this more simply nowadays.

Destry · 2020-06-08 10:22:49

Fawk. Just wrote a detailed response. Session timed out. Browser didnt’ recover it. Nothing pisses me off more than having to rewrite detailed writing lost to web technology.

Is it really necessary to have such short session times? Or do I really have to use an external editor just to ensure forum post drafts are not lost?

/back to the editor/

jakob · 2020-06-08 10:41:37

Have a look at this thread too which discusses another way of alphabetising a list of articles using more core tags.

Bloke · 2020-06-08 10:48:09

Destry wrote #323610:

Just wrote a detailed response. Session timed out… Is it really necessary to have such short session times?

Feel for you. I’ve stepped on that rake more than a few times. Now, before hitting Submit/Preview, I’ve actually taken to opening a fresh forum tab to see if I’m still logged in and, if not, logging in again then posting straight away. Annoying, but saves rage.

I think the session time’s something like 30-45 mins (a guess). Which is fine for short posts but if, like me, you start writing a post then go off and collect some more background info, get distracted by something shiny and come back to it, that time can easily be eaten.

Destry · 2020-06-08 11:48:28

Bloke wrote #323615:

I think the session time’s something like 30-45 mins (a guess).

Yeah, that should be enough. I’ll have to remember to bump it with a preview click more often, I guess. Or draft in Writer, the always-sensible move.

Anyway, the rewrite, not as eloquent as before…

In relation to the original example, I’m roughly aiming for the home/glossary/article structure (all other design elements aside), and the synonymous terms handling, which I’ll come back to.

In my case, if I use that arrangement, the homepage would be the glossary project’s home and about page combined, with some visual pizazz to help give a sense of the site’s subject at a glance. The homepage would be like a book’s front and back jacket covers in purpose/function.

On the other hand, I’m also tempted to put the glossary on the homepage directly, and either a brief overview para at top of that or, more sensibly, use an article for About content and link to it from the footer, for example. But for the moment, the previous structure is on the table.

Either way, I intend on using the /titles only URL pattern (i.e. glossary.domain.tld/term), so how I handle About info wouldn’t make much difference (glossary.domain.tld/about). And if I can get away with using only the ‘default’ section/page/style for the whole site, and whatever forms, of course, I’d be happy.

I like how that site handles the synonymous terms in relation to primary terms. That was the main reason I pointed the site out as a glossary model. And the glossary terms list(s) also have to be ascending alphabetically (not by date, etc). Oleg seems to have captured both behaviours perfectly in his solution, though I’ve not got any further yet than installing the plugin.

[ADDED] I also like the breadcrumbs, but I’m not sure that would work in a sections-less site. If I did use them, I’d want to add the letter sections between ‘Glossary’ and the active term (e.g. Home/Glossary/A/Arsehole). Though that might not be important if the search and tagging features are strong enough. The example glossary linked above has about 210 entries. I don’t think I’ll have that many, but it’s not clear yet.

I’m happy using Oleg’s solution if it’s still considered contemporary enough for the long term. He has captured the synonyms behaviour and alphabetization of terms perfectly, as far as I can tell. But I am also happy using a native solution if it’s not so logically complex that my brains melt and run out my arse. I can maybe manage Oleg’s solution if I don’t have to do more than plug in the snippets, but their constituent syntax is beyond my level or desire to grock.

(Btw, I’ve checked my PHP extensions, and the ‘DOM’ extension — an etc_query requirement — is not listed in the .ini file(s) at all. Don’t know if it’s there by default in PHP 7 or not, or how I would add it, if needed. Also, the XPath link in the plugin docs is broken. Looks like ‘Schools’ updated it to this)

(Remember, I’m happily moving further away from web tech, not closer. If I retain what little I know in the next five years, it’ll be a wonder.)

Textpattern has really blossomed as of late, and that’s fantastic for a new generation, and the die-hards. The logic built into tags now is profound and, in my opinion, often quite abstract. Too abstract for me, anyway. The increasing number of attributes and values, with their symbolism and nuanced magic, seems increasingly geared to developer wavelengths. Sure, you ‘don’t have to know PHP’, but it’s almost a new kind of tag-based programming language to learn, beyond simple HTML. Combined with ‘yield’ and ‘variable’, I’m often puzzled by what others find fundamental. Either that or you stick with the foundational tags that work by themselves and run simple sites. Nothing wrong with simple sites. I like simple sites, front and back.

Maybe my glossary project turns into a general glossary theme so others like me without a dev gene can manage without having to hire anyone. If we can decide which is the easier path in that respect, I might consider putting that dry- prefix to use, or more appropriately, the pub-.

Last edited by Destry (2020-06-08 11:52:53)

gaekwad · 2020-06-08 12:52:21

Bloke wrote #323615:

I think the session time’s something like 30-45 mins (a guess).

It appears to be 2400 seconds (40 minutes), I’ve just tweaked it up to 3600 seconds (1 hour). If bad stuff happens, we can flip it back.

Bloke · 2020-06-08 13:05:41

gaekwad wrote #323626:

It appears to be 2400 seconds (40 minutes), I’ve just tweaked it up to 3600 seconds (1 hour).

Thank you. That’ll please long-formers like me.

Bloke · 2020-06-08 14:01:57

Destry wrote #323622:

In relation to the original example

That’s a nice looking site. In terms of navigability, I’d be tempted to dim letters such as Q, Z and K in the alphabetic list at the top as they contain no terms. Maybe even make them unclickable, rather than click to find there are no terms. Oh, and I’d remove the duplicate ‘O’ :)

Either way, I intend on using the /titles only URL pattern

Remember, from 4.8.x you can use different permlink schemes for any section so you’re no longer limited to just one site-wide. If the glossary section suits /section/title or /breadcrumb/title better, use that. You can’t (yet) use custom schemes though, so inserting the letter as an extra navigable chunk is not possible.

[well, it is possible but you have to add any stuff after any content that Txp expects – this is what things like smd_access_keys does: adds crud after the URL for its own use. You can then use <txp:page_url> to get at these additional URL components and use them in your page.]

I can maybe manage Oleg’s solution if I don’t have to do more than plug in the snippets, but their constituent syntax is beyond my level or desire to grock…. The logic built into [Txp] tags now is profound and, in my opinion, often quite abstract. Too abstract for me, anyway.

The very programmery nature of Oleg’s solution and the need to understand XSLT a bit is the reason I suggested that core might be bale to help now in a more readily-understandable form.

Yes, things like <txp:evaluate> and the escape attribute need a bit of brain power but for this project I was more thinking of using shortcodes to output various chunks and plugging those into a regular <txp:article_custom> tags. Sorting the data in the second pass might be something that remains a plugin, as is iterating over comma-separated values. Txp can find and match on custom field lists but can’t (yet) iterate over them natively without a bit of trickery.

[side note: perhaps introduce container support such as the following. We’d need to factor in trimming internal values somehow, and how to grab the current value similar to the way <txp:yield> does for output_forms:

<txp:custom_field name="synonyms" separator=",">
    do some stuff here with 'current' value set to the iterable content item
</txp:custom_field>

]

With the ability to now filter by custom field directly from the URL you might even be able to turn this project on its head. Maybe write your articles and use a custom field to list the terms mentioned. Then use those to offer links back to the content from glossary items so it functions more like a combined glossary/index.

Dunno. That might be tricky, but it’s something I’d be keen to explore and see how far we can get with native tags. Building tables of contents is fairly easy. Building automated indexes is harder and would be something that would certainly set Txp apart if we could demonstrate a way of doing it!

Destry · 2020-06-15 06:45:35

Thank you, Bloke. I’m still working on getting some representative content together. Everything will probably be local for a while. But I will undoubtedly need to get back to this thread and some questions eventually.

Destry · 2020-09-23 12:33:00

Resetting the stage for synonymous terms. The idea being to merge the current glossary architecture that works with etc_query to add synonymous terms to the glossary lists via a ‘synonyms’ custom field, or to achieve the same result in a native manner. Frankly, I don’t care which way it is because both are going to be a learning experience for me that I won’t be able to muster alone. More important to me, I think, is the approach that requires the fewest number of form templates and the fewest lines of markup overall. That makes a big difference when coming back to it years later and trying to remember what’s going on under the hood.

So for the sake of stepping off the bridge somewhere, I’ll recap what the current glossary architecture is and does (conditions satisfied), and then give a closer reflection on Oleg’s XSL approach. Later, if someone wants to propose a native solution, that’s fine, but be prepared to demonstrate the markup examples so I have a lead to start with.

Glossary behaviour conditions

Txp sections and pages have a 1:1 relationship. Just so you know.

Condition A (Default section):

Visitor arrives to homepage, sees list of glossary categories. ✔︎
When link in list is clicked, taken to Glossary section and shown list of related articles. ✔︎
List of articles is sectioned into alphabetical sections by letter. ✔︎
Only letter sections containing actual articles/terms appear. ✔︎
When a given term link is clicked; full article is displayed. ✔︎

Condition B (Glossary section):

Visitor arrives to Glossary via main nav link for glossary; sees full list of glossary terms (article titles). ✔︎
Full list of terms is sectioned into alphabetical sections by letter. ✔︎
Only letter sections containing actual articles/terms appear. ✔︎
When a given term link is clicked; full article is displayed. ✔︎

Unlike with the original model for this idea, I do not at this time need a sub-navigation system for the lettered headings of the full glossary, so that can be ignored in architecture considerations. The glossary is for people new to traditional tools and woodworking, thus they probably don’t know what names to jump to anyway, and in any case, the homepage provides a categorical facilitation, at least. The aim for now is to encourage scrolling/perusing all the terms (there will not be thousands).

Latest pieces currently running the Glossary

Following are the current working pieces of the glossary. I’m happy with this. The only thing missing so far is the synonymous terms behaviour.

Default (home) template:

<txp:category_list parent="groups" 
                   exclude="groups" 
                   wraptag="ol" 
                   break="li" 
                   class="catslist"  
                   sort="name desc">
<a href="<txp:site_url />glossary/?c=<txp:category />"><txp:category title /></a>
</txp:category_list>

Glossary template:

<txp:if_article_list>
    <h1 class="titre">Glossary</h1>
    <h2>Subcategories</h2>
    <txp:category_list parent="groups" 
                       exclude="groups" 
                       wraptag="ul" 
                       break="li" 
                       class="catslist"  
                       sort="name desc">
        <a href="<txp:site_url />glossary/?c=<txp:category />"><txp:category title /></a>
    </txp:category_list>
    <txp:if_category>
        <h2>Entries under <txp:category title /></h2>
        <txp:hide>plus alphabetized list of articles filtered by the category</txp:hide>
    </txp:if_category>
</txp:if_article_list>

<txp:hide>
    in default section view, txp:article outputs the full glossary list.
    in individual article view, txp:article shows a single full article.
</txp:hide>
<txp:article sort="UPPER(Title)" 
             breakby="glossary_sublists" 
             breakform="glossary_sections"  
             listform="terms_alphabetical" 
             form="default"
             class="termslist" />

In that last article tag, the referenced forms are…

listform="terms_alphabetical is just a wrapping permlink tag on a title tag inside lis.
form="default" is my full article view markup

And then…

glossary_sections form:

<section>
    <h3><txp:yield item="breakby" /></h3>
    <ol class="termslist"><+></ol>
</section>

glossary_sublists form:

<txp:evaluate query='substring(<txp:title escape="quote" />, 1, 1)' escape="upper" />

Synonymous terms: XSL approach

I have not attempted anything here yet with Oleg’s synonymous terms approach. I don’t even have etc_query installed yet. But just to think through it…

Step 1 of 2

Create a structured list of all terms (“main” and “synonyms”), retrieved directly from the database:

<txp:etc_query name="terms" markup="db" data="Section='glossary'" populate="article" wraptag="ol">
	<li data-title="{!title||strtolower}">
		<txp:permlink><txp:title /></txp:permlink>
	</li>
	<txp:etc_query data="{{?synonyms}}" markup="list">
		<li data-title="{{$strtolower}}">
			{{?}} (see <txp:permlink><txp:title /></txp:permlink>)
		</li>
	</txp:etc_query>
</txp:etc_query>

And store it in <txp:variable name="terms" />.

Right away I’m wondering how to ‘store’ that snippet into a txp variable, because variables always confuse me.

But after that curiosity, I can see that the query is pulling the two kinds of terms (main and synonyms) and already making them into a functioning — but non-alphabetized — terms list. I don’t know what the markup="" and populate="" tag attributes mean/do, but my ignorance probably isn’t a show stopper to them working.

Since I don’t know how to treat this variable at the moment, I’ll move on, but it seems I will need to merge this concept into my my existing glossary page markup somewhere, and since the synonymous terms does not account for the lettered section headings, as already established in my markup, then it should be somewhere below that so it doesn’t interfere with lettered sections, or so the reasoning goes.

Step 2 of 2

Reorder the li items of this stored list by their data-title attribute:

<txp:etc_query data='<txp:variable name="terms" />'>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" encoding="utf-8" omit-xml-declaration="yes" />
<xsl:template match="ul">
	<ul>
	<xsl:for-each select="li">
		<xsl:sort select="@data-title" order="ascending" />
		<xsl:copy-of select="." />
	</xsl:for-each>
	</ul>
</xsl:template>
</xsl:stylesheet>
</txp:etc_query>

Again, I don’t know what to do with this because I’m faced with something I’ve never used before, an XSL stylesheet. Does that style need to go in a separate styles file? In the head of the page template? Directly into the main markup? Or do I need to create a new page template in XML doctype?

Also, how must it be changed to merge with the existing structure?

This might be where Oleg can shed light, but I am not in a rush.

If those much wiser than me, including the progenitor of the above solution, suggest a native approach to the problem; perhaps one that is more copacetic to the existing markup… I’m all ears. The more concise the markup and less need for forms, the better I like it.

Last edited by Destry (2020-09-24 14:28:17)

Destry · 2020-09-23 17:38:21

Destry wrote #326047:

Right away I’m wondering how to ‘store’ that snippet into a txp variable, because variables always confuse me.

For example, I’m looking at the actual doc for the variable tag, and I’m guessing the first example is the relevant one simply because I see the word ‘store’ being used there, as is used here. And I’m looking at it… and I’m like, what in that big search snippet is being stored?

The whole snippet?
Just the part between <txp:else /> and </txp:if_category> where the variable tag is actually hiding?
Is that why it’s positioned at that location when the lead paragraph to that snippet says ‘Somewhere at the very beginning of a template’?
(I don’t have a desktop calculator or know how to use memory keys.)

And there’s something twisty about that next line of instruction: ‘Later down the Page template or in a separate Form template you can read the attribute values previously set conditionals come in handy at times’. Eh? Previous set conditionals? So does that mean the whole if_search snippet was stored? And if so, why is the variable tag tucked where it is?

I’m not trying to be funny or smart here. I’m honestly trying to show my exact stumbling as I look at that example in user docs and try to make heads or tails of it. I can’t. I’m sure it makes perfect sense to the developer-minded, but… And many examples in tag docs are equally sparse in detail and clarification. Thus, in this case, I can’t use docs to help me with a real situation where it could, expectedly, be useful at helping me self-accomplish something (at least partly).

I sincerely don’t like being overly reliant on busy people that find this stuff elementary, and especially after straggling in and out here for nearly 2 decades (yipes). I really don’t. Part of it is I don’t work in web anymore, and not for a long time, and won’t again, and my own humble needs are low bar, usually, so not a lot of impetus on my part to raise the bar. Other life duties call, if you see what I mean. And I don’t envy the people who have to have the energy to maintain fix user docs for people like me. Believe me, I know what energy it takes to try and be clear in docs. But, unfortunately, I’m often reliant when it comes to Textpattern tag-fu, which is really where the main game is, isn’t it?

Just wanted to get that bit of frustration off my chest and let you know — and y’all know who you are — that I am extremely grateful for your helps now as ever I was.

But coming back to that example, and how it may or not apply to the synonyms objective this thread has most recently taken. Let’s say instead of an if_search snippet example, it’s actually giving the snippet example in Step 1 of 2 in the previous post. Where do I stick that snippet (page template? form? where the sun don’t shine?) and where does the variable tag go in relation? Little big things.

Bloke · 2020-09-23 17:53:54

Oooh, there’s a typo or something’s been hacked out of that page by mistake. Will fix.

In the meantime, the only bit that’s “stored” is the value of the <txp:variable> tag itself. In this case, the value 1 assigned to the variable called “homepage”. Once that’s set, you can then use:

<txp:if_variable name="homepage" value="1">
   do something here because it's set
<txp:else /> 
   do this if it's not set
</txp:if_variable>

When you use <txp:variable> you can either set it to the given value or you can use it as a container and set it to the entire contents of the container. So:

<txp:variable name="destry" value="hello there" />

and:

<txp:variable name="destry">hello there</txp:variable>

Are functionally identical.

etc · 2020-09-23 18:33:50

Destry wrote #326047:

Create a structured list of all terms (“main” and “synonyms”), retrieved directly from the database:

<txp:etc_query name="terms" markup="db" data="Section='glossary'" populate="article" wraptag="ol">...

And store it in <txp:variable name="terms" />.

Right away I’m wondering how to ‘store’ that snippet into a txp variable, because variables always confuse me.

Sorry, the progenitor was busy climbing boulders before it rains :-) It’s just an etc_query feature: name="varname" attribute stores its output in <txp:variable name="varname" />.

TBC

etc · 2020-09-23 20:42:56

Destry wrote #326047:

Synonymous terms: XSL approach

I can see that the query is pulling the two kinds of terms (main and synonyms) and already making them into a functioning — but non-alphabetized — terms list. I don’t know what the markup="" and populate="" tag attributes mean/do, but my ignorance probably isn’t a show stopper to them working.

These are etc_query attributes meaning ‘extract data from db’ (markup="db") and populate article fields (populate="article"). etc_query can extract data from many types of sources (db, json, html, etc) so it needs to know what it deals with.

Since I don’t know how to treat this variable at the moment, I’ll move on, but it seems I will need to merge this concept into my my existing glossary page markup somewhere

You can output it with <txp:variable name="terms" /> tags where you want (after <txp:etc_query name="terms" ... /> tag).

Step 2 of 2

Reorder the li items of this stored list by their data-title attribute:

<txp:etc_query data='<txp:variable name="terms" />'>...

Again, I don’t know what to do with this because I’m faced with something I’ve never used before, an XSL stylesheet. Does that style need to go in a separate styles file? In the head of the page template? Directly into the main markup? Or do I need to create a new page template in XML doctype?

You don’t need to do anything (except learning bases of XSLT to understand what happens), the stylesheet is already contained inside the second etc_query block. The latter will transform the unordered <ul /> list stored in <txp:variable name="terms" /> according to this stylesheet, namely reorder it by title.

Also, how must it be changed to merge with the existing structure?

This is a tougher one, if you mean dividing the list alphabetically. Leave me some time to explore etc_query meanders.

If those much wiser than me, including the progenitor of the above solution, suggest a native approach to the problem; perhaps one that is more copacetic to the existing markup… I’m all ears. The more concise the markup and less need for forms, the better I like it.

Hmm, I can’t find a better native approach (unless we consider <txp:php />), would love to see one.

jakob · 2020-09-23 21:20:45

etc wrote #326058:

This is a tougher one, if you mean dividing the list alphabetically. Leave me some time to explore etc_query meanders.

That sounds intriguing ;-)

Destry wrote #326047:

… perhaps one that is more copacetic to the existing markup… I’m all ears.

‘copacetic‘ is not a word I’ve heard before and I had to look it up. The dictionary says “North American informal” (which might explain it) but is it used often in everyday language? Anyhow, nice to learn something new :-)

Textpattern CMS support forum

#16 2020-06-07 18:57:01

Re: Glossary architecture

Destry wrote #323594:

#17 2020-06-08 10:22:49

Re: Glossary architecture

#18 2020-06-08 10:41:37

Re: Glossary architecture

#19 2020-06-08 10:48:09

Re: Glossary architecture

Destry wrote #323610:

#20 2020-06-08 11:48:28

Re: Glossary architecture

Bloke wrote #323615:

#21 2020-06-08 12:52:21

Re: Glossary architecture

Bloke wrote #323615:

#22 2020-06-08 13:05:41

Re: Glossary architecture

gaekwad wrote #323626:

#23 2020-06-08 14:01:57

Re: Glossary architecture

Destry wrote #323622:

#24 2020-06-15 06:45:35

Re: Glossary architecture

#25 2020-09-23 12:33:00

Re: Glossary architecture

Glossary behaviour conditions

Condition A (Default section):

Condition B (Glossary section):

Latest pieces currently running the Glossary

Default (home) template:

Glossary template:

Synonymous terms: XSL approach

Step 1 of 2

Step 2 of 2

#26 2020-09-23 17:38:21

Re: Glossary architecture

Destry wrote #326047:

#27 2020-09-23 17:53:54

Re: Glossary architecture

#28 2020-09-23 18:33:50

Re: Glossary architecture

Destry wrote #326047:

#29 2020-09-23 20:42:56

Re: Glossary architecture

Destry wrote #326047:

#30 2020-09-23 21:20:45

Re: Glossary architecture

etc wrote #326058:

Destry wrote #326047:

Board footer