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

This forum is for Single-Sourcing your Flare content to multiple outputs.

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

Postby mattf on Thu Jun 22, 2017 3:22 pm

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.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

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

Postby Nita Beck on Thu Jun 22, 2017 3:29 pm

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
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3286
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

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

Postby mattf on Thu Jun 22, 2017 4:03 pm

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.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

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

Postby Nita Beck on Thu Jun 22, 2017 7:19 pm

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
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3286
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

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

Postby mattf on Fri Jun 23, 2017 11:19 am

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.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

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

Postby Nita Beck on Fri Jun 23, 2017 11:41 am

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
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3286
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

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

Postby mattf on Fri Jun 23, 2017 12:06 pm

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.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

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

Postby paintedturtle on Fri Jun 23, 2017 1:47 pm

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.
paintedturtle
Propeller Head
 
Posts: 87
Joined: Wed May 25, 2016 3:35 pm

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

Postby jjw on Fri Jun 23, 2017 4:44 pm

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.
jjw
Sr. Propeller Head
 
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

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

Postby Nita Beck on Fri Jun 23, 2017 5:46 pm

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
Content Strategist / Information Architect / Flare Consultant: http://beck-communications.com
Manager, Rochester Flare User Group: http://www.facebook.com/RochesterFlareUserGroup
Nita Beck
Senior Propellus Maximus
 
Posts: 3286
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

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

Postby Psider on Sun Jun 25, 2017 11:36 pm

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 ... groups_in_<div>_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>
Psider
Propellus Maximus
 
Posts: 581
Joined: Wed Jul 06, 2011 1:32 am

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

Postby mattf on Mon Jun 26, 2017 7:29 am

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.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

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

Postby paintedturtle on Mon Jun 26, 2017 8:24 am

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.
paintedturtle
Propeller Head
 
Posts: 87
Joined: Wed May 25, 2016 3:35 pm

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

Postby kirinawust on Tue Sep 25, 2018 6:28 am

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
kirinawust
Propeller Head
 
Posts: 13
Joined: Tue Nov 05, 2013 5:08 am

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

Postby richt on Mon Jan 14, 2019 6:12 am

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.
richt
Propeller Head
 
Posts: 27
Joined: Wed Nov 28, 2018 6:38 am


Return to Single-Sourcing

Who is online

Users browsing this forum: No registered users and 2 guests