Editing Modules

What is a Module? A module is the basic building block of a Connexions course, textbook, or other type of collection. You can think of it as a small knowledge chunk that addresses a single topic or a specific aspect of a topic. Every author determines the size of their module, ranging from a few paragraphs to an entire textbook chapter. To a student or reader viewing a course or collection, a module is simply a web page in the collection. Modules allow readers to follow the information path arranged by the author or instructor or to branch off and discover their own path. To an instructor putting a collection together, having topics in different modules allows easy selection and arrangement of the information. An instructor can include existing modules from other courses or other academic disciplines that are important to the presentation of the course subject. An example of the contents of a new module are shown in , which displays the "Manage Files" screen located under the "Files" tab.

The Module Status Sidebar The "Module Status" sidebar contains important status information about the module and several links to useful tasks for the module editor. This sidebar appears to the right of the module contents and contains the following items: State - the current status of the module Last action - The last action performed on the module, who performed it, and when Actions - This item displays links to the Connexions pages for publishing modules to the Content Commons and discarding the current operations on the module. When editing an existing module, this item also displays links for suggesting edits to original authors and creating a derived copy of an existing module View - This item displays links to preview the on-line version of the module, the print version, and the CNXML source. When editing an existing module, this item also displays a summary of the differences between the version of the module in your work area and the last published version

Editing Modules Once you have created a new module in or added an existing module to your work area, you will need to edit the module to add content and files (such as images). These operations are performed with the links and buttons on the "Manage Files" screen or the "Module Status" sidebar. The recommended sequence to perform these operations in is described in this module and appears in the following list: Edit the CNXML file. Add any other files that you want to associate with the module. Edit the metadata to enter the appropriate search keywords and the module title. Edit the module roles. Add links to the module. Preview the module in both print and on-line versions. Publish the module. Each of these operations of module editing will be discussed in the following sections.

Show/Hide ToolbarsEach page in the authoring area, including the MyCNX Home Page and module editing areas, features a useful "Show/Hide Sidebars" icon. When you click on the icon, the right and left authoring sidebars are hidden and the content pane is expanded. This is especially useful when editing modules using Edit-In-Place.Once the Show/Hide Toolbars icon has been clicked, you can reduce the editing area and display the sidebars by clicking it again.

Editing the CNXML File The "Edit" tab for the module displays the contents of the "index.cnxml" file. This file contains the text that appears in the module, plus the CNXML instructions to include any image, sound, or other media files that appear in the module. The default content display and edit is with the Edit-In-Place editor. Alternatively, you can display and edit the content with the Full Source editor by clicking

Switch to Editing 
            Full Source

. From this tab you can perform the following actions on the file: Import content into the index.cnxml file Export the index.cnxml file to an external XML editor Edit the index.cnxml file with the Edit-In-Place editor Edit the index.cnxml file with the Full Source editor

Import Content into the "index.cnxml" File To import content into the "index.cnxml" file, use the following steps: Select the format of file you want to import from the drop-down list next to the Import button. The valid formats are: Microsoft Word, OpenOffice Writer, XMLSpy/Authentic, and Plain XML. Click Import. A screen displays with a text box for the pathname of the file you want to import. Type the pathname of the file in the text box or use Browse to display the name of the pathname in the text box. Click Import. The content of the file you specified is copied into the "index.cnxml" file in your module. When you click Import in the last step, the contents of the "index.cnxml" file are overwritten by the contents of the imported file.

Export the "index.cnxml" File to an External XML Editor You can export the "index.cnxml" file so that you can edit it with a software package that is specifically designed to edit XML files. The "index.cnxml" file must be altered to allow the XML editor to read it. And once you have completed your edits, the file must be altered again to remove the changes for editor readability. The Connexions Export and Import functions automatically add and remove the changes for editor readability. Currently, the only XML editor format supported by Connexions is the format used by the Altova xmlspy® editor or the Altova authentic® editor. To export the "index.cnxml" file to be edited with an XML editor, use the following steps: Select the format of the file you want to export from the drop-down list next to the Export button. The valid formats are: XMLSpy/Authentic, and Plain XML. Click Export. A dialog box displays asking if you want to open the file or save it to a disk. Specify that you want to save the file to a disk. Specify the pathname of where you want to save the file. Launch your XML editor and edit the file. To import the "index.cnxml" file back into Connexions, use the instructions for Import Content from Outside Connexions mentioned earlier in this module.

Edit the index.cnxml file with the Edit-In-Place Editor The Edit-In-Place editor is the default editor on the "Edit" tab. You can insert new text and media objects into a module or modify the existing contents of a module with this editor. You do not have to be familiar with the CMXML tags to use Edit-In-Place. It inserts the appropriate CNXML tags for you when you insert a new item in the file. In addition, it has a help feature that describes the CNXML tags for the items you insert or edit with it.

Inserting Content in an Empty Module To insert text and media objects into a new module that contains no content, use the following steps: Click in the white box that says "Click To Edit Paragraph" in the Edit-In-Place editor.

The white box is replaced by a blue editing box. Type the text you want to add in the blue editing box.

Click Save to save the text you typed. The blue editing box is replaced by a white box that displays your entry.

Editing Existing Content with Edit-In-Place To edit the content of a module, use the following steps: Display the module you want to edit with Edit-In-Place. Scroll down to display the white text box that contains the item you want to edit. Click in the text box. The white box is replaced by a blue editing box that displays the text of the element.

Make the necessary changes to the item. Click Save to save the entry or click Cancel to clear the entry in the blue editing box. Repeat steps 2 through 5 for any item you want to edit. In the white text boxes mathematical equations are displayed as they appear in the module. In the blue editing box mathematical equations are displayed in the MathML markup language. Edit equations by making changes to the MathML.

Adding Content Items with Edit-In-Place You can add new content items to a module with Edit-In-Place. The types of items you can add are: sections, paragraphs, examples, exercises, notes, lists, code blocks, equations, and tables. Edit-In-Place places the opening and closing CNXML tags around the item and it generates a unique item ID for each item you add. To add new items, use the following steps: Display the module you want to edit with Edit-In-Place. Scroll down to display the location in the module in which you want to insert the content item. You can insert the new item above or below and existing item by using the Insert... link above or below the existing item Select and click the type of item you want to enter from the drop-down list next to the Insert... link. These items are described in the help text, which can be accessed by selecting "Other Elements" from the drop-down list. An empty blue editing box displays for the item you selected. You can display help text for the item you selected by clicking Help editing xxx in the upper right corner of the blue box, where xxx is the CNXML tag for the item you selected. Type the text that is appropriate for the type of item in the blue editing box. Click Save to save the entry or click Cancel to clear the entry in the blue editing box. Repeat steps 2 through 6 for each new content item you want to add to the module.

Edit the "index.cnxml" File with the Full Source Editor You can edit the content and CNXML tags in the "index.cnxml" file within Connexions with the Full Source editor. This method of editing is recommended for quick changes only. This is a simple text editor and it does not have the advanced functions (for example, spell checking and text searching) that are available with commercially available text editors. To edit the file with the Full Source editor, use the following steps: Click Switch to Editing Full Source on the "Edit" tab. The contents of the "index.cnxml" file are displayed in the Full Source editor mode.

Scroll down to display the location in the module in which you want to edit. Click in the text window and begin editing. Click Save to save to save your changes. As you edit the "index.cnxml" file, click Save at any point to save your changes. The page reloads and validates your CNXML markups every time you save your changes. If there are no CNXML tag errors, your markup is valid and "Saved" appears in an information box at the top of the tab. If there are errors in your CNXML markup, they are listed above the file content. Saving and publishing are two different operations. When you save your editing changes in the Full Source editor, your changes are saved in your work area; they are not entered into the Connexions repository. Your module must be published to be entered into the repository and be accessible by visitors to Connexions. For information about publishing, see the topic Publishing the Module later in this module.

Validating Your Work in the Full Source Editor Any "index.cnxml" file that you publish in the Connexions repository must be a valid CNXML document. This means that the file must be well formed and contain no CNXML errors. If it does contain errors, a description of each error appears when you click Save. Your changes are not saved until the errors are corrected.

A description of the errors appears in the information box that appears above the content. You cannot publish the module in Connexions until all the CNXML errors are corrected and the "index.cnxml" file is validated.

Adding Associated Files to a Module In addition to the "index.cnxml" file, a module can contain other files (such as images and supplemental downloads) that are associated with the module. You can add these files from the "Files" tab. The file must exist before you add them to the module. When you add these items, you create an instance of the item in Connexions.

File Guidelines Before you add an associated file to a module, please note the following guidelines for files and filenames: The size of a file must be smaller than 50 MB. The first character in a filename cannot be a digit. For example, a file named "1965mustangphoto.gif" would result in an error. Renaming the file to "photo1965mustang.gif" prevents the error. A filename cannot contain an embedded blank space. For example, the file named "eiffel tower.png" would cause an error. Renaming the file to "eiffel_tower.png" or "eiffeltower.png" prevents the error. Use only alphanumeric, "." (dot), "-" (hyphen), and "_" (underscore) characters in a filename. Multimedia files must have a recognized MIME (Multipurpose Internet Mail Extension) type.

Adding a File to a Module To add a file to a module, use the following steps: From the Files page, click the Add New File button. A new page will load. Click Browse. The "File Upload" dialog box displays. Locate the appropriate file and click on its filename. Click Open. The file path appears in the text box next to Browse. Click Save to upload the file into Connexions. A confirmation message will display, along with a preview if the file is an image.

Renaming, Cutting, Copying, and Removing Items in a Module You can rename, cut, copy, or remove any item that you add to a module. These operations are done at the module level in the same way as they are done at the work area level. See Removing Items from a Work Area, Renaming Items in a Work Area, and Cutting or Copying Items in a Work Area, for a description of how to do these operations in work areas. You should not rename, cut, copy, or paste the "index.cnxml" file.

Editing Metadata To enable users to search the Connexions Content Commons for a module, Connexions must have some information on the module. It is very important that you insert metadata into the module.

To insert metadata, use the following steps: Click the "Metadata" tab to display it. Type the name you want to give the module in the "Title" field. This name will appear wherever the module title appears in Connexions. Select the primary language of the module in the "Language" dropdown menu. You may also specify a regional variant of the language by clicking the checkbox next to "Choose a regional variant" and then selecting the appropriate item. Click on the boxes corresponding to the subject matter of the module under the "Subject" heading. You may select more than one subject. Type the topic related terms that a user may use in a search for the module in the "Keywords" field. Enter each term on a separate line. Type a brief description of the module topic in the "Summary" field. You may markup the summary with inline CNXML. Do not repeat the title of the module in the summary. The summary displays under the title in the module and restating the module title in the abstract is redundant. Click Save. A message that the metadata was updated displays.

Editing Module Roles As creator of a module, by default you hold all three roles: author, maintainer, and copyright holder. Authors receive credit for writing the material. The author is the person who is responsible for the creation of the work, but may or may not be the person who actually enters the work into the Connexions. Any module work must have at least one person with an author role before it can be published in Connexions. Maintainers are able to edit and publish successive versions of a module. Most authors will serve as maintainers for their materials, but some may choose not to. Authors may appoint additional maintainers to assist them in updating the materials. Copyright Holders have the legal right to license the materials. In most cases, the copyright holder is the same person as the author, but this may not be the case in institutions where faculty and employees are required to sign over copyright to the institution. In this case the institution serves as copyright holder and the individual retains the author and/or maintainer roles. Additionally, there are two other roles that Connexions offers for special content types. These roles are not granted permission to publish content. Editors receive credit for editing a module or collection. Editing duties may include checking the material for accuracy, grammar, spelling, organization, and so on. Unlike authors, editors do not take credit for the ideas behind the content, but rather for its organization and presentation. Editors do not have rights to publish materials in Connexions, so editors who are also responsible for keeping modules or collections up-to-date must be assigned the maintainer role in order to publish new versions of the content. Editors are listed under the "More about this content" link that appears at the end of the module. Translators have taken existing Connexions content and translated it from one language into another. Translators are listed next to the authors' names in the content headers. As with editors, translators do not have permission to publish or update modules, so translators with publication responsibilities should also be assigned as maintainers for the content. You can grant one or more roles to other Connexions account holders who you want to collaborate with you on the module. The "Roles" tab has a search feature for locating these people. The current collaborators on the module are listed by role under the heading "Current Roles" on the "Roles" tab. You can change the roles assigned to these people by selecting or deselecting the check boxes in the "Authors", "Maintainers", "Copyright Holders", "Editors" and "Translators" columns under the heading "Change Roles". The following paragraphs describe how to grant or update roles.

When you grant or update roles for a collaborator in a module in a workgroup, these changes do not take affect until that person accepts the role change and you publish the module. The prospective collaborator must accept the role because Connexions provides its account holders with the ability to accept or reject a role in another person's module. If there are any pending roles (roles not yet accepted or rejected) for a module, Connexions will not let you publish that module. Once the collaborator accepts the role or updated role, you must publish the module for Connexions to recognize the collaborator. Connexions looks to the information in a published module to see who is an author, maintainer, copyright holder, editor, or translator for the module. All pending role additions or changes must be accepted or rejected by the prospective authors, maintainers, and copyright holders before you can publish a module in Connexions. And you must publish a module with the new roles before Connexions will recognize the new roles.

Granting Roles to Someone Outside of Your Workgroup To grant one or more roles in a module to a Connexions account holder outside of the current workgroup, use the following steps: Click the "Roles" tab to display it. Type the first or last name of the person you want to grant a role to in the text box next to Search. Click Search. The Connexions accounts are searched and any Connexions accounts that match the search string are displayed. Select the check boxes for the appropriate roles next to the name of the person you want to add and click Add People. The name of the new collaborator appears with the names of authors, maintainers, and copyright holders under the "Current Roles" heading and in the table under the "Change Roles" heading. In both places, the new collaborator is noted as a role change that is pending acceptance. Look at the table under the "Change Roles" heading and verify that the check boxes in the "Author", "Maintainer", "Copyright Holder", "Editor", and "Translator" columns are checked for the roles you want to grant to the new collaborator. If necessary, you can click the check boxes to change which roles will be granted. Click Submit Changes. The next time the new collaborator logs into Connexions, he or she will be notified of a pending role request. Connexions will not apply the roles to the new collaborator until he or she accepts the role request.

Granting Roles to a Member of Your Workgroup To grant one or more roles in a module to a member of your current workgroup, use the following steps: Click the "Roles" tab to display it. Click the "Select from members of your current workgroup" link. A table that lists all the members of the current workgroup appears under the link. Locate the name of the person or persons in the table that you want to grant roles to and click the check boxes in the Authors, Maintainers, and Copyright Holders columns to select the roles for that person. Click Add People. The name of the newly added collaborator appears with the names of authors, maintainers, copyright holders, editors, or translators under the "Current Roles" heading and in the table under the "Change Roles" heading. In both places, the new collaborator is noted as a role change that is pending acceptance. A notification of a pending role request will display to the collaborator upon his or her next login to Connexions. Connexions will not apply the roles to the new collaborator until he or she accepts the role request.

Changing the Order of Appearance for Author Names To change the order in which the authors' names will appear on the module, use the following steps: Click the "Roles" tab to display it. Verify that all users who should have an author role on the module are listed in the "Change Roles" table. Select or deselect the check boxes in the "Adjust Roles" columns to make any necessary additions or changes to the module roles. Click Submit Changes to save the role changes. The next step will erase any role changes that you have not saved with the Submit Changes button. Click the up or down arrows in the "Order" column to move an author up or down in the order of appearance in the module. The single arrows move the name up or down one place. The double arrows move the name to the top or bottom of the list. To have an author's name appear first in the module, his or her name must be at the top of the "Change Roles" table. The second name from the top of the table will appear as the second name in the list of authors, and so on.

Changing Role Assignments To change the roles in a module that were previously granted to a user, use the following steps: Click the "Roles" tab to display it. Locate the name of the person or persons in the "Change Roles" table of which you want to change roles. Click on a check box that contains a check mark to remove the check mark and to remove that role from the person. Click on an empty check box to make a check mark appear and to grant that role to the person. Click Submit Changes. The "Change Roles" table is updated to show the role changes and to note the role changes that are pending acceptance. A notification of a pending role change request will display to the collaborator upon his or her next login to Connexions. Connexions will not apply the roles to the new collaborator until he or she accepts the role request.

Removing a Collaborator To remove a collaborator from a module, use the following steps: Click the "Roles" tab to display it. Locate the name of the person or persons in the "Change Roles" table of which you want to remove. Click on the check box in the "Remove User" column for the collaborator you want to remove. Click Submit Changes. The "Change Roles" table is updated with the removed collaborator not appearing on the list of users with roles. A notification of a pending role request will display to the collaborator upon his or her next login to Connexions. Connexions will not remove the collaborator until he or she accepts the role removal request.

Viewing and Processing Pending Role Requests Connexions makes it easy to collaborate on educational materials. One way to do this is to share authorship or maintenance of a module or collection. If another author has granted you a role in their module or collection so that you can collaborate with them, the "Pending" sidebar will appear in the upper right corner of your Connexions pages.

Click the Role Request link to display the "Collaboration Requests" screen. From this screen you can view and act upon: Requests awaiting your approval Requests you have made awaiting others' acceptance Completed requests

Requests Awaiting Your Approval If another Connexions author grants you a role on their module or collection as an author, maintainer, copyright holder, editor, and/or translator an entry appears under the 'Requests Awaiting Your Approval' section of the "Collaboration Requests" screen. To accept the request select the check box in the table for the request you wish to accept and click Accept. To reject the request, select the check box in the table for the request you wish to reject, and click Reject. If you have been requested to be added to a module or collection as a copyright holder, you must select the check box indicating that you agree to the license which has been selected for that module before you can accept the request. A link to the license is provided in the "License" column of the table.

Requests You Have Made If you have requested that someone be added to one of your modules or collections as an author, maintainer, and/or copyright holder, an entry appears under the "Requests You Have Made" section of the "Collaboration Requests" screen until the other author acts on it. You can cancel pending requests from here.

Completed Requests Any requests you have made that were accepted or rejected are listed in the "Requests You Have Made -- Completed" section of the "Collaboration Requests" screen. When you no longer need to keep the record, you can delete it.

Adding Featured Links to a Module To add or edit links that are associated with a module, click on the "Links" tab on the editing interface. The "Edit Featured Links" screen displays.

From the "Links" tab you can: Add new links Edit existing links Delete a link These links are viewable in the "Links" tab that displays with each module. The featured links appear under their specified category type, for example, the supplemental links are listed under the "Supplemental" heading.

Adding New Links To add a new link to a module, use the following steps: Type the label for the link in the "Name" field (required). Click on the down arrow next to the "Link Type" field and select the type of link from the drop-down list. Click on the down arrow next to the "Link Strength" field and select a number from the drop-down list for the strength of the link. 5 is the strongest link. Identify the target of the link by typing in a module ID in the "Module ID" field or typing a URL in the "Link URL" field. You can optionally specify a version if you entered a module ID. Click Add to add the link.

Editing Existing Links If the module already contains links, they will appear in the top half of the screen. To edit an existing link, use the following steps: Update the contents of the "Name" field to change the label of the link. Click on the down arrow next to the "Link Type" field and select another type of link from the drop-down list. Click on the down arrow next to the "Link Strength" field and select another number from the drop-down list for the strength of the link. 5 is the strongest link. Update the contents of the "URL" field to change the URL of the link. Click Update Links to make your changes.

Deleting a Link To delete an existing link, select the checkbox in the "Delete" column in the list of existing links. Then click Update Links to delete the link.

Previewing the Module After editing the module, you should preview the module to verify that it appears as you want it to appear. You can view modules from the "Preview" tab in the following ways: Preview the module on-line Preview the module in a print version (PDF file) View the change summary View the markup source for the module

Previewing Modules On-Line To view a module on-line, use the following steps: Click on the "Preview" tab. The "Preview" screen displays. Click the Online Preview link. This displays an on-line version of the module that is similar to the on-line display of the published module. The difference between the preview and the published versions is that the preview does not contain the links and tabs at the beginning and the links at the end of the module. Review the module content and verify that it appears as you intended it to display. Use your browser's "Back" function to return to the "Preview" screen.

Previewing a Print Version of the Module The print version of a module is formatted differently than the on-line version. This difference is necessary because of the differences in the on-line and printed media. To view a print version of the module, use the following steps: Click on the "Preview" tab. The "Preview" screen displays. Click the Print Preview link. An "Opening index.pdf" dialog box appears. Verify that the option to open the file with a PDF viewing application is selected and click OK. The print version of the module displays. Review the module display and verify that text and figures display as you intended them to display. You can print this PDF file using your PDF viewer's file/print option. Close the PDF viewing application.

Viewing Change Summary When editing an existing module, you can view a summary of the differences between the last published version of the module and the version you are currently editing. Click the Changes link to view the change summary. This option is useful when you checked out a module some time ago and do not remember what changes you made to it.

The "Change To" summary lists changes to the module, including role assignments and the names of any files that were changed, files that were added, and files that were removed. Click on a file name to display a brief description of the changes.

Previewing the code source Occasionally it may be convenient to view the markup source for a module. To view the source of the module, click the Source link under the "View" heading in the "Module Status" sidebar. The most recent markup source that has been saved displays. This feature is useful when you are trying to find a markup error.

Discarding Your Changes The situation may arise in which you wish to return a module that you are editing back to its original state: the state in which it was before you began editing it. To do this, click the Discard link under the "Actions" heading in the "Module Status" sidebar. The module will revert back to the state it was in when you checked it out. If the module is new and has never been published, you will lose all the content you entered and the module will be blank.

Publishing the Module To make your module or your changes to an existing module viewable by anyone on the Internet, you must publish the module in Connexions. To publish a module, use the following steps: Click on the "Publish" tab. The "Publish Module" screen displays. This screen contains a list of reminders for you to check before you publish the module. Type a brief description of your work on the module in the "Description of Changes" text box. Click Publish. Your work on the module is entered into the Connexions Content Commons. Once in the Content Commons, anyone with Internet access can view the module.

A new module would not necessarily have editing changes, so in the "Description of Changes" text box you might enter a comment like, "Created a new module". The act of publishing a module is different from clicking on the Save button in an editing session. When you save your changes, only you and the people who have access to your workgoup can see your changes. When you publish a module, the entire world can view your work on the Internet.