Creating scrolling web pages with multiple topics
Creating scrolling web pages with multiple topics
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)?
-
- Propeller Head
- Posts: 17
- Joined: Fri Dec 04, 2015 3:16 pm
- Location: Bristol, UK
- Contact:
Re: Creating scrolling web pages with multiple topics
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.
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
-
- 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
We're using this solution. It's working well, and we haven't had any trouble with it.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.
Re: Creating scrolling web pages with multiple topics
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
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.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?
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
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?
https://stripe.com/docs/
How can this sort of model be implemented with Flare?
-
- Jr. Propeller Head
- Posts: 4
- Joined: Tue May 15, 2018 5:00 am
Re: Creating scrolling web pages with multiple topics
Hello ,
I am having the same concern of adding mutiple chuncks to a long web page by an easy way.
jjw wrote:
Thank you for any .
I am having the same concern of adding mutiple chuncks to a long web page by an easy way.
jjw wrote:
Could someone please explain to me, a newbie, the process of "changing the link" in a snippet as suggested?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.
Thank you for any .
Re: Creating scrolling web pages with multiple topics
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.
-
- Propeller Head
- Posts: 12
- Joined: Wed Feb 13, 2019 10:05 am
Re: Creating scrolling web pages with multiple topics
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.
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
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
Try manually creating a snippet link to a topic *.htm file.
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.
Code: Select all
<MadCap:snippetBlock src="Topic.htm" />
Re: Creating scrolling web pages with multiple topics
Forgive me but I am a bit confused, you create a snippet linked to a topic, and then do what with it exactly?Dave Lee wrote:Try manually creating a snippet link to a topic *.htm file.
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.Code: Select all
<MadCap:snippetBlock src="Topic.htm" />
-
- Senior Propellus Maximus
- Posts: 3672
- Joined: Thu Feb 02, 2006 9:57 am
- Location: Pittsford, NY
Re: Creating scrolling web pages with multiple topics
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.
Technically, a snippet under the hood is identical to a topic. They just have a different file extension.
Nita
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Re: Creating scrolling web pages with multiple topics
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.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?
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.
-
- Propeller Head
- Posts: 12
- Joined: Wed Feb 13, 2019 10:05 am
Re: Creating scrolling web pages with multiple topics
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.
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
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
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
-
- Propeller Head
- Posts: 12
- Joined: Wed Feb 13, 2019 10:05 am
Re: Creating scrolling web pages with multiple topics
Thanks David. That worked.
-
- Propeller Head
- Posts: 11
- Joined: Wed Feb 03, 2016 5:22 am
- Location: England, UK
Re: Creating scrolling web pages with multiple topics
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.