Creating scrolling web pages with multiple topics

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

Creating scrolling web pages with multiple topics

Postby CoolLime on Tue May 08, 2018 8:41 am

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)?
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby TechOnTheBrain on Sun May 13, 2018 4:05 am

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
TechOnTheBrain
Propeller Head
 
Posts: 15
Joined: Fri Dec 04, 2015 3:16 pm
Location: Bristol, UK

Re: Creating scrolling web pages with multiple topics

Postby kmorrison on Tue May 15, 2018 7:24 pm

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.
kmorrison
Propeller Head
 
Posts: 85
Joined: Mon Nov 11, 2013 3:04 pm
Location: Ottawa, Canada

Re: Creating scrolling web pages with multiple topics

Postby CoolLime on Thu Jun 07, 2018 11:51 am

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?
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby jjw on Thu Jun 07, 2018 2:56 pm

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

Re: Creating scrolling web pages with multiple topics

Postby CoolLime on Tue Jun 19, 2018 8:58 am

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?
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby AnneLatapie on Wed Aug 29, 2018 12:41 am

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:.

:)
AnneLatapie
Jr. Propeller Head
 
Posts: 4
Joined: Tue May 15, 2018 5:00 am

Re: Creating scrolling web pages with multiple topics

Postby CoolLime on Tue Mar 05, 2019 2:03 pm

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.
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby DavidSkoglund on Mon Mar 11, 2019 11:09 am

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.
DavidSkoglund
Propeller Head
 
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Creating scrolling web pages with multiple topics

Postby CoolLime on Tue Aug 13, 2019 9:54 am

Just wanted to try to revive this in case anyone has discovered anything about how to do this?
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby Dave Lee on Tue Aug 13, 2019 11:57 pm

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.
Dave Lee
Master Propellus Maximus
 
Posts: 5609
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: Creating scrolling web pages with multiple topics

Postby CoolLime on Wed Aug 14, 2019 7:43 am

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?
CoolLime
Propeller Head
 
Posts: 41
Joined: Mon Apr 18, 2016 6:50 am
Location: Toronto, Canada

Re: Creating scrolling web pages with multiple topics

Postby Nita Beck on Wed Aug 14, 2019 11:26 am

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
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: 3271
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Creating scrolling web pages with multiple topics

Postby Dave Lee on Wed Aug 14, 2019 11:51 pm

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.
Dave Lee
Master Propellus Maximus
 
Posts: 5609
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: Creating scrolling web pages with multiple topics

Postby DavidSkoglund on Thu Sep 05, 2019 8:29 pm

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.
DavidSkoglund
Propeller Head
 
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Creating scrolling web pages with multiple topics

Postby Dave Lee on Thu Sep 05, 2019 11:56 pm

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
Dave Lee
Master Propellus Maximus
 
Posts: 5609
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: Creating scrolling web pages with multiple topics

Postby DavidSkoglund on Fri Sep 06, 2019 6:41 am

Thanks David. That worked.
DavidSkoglund
Propeller Head
 
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am


Return to Single-Sourcing

Who is online

Users browsing this forum: No registered users and 2 guests