How do I create a cross-reference to a numbered step?

This forum is for all Flare related Tips and Tricks.
Have a tip or trick you use while working in Flare? Share it here.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

I've continued to think about this idea of xref-ing to a numbered step and, WOAH, I offered a solution back at MadWorld 2019 in my Listapalooza session, which I also did as a webinar! Gosh, I had completely forgotten.

Here is the CSS solution I invented:

Code: Select all

/* Example of using OLs but suppressing the list style and using Flare autonumbers instead so we can xref to list items */

ol.StepNum
{
}

ol.StepNum > li
{
	list-style-type: none;
	mc-auto-number-format: 'X:Step {n+}. ';
	mc-auto-number-position: outside-head;
	mc-auto-number-offset: 60px;
	mc-auto-number-class: StepNum;
}

ol.StepNum > li:first-child
{
	mc-auto-number-format: 'X:Step {n=1}. ';
}

span.StepNum
{
	color: red;
	font-weight: bold;
}

MadCap|xref.Step
{
	mc-format: '{paranumonly}';
}
And here's how the topic looks in the XML Editor where I have an xref to the list item. I had to put a bookmark in the list item so I could point the xref to the bookmark, rather than to the step itself.

I hope this can be an inspiration. You know, I had TOTALLY forgotten that I had solved this, and I'm going to use it in one of my own projects this coming week!

Cheers.

p.s. I have not tested the output with a screenreader, so I don't know if the screenreader would announce the step numbers. I also tested this only in HTML5 output, not PDF, but I'd think it should work for PDF, too.
You do not have the required permissions to view the files attached to this post.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

If I may cooperate with you: The link to the webinar and accompanying material is
https://www.madcapsoftware.com/webinars ... s-in-flare

I think the mentioned trick is covered in point no. 6 inside the accompanying PDF (and of course must be in the video as well, I assume).
But there are a lot more tricks presented there. Quite interesting. Thank you, Nita!
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

My only reservation about my Listapalooza ideas now three years later is that not all of my ideas might be accessibility compliant. I definitely no longer recommend using paragraphs with auto-numbers in lieu of true <ol>s, as I said earlier in this thread.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

Nita Beck wrote:p.s. I have not tested the output with a screenreader, so I don't know if the screenreader would announce the step numbers. I also tested this only in HTML5 output, not PDF, but I'd think it should work for PDF, too.
I apologize if I was bothering you, Nita. I only want to ask if, by chance, you might have an update on how accessible the solution with the autonumbering in li items is.

Mtia and regards, a.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How do I create a cross-reference to a numbered step?

Post by Nita Beck »

No need to apologize. You're not bothering me at all.

Alas, I'm not an accessibility expert, and I've not updated my original solution. All I know is what I said most recently above, that the solution involving using paragraphs with auto-numbers in lieu of true numbered list items is very likely not to be accessibility compliant, as a screenreader is unlikely to interpret the paragraphs as a list and announce it to a lower-vision user as such. I could be wrong on that, but I'm highly cautious.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

Ok, thank you for the quick reply and clarification.
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

UPDATE: See next post (viewtopic.php?f=12&t=5968&p=145639#p145639)

Nita and all,
I took another look at that whole reference step numbers and accessibility thing.
As far as I saw, at least any li tags with MadCap Autonumbering directly attached to them are converted to tables in the output in my Flare 2022r2 installation, resulting in ols and uls with tables instead of li tags.
(UPDATE: After further investigation, whether or not a table is created for the autonumbering and the following content seems to depend on the mc-auto-number-position. Still, the following solution works with mc-auto-number-position: outside-head; . Probably it could be adapted to inside-head but it would not make much difference, afai see right now.)
So, since I anyway want paragraphs in the li tags, I build on your styles, Nita, and adapted them in the following way to make them hopefully nicely usable for MC cross references and at the same time hopefully accessible as normal html lists:

Preview from Flare's XML Editor:
In the XML Editor.png
Preview from the Output:
In the Output.png
CSS Code:

Code: Select all

ol.StepNum
{
}

ol.StepNum > li > p:first-child
{
	mc-auto-number-format: 'X:Step {n+}. ';
	mc-auto-number-position: outside-head;
	mc-auto-number-offset: 0px;
	mc-auto-number-class: StepNum;
}

ol.StepNum > li > table
{
	margin-left: -150vw !important;
	margin-top: 1.5rem;
	float: left;
}

ol.StepNum > li > table > tbody > tr > td:nth-child(2)
{
	display: none;
}

ol.StepNum > li:first-child > p:first-child
{
	mc-auto-number-format: 'X:Step {n=1}. ';
}

span.StepNum
{
	color: red;
	font-weight: bold;
}

MadCap|xref.Step
{
	mc-format: '{paranumonly}';
}
The html code in Flare's Text Editor should look something like this:

Code: Select all

        <ol class="StepNum">
            <li>
                <p MadCap:autonum="Step 1. "> </p>
                <p>Get a cat.</p>
            </li>
            <li>
                <p MadCap:autonum="Step 2. "><a name="win_lottery"> </a>
                </p>
                <p>Win the lottery.</p>
            </li>
            <li>
                <p MadCap:autonum="Step 3. "> </p>
                <p>Get a dog.</p>
            </li>
            <li>
                <p MadCap:autonum="Step 4. "> </p>
                <p>Repeat, especially <MadCap:xref href="#win_lottery" class="Step">Step 2</MadCap:xref>.</p>
            </li>
        </ol>
The trick is that the first p item in each li should only contain the MadCap:autonum attributes and a potential bookmark, if the list item should be referenced / linked to.
"Normal" list numbering and MC autonumbering are incremented separately but parallel to each other. In the Flare XML Editor the first p tag can be used to check if both numbers are incremented in the same way.
The actual content of each list item starts with its 2nd p tag!
When adding new p tags, the XML Editor needs some F5-refresh-love quite often to update the visual representation of the MC autonumbering. Don't let yourself get confused at first. It does work fine.
In the output, each first p tag is transferred into a table but the li tags stay li tags. The styles move these tables out of the screen but leave any bookmarks intact since they are needed for linking to that spot.
Hope, it makes some sense. Maybe I overlooked something. Anyone who finds errors or has ideas for improvement, please contribute. Thank you!

Regards, a.
You do not have the required permissions to view the files attached to this post.
Last edited by autocart on Thu Dec 08, 2022 5:15 am, edited 4 times in total.
autocart
Propeller Head
Posts: 36
Joined: Mon Oct 16, 2017 9:14 am

Re: How do I create a cross-reference to a numbered step?

Post by autocart »

UPDATE:
It can be done even easier and cleaner:
  1. In ol.StepNum > li > p:first-child change mc-auto-number-position: outside-head; to mc-auto-number-position: inside-head;.
  2. And add display: none; to span.StepNum.
  3. Drop the selectors ol.StepNum > li > table and ol.StepNum > li > table > tbody > tr > td:nth-child(2).
  4. The property mc-auto-number-offset in the selector ol.StepNum > li > p:first-child can also be dropped.
The advantages are:
  1. No more extra first paragraph needed. (As a matter of fact, with just a bit of simple css adjustment, it will also work on li items without p tags.)
  2. The css and html code in the output is much cleaner, e.g. no complex selectors with tables that move them out of the viewport anymore.
So, the output looks the same as before, duh (see previous post).

In Flare's XML Editor it looks something like this:
In Flare's XML Editor-better.png
Here is the new CSS:

Code: Select all

ol.StepNum
{
}

ol.StepNum > li > p:first-child
{
	mc-auto-number-format: 'X:Step {n+}. ';
	mc-auto-number-position: inside-head;
	mc-auto-number-class: StepNum;
}

/* Not sure if this one selector is needed but it seems it does not hurt. */
ol.StepNum > li:first-child > p:first-child
{
	mc-auto-number-format: 'X:Step {n=1}. ';
}

span.StepNum
{
	color: red;
	font-weight: bold;
	display: none;
}

MadCap|xref.Step
{
	mc-format: '{paranumonly}';
}
Here is how the HTML code might look like in Flare's Text Editor:

Code: Select all

<ol class="StepNum">
  <li>
    <p MadCap:autonum="Step 1. ">Get a cat.</p>
  </li>
  <li>
    <p MadCap:autonum="Step 2. "><a name="win_lottery"></a>Win the lottery.</p>
  </li>
  <li>
    <p MadCap:autonum="Step 3. ">Get a dog.</p>
  </li>
  <li>
    <p MadCap:autonum="Step 4. ">Repeat, especially <MadCap:xref href="#win_lottery" class="Step">Step 2</MadCap:xref>.</p>
  </li>
</ol>
Best regards, a.
You do not have the required permissions to view the files attached to this post.
Post Reply