Page 1 of 1

Creating scrolling web pages with multiple topics

Posted: Tue May 08, 2018 8:41 am
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)?

Re: Creating scrolling web pages with multiple topics

Posted: Sun May 13, 2018 4:05 am
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.

Re: Creating scrolling web pages with multiple topics

Posted: Tue May 15, 2018 7:24 pm
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.

Re: Creating scrolling web pages with multiple topics

Posted: Thu Jun 07, 2018 11:51 am
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?

Re: Creating scrolling web pages with multiple topics

Posted: Thu Jun 07, 2018 2:56 pm
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

Re: Creating scrolling web pages with multiple topics

Posted: Tue Jun 19, 2018 8:58 am
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?

Re: Creating scrolling web pages with multiple topics

Posted: Wed Aug 29, 2018 12:41 am
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:.

:)

Re: Creating scrolling web pages with multiple topics

Posted: Tue Mar 05, 2019 2:03 pm
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.

Re: Creating scrolling web pages with multiple topics

Posted: Mon Mar 11, 2019 11:09 am
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.

Re: Creating scrolling web pages with multiple topics

Posted: Tue Aug 13, 2019 9:54 am
by CoolLime
Just wanted to try to revive this in case anyone has discovered anything about how to do this?

Re: Creating scrolling web pages with multiple topics

Posted: Tue Aug 13, 2019 11:57 pm
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.

Re: Creating scrolling web pages with multiple topics

Posted: Wed Aug 14, 2019 7:43 am
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?

Re: Creating scrolling web pages with multiple topics

Posted: Wed Aug 14, 2019 11:26 am
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.

Re: Creating scrolling web pages with multiple topics

Posted: Wed Aug 14, 2019 11:51 pm
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.

Re: Creating scrolling web pages with multiple topics

Posted: Thu Sep 05, 2019 8:29 pm
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.

Re: Creating scrolling web pages with multiple topics

Posted: Thu Sep 05, 2019 11:56 pm
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

Re: Creating scrolling web pages with multiple topics

Posted: Fri Sep 06, 2019 6:41 am
by DavidSkoglund
Thanks David. That worked.

Re: Creating scrolling web pages with multiple topics

Posted: Tue Jul 13, 2021 2:24 am
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. :(