DITA Best Practices : Project view

The Project view is designed to assist the user in organizing and managing related files grouped in the same XML project. The actions available on the context menu and toolbar associated to this panel, enable the creation of XML projects and shortcuts to various operations on the project documents.

The Project View

The default layout initialized by the Window > Reset Layout menu item positions the Project view on the left side of the Oxygen XML Editor window, above the Outline view. A closed view can be quickly reopened at any time with the Project > Show Project View menu action.

The tree structure occupies most of the view area. In the upper left side of the view, there is a drop-down list that holds all recently used projects and project management actions:

Open Project ... (Ctrl (Meta on Mac OS)+F2) - Opens an existing project. An alternate way to open a project is to drop an Oxygen XML Editor XPR project file from the file explorer in the Project panel.
New Project - Creates a new, empty project.

The following actions are grouped in the upper right corner:

Collapse All - Collapses all project tree folders. You can also collapse/expand a project tree folder if you select it and press the Enter key.
Link with Editor - When selected, the project tree highlights the currently edited file.
Note: This button is disabled automatically when you move to the Debugger perspective.
Settings - A sub-menu containing the following actions:
- Filters - Allows you to filter the information displayed in the Project view. Click the toolbar button to set filter patterns for the files you want to show or hide. Also, you can set filter patterns for the linked directories that are hidden.
- Show Full Path - When selected, linked files and folders are presented with a full file path.
- Enable Master Files Support - Select this option to enable the Master Files support.
- Change Search and Refactor operations scope... - Allows you to change the collection of documents that define the context of the search and refactor operations.
  - Use only Master Files, if enabled - Restricts Oxygen XML Editor to perform the search and refactor operations starting from the master files defined for the current resource. This option is available when you select Project in the Select the scope for Search and Refactor operations dialog and the Master Files support is enabled.

The files are organized in an XML project usually as a collection of folders. There are two types of folders:

Logical folders - marked with a blue icon on Windows and Unix/Linux () and a magenta icon on Mac OS X (). This folder type has no correspondent on the physical disk, being used as containers for related items. Creating and deleting them does not affect the file system on disk.
Linked folders - marked with a yellow icon on Windows and a blue icon on Mac OS X which is exactly the folder icon used by the Windows Explorer and Mac OS Finder applications. They content mirror a real folder existing in the file system on disk.

Creating New Project Items

A series of actions are available in the contextual menu:

New > File - Creates a new file and adds it to the project structure.
Add Folder - Adds a link to a physical folder, whose name and content mirror a real folder existing in the file system on disk. The icon of this action is different on Mac OS X () as the standard folder icon on Mac OS X is not the usual one from Windows and Unix/Linux systems.
New > Logical Folder - Creates a logical folder in the tree structure (the icon is a magenta folder on Mac OS X - ).
New > Logical Folders from Web - Replicates the structure of a remote folder accessible over FTP/SFTP/WebDAV, as a structure of logical folders. The newly created logical folders contain the file structure of the folder it points to.
New > Project - Creates a new project, after closing the current project and all open files.

Add Content to a Logical Folder

You can add content to a logical folder using one of the actions available in the contextual menu:

Add Folder - Adds a link to a physical folder, whose name and content mirror a real folder existing in the file system on disk. The icon of this action is different on Mac OS X () as the standard folder icon on Mac OS X is not the usual one from Windows and Unix/Linux systems.
Add Files - Adds links to files on disk.
Add Edited File - Adds a link to the current edited file to the project.

Managing Project Content

You can create linked folders by dragging and dropping a folder from the Windows Explorer / Mac OS X Finder over the project tree or by selecting in the contextual menu Add Folder.

Note: The liked files presented in the Project view are marked with a special decorator.

Also, you can move the resources of the project with drag and drop operations on the files and folders of the tree.

When adding files to a project, the default target is the project root. To change a target, select a new folder. Files may have multiple instances within the folder system, but cannot appear twice within the same folder.

To remove one or more files or folders, select them in the project tree and press the Delete key or run the contextual menu action

Remove from Project. To remove a file or folder both from project and disk, run the contextual menu action

Remove from Disk (Shift+Delete) which is available for both logic and linked files.

CAUTION:

In most cases this action is irreversible, deleting the file permanently. Under particular circumstances (if you are running a Windows installation of Oxygen XML Editor and the Recycle Bin is active) the file is moved to Recycle Bin.

To create a file inside a linked folder, choose the New > File action from the contextual menu.

There are three ways you rename an item in the Project view: To begin editing an item name in the Project view, select the item and do one of the following:

invoke the Rename action from the contextual menu;
press F2;
click the selected item.

To finish editing the item name, press Enter on your keyboard.

Note: The Rename action is available on logic files also.

If a project folder contains many documents, a certain document can be quickly located in the project tree if the user selects with the mouse the folder containing the desired document (or some arbitrary document in this folder) and types the first characters of the document name. The desired document is automatically selected as soon as the typed characters uniquely identify its name in the folder. The selected document can be opened by pressing the Enter key, by double-clicking it and with one of the Open actions from the pop-up menu. The files with known types are opened in the associated editor while the binary files are opened with the associated system application. To open a file of known type with other editor than the default one, use the Open with action.

The project file is saved automatically on disk, every time the content of the Project view is modified by actions like adding or removing files or folders and drag and drop to/from the Project view.

Validate Files

The currently selected files in the Project view can be validated against a schema of type Schematron, XML Schema, Relax NG, NVDL, or a combination of the later with Schematron with one of the following contextual menu actions:

Check Well-Formedness - checks if the selected file or files are well-formed.
Validate - validates the selected file or files against their associated schema. EPUB files make an exception, because this action triggers a Validate and Check for Completeness operation.
Validate with Schema... - validates the selected file of files against a specified schema.
Configure Validation Scenario - allows you to configure and run a validation scenario.

Applying Transformation Scenarios

The currently selected files in the Project view can be transformed in one step with one of the actions Transform > Apply Transformation Scenario(s), Transform > Configure Transformation Scenario(s)... and Transform > Transform with... available on the right-click menu of the Project view. This, together with the logical folder support of the project allows you to group your files and transform them very easily.

If the resources from a linked folder in the project have been changed outside the view, you can refresh the content of the folder by using the Refresh action from the contextual menu. The action is also performed when selecting the linked resource and pressing F5 key

A list of useful file properties like the ones available in the Properties view can be obtained with the Properties action of the contextual menu invoked on a file node of the Project view tree, in the following dialog:

The Properties Dialog

Right-clicking any object in the tree view displays the Project menu with functions that can be performed on, or from the selected object. Options available from the Project menu are specific to the object type selected in the tree view.

You can also use drag and drop to arrange the files in logical folders (but not in linked folders). Also, dragging and dropping files from the project tree to the editor area results in the files being opened.

Other Context-Dependent Actions

Many of the actions available in the Project view are grouped in a contextual menu. This menu is displayed after selecting a file or folder and then pressing right-click (or Ctrl+Click on Mac OS X)

Show in Explorer (or Show in Finder on Mac OS X) - On Windows, the content of the selected folder, or the selected file is presented in a specific explorer window. On MAC OS X, the parent folder is opened and the selected folder is highlighted in a specific finder window. This window also presents selected files.
Open with - Open selected file with one of internal tools: SVG Viewer , Hex Viewer , Large File Viewer , MathML Editor , WSDL/SOAP Analyzer, DITA Maps Manager , Archive Browser .
Open All Files - Opens in the editor view all files contained by the selected resources.
Refresh - Refreshes the content of the Project view;
Note: When you refresh the content of the Project view, Oxygen XML Editor also refreshes the dependencies between the resources in the Master Files directory.
Find/Replace in Files - Allows you to find and replace text in multiple files.
Check Spelling in Files - Allows you to check the spelling of multiple files.
Open in SVN Client - Syncro SVN Client tool is opened and it highlights the selected resource in its corresponding working copy.

Menu Level Actions

The following actions are available in the Project menu:

New Project - Creates a new, empty project.
Open Project ... (Ctrl (Meta on Mac OS)+F2) - Opens an existing project. An alternate way to open a project is to drop an Oxygen XML Editor XPR project file from the file explorer in the Project panel.
Save Project As... - Allows you to save the current project under a different name.
Validate all project files - Checks if the project files are well-formed and their mark-up conforms with the specified DTD, XML Schema, or Relax NG schema rules. It returns an error list in the message panel.
Show Project View - Displays the project view.
Reopen Project - Contains a list of links of previously used projects. This list can be emptied by invoking the Clear history action.