Handling changes in Content folder structure wrt compiling

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Handling changes in Content folder structure wrt compiling

Post by mattf »

I broke all the external links to our webhelp because I changed the Content directory's flat structure and put all the topics into folders by topic type (Concepts/Tasks/Reference) and then by UI component. For some reason I had thought Flare was ignoring the Content folder structure in compiling, but now I realize that a) I don't know where I got that idea and b) it's patently untrue. One look at any of the topic URLs in the published webhelp indicates that the output follows the Content directory's structure. I hadn't noticed because the path always said like "http://compassuserguide/#cncpt_cruise_c ... _rates.htm" so the Content directory is not mentioned. But the path starts at the Content level nonetheless.

So does this mean we are doomed to keep adding to a flat organization and scrolling forever to find our project files? This doesn't seem right. Does Flare have a way to get around this? I searched existing topics and I saw a discussion of ID numbers. That sounds promising, but it doesn't change the fact that nesting the topics in folders changes the path and the path is used in the output.

Anybody have any ideas? I can't believe everyone else maintains projects for years without experiencing a need to change the Content directory structure.

Thanks in advance.

-Matt
Matt F
You learn something new every day if you're not careful.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Handling changes in Content folder structure wrt compili

Post by Psider »

Flare totally works with sub-folders. (I assume this is what you mean, rather than specifically the Content folder - there is a setting which controls whether that folder is generated in the output or not).

But I'm not sure what you mean by "external links"? Do you mean, for example, someone saved a topic to bookmarks, and now that bookmark doesn't work? Or do you mean you have a merged help setup and links between the child projects no longer work? Or something else?
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Handling changes in Content folder structure wrt compili

Post by mattf »

Hi Psider,
What I've done is changed my structure from having most of the topics (files) at root of the Content folder to having the files all in subfolders. Our company has a separate knowledge base (part of ServiceNow) that contains stub articles for every article in our webhelp, so the webhelp can be searched from ServiceNow. We publish the webhelp to an internal server. Each link from that KB contains a path to the article on our internal webhelp server (and by contrast, all of the ServiceNow KB articles themselves are stored in the cloud with ServiceNow).

The change was, I moved all the files into new subfolders (using the Flare interface, so that links would update), but what I didn't realize was that when I published with this new structure, the new folders were now listed in the path. So those 'external links' from ServiceNow all broke. I had to pull those files all out into a flat organization again.

Thanks for your response.
-Matt
Matt F
You learn something new every day if you're not careful.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Handling changes in Content folder structure wrt compili

Post by Psider »

A yep, I think I see. You were expecting the added folders to only be added in your source project and not be included in your output, right?

If all your files were in the project root in the source, then there's essentially no folder structure in play when you generate. Resulting in yourwebserver.com/filename.htm when you publish. So I would link from my website to yourwebserver.com/filename.htm and the link would work. Then you change your source project to include sub-folders, and my link no longer works because the structure when you generate maintains those folders.

I don't think there is any way to force Flare to re-organise your content into a flat structure when you generate, while maintaining a structure in the editing environment, although it's been a while since I've used it. The place to look would be your Target settings, if it exists.

You can update all your links in ServiceNow to point to the correct path. Probably a big job. Using Context Sensitive Help (I assume this is the IDs you were talking about) should mean you wouldn't have to update the links if you change the paths again in future. (Basically the link opens a particular file which runs a script. This checks the id included in the url against a compiled list, and opens the associated topic path.)

I think most places accept that external links may break if the files or folders are renamed, or have rules that all content is in the root, or that files and folders are never moved or renamed. There may be a search function to help you filter in the content view, but again, it's been a while - have a look at the available buttons and perhaps try Ctrl+F after clicking in the pane.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Handling changes in Content folder structure wrt compili

Post by Psider »

Another thought might be to keep everything in the root, and find your topics using the table on contents file rather than the Content pane? I had a colleague who worked like that.

You could potentially have a second table of contents file that you only use for your own navigation purposes and never use in a target.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Handling changes in Content folder structure wrt compili

Post by NorthEast »

mattf wrote:So does this mean we are doomed to keep adding to a flat organization and scrolling forever to find our project files? This doesn't seem right. Does Flare have a way to get around this? I searched existing topics and I saw a discussion of ID numbers. That sounds promising, but it doesn't change the fact that nesting the topics in folders changes the path and the path is used in the output.
If the links to your help point to the specific topic filename/path, then obviously if you change that filename/path the link will break.

The "discussion of ID numbers" that you saw would be talking about using context sensitive help (CSH) identifiers.
To use CSH, you'd first add an "alias" file to your project. In your alias file you'd add an "identifier", which is a text reference that you're going to use when you have a link to the help (e.g. "cabin_rates"). After adding the identifier, you link the identifier to the topic in your help ("cabin_rates" = "Content/Folder/cncpt_cruise_cabin_category_rates.htm").

For example, in Flare's help, this is a CSH link to a topic using the CSH identifer "Alias_Editor". Note that the link includes the identifier (cshid=Alias_Editor) rather than the topic filename you'll end up at.
http://help.madcapsoftware.com/flare2017r3/Default.htm#cshid=Alias_Editor

So in this example, the identifier "Alias_Editor" is linked to the topic http://help.madcapsoftware.com/flare2017r3/Content/Flare/CSH/Creating-Assigning-Identifiers.htm

The advantage of this is that the link to your help will always remain the same, but you can edit the alias file to change the topic name or location without breaking that link.
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Handling changes in Content folder structure wrt compili

Post by mattf »

Thanks both of you for the help understanding this and for the good ideas. I am not yet using full-on CSH, so the identifiers are theoretical for us at this point. But it sounds like what Dave describes -- using the alias file -- might be exactly what we need until we implement CSH the way we want to. It looks like a sort of redirect that I can manage myself. I'll explore that. Also, using a separate TOC for working on the project is a great idea.
Thanks!
Matt F
You learn something new every day if you're not careful.
mattf
Sr. Propeller Head
Posts: 277
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: Handling changes in Content folder structure wrt compili

Post by mattf »

It looks like this is a viable solution, but I have two further questions.

1) I've set up a header and alias file and tested the links, and they work. If I now change a file in my Content directory (change its name or move it into a subfolder) will Flare update the Alias file automatically as part of the "Do you want to update links" function, as it does with cross references and hyperlinks, or do I have to go in and update the file path myself?

2) How can I get rid of the prefix NEW in my CSH identifiers? I entered my own prefix ("TC") and now the identifiers are all named "TCNEW28", "TCNEW29", etc. I had hoped my prefix would overwrite the default one but it doesn't. I see in Flare's help that it seems to be this way by design. [EDIT: I mean, I know I can hand-edit each entry on the alias file, but I'd rather not.]

Thanks again,
-Matt F.
Matt F
You learn something new every day if you're not careful.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Handling changes in Content folder structure wrt compili

Post by NorthEast »

1) Yes. Try it.

2) If you generate aliases, I think it adds "NEW" if you don't select Include topic name... - no idea why it does that. I enter the alias name manually rather than do it this way.
Post Reply