How to Author Teaching Files

This article is a shorthand guide for creating and editing MIRC documents using the MIRC Author Service.

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 Creating a New Document

To create a new document, launch your browser and go the MIRC site's query page. On MIRC sites running early versions of the software, select the storage service on which you wish to create a document and click the Author Service button on the right side of the page. On recent versions, log in to the server and click the Advanced Authoring Tool link on the left side of the page.

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.

Error creating thumbnail: Unable to save thumbnail to destination

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 standard 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.

After selecting the template, click the Submit Request button.

The author service will display a page like the one below.

Error creating thumbnail: Unable to save thumbnail to destination

The page 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 <a href="http://mirc.rsna.org/mircstorage/documents/fileservice/FileServiceQuickStart.xml">How to Use the MIRC File Service</a>.

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.

Error creating thumbnail: Unable to save thumbnail to destination

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.

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 Editing an Existing Document

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 as shown below.

Error creating thumbnail: Unable to save thumbnail to destination

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.

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 and which appears only in the tab or mstf format, 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.

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 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 Use the MIRC File Service.

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.

Error creating thumbnail: Unable to save thumbnail to destination

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.

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, view the image-section's tab and 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.

Error creating thumbnail: Unable to save thumbnail to destination

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.

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").

Error creating thumbnail: Unable to save thumbnail to destination

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.

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 (it's great to be king).

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.