Creating scrolling web pages with multiple topics

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Creating scrolling web pages with multiple topics

Post by CoolLime »

I am planning to construct a documentation web site based on the same content contained in topics that I use to put out PDF documents. However, one of the requirements of the web site is that often these multiple topics, which would be individual sections or sub-sections in a PDF, are displayed on the same web page such that users scroll down through them. Is this possible to construct the HTML5 output in Flare to do this? Or would it require creating brand new long topics that contain the information that were in the individual topics (this latter scenario is what I really want to avoid)?
TechOnTheBrain
Propeller Head
Posts: 17
Joined: Fri Dec 04, 2015 3:16 pm
Location: Bristol, UK
Contact:

Re: Creating scrolling web pages with multiple topics

Post by TechOnTheBrain »

With DITA you can 'chunk' topics together as a single page in the output. It sounds like you want to do a a similar thing with Flare. As far as I know, the only way to do this is to put every topic you want to 'chunk' into snippets, and then include those snippets inside topics as required.
Not as elegant as 'chunking' but it basically works. There are some disadvantages I can't remember right now but I think the main one is to do with relationship tables, so won't affect you if you're not using these.
Eric Weston
kmorrison
Sr. Propeller Head
Posts: 104
Joined: Mon Nov 11, 2013 3:04 pm
Location: Ottawa, Canada
Contact:

Re: Creating scrolling web pages with multiple topics

Post by kmorrison »

TechOnTheBrain wrote:With DITA you can 'chunk' topics together as a single page in the output. It sounds like you want to do a a similar thing with Flare. As far as I know, the only way to do this is to put every topic you want to 'chunk' into snippets, and then include those snippets inside topics as required.
Not as elegant as 'chunking' but it basically works. There are some disadvantages I can't remember right now but I think the main one is to do with relationship tables, so won't affect you if you're not using these.
We're using this solution. It's working well, and we haven't had any trouble with it.
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Post by CoolLime »

So let me see if I understand correctly... if you want one long scrolling web page in Flare with multiple topics on that page, the only way is to turn to those topics into snippets and insert them into one topic?
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Creating scrolling web pages with multiple topics

Post by jjw »

CoolLime wrote:So let me see if I understand correctly... if you want one long scrolling web page in Flare with multiple topics on that page, the only way is to turn to those topics into snippets and insert them into one topic?
I feel your pain! It might be worth making a feature request. Authorit has (or had when I was using it) an option where you can mark topics to be merged in html output and it was quite useful. The topics just merged into the nearest preceding unmerging topic. TBH it was a little less intuitive than not merging because you couldn't just glance at a TOC and see how it would render unless you marked the merging topics somehow.

Actually, in your scenario ... you don't HAVE to turn everything into snippets. You can use topics as snippets - you just have to create them manually, the easiest way is to insert a placeholder snippet and change the link. Not saying I'd recommend it because it's not formally supported by MadCap so it could break at any time, but it's possible. It would let you avoid having a whole separate structure of topics and snippets to manage.

J
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Post by CoolLime »

I am just thinking that nowadays web pages tend to scroll longer, especially those geared toward developer documentation, because people like developers are adept at using the search function built into their browsers. Topic-based authoring is what Flare is all about, but topics are short chunks of standalone information. Take an example like:

https://stripe.com/docs/

How can this sort of model be implemented with Flare?
AnneLatapie
Jr. Propeller Head
Posts: 4
Joined: Tue May 15, 2018 5:00 am

Re: Creating scrolling web pages with multiple topics

Post by AnneLatapie »

Hello :flare:,

I am having the same concern of adding mutiple chuncks to a long web page by an easy way.

jjw wrote:
You can use topics as snippets - you just have to create them manually, the easiest way is to insert a placeholder snippet and change the link.
Could someone please explain to me, a newbie, the process of "changing the link" in a snippet as suggested?

Thank you for any :idea:.

:)
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Post by CoolLime »

Is there anyone else out there who has insight into this topic? It seems silly in this day and age to not have the ability to create online documentation that scrolls across many topics, especially as far as developers go.
DavidSkoglund
Propeller Head
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Creating scrolling web pages with multiple topics

Post by DavidSkoglund »

I think I know exactly what you are after. I'm new to Flare as well and am also curious if it can be done.

I had a similar use case at a previous job where we used Arbortext (DITA). It was an extremely large developer guide that we included in the help center. I had extremely large sections of documentation that if I broke it into individual files I would have ended up with thousands of files to keep track of. In Arbortext I was able to insert topics within topics and nest them. You just had to be very careful at knowing where to insert them within the larger topic to make sure the XML was valid. An additional benefit of this was that the embedded topics would also have their own entry in the TOC as children of the parent topic. That made it easier to navigate through the topic in the output.

I'm also curious if this can be done easily, especially if there is an implementation where the nested topic/snippets/etc create TOC entries to aid in navigation.
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Post by CoolLime »

Just wanted to try to revive this in case anyone has discovered anything about how to do this?
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Creating scrolling web pages with multiple topics

Post by NorthEast »

Try manually creating a snippet link to a topic *.htm file.

Code: Select all

<MadCap:snippetBlock src="Topic.htm" />
It appears to build without errors and work properly (e.g. relative links and snippet conditions work), but you'd need to test it properly yourself.
CoolLime
Propeller Head
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Post by CoolLime »

Dave Lee wrote:Try manually creating a snippet link to a topic *.htm file.

Code: Select all

<MadCap:snippetBlock src="Topic.htm" />
It appears to build without errors and work properly (e.g. relative links and snippet conditions work), but you'd need to test it properly yourself.
Forgive me but I am a bit confused, you create a snippet linked to a topic, and then do what with it exactly?
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Creating scrolling web pages with multiple topics

Post by Nita Beck »

Dave is suggesting that you add the code for a snippetBlock by hand, as he's shown, and that instead of pointing to scr to an .flsnp file, you point it to an .htm file. His working theory is that this could work as the way to embed a TOPIC into a topic, rather than embed a SNIPPET into a topic. Flare's UI only supports the latter, but Dave's idea is that the hand-crafted code may work.

Technically, a snippet under the hood is identical to a topic. They just have a different file extension.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Creating scrolling web pages with multiple topics

Post by NorthEast »

CoolLime wrote:Forgive me but I am a bit confused, you create a snippet linked to a topic, and then do what with it exactly?
It's as Nita explained, you add the code for the snippet link in your topic, and point it to the *.htm file that you want to insert.

Just try it out. It will insert the topic inside another topic. It appears to work fine, and correctly processes links and snippet conditions.

After reading this thread properly, jjw actually suggested this same solution last year.
DavidSkoglund
Propeller Head
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Creating scrolling web pages with multiple topics

Post by DavidSkoglund »

I tried this and it built. I was expecting to see parent/child links in the TOC for the embedded topics but I didn't see that. Unless I'm missing something simple and obvious, I don't see how this is much different than just having a bunch of H2s under the main topic.

When I used DITA, what embedding topics really got you was the TOC links that jumped you to the middle of a long topic.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Creating scrolling web pages with multiple topics

Post by NorthEast »

Well, it's displaying a topic within another topic, which was the original question.

The embedded topics within the main topic aren't displayed in the TOC, because there are no links to them in the TOC (just the main topic).

If you want to automatically add links in the TOC to the embedded topics/headings inside the main topic, then:

1. Go to the TOC item for the main topic.
2. Go to the Auto-generate tab.
3. Select Compute sub-entries from linked file.
4. Select Insert Computed Entries.
5. Set the Depth to 1 (or however many heading levels you want).

It's in the help: https://help.madcapsoftware.com/flare20 ... ked%20file
DavidSkoglund
Propeller Head
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Creating scrolling web pages with multiple topics

Post by DavidSkoglund »

Thanks David. That worked.
Don Barwick
Propeller Head
Posts: 11
Joined: Wed Feb 03, 2016 5:22 am
Location: England, UK

Re: Creating scrolling web pages with multiple topics

Post by Don Barwick »

I have previously submitted a feature request to enhance the Insert Snippet user interface to let you insert a topic file as a snippet. Evidently nothing has come of it so far. :(
Post Reply