Building Your Library

After defining a library, you are now ready to build that library. Regardless the type of content collection definitions you have included in your library, Collection Builder or Collection Reference, you need to run a build on all content collection nodes.

When you define your library, your main focus is on the Properties grid in your Library Manager. However, when you build your library, your focus will be on the Content tab to the left of the properties pane (Figure 1).

Figure 1. Library Manager

Determining the Scope of a Build

With Library Manager you can determine the scope of a build. Meaning, you can build a single content collection or multiple content collections at a time. You determine the content collections that you want Library Manager to build by your selection in the Content Tree pane. Figure 1 shows a sample content tree pane with folder, collection builder, and collection reference nodes.

If you click on the "NXT 4 Documentation" library node, then choose Build Entire Library  from the Content menu (or right-click menu), Library Manager will build your complete library no matter what node you currently have selected in the tree. This is what you will need to do the first time you build your library. However, if you select a folder node (i.e. in figure 1, "Sample Collections") and then choose Build Subtree , Library Manager will only build the content collections on that "branch." In other words, only content collection decendents of the node you select will Library Manager build. Furthermore, you may also select a specific collection node (i.e. in figure 1, "Country Quick Facts") in your tree and choose Build Subtree  and Library Manager will only build that collection.

What Happens When You Build

When you define and create a library within the Library Manager, there are many things happening and many files involved. The Library Manager handles things differently on your first, initial build than on subsequent (update) builds. However, before you can run a build on your library, whether initial or subsequent, you must Save the settings in your library.

What Happens When You Save

Before Library Manager allows you to build your library (or any part thereof) you must choose Save from the File menu. If you forget to do this and choose Build Entire Library or Build Subtree from the Content menu (or right-click menu), Library Manager will ask you if you want to save by displaying the dialog box in Figure 2.

Figure 2. Save Library Before Build Dialog Box

Click Yes in this dialog if you want to save your library and have Library Manager continue with the build. Click No if you want to terminate the build process and not save your settings.

When you save your library for the first time Library Manager does the following:

Library Manager places all of these files in the directory that you designate as your Build Output Dir in your library properties .

After you save your library for the first time, the Library Manager updates these files with any appropriate changes upon subsequent saves.

What Happens on Your First Build

After you, or Library Manager, saves your library, you can now run a build on that library. When you choose a  Build option from the Content menu (or right-click menu), Library Manager runs a preliminary check on all library, folder, and collection node information to see if all necessary information to run the build is present. Library Manager checks each node in your library to make sure you have not omitted any necessary information (like root directory for the File System Content Bridge), or, if you have manually modified any of the library files, it validates them against the respective Document Type Definition.

If the pre-build validation does not detect any errors, and you have not set your Library Manager preferences to stop builds when you have validation warnings, then the Library Manager will automatically start building your library (or part thereof) after completing the validation check and you will see the dialog in Figure 3. However, if the Library Manager does detect errors in the validation, the build will not run and the process stops. You must correct the errors before you are able to successfully run a complete build. The build process will terminate for warnings as well if you have set your Library Manager preferences accordingly. When you run a successful build you see the dialog in Figure 4.

Figure 4. Build Progress Dialog Box

This dialog displays the following:

If you scroll up and down in the Build log box, you will see that the Library Manager treats each collection node individually from the stand point of error and warning reporting. You can find the cumulative totals for errors and warnings just below the Build log box. If you choose to record the build log output to a file (Figure 3), you can open that file and see the same information in that log file.

Behind the Scenes

Library Manager does the following when you choose Build from the Content or right-click menu:

The Library Manager and the content bridges work together to build your content collections and library with very little effort on your part. You do the majority of your work in adding the necessary information to define your library, folder, and collection nodes.

What Happens on Subsequent Builds

You can run subsequent builds at will when you want to update your content collections or your library in general. In general, the files that the Library Manager created are updated and the collection builders are rebuilt. With each subsequent build, an update file is created. Each update file is immediately merged into the master collection. But the file remains available for you to distribute to your end users. Also, collectin references are copied again, if they have changed since the last update. For more information regarding updating and rebuilding see the Updating and Rebuilding of the Updating and Managing Your Content section.