How to Author Teaching Files

This article is a shorthand guide for creating and editing MIRC documents using the MIRC Author Service. MIRC provides several ways to create and edit documents:

• The Basic Author Service allows a user to create a document, submitting files and images which reside on the user's local computer.
• The Advanced Author Service allows a user to create and edit documents, submitting files and images which reside in the user's file cabinet on the MIRC site.
• The Zip Service allows a user to create one or more documents by submitting a zip file containing a tree of directories, each directory containing the files and images for one document.
• The TCE Service allows a user at a PACS diagnostic workstation to create and submit documents to a MIRC site.
• The Submit Service provides a way for third-party, client-side authoring tools to interface with a MIRC site. It also allows MIRC documents which have been exported from one site to be submitted to another site.
• The DICOM Service provides automatic document creation for images received via the DICOM protocol. While this service was intended for clinical trials, it has been used for teaching file creation as well.

All MIRC documents, no matter how they were created, can be edited in the Advanced Author Service.

This article describes the Basic Author Service and the Advanced Author Service. Articles describing the other services are available on the MIRC wiki at mircwiki.rsna.org.

1 Prerequisites

To use the MIRC Author Service, you must have an account on the storage service where you will create documents. See your MIRC site administrator, who will create an account with user and author roles. Your account will consist of a username and password which you will use to access the author service.

2 The Basic Author Service

The Basic Author Service was designed for people who have images on their local computer. It allows users to quickly create a document from a simple form with a small set of fields and to add images and other files to the document by browsing for them.

To access the Basic Author Service, log in to the server and click the Basic Authoring Tool link. The author service will display a window containing the document form. Follow the steps shown in the window, filling in as many of the fields as desired.

To include images, click the Browse... button and navigate to an image. After selecting an image, a new Browse... button will appear, allowing selection of another image. If many images are to be included, they can be collected into a zip file. When the author service receives the zip file, it will automatically unpack it and add all its contents to the document.

After filling in the form, click the Create Teaching File Document button. The browser will then send the form and the selected files to the server, which will create the document and return a page displaying it. The document can then be edited further, if desired, in the Advanced Author Service.

3 The Advanced Author Service

3.1 Creating a New Document

To create a new document, log in to the server and click the Advanced Authoring Tool link.

The author service will then display a page welcoming you. Enter your name, affiliation, and contact information as you wish to see it appear in the document. This information is remembered by the author service and filled in for you each time you create a new document.

Select the template you wish to use to create the new document by clicking the down arrow on the selection box and choosing one of the items in the menu. Several templates covering all the display modes are provided. Your MIRC site administrator may have created additional templates. A template is simply a starting point for editing a document. Templates can simplify the task of creating documents, but no matter what template you select, you can make changes to create the document in any format you wish.

The display modes are:

• MIRC Standard Teaching File (mstf) is a framed layout with separate frames for images and text sections and tabs across the top for selecting sections to view. This is the most commonly used format for teaching files.
• Tab format is a framed layout in which each section has a separate tab and only one section is visible at a time. This is the most commonly used format for clinical trials documents.
• Page format is a flat web page layout, in which the images and sections are arrayed linearly down the page. This is the most commonly used format for documentation and for teaching files that are to be printed.

After selecting the template, click the Submit Request button. The author service will open the template and display it in the editor window.

3.2 Editing an Existing Document

Error creating thumbnail: Unable to save thumbnail to destination

To edit an existing document, first view the document by finding it with a query on the query page and then clicking on the title of the document in the query results.

If the document is displayed in page mode, scroll to the bottom of the page. If the document is displayed with tabs, click the Document tab and scroll to the bottom. You will see a small table of buttons.

Click the Edit button. The author service will open a new window and display the document in the editor, allowing you to add, delete, or modify the contents. Be sure to click the Save or Preview buttons to ensure that your changes are saved.

Note: If the Edit button is not enabled, there are two possibilities: you may not have permission to edit the document, or you may not have logged in. To log in, go back to the query page and click the "Login" button on the right side of the page.

3.3 The Author Service Editor

The editor window contains four sections. On the right is a column of icons representing all the files you have in your private file cabinet. You can learn about how to insert, delete and manage files by reading How to Store Images in MIRC.

At the top is a toolbar providing various functions. As you roll the mouse over the buttons, a short description of the function is displayed.

The left-most button switches the author service between the simplified normal mode and the advanced mode which is described in the Advanced Functions section below. The next two buttons save the changes you make to the document and display the document in a separate browser window so you can see how the document will look to users who view it.

The next group of buttons allows you to create, delete, and move document sections. The template you chose to begin creating the document contained one or more sections. With these buttons, you can modify the document to fit your current purpose. If you create a new section, you will want to change its heading as described in the Advanced Functions section below.

The last group of buttons allows you to insert, delete, and move various kinds of items that may be placed in sections. For instance, some of the buttons insert paragraphs, captions, images, patient tables, and quizzes; another removes selected items, and the last two move selected items up or down on the page.

Error creating thumbnail: Unable to save thumbnail to destination

Under the toolbar is a row of section titles.

Error creating thumbnail: Unable to save thumbnail to destination

If you click on a section heading, the contents of that section are displayed in the main body of the page, with each paragraph, caption, image, patient, and quiz shown in a separate box. Clicking on a box selects it, allowing you to edit it, remove it or move it up or down on the page.

Browse the sections of the document, adding, deleting, and modifying content where you wish.

• While you are editing a paragraph, if you enter a lot of text into a box and want a larger box, click the Save button. The author service will resize the text boxes.
• When entering text in a text box, if you separate text lines by a blank line, the author service will generate separate paragraphs for you. If you start a new line with a '-' character, the author service will generate a bullet list for you. If you start a new line with a '#' character, the author service will generate a numbered list for you.

Note that some sections are fixed in place and cannot be deleted - Document, Title, Authors, Abstract, Keywords, References, Indexed Content, PHI, and Permissions. If you don't have anything to add to such a section, you can leave it alone; empty sections are not displayed to users. If you create or move sections, they are constrained to positions between Keywords and References.

As you work, you should periodically click the Save button to save the changes you have made. When you click the Save button, the author service will redisplay the editor page to allow you to continue editing. If the author service indicates that the document had an error, see note 2 below.

If you wish your document to be private, or if you wish to otherwise restrict access to it, see the section on Creating Private and Public Documents.

3.4 Advanced Functions

The left-most button in the toolbar switches the editor between the normal mode and the advanced mode. In the advanced mode, several tabs are shown that are not presented in the normal mode:

• The Document tab allows you to change the display format, the background color, and several attributes describing the document. These are typically defined in the template and do not need to be changed.
• The Indexed Content tab allows you to enter keywords in numerous categories. This information is not displayed to viewers of the document, but it is used in queries, making the document more easily discoverable in some situations.
• The PHI tab allows you to indicate that the document contains Protected Health Information. If you include such information in your document, you must include a PHI section in order to tell the MIRC site that distributes the document to keep an audit trail of users who have viewed the information, as required by HIPAA.
• The Permissions tab allows you to specify who can read, update, export, and delete the document on the server. More details are supplied in the section on Creating Private and Public Documents, below.

The advanced mode also provides some additional parameters within document sections.

• The Heading field allows you to change the heading that is displayed above the section in the document.
• The Visible field allows you to specify whether the section should be displayed when the document is viewed. The choices are yes, no, and owner. If you have text that would be useful in a query but not necessarily in viewing the document (for instance, a transcript of an audio file that is referenced in the document), you can put it in a visible="no" section. If you have notes which you want to keep with the document but which you don't want others to see, you can put it in a visible="owner" section.
• The Image width field, which is only displayed in normal document sections, allows you to specify the maximum width of images that are to be displayed in the section. The default is 256, which works well for most types of documents, but which can be increased if you want to show more detail.
• The Pane width field, which is only displayed in a special type of section called an image-section, allows you to specify the width of the main image display pane on the right side of the section. The default is 700, which works well for most types of documents.
• The Suppress icons checkbox, which is only displayed in image-sections, allows you to suppress the display of token images in the lower left corner of the window when the image-section is displayed. This provides more room on the left side for text sections to be displayed.
• The Include insertion point checkbox, which is only displayed in image-sections, places an indicator at the end of the section, allowing images to be added by users who have author privileges on the document. When a document containing insertion point is displayed, a button entitled Add Images to This Document is displayed in the table at the bottom of the Document section. Clicking the button allows images to be added without having to go through the Author Service.

3.5 Adding Images to a Document

Images can be added to any normal document section. The most effective places to put images depends on the display mode of the document. If you put an image in the document and don't like the way it looks, you can select it and delete it from the document; then, you can insert it from the file cabinet in another place.

When you are selecting a DICOM image for insertion in the document, you may want to check on its parameters. If you hold the Alt key down and click the image in the right-hand column (the file cabinet), the server will display a list of all the elements in the DICOM image in a separate window. After looking at it, you can close that window and return to the editor.

To insert images into the currently displayed section, select them in the column on the right side of the window and click the Insert images button in the Items section of the toolbar. To select an image, click on it. To select a range of images, click the first one, hold down the shift key, and click the last one. To select images at random, hold the control key and click on the images you want. Each control-click on an image toggles its selection.

If you enter some text in the field at the top of the file cabinet column on the right side of the window, you can use the Find button in the file cabinet on the right side to select images containing that text in their keywords. More information about the use of keywords in the file cabinet is contained in How to Store Images in MIRC.

As noted in the Advanced Functions section, there is a special kind of section that can appear in a tab or mstf document. This type of section, called an image-section, has special features when the document is displayed. Because an image-section can only contain images and is typically used to hold a substantial number of them, the editor treats it a little differently.

You can use the click, shift-click, and control-click buttons to select groups of images in the image-section and then use the up-arrow and down-arrow buttons in the toolbar to move them forward or backward in the section.

3.6 Adding Annotations to Images

Images in an image-section may be annotated. This feature requires that an SVG viewer be installed on the author's computer. The free Adobe SVG viewer can be obtained from the Adobe SVG Site.

To open an image in the image editor, click the tab for the image-section and then double-click the image. The image editor will then replace the main author service editor window and present the image along with a toolbar containing icons for drawing lines, arrows, circles, and text.

The two icons at the left end of the toolbar provide a way to return to the main editor either with or without saving the annotation changes.

The actual annotations are saved in a special format (SVG) which most browsers do not display without plug-ins. For this reason, when an image is saved in the image editor, the author service automatically creates a browser-viewable (JPEG) version of the image to be displayed when users view the document. The original annotations in SVG format are preserved, allowing the author to edit them at any time.

3.7 Adding Captions to Images

Captions can be added to images in an image-section. To open an image in the caption editor, double-click the image while holding down the Ctrl key ("C" for "Caption"; "C" for "Ctrl").

Two types of captions are provided:

• Captions which are always displayed when the image is shown in the right pane of the image-section display.
• Captions which are concealed until the user clicks a place-holder to show them.

An image may have one caption of each type.

When a document is displayed in page display mode, all captions appear just below the image.

3.8 Creating Private and Public Documents

As noted in the Advanced Functions section, you can use the Permissions tab to control who can access your document. If the tab is not displayed, click the left-most button in the toolbar.

The owner of a document has absolute control over it, including read, update, export, and delete privileges. The username of the creator of the document is automatically entered in the field when the document is first created. You can add other owners by inserting their usernames in the field, separated by spaces.

The Read access, Update access, and Export access fields control access of specific types indicated by their names.

• If you click a Private radio button for a type of access, only the owners will have that type of access.
• If you click a Public radio button for a type of access, anyone has that type of access, including users who are not logged in to the server.
• If you click the third radio button for a type of access and enter a list of usernames and/or roles, you can restrict access to specific users or groups of users. Note that if you put an asterisk in that field, and the radio button is selected, that type of access is granted to the public.
• There is no way to grant delete privileges other than to make a user an owner of the document.
• The MIRC administrator has all forms of access to all documents on the server.

3.9 Notes

Here are a few additional items that may be useful:

1. The Preview button in the toolbar requires that the document already be installed on the server. Thus, when the document is first created, you must save it before the preview function will work. From then on, you can click Preview at any time and see the document as it will be displayed for users.
2. Special care should be taken when entering HTML into a document. If it is done incorrectly, it will produce a document that is not well-formed. Such a document will not parse, and the author service will display an error message from the parser. Depending on the specific error, the message may be quite explicit or very cryptic. If you get an error which says something about a tag or element not being closed properly, look carefully at any elements you have entered, ensure that all elements are properly closed, and resubmit the document.
3. The author service currently supports JPEG, GIF, PNG, TIFF, and DICOM images. It requires that a DICOM image have a SOP Class UID identifying it as one of the types it knows. The author service knows about all the common types of DICOM images and many uncommon ones, but not all types of DICOM objects.