Click or drag to resize
Sandcastle Help File Builder

Folder and File Items

Folder nodes can be used to organize the content items in a project. The file nodes represent conceptual content topics, images, content layout files, and various other supporting files that may or may not be compiled into the help file.

Adding Folders and Files

To add a folder or file, right click on the root project node or any other folder or file node and select one of the Add menu options. These options can also be selected from the File | Project Explorer | Files menu. Files can also be dragged and dropped on the folder and file nodes from Windows Explorer.

Folders and files added while the root project node or a root file node is selected will be added to the root folder of the project. Folders and files added while a folder item is selected will be added as children of the selected folder. Folders and files added while a child of a folder node is selected will be added as children of the parent folder of the selected item.

Note Note

Folders and files become part of the project and will reside in the project folder. Existing files that are not under the project folder are copied to it.

Add Options

The following options can be used to add items to the project:

  • New Item - This lets you add a new file item based on a template. A set of common template files appears in the submenu along with additional submenus containing conceptual content topic templates and custom template files that you can create.

    Tip Tip

    To add your own custom project template files, place them in the Item Templates folder in the help file builder's Local Application Data folder. To add your own conceptual content topic template files, place them in the Conceptual Templates folder in the help file builder's Local Application Data folder. See the Special Folder Locations topic for more information.

  • New Folder - Add a new folder to the project.

  • Existing Folder - Add an existing folder to the project. If the folder contains subfolders and/or files, they are added to the project recursively as well. The folder must be a child of the project folder or one of its subfolders.

  • Existing Item - Add an existing file to the project. The build action will be set based on the file's extension.

  • Import from Media Content File - This option will add images to the project based on the information in a conceptual content media content file. The images added will have their build action set to Image and their additional properties will be set to the values from the content file. If referenced in conceptual content topics, these image will be copied to the .\Media folder in the resulting help file output.

Editing a Folder or File Item

When selected, folders allow you to edit their name. Changing a folder name changes the parent folder name in all child items as well. All file items have a Name property that lets you edit their name. In addition, they all have a BuildAction property that specifies how the file is treated at build time. Other properties, if any, depend on the selected build action.

Tip Tip

Files and folders can be dragged and dropped or cut/copied and pasted to move them from one folder to another within the project.

Tip Tip

To edit the content of a file, double-click it, hit Enter while it is selected, or select the Open option on its context menu.

For files that have a custom editor such as content layout files or token files, the Open in Text Editor context menu option will open the file in the standard text editor. This allows you to spell check the content.

Removing a Folder or File Item

To remove a folder or file, right click on it and select the Exclude from Project or Delete option. These can also be selected from the File | Project Explorer | Files menu. The Exclude from Project option will remove the item from the project but leaves it on disk. Delete will remove it from the project and permanently deletes it from the disk as well.

Caution note Caution

If a folder is deleted, all child items are deleted recursively as well.

Linked Items

Help file builder projects support linked items as well. Linked items are files that appear in the current project's folder structure but are physically located in a location outside of the current project's folder structure. An example would be sharing a token file between multiple projects. If the file is edited in one project, those changes are reflected in the other projects in which it is a linked or actual item when those projects are built.

The standalone GUI supports them for use but cannot add them. They can be added in Visual Studio in the usual manner. Select the option to add an existing item and, in the file selection dialog box, rather than clicking the Add button, click the drop down arrow on it and select the Add as Link option.

If you do not have Visual Studio, the only way to create linked items is by manually editing the project in a text editor. To do so, add a build item to an item group. This is done by adding an element named after the build action (i.e. Tokens for a token file). The Include attribute points to the relative path of the file which is typically outside of the current project's folder structure. Add a Link element nested within the build item and set its property value to the relative path of the item within the current help file builder project. For example:

<Tokens Include="..\SomeOtherProject\Tokens\SharedTokensFile.tokens">
  <Link>Tokens\SharedTokens.tokens</Link>
</Tokens>

The example above creates a linked tokens file. Its physical location is one level up from the help file builder project folder in another project folder (..\SomeOtherProject\Tokens). Its virtual location within the current project will be in a folder called .\Tokens.

Linked items will have a Remove option rather than a Delete option. This removes them from the project but leaves them on disk in their original location since they may belong to another project.

See Also