One way to combine generated content with Flare-managed content is to use snippets. Here is a generic structure:
Generated topics each contain:
Generated snippet – periodically refreshed
Generated snippet – updated with Flare editors
Consider a simple case where the generated content comes from a CSV file. For this example, the CSV is analogous to a table with two columns. The first column is a name of some reference subject and the second column is the description.
Flowers,Flowers are structures which are part of some plants…
Unicorns,Unicorns are figments which occur in some imaginations…
Sunbeams,Sunbeams bathe the earth in radiation when another object does not block the sun…
Rainbows,Rainbows lead to the other side…
The term CSV is thrown around loosely. For this example, the CSV has only two entries per line. The entries are delimited by one comma. To provide a simple example, the content itself does not have commas. Here is one way to read a CSV with Visual Basic:
How to: Read From Comma-Delimited Text Files in Visual Basic from MSDN
This example dispenses with the exception handling for reading clarity. But bad files should be expected and handled. There is a decent discussion at the bottom of the article about other considerations.
To create the TOC, topics, and snippets, Linq to XML is used. This has been discussed in previous blog entries. The procedures in the sample are fairly targeted. Generalized, overloaded procedures would be better. But reading clarity, the scopes of the procedures are narrow.
This example also assumes a specific project structure and existing folders. A working utility should check for folders and add folders if necessary. The flexibility to specify sub folders is also a plus. And of course we don’t want to limit ourselves to CSV. But rather than cloud the example, here is the code without all of that:
Module Module1
Public Sub CreateSnippet(ByVal fileName As String, ByVal description As String)
Dim Snippet As XDocument = _
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
</head>
<body>
<p><%= description %></p>
</body>
</html>
Snippet.Save("C:\Example\Content\Resources\Snippets\" & fileName)
End Sub
Public Sub CreateTopic(ByVal fileName As String, ByVal topicName As String)
Dim Topic As XDocument = _
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head><title><%= topicName %></title>
</head>
<body>
<h1><%= topicName %></h1>
<MadCap:snippetBlock src=<%= "Resources/Snippets/" & topicName & "-Refreshable.flsnp" %>/>
<MadCap:snippetBlock src=<%= "Resources/Snippets/" & topicName & "-EditInFlare.flsnp" %>/>
</body>
</html>
Topic.Save("C:\Example\Content\" & fileName)
End Sub
Sub Main()
Dim FlareToc As XDocument = _
<?xml version="1.0" encoding="utf-8"?>
<CatapultToc></CatapultToc>
Using MyReader As New FileIO.TextFieldParser("C:\Example\wonderful-things.csv")
MyReader.TextFieldType = FileIO.FieldType.Delimited
MyReader.SetDelimiters(",")
Dim currentRow As String()
While Not MyReader.EndOfData
currentRow = MyReader.ReadFields()
CreateTopic(currentRow.First & ".htm", currentRow.First)
CreateSnippet(currentRow.First & "-Refreshable.flsnp", currentRow.Last)
CreateSnippet(currentRow.First & "-EditInFlare.flsnp", "Default text")
FlareToc.Add()
FlareToc.Root.Add(<TocEntry Link=<%= "/Content/" & currentRow.First & ".htm" %> Title=<%= currentRow.First %>></TocEntry>)
End While
End Using
FlareToc.Save("C:\Example\Project\TOCs\wonderful-things.fltoc")
End Sub
End Module
Here are the generated files in the folders:
Here is the TOC:
<?xml version="1.0" encoding="utf-8"?> <CatapultToc> <TocEntry Link="/Content/Flowers.htm" Title="Flowers"></TocEntry> <TocEntry Link="/Content/Unicorns.htm" Title="Unicorns"></TocEntry> <TocEntry Link="/Content/Sunbeams.htm" Title="Sunbeams"></TocEntry> <TocEntry Link="/Content/Rainbows.htm" Title="Rainbows"></TocEntry> </CatapultToc>
Here is a snippet:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head></head>
<body>
<p>Flowers are structures which are part of some plants...</p>
</body>
</html>
And here is a topic:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
<title>Flowers</title>
</head>
<body>
<h1>Flowers</h1>
<MadCap:snippetBlock src="Resources/Snippets/Flowers-Refreshable.flsnp" />
<MadCap:snippetBlock src="Resources/Snippets/Flowers-EditInFlare.flsnp" />
</body>
</html>