Docs updates

Bloke · Today 16:43:51

If anybody has any spare capacity, please join me in updating the docs for 4.9.0. I’m going to tackle the callbacks but I’ve been tinkering with the tags and adding the new attributes, as well as (finally) converting tags over to use the generic glocal attribute _include file to save us repeating ourselves endlessly.

I think I’ve got it to the stage where it’s fairly stable. The general idea is that if you {$ include atts-global.html %} it will add the Global Attributes block with all attributes shown. Now, of course, some global attributes don’t make sense in certain tags, and some have different defaults to the norm.

As you’ll see in the txp:image tag docs for example, sort, limit and offset don’t make sense, so I’ve added parameters to the include which will omit them:

{$ include atts-global.html sort="" limit="" offset="" %}

Not all attributes are wired up to permit them to be excluded this way (yet). As we find tags that don’t need them, we can maybe add conditionals to the _include/atts-global.html file to permit them to be excluded. I’m tempted to simply omit the global attributes entirely for conditional tags and only hard-code the few we need, because most of them don’t apply.

As well as being able to skip them, it’s also possible to pass in values to these parameters. This will set the default value for that attribute in that tag. So, for example, the txp:images tag docs use these parameters:

class="tag name or unset" offset="0" limit="0" sort="name asc"

There’s currently one special case: sort. There is a dedicated parameter called sortvals which, if set, will add the passed HTML block into the sort attribute’s description block. This allows us to explicitly list the available sort values (usually the column names), which is quite handy. Without this parameter, it will just inform people they can use ‘any database column’ as a fallback, which isn’t as helpful.

The only slight snag with this parameter is that it can be a bit wordy and also, if we want to include any other values in the block from elsewhere, it breaks Jekyll. For this reason, it’s easier to assign the block to a variable first using the capture syntax, and just pass that variable in. This is what the images tag does to asssign the contained HTML block to an svals variable:

{% capture svals %}
<br><code>alt</code>
<br><code>author</code>
<br><code>caption</code>
<br><code>category</code>
<br><code>date</code>
<br><code>ext</code> (image file extension)
<br><code>h</code> (image <code>height</code> attribute)
<br><code>id</code> (image id#)
<br><code>name</code> (image name)
<br><code>thumb_h</code> (thumbnail <code>height</code> attribute)
<br><code>thumb_w</code> (thumbnail <code>width</code> attribute)
<br><code>w</code> (image <code>width</code> attribute)
<br>
{% endcapture %}

Then it’s a simple case to pass this variable name to the sortvals parameter, without any quotes:

{% include atts-global.html sortvals=svals %}

(plus all the other parameters that I omitted for clarity).

It’s fairly straightforward. When we move the docs to a Txp-hosted solution, I can see this being an analague to a bunch of shortcodes with <txp:yield> or passed-in variable names that allow us to build or exclude parameter lists for each tag. Bonus marks if we can get it to read it from the master list of attributes in core code and build itself. But that’s future.

For now, if anyone has any time to help me trawl through the docs and update them, it would be massively appreciated. Also, if anybody would like to have a first stab at a txp:images srcset example using the automatic thumbnails, that wouild be amazing. I’m aware the syntax may change slightly (become simpler) in 4.9.1, but if we can get a worked example up now, it will only need a tweak when 4.9.1 drops in the New Year.

Many thsnks in advance for any help. If anybody would like direct commit access to the docs, please ask. Otherwise, PRs are welcome.

Textpattern CMS

Textpattern CMS support forum

#1 Today 16:43:51

Docs updates

Board footer