Edit a Module
Once you have created your module, your next step as an author will be to edit your content. While it is possible to upload existing documents using one of the importers, you will need to be able to make edits and updates to the resulting CNXML code without starting from scratch each time. Fortunately, there are two editors that allow you to create and edit content directly in your workspace:
- Edit-in-Place: A lightweight WYSIWYG (What You See Is What You Get) editor optimized for making minor edits, insertions, and deletions to your module.
- Full Source: A simple text editor that allows you to make changes directly to the raw CNXML source code.
While it is recommended that authors use Edit-in-Place whenever possible, there are some authoring tasks - such as reordering existing sections or paragraphs - which are much easier to complete using the Full Source editor. As a result, authors should be familiar with both editing options regardless of their preferred workflow.
Edit-In-Place is a convenient tool for making quick and easy changes to existing modules. Using Edit-In-Place, you can:
- Add or remove CNXML elements (e.g. paragraphs, lists, equations, exercises, etc.)
- Edit existing elements
- Preview existing documents
Note: An element is a single logical chunk of your document - for example, a paragraph, quotation, or emphasized text - that is defined by a pair of CNXML tags. Elements can be nested; for example, you can have an emphasis element exist inside of a paragraph element, which in turn might exist within a section element. For more information on the elements that make up CNXML and how to use them, please see the CNXML help page.
After you have successfully created your module, you will immediately be taken to the Edit-in-Place editor and presented with a blank document:
At this point you have two options: begin editing the module from scratch or import an existing document. For the sake of clarity this walkthrough will assume a blank document, but the same steps apply when making edits to an imported module.
You'll notice that this document currently contains a single blank paragraph (the white box). Clicking on this element will bring up an editor window that will allow you to add content:
If you look at the top of the blue-shaded area, you will see the beginning of a paragraph (
<para>) element, with the corresponding closing tag (
</emphasis>) following at the bottom of the editor. Edit-in-Place takes care of much of this type of CNXML overhead, allowing you to concentrate on the contents - rather than the structural details - of the module. You can use this editor to create content in this paragraph, either by typing and/or pasting plain text or by including valid CNXML markup (such as
<link>). When finished, click the "Save" button. If you have made any errors, you will have a chance to make corrections or cancel your edit; otherwise, your changes will be saved.
If you need more information about the CNXML language, clicking on the "Help editing <para>" link in the upper-right corner will open additional CNXML documentation in a pop-up window. This link is contextual; it will always take you to the help page for the element type you are currently editing (e.g. if you are editing a table, the link will display as "Help editing <table>" and direct you to the CNXML table help page). This documentation tool is very handy when authoring and is a great way to learn the language as you go.
Adding New Elements
There are two types of elements in CNXML: block and inline. Inline elements, such as
<link>, can be applied within an existing element as a way of marking up a specific piece of text (in this example, by adding emphasized formatting or a hyperlink, respectively). Block elements, on the other hand, provide structure for a document; examples of block-level elements include
You can use the Edit-in-Place editor to create additional block-level elements within your module using the
Insert ... drop-down menu:
Insert ... menu appears before and after every block-level element in the module. In cases where block elements are "nested" - for example, a
<para> inside of a
<section> - you will have also have the ability to create additional nested elements (e.g. a second paragraph within that section).
Note: Some block-elements, such as
<media>, are currently not fully supported by Edit-in-Place; in these cases you can create the element manually from within an empty
<para> element, or use the Full Source editor to create and edit that element.
Editing Existing Elements
After creating or importing elements, you can make changes to your module using Edit-in-Place. As an example, consider the following module:
To edit the contents of the paragraph shown above, simply click anywhere in the white box surrounding the paragraph text to open the paragraph editor:
Note:Instead of editing just one paragraph, you could also choose to edit the entire "What is XML?" section by clicking the "edit entire section" link. This would allow you to edit the same paragraph along with other section contents, giving you the ability to reorder contents or merge existing elements without entering the Full Source editor.
After making your edits you will need to save your changes by clicking on the Save button at the bottom of the blue-shaded box. The code will be checked to make sure that your CNXML is valid and, if it is, your changes will be saved. If you have errors in your code, you will receive an error message and have the opportunity to make the necessary corrections or Cancel your update. You can also choose to Delete the element entirely (this will permanently delete the element you are editing, so be careful when selecting this option!).
Once you have saved or discarded your edits, you will be returned to the main Edit-in-Place screen where you can move on to your next edit.
For most authors, the Edit-in-Place option will work for the majority of their needs. This is the recommended option because, in addition to allowing you to easily create and edit CNXML elements, the Edit-in-Place editor validates your CNXML markup before saving your changes, ensuring that you cannot save markup errors to your module.
There are certain tasks, however, where it will be necessary to go beyond the limitations and protections of the Edit-in-Place option. For these purposes, you have the option to use the Full Source editor.
To switch to the Full Source editor, simply click on the "Full-Source Editing" link at the top of the Edit-in-Place editor:
The Full Source editor gives you full control over the CNXML elements in the module, allowing you to make any edits you choose to both the content and the structure of the document. There are a few key points to keep in mind when working in the Full Source editor:
- Ignore the metadata. The first portion of all CNXML documents includes information about the document type as well as several read-only elements (such as the module title, author, and version number) that can only be changed from within the application. Any content above the first
<content>tag should be ignored, and any changes to this portion of the document will be ignored.
- You can save errors. Unlike the Edit-in-Place editor, the Full Source editor will allow you to save invalid CNXML code. Modules containing invalid markup cannot be published, and you will not be able to switch back to Edit-in-Place until the errors have been corrected.
- Save your work. The "Save" button is located at the very bottom of the Full Source editor. Don't forget to save your work after making changes, otherwise the most recent edits will be lost when you close your browser window or navigate away from the current page.
- Work on one thing at a time. Because it can be difficult to locate errors in the Full Source editor, it is best to work on one portion of your document at a time, saving after each edit. This way, if you do make a mistake, it will be easier to determine which area of the module is affected and what might have caused the error.
- Create a backup. If you plan on making several changes in the Full Source editor, you may wish to export your module as a backup or copy the contents of the text area to a document on your desktop. This way, should you find yourself in a position where you have made errors and cannot salvage your module, you have a way to go back to your most recent working version of the content.
You can return to the Edit-in-Place editor (assuming you do not have any errors in your CNXML markup) by clicking on the "Edit-in-Place" link at the top of the editor window.
Each module and collection editing area 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 Sidebars icon has been clicked, you can reduce the editing area and display the sidebars by clicking it again.
Click on the "Show/Hide Sidebars" icon...
...and the editing area fills the page. Click on the icon again to return to your normal view.
(Up to 'Authoring')