Snippets as table rows? Well, I never...

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Snippets as table rows? Well, I never...

Post by mattf »

Does anyone have experience creating snippets that can be pulled into tables as individual rows? Our API has lots of params and response fields that get used over and over again, and I'd like to single-source the tabular data. In this way I hope to avoid saying "This is a required field" in one table and "Required." in another when both tables are referencing the same item. But it seems inherently problematic. The content cannot be put into a variable because, being text only, variables cannot be divided into columns for name, datatype, description, etc. So that leaves us with snippets, but I've had trouble using snippets in tables before, and vice versa. This would be a stack o' snippets making up a table. Has anyone taken this quest and emerged victorious? If so, what did you do?
Thanks,
-Matt
Matt F
You learn something new every day if you're not careful.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Snippets as table rows? Well, I never...

Post by Nita Beck »

I could be very wrong but I know that others have tried it and I think the consensus is that it doesn't work, although I don't know why. I think issues crept in with widths of columns, for example. Also, I'm not sure how one could structure the code of the table and the code of the snippets, which would have just the <tr> code, right?

Maybe others have more insight.

I long ago stopped using tables for parameter descriptions. I either use unordered lists or definition lists (the latter of which I have to code by hand, but I created a placeholder snippet that I could drop in place, convert to text, and edit away). For API documentation, I definitely use definition lists (no pun intended).
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Snippets as table rows? Well, I never...

Post by mattf »

Nita, well, now I'm just as curious as a kitten. I don't know definition lists, at least not by that name. Don't suppose you could send me a screenshot of what these definition lists look like?

I'm not surprised you haven't heard of great success with this. Snippets and tables seem to be an inherently dangerous mix, like shaving and breakdancing.

Thanks for the reply.
-Matt
Matt F
You learn something new every day if you're not careful.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Snippets as table rows? Well, I never...

Post by Nita Beck »

You can learn about definition lists here: https://www.w3schools.com/html/html_lists.asp. (Hmm, I've always known these as definition list, but I see they're called description lists.)

Flare's stylesheet editor (I think) lets one create a definition list style. But there's so way (I think this is still true) to add a definition list in the XML Editor. So you have to code it by hand.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Snippets as table rows? Well, I never...

Post by mattf »

Nita, I checked out your link. Thanks! The description lists look pretty much as I thought they would. It turns out I have created such things just using p. tag subclasses and applying CSS. But the description list tags should come in very handy. It's still not crystal clear to me how you'd single source them, though. Anyway, I'll give them a spin. Thank you!
-mdf
Matt F
You learn something new every day if you're not careful.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Snippets as table rows? Well, I never...

Post by Nita Beck »

mattf wrote:It's still not crystal clear to me how you'd single source them, though. Anyway, I'll give them a spin. Thank you!
-mdf
I end up having a large set of parameter snippets, each of which contains a single definition list consisting of the parameter name (in the <dt> tag) and its definition (in the <dd> tag). I can drop in a given parameter's snippet wherever that parameter needs to be covered.

It's really no different than your wanting to use table row snippets.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Snippets as table rows? Well, I never...

Post by mattf »

Ah, yes. I get it! Thanks Nita. You're always so helpful.
Cheers.
Matt F
You learn something new every day if you're not careful.
paintedturtle
Propeller Head
Posts: 88
Joined: Wed May 25, 2016 3:35 pm

Re: Snippets as table rows? Well, I never...

Post by paintedturtle »

Nita Beck wrote:I could be very wrong but I know that others have tried it and I think the consensus is that it doesn't work, although I don't know why. I think issues crept in with widths of columns, for example. Also, I'm not sure how one could structure the code of the table and the code of the snippets, which would have just the <tr> code, right?
Can you/anyone remember why snippets as table rows are problematic?

I have just begun experimenting with using a snippet that's made up of one entire table row and steps 1-2. For this set of docs, it's been working so far for me (though I could be entirely wrong!). This type of document always has the same table style set for the table so the width will be the same. It appears that they're all ending up at the end of a page so haven't checked if that ends up with step 3 starting in a new table, not just row. Anyway, there's my 2 cents.
Technical Writer using and experimenting with Flare version 12.0.5991.
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Snippets as table rows? Well, I never...

Post by jjw »

Can you/anyone remember why snippets as table rows are problematic?
I can imagine that it would be a problem having invalid html in the source topic - like a table that contains an element (the snippet element) that doesn't belong in a table.

I did play around with having single row table snippets and building blocks of tables out of them and then using a script or a word macro to search for contiguous tables in the output and merging them - but it seemed more trouble than it was worth.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Snippets as table rows? Well, I never...

Post by Nita Beck »

jjw wrote:I can imagine that it would be a problem having invalid html in the source topic - like a table that contains an element (the snippet element) that doesn't belong in a table.
Yes, exactly, that is one of the problems.

A problem I recall people reporting is that even if they got the snippet to resolve correctly in the table in generated output, for a reason they could not figure out, the widths of the columns of the snippet-sourced rows didn't have the same width as the columns of the "live rows" in the table.

I agree, it was more trouble than it's worth.

And that's one reason I stopped using tables for things like field/parameter descriptions.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Snippets as table rows? Well, I never...

Post by Psider »

I was curious and discovered you can format definition lists to look like tables if you wrap the dt and dd in a div tag. I don't know how this would work in Flare, but figured I'd post the code in case it was useful.

https://developer.mozilla.org/en-US/doc ... >_elements

CSS:

Code: Select all

dl {
	display: table;
	border: 1px solid black;
	border-collapse: collapse;
	vertical-align: top;
	}
dl > div {display: table-row;}
dt, dd {
	display: table-cell;
	border: 1px solid black;
	padding: 0.2em;
	}
Definition List sample:

Code: Select all

<dl>
	<div>
		<dt>Mouse</dt>
		<dd>Small mammal that eats cheese.</dd>
	</div>
	<div>
		<dt>Giraffe</dt>
		<dd>Large mammal with a really long neck to help it reach the tender leaves at the top of the tree</dd>
	</div>
	<div>
		<dt>Drop bear</dt>
		<dd>
		<p>Australian marsupial that looks like a koala, but is really much scarier.</p>
		<p>Drop bears sit in trees over a path, waiting for unsuspecting prey. When the prey walks under the tree, they drop on to their victims.<p>
		<p>Drop bears are known to favour foreign tourists. Australians are naturally repellent to drop bears due to eating copious amounts of the local delicacy "Vegemite toast".</p>
		</dd>
	</div>
</dl>
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Snippets as table rows? Well, I never...

Post by mattf »

Thanks Psider, you get the "Extra Mile" award today. If I get a chance to try this in Flare soon I'll report back.
Matt F
You learn something new every day if you're not careful.
paintedturtle
Propeller Head
Posts: 88
Joined: Wed May 25, 2016 3:35 pm

Re: Snippets as table rows? Well, I never...

Post by paintedturtle »

Nita Beck wrote:
jjw wrote:A problem I recall people reporting is that even if they got the snippet to resolve correctly in the table in generated output, for a reason they could not figure out, the widths of the columns of the snippet-sourced rows didn't have the same width as the columns of the "live rows" in the table.
Hmm, now I'm genuinely confused why my snippet first row of a table appears to be working. The bottom row is a snippet and the columns align with my top row fine. The snippet row works for now across multiple topics, so I'll keep it, but also keep an eye on it.

Thanks for the info, ya'll.
You do not have the required permissions to view the files attached to this post.
Technical Writer using and experimenting with Flare version 12.0.5991.
kirinawust
Propeller Head
Posts: 19
Joined: Tue Nov 05, 2013 5:08 am

Re: Snippets as table rows? Well, I never...

Post by kirinawust »

Hi paintedturtle,
how did you achieve this?
My 1-row-snippets, when in html inserted between the normal table rows, is displayed overlapping the other rows, even showing the error messages "Table Row Outside Table:" once per table cell.

I am going for 1 snippet per parameter value, packed in a <p>, but I'd love to know how snippets could work as table rows.

Ina
richt
Propeller Head
Posts: 42
Joined: Wed Nov 28, 2018 6:38 am

Re: Snippets as table rows? Well, I never...

Post by richt »

I just tried using snippets and variables to build some tables in Flare 14, but no dice.

To start, I built a basic snippet containing an 8x4 table. The table header names are static, and I defined the content of each row using 8 distinct variables. The trouble is, if you build this table as a single snippet, you can't have more than one row of variables since you can't declare the definition of a variable more than once.

Then I chopped the table up into two snippets: one for the header, one for the row, with the idea of repeating the row snippet three times. That sort of worked, but then the table comes out of sync; the columns no longer line up based on the content, and because I'm building this for online help I can't just force the css to use a set width (unless I do something janky like 12.5% screen width per column). This way, I'm defining 8 variables per snippet plus custom css, three times per topic, just to display 24 relatively static values. In terms of effort to reward, it's a waste of time.

So ultimately, all I can do is build the table frame as a snippet, drag it into each topic, then convert it to text and update its contents. Not exactly elegant, but that seems to be Flare's limit unless someone's got a better idea.
Gregjohnsondsm
Jr. Propeller Head
Posts: 2
Joined: Thu Dec 05, 2019 1:53 pm

Re: Snippets as table rows? Well, I never...

Post by Gregjohnsondsm »

While we have done this, use snippets to form table rows (although not officially a table row, which is why I am here) it is not for the faint of heart.
Steps:
1. Create EXCEL file with the data/parameters we want.
2. Create XML code to embed in the EXCEL table to be used by the VBA macro to generate the snippets.
3. Run the macros and then copy the snippets to the correct directories in FLARE.
4. Generate another TABLE snippet that has links to the above snippets in XML. Again generated by VBA macros in EXCEL.
5. Once setup it makes a reasonable table.

BUT, I can find no way to make the header appear on the top of all pages. Basically it is not a TABLE but a listing of snippets.

Examples Below:

Code like this inside of EXCEL Cell. ( this method and code was modified from The Techwriting Engineer by Mattias Sander)

<tbody>
<tr MadCap:conditions="&CHAR(34)&"Manuals.Appendix Table"&CHAR(34)&">
<td class="&CHAR(34)&"Parameters"&CHAR(34)&">"&B2&"</td>

<td class="&CHAR(34)&"Parameters"&CHAR(34)&"><![CDATA["&D2&"]]></td>
<td class="&CHAR(34)&"Parameters"&CHAR(34)&">"&E2&"</td>
<td class="&CHAR(34)&"Parameters"&CHAR(34)&">"&F2&"</td>
<td class="&CHAR(34)&"Parameters"&CHAR(34)&">"&G2&"</td>
</tr>
</tbody>

Read his/her BLOG for details.
VBA code then generates snippets that look like: Notice the use of [CDATA[... this eliminates one of the issues Nita had with invalid code.

<tbody>
<tr MadCap:conditions="Manuals.Appendix Table">
<td class="Parameters">Adaptive_Derivative_Deadband</td>
<td class="Parameters">REAL</td>
<td class="Parameters"><![CDATA[Surge Adapter - Deadband to eliminate process noise in derivative calculation ]]></td>
<td class="Parameters">PV units</td>
<td class="Parameters">20</td>
<td class="Parameters"></td>
</tr>
</tbody>


Then the TABLE. fsnp code looks like this: With each snippet being called out on a line.

<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="2" MadCap:lastHeight="43" MadCap:lastWidth="878">
<head>
</head>
<body>
<table style="margin-left: 0">
<col style="width: 1.75in;" />
<col style="width: .5in;" />
<col style="width: 3.5in;"/>
<col style="width: 0.75in;" />
<col style="width: 2.0in;" />
<col style="width: .5in;" />
<tbody>
<tr>
<td class="Parameters" style="border-top-style: solid;">Name</td>
<td class="Parameters" style="border-top-style: solid;">Data Type</td>
<td class="Parameters" style="border-top-style: solid;">Description</td>
<td class="Parameters" style="border-top-style: solid;">Units</td>
<td class="Parameters" style="border-top-style: solid;">Typical Values</td>
<td class="Parameters" style="border-top-style: solid;">Version</td>
</tr>
</tbody>
</table>
<MadCap:snippetBlock src="../../PACView Parameters/Config_AS/Adaptive_Derivative_Deadband.flsnp" />
<MadCap:snippetBlock src="../../PACView Parameters/Config_AS/Adaptive_Derivative_Gain.flsnp" />
<MadCap:snippetBlock src="../../PACView Parameters/Config_AS/Adaptive_Derivative_Max.flsnp" />
<MadCap:snippetBlock src="../../PACView Parameters/Config_AS/Adaptive_Gain.flsnp" />


Then you simply insert the TABLE.fsnp code into a flare sheet like this: There are three tables because of some limit to the number of snippets allowed. (60 maybe?)

<?xml version="1.0" encoding="utf-8"?>
<html xml:lang="en-us" MadCap:conditionTagExpression="include["Manuals.Appendix Table"]" xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head><title></title>
<link href="../Resources/Stylesheets/ECTDoc_Styles.css" rel="stylesheet" />
</head>
<body>
<h1 class="Appendix_H1"><a name="_Toc323731709"></a>SpeedPAC Configuration Parameters</h1>
<MadCap:snippetBlock src="../PACView Parameters/Config_ST/Table1.flsnp" />
<MadCap:snippetBlock src="../PACView Parameters/Config_ST/Table2.flsnp" />
<MadCap:snippetBlock src="../PACView Parameters/Config_ST/Table3.flsnp" />
</body>
</html>
Post Reply