1

Getting Started with Topic-Based Authoring and Content Reuse in MadCap Flare

As writers, we need to be aware of the many tools that are available to help us deliver our content to our audiences. To serve the varied needs of people today, we need to, as Robinson says, “think outside the books.” You can use Flare to author content once and use it in many ways, including web sites, booklets, manuals, posters, e-books, and more.

In this training guide, you’ll start from an existing project, make changes to learn some basic techniques in Flare, and explore content reuse by creating a Horror Movie booklet as well as a Movie Database web site. You’ll format text, insert images and videos, and create cross-references. You’ll see how easy it is to construct multiple deliverables when you put your content into stand-alone topics. You’ll also use variables and conditional text to customize your content for different purposes.

2

Exercise files The exercise files are available at https://drive.google.com/open?id=1f2j_O1n-ZzFIA1l7gTh4pCg2Ibj4HEOL

You’ll need to download the zip file and extract the files to a location on your computer, such as the Desktop.

1. After downloading the zip file, right-click on it.

2. From the shortcut menu, select Extract All.

3. Select Browse, and then select a file location, such as the Desktop.

4. Select Extract.

Get acquainted with Flare Start Flare, and then take a few minutes to get familiar with the major areas of the screen and some of the terminology.

1 Menus and toolbar

You’ll use the menus and the toolbar to perform major tasks such as saving files, editing text, and generating your project.

Tip: Most of the typical editing buttons are on the Home menu.

1

2

3

4

3

2 Panel selectors

You’ll use these buttons to display the Project organizer or the Content explorer.

• Project organizer: When you want to work on project-level settings and components, select this option. For example, you can set up variables, tables of contents (TOCs), output types (targets), and other project-wide features and settings.

• Content explorer: When you want to add or edit your content, select this option. You’ll see folders and files for the topics in your project.

Tip: It’s easy to accidentally close these panels. You can get them back by going to the View menu and selecting the name of the panel.

3 Main workspace

After you select something from the left panel, you’ll work on it in this area. At that point, this area will display local menus and a local toolbar.

4 Builds and messages area

After you build a project, status messages and file links will appear here.

Tip: If you wish, you can reduce or enlarge the space that is taken by this area: Position your mouse pointer on the top border, and then drag down to make it smaller or drag up to make it larger.

4

Create a project from an existing project For these exercises, you’ll use the exercise files as a template for a new project. By working from this set of files, you can learn the basics of Flare without having to create all of the components on your own. Also, by creating a new project, rather than simply opening the exercise files, you preserve the files in their original state and can do further work with them in the future.

1. In the main workspace, select New Project.

2. Enter this basic project information:

a. For Project name, enter: MyMovieDatabaseProject.

b. For Project folder, select the button (…), and then select the location where you want to save your project, such as the Desktop.

c. Select Next.

3. Create your project from the exercise files:

a. In the lower left corner of the dialog box, select New from existing.

b. Select the button (…).

c. Go to the place where you save the exercise files, open the project folder, and then select MovieDatabaseExerciseFiles.flprj.

d. Select Next.

4. On the final page of the wizard, select Finish.

5

View the existing topics When you create a new project from an existing project, it includes content files and other project components. Take a moment to review some of the content.

1. In the lower left corner, select Content explorer.

2. Double-click the topic Comedy-Best.htm to open the content in the XML editor.

3. Notice the XML tags on the left side of the editor for the heading (h1), the paragraphs (p), the ordered list (ol), and the list items (li).

4. Select one of those XML tags, such as the h1 or the first p, and notice that the whole paragraph is selected.

5. In the content explorer, open and briefly explore these other topics that you’ll be working with:

• Horror-Heroines.htm

• Musical.htm

• Trivia.htm 6. Notice that every opened file is represented by a tab in the XML editor.

7. Close the Trivia topic by clicking the small X on the right side of the tab.

8. Close the remaining topics and the Start Page.

Create an intro topic for your horror movie booklet For this training project, you’re going to create a horror movie booklet that features a limited set of topics, and an HTML site that includes all of the topics. For your booklet, you need to create an introduction. You’ll use this file for several of the exercises in this guide.

1. In the content explorer, right-click the Content folder, and then select New > Topic.

2. Make these selections:

a. For Source, keep the default selections, New from template and NewTopic.htm.

b. For File name, enter this text (without spaces): HorrorIntroduction

c. For 1st heading, enter this text (with spaces): Introduction to Horror Movies

3. Select Add. Your new topic appears in the main workspace. The text that you entered as 1st heading appears as the heading and is tagged with the h1 style.

4. On the left side of the editor, select the p tag to select the default text, and then select the Delete key.

5. Select the Enter key to create a new paragraph.

6

6. Enter: This guide introduces you to one of our favorite movie genres.

7. Select the Save all button, which is above the File menu.

You’ll continue to work with this topic in the next exercise.

Insert an image In this exercise, you’ll insert a Shutterstock image that was already added to the project, and then you’ll resize it so that it looks good on the page.

1. Place your cursor at the end of the paragraph that you wrote earlier.

2. Select the Enter key to create a new paragraph.

3. Go to the Insert menu, and then select Image.

4. In Under Images in project, open Resources, then open Images, then select horror.jpg, and finally, select OK.

5. Resize the image by dragging:

a. Scroll so that you can see the lower right corner of the image.

b. Position your cursor over the lower right corner of the image until the Resize icon appears.

c. Drag the mouse up and to the left until the image is about half the original size.

6. Select Save all.

You’ll continue to work with this topic in the next exercise.

7

Insert cross-references When topics are closely related, you can provide cross-reference links to help your readers to access the information that they need.

Flare allows you to create different cross-reference formats. For this project, you’ll use the default format, which dynamically includes the page number in print-based output and excludes it in web-based output. You’ll see these differences later, when you build your deliverables.

1. Place your cursor to the right of the image, and then select the Enter key to create a new paragraph below the photo.

2. Enter this text (including the colon at the end): To learn more about this genre, we recommend these articles:

3. Select the Enter key to create a new line.

4. In the content explorer, select Horror-Heroines.htm, and drag it to your new paragraph to create a cross-reference link.

A hyperlink appears, showing the 1st heading from the selected topic.

5. Select the Enter key to create a new paragraph, and then drag Musical.htm there.

6. Apply the bullet list format to the two cross-references:

a. On the left side of the XML editor, select the p tag for the first cross-reference.

b. While holding down the Shift key, select the p tag for the second cross-reference.

c. Go to the Home menu, and then select the bullet list button. The text will appear with bullets. On the left side of the editor, you’ll see the unordered list tag (ul) and the list item tags (li).

7. Select Save all.

You’ll continue to work with this topic in the next exercise.

8

Conditionalize text to show/hide it in different deliverables Sometimes when you’re reusing content in multiple deliverables, you need slightly different versions of a topic. In this case, your booklet needs to include a sentence that invites readers to visit your web site. But you need to hide that text when this topic is published on your web site. To achieve this goal, you’ll conditionalize this sentence as Print Only.

1. Position your cursor at the end of your second cross-reference, and then select the Enter key to create a new paragraph.

2. In the toolbar at the top of the screen, select the bullet icon to remove the bullet from the new paragraph. On the left side of the editor, the li tag changes to p.

3. Enter: For even more articles, visit our web site.

4. Conditionalize the new paragraph:

a. Select the p tag to select the paragraph.

b. Right-click on the selected text, and then select Conditions.

c. Select PrintOnly, and then select OK.

Flare applies pink formatting to indicate the conditionalized text. This formatting will not appear in the published topic.

5. Select Save all.

9

6. To see how the conditional text works, preview your booklet and your web site:

a. Select the little arrow on the Preview icon, and then select Preview as Movie-PDF-Target.

b. In the Preview window, scroll down to view the complete topic, including the final sentence about

visiting the website.

c. Near the top of the Preview window, change Target to Movie-HTML-Target.

d. Scroll down to see that your final sentence is hidden.

7. Close the preview window.

8. Close your introduction.

Update variables to customize the content When you’re creating reusable content, you might need to change a few words to suit different communication purposes. For example, if you were creating training guides for different clients, you might want to show the client’s name on the cover page and in the introduction. By storing the client name in a variable, you can change the variable definition, and Flare will automatically update all of the topics where that variable appears.

In this project, a number of variables have been created for you. You’ll update two variables and will see the changes that Flare makes automatically.

1. To see a file that uses variables:

a. Open the Content explorer, expand the PrintOnlyTopics folder, and then double-click Copyright.htm.

10

b. Notice specially formatted text indicating variables such as Guide Title, Copyright Year, and Company Name.

You’ll view this topic again later in this exercise.

2. Open the variables file:

a. In the left pane, select Project organizer.

b. Open the Variables folder.

c. Double-click General.

Notice the difference between the Name column and the Definition column. The Name is a label to identify the variable. The Definition is the text that you want to show in your topics. Whenever you want to change the text that is stored in a variable, you need to select the Definition column, not the Name column.

3. Change the Definition for the CompanyName variable:

a. In the CompanyName row, select the text that currently appears in the Definition column (My Company LLC). The whole row is highlighted blue. When you start typing, in the next step, your text will appear in the Definition column. Note: If your text shows up in the Name column instead, select the Esc key on your keyboard and try again.

b. Enter your first and last name as the name for your company, such as Jane Jones, and then select the Enter key.

4. In the Definition column for the GuideTitle variable, enter Guide to Horror Movies, and then select the Enter key.

5. Select Save all. Note: You won’t add a new variable in this exercise, but it’s as simple as selecting the Add Variable button and then typing a name and a definition.

6. Close the General file.

11

7. Notice the updates in Copyright.htm, and then close the file.

8. To see another file that uses the GuideTitle variable:

a. In the content explorer, expand the PrintOnlyTopics folder, and then double-click TitlePage.htm. Your guide title appears there. Don’t worry if the text appears odd—that’s because Flare is showing you the variable names (or shortened versions of them) as well as the variable values.

b. Close the Title Page file.

Insert a variable You’ve seen how variables are used in files and how they are updated. But how do you add variables to your topics? You’ll find out in this exercise.

1. In the content explorer, open your introduction.

2. At the beginning of the first paragraph, delete the phrase This guide

3. Place your cursor at the beginning of the sentence, and then insert the Guide Title variable:

a. Go to the Insert menu, and then select Variable.

b. Select GuideTitle, and then select OK. The variable name and your guide title appear with special formatting. If your title is long, only part of it will appear, but don’t worry—the full title will appear when you build your deliverable.

4. Select Save all.

5. To see how the variable will look in the deliverable, select the Preview icon and then select Preview As Movie-PDF-Target.

6. Close the topic.

12

Apply styles Styles are used to format text, tables, pictures, and other elements consistently. Although you can use the toolbar buttons to manually format text and other elements, you should always use styles as a best practice. Doing so ensures consistency. In this exercise, you’ll learn how to apply styles.

1. In the content explorer, open Trivia.htm. This file consists of questions and answers.

2. Select the p tag for the first question (What was the first sound film to win the Best Picture Oscar?).

3. Go to the Home menu, find the Style section in the middle of the toolbar, and then select h2 from the drop-down list.

4. Repeat the previous steps to format each question as h2.

5. Below the final question, select all of the p tags for the list of actors, and then on the toolbar, select the Bullet List icon.

6. Select the p tag for the final sentence, which refers to the source of the information in this article, and then select p.source from the Style drop-down list.

You’ll continue to work with this topic in the next exercise.

Update a style One benefit of XML authoring is that content is separated from the format. Text easily can be reused in multiple deliverables because it can quickly be reformatted based on the stylesheet (CSS) for the deliverable. If you need to change a format, you simply make one change in the stylesheet, and it cascades through all of your topics. In this exercise, you’ll update the h1 style by changing the font color.

1. To see how the h1 style currently looks, look at the heading of the Oscars Trivia topic. On the left side of the workspace, notice the h1 tag. You’re going to change the appearance of all h1 text in your project.

2. In the content explorer, open Resources > Stylesheets.

3. Double-click MainStyles.css.

4. To modify the h1 style, make these selections:

a. In the All Styles drop-down list below the MainStyles.css title bar, select Heading Styles.

13

b. On the left, select h1.

c. On the right, select Font.

d. In the Color box, select the drop-down arrow, and then choose any color that you like.

Flare shows a preview in the lower right section of the Styles editor.

5. Select Save all.

6. Close MainStyles.css, and see the new appearance of the heading in the Oscars Trivia topic.

Insert drop-down text Whenever possible, a writer should avoid overloading readers with more information than they need. MadCap Flare makes it easy to achieve this goal in HTML outputs by providing a drop-down text feature. Text is hidden under a "hotspot" until the user selects it. In this exercise, you’ll apply this feature in one of the movie files..

1. In the Oscars Trivia topic, select the first question and answer pair:

a. Select the h2 tag for the first question (What was the first sound film to win the Best Picture Oscar?).

a. b.

c.

14

b. While holding down the Shift key, select the p tag for the paragraph below the question.

2. Go to the Insert menu, and then select Drop-Down Text. Flare applies formatting tags, which you can see on the left side of the screen. Later, when you build your HTML site, you’ll see how the hot-spot works.

Note: If you hover your mouse over the tags on the left, you can see that the question is formatted as MadCap:dropDownHead, and the answer is formatted as MadCap:dropDownBody.

3. Repeat the previous steps for each of the remaining question-and-answers. Note: The final question has a multi-paragraph answer, including a bulleted list. On the left, select the h2 tag, the following p tag, and the ul tag (which selects all of the li tags, too), and then apply the hotspot.

4. Select Save all.

5. To preview your hotspots, select the Preview button in the top left corner of the editor, and then select Preview as Movies-HTML-target.

15

6. In the preview, select the first question, and verify that the answer appears below it. Your preview should match the following example.

7. Close the preview.

8. Preview the PDF output, and notice that the hotspots no longer appear, since hotspots are available only in the HTML output.

9. Close the topic.

Select the content and settings for your printed document Flare creates deliverables by using the stylesheets, page layouts, variables, and other components in the Project organizer. In this training guide, you’ll learn about these two components:

• TOC: A TOC identifies the topics to include and the order in which to present them. Print documents (for example, PDF and e-book outputs), Flare will include only the topics that you add to the TOC.

• Target: A target identifies all of the components and settings that Flare will use to build your deliverable. For example, the target identifies the stylesheet and the TOC.

In this exercise, you’ll start with an existing TOC and an existing target, and will make a few changes.

1. In the left pane, select Project organizer.

2. Set up the TOC for your genre-specific document:

a. Double-click TOCs.

b. Double-click Print TOC.

16

The TOC appears in the main workspace. You can see that it was partially created for you in the project files for this training guide.

c. In the left pane, select Content explorer, and then drag the specified files into the TOC editor, below the entry for PrintTOC.

• HorrorIntroduction.htm

• Horror-Heroines.htm

• Musical.htm

Your TOC should match the following picture, except that your company name will appear in the first entry. Note that the topics are represented by the heading text, not the file name. If needed, you can rearrange the topics by using the up and down arrow buttons, as illustrated.

d. Select Save all.

e. In the project organizer, right-click Print TOC, select Rename, enter: Horror-Print TOC, and then press the Enter key.

f. When the Update Links message appears, select Update Links.

3. Set up a target to identify the other settings for your printed document:

a. In the project organizer, double-click Targets.

b. Double-click Movies-PDF-Target to open the properties editor.

c. For Master TOC, select Horror Print TOC. You are telling Flare that when you generate the PDF, you want to use this TOC to determine the files to include, and the order to include them.

d. Skim through the displayed properties and the left menu to understand what aspects of the deliverable are controlled by the target.

17

e. In the left menu, select Conditional text, and then select the settings as illustrated below. You are telling Flare that when you build the PDF, you want to include text that is tagged as PrintOnly and to exclude text that is tagged as OnlineOnly.

4. Select Save all.

Build and verify your printed document After creating your content and setting up your TOC and your Target, you are ready to build your booklet. You’ll see how all of your work in Flare looks in the final product.

1. Go to the Project menu at the top of the screen, select the arrow on the Build primary button, and then select your PDF target.

Note: If you are prompted to save changes, select Yes.

2. At the bottom of the screen, if the Builds area is not fully visible, drag the top border upward.

3. When the Status of your build is Finished, double-click the PDF icon to see the PDF file.

Note: You might have to scroll right to see the Status column of the Builds table.

18

4. Verify the components that you created during the previous exercises:

Your name and your guide title appear on page 1 and on page 2.

The Contents page shows the selected topics in the correct order:

o Introduction

o Heroines of Horror

o Little Shop of Horrors Checks All the Boxes

The top-level headings in each topic are the color that you selected in the Style Editor.

Your introduction includes the horror movie picture, the bulleted list, and the hyperlinked cross-references.

The cross-references go to the topics as indicated.

At the end of the introduction, you see a statement about visiting your web site.

19

Select the content and settings for your web site In addition to your genre-specific booklet, your fictitious company also maintains a website full of movie-related content. In this exercise, you’ll set up a website that includes all of your content, and you’ll set up a TOC to create menus that direct users to special topics.

1. In the project organizer, go to the TOCs folder, and open Online TOC. It contains only one topic.

2. Set up the TOC books, which will become the menus in the web site:

a. Near the middle of the TOC Editor toolbar, select the New top-level book button, and then enter: Horror

b. Again select the New top-level book icon, and then enter: Comedy

c. Again select the New top-level book icon, and then enter: More Info

d. Select each book, and then select the up-arrow or down-arrow buttons the TOC Editor toolbar to move it into this order:

• Comedy

• Horror

• More Info

e. Select the Expand All button so that you can see the contents of the books.

Note: For now, ignore the placeholder topics, which are named New Entry.

20

f. Drag Oscars Trivia into the More Info book.

As you drag, the mouse pointer becomes a down arrow.

When you release the mouse button, the topic appears in the More Info book.

g. From the content explorer, drag Comedy-Best.htm and Musical.htm into the Comedy book.

h. Drag Horror-Heroines.htm and Musical.htm into the Horror book. Note: Musical.htm will be listed on both menus.

21

i. Delete the New Entry topics. Your TOC should match this illustration:

j. Since you have an introduction topic for the Horror category, right-click on the Horror book,

select Link to Topic, and then select HorrorIntroduction.htm. The appearance doesn’t change in the TOC, but you’ll see the results of this action when you build your HTML output.

k. Select Save all.

3. Set up the target for your web site:

a. In the project organizer, open the Targets folder, and then double-click Movies-HTML-Target to open the Target Editor.

b. For Startup Topic, select the button, and then select /Content/Home.htm. This file will be the home page of your web site.

c. For Master TOC, select the drop-down arrow, and then select Online TOC.

4. Select the Skin tab, and for Skin select HTML 5 – Top Navigation.

5. Select Save all.

22

Build and verify your web site Now that you’ve created your content, set up your TOC, and set up your target, you can build your web site.

1. Go to the Project menu at the top of the screen, select the arrow on the Build primary button, and then select your HTML target.

Note: If you are prompted to save changes, select Yes.

2. At the bottom of the screen, adjust the display of the Builds area so that you can see the list of builds.

3. When the Status of your build is Finished, double-click the HTML 5 icon to see your web site. Note: You might need to scroll right to see the Status column of the Builds table.

4. When prompted to choose a web browser, choose Chrome.

5. Verify that your web site meets these requirements:

Your name appears on the home page.

The top menus are: Comedy, Horror, and More Info.

Your selected files appear on the appropriate menus.

When you select the Horror menu, your intro topic appears.

In your intro, you do not see the conditionalized sentence about visiting your website.

The cross-references in your intro do not include page numbers, and they open the correct files.

In the search box, you can enter search terms such as Emily Blunt, Little Shop, and Alien to find the articles that contain those terms.

In the Oscars Trivia file, the hotspots work correctly.

Learn more about Flare To learn more about Flare, visit MadCap Flare’s Online Help at https://help.madcapsoftware.com/flare2019/Content/Flare/Introduction/Home-Flare.htm.