Using the Authoring Connector

Content authors use the Authoring Connector to submit their content from Word XP. An entire document or a selected part of a document can be submitted. Content authors can create a new page, update an existing page originally created by using the Authoring Connector, or replace an existing page.

Creating a New Page

The process of creating a new page using the Authoring Connector consists of several steps:

• If you would like to submit part of a Word document, select the content as required. If you are submitting an entire document, don't make any selection.

• Change the URL pointing to the OC.aspx file if you are publishing to a different server or using a different file location.

• Choose a channel where the new page will be published, and a template on which it will be based. These parameters can either be chosen as a publishing task or be specified manually.

• Set up the page properties.

• Preview the page and confirm your choices.

The first step is to select in the Word document the content to be published; alternatively, the entire document will be published. Then, choose the File > Send to MCMS > Create New Page menu option. If the document has not been saved, you will be prompted to save it (Figure 7-6); click Yes. The Authoring Connector Wizard is then launched. If a selection has been made in Word, the Authoring Connector prompts you to choose whether to publish the selection or the whole document, as shown in Figure 7-7. If no selection has been made, the text in the middle section of the Welcome screen is not displayed (Figure 7-8).

Figure 7-6. Word XP prompt before the wizard is launched

Figure 7-7. Authoring Connector Wizard Welcome screen, selected text being submitted

Figure 7-8. Authoring Connector Wizard Welcome screen, entire document being submitted

From this screen you can change the URL for the OC.aspx if required. Once the OC.aspx location is set up for a document, it is saved to the CmsServerUrl property in the Word document when the wizard has completed. It does not need to be set up again if there have been no changes. It also becomes the default for any other Word document opened on a client machine that does not already have the CmsServerUrl property defined. In addition, any Word template based on the document with this property will pick up the OC.aspx location. To change the location, select the "Change server name and path" check box and click Next; then specify the new URL (Figure 7-9) and click Next.

Figure 7-9. Change the default server and location dialog

The wizard can only be accessed by users who have authoring rights in at least one of the channels on the CMS site. If the current user does not have sufficient permissions on the CMS server, an additional login dialog will be displayed (Figure 7-10).

Figure 7-10. Login dialog

Then, a Publishing Task dialog is displayed, as shown in Figure 7-11. This dialog presents a list of publishing tasks from which an author can choose. Publishing tasks are preconfigured by an administrator. Each publishing task is listed by name. This name is an alias for a combination of three parameters, as follows:

• A short description of the task, which is displayed in the dialog when the task has been selected

• A template on which a new page will be based

• A channel where a new page will be published

Figure 7-11. Publishing Task dialog

When content is created using the Web Author, the content author needs to navigate to a channel where the new page will be submitted, select a template on which the new page will be based, and then enter the content into the placeholders. In the Authoring Connector, using publishing tasks allows administrators to preconfigure the channel and the template. Therefore, an author does not require any additional knowledge of the CMS site structure: The document content is uploaded into the preconfigured template and stored in the preconfigured channel based on the parameters defined by a publishing task.

The author only needs to create the document and choose a task; the task guarantees that the appropriate template is selected and the content is submitted for publishing in the appropriate channel, thus reducing the probability of a user error.

The author rights on channels and templates determine which tasks are displayed. Only tasks that contain channels and templates to which the current user has rights are shown. For example, if an author only has access to one channel, then only the tasks related to that channel will be displayed, provided the author has rights to the templates used in these tasks.

The Authoring Connector also provides the ability for an author to override the publishing tasks and manually enter a channel and a template. To achieve this, check the "Manual entry of channel and template" box if it is enabled, and click Next. In the Channel Information dialog, navigate to the required channel, or type the full path from the root channel Channels, as shown in Figure 7-12, and click Next. In the Template Information dialog, navigate to the required template, or type the full path from the root template gallery Templates, as shown in Figure 7-13.

Figure 7-12. Channel Information dialog

Figure 7-13. Template Information dialog

NOTE: The template path is based on the template gallery hierarchy and not the physical location of the template file.

Regardless of whether the template is specified by a publishing task or manually, the Authoring Connector does not provide the ability to target placeholders within the template. The content is inserted into a page depending on the type and number of placeholders defined within a template, as follows:

• If there are one or more OfficeHtmlPlaceholders within the template, the content is inserted into all of them as inline content to be displayed within a page. For instance, if there are two OfficeHtmlPlaceholders within a template, the content will be inserted into both of them. The content can be either the entire document or a selected part of the document. The properties of each of the OfficeHtmlPlaceholders define what content will be published and how.

  For example, if images are not allowed for a particular OfficeHtmlPlaceholder, then only text from the Word document will be inserted into this placeholder and displayed on a page; all images will be filtered out. If the same template has another OfficeHtmlPlaceholder that allows images but no text, then only images from the Word document will be inserted into this placeholder; the text will be filtered out.

• If there are one or more OfficeAttachmentPlaceholders within the template, the entire source document is inserted into all of them as a file attachment; the link to the document is displayed within a page. Regardless of whether part of the document has been selected or not, the entire document will be inserted as an attachment. For example, if there are two OfficeAttachmentPlaceholders within a template, the source document will be inserted into both of them as an attachment in exactly the same way.

  If there are one or more OfficeHtmlPlaceholders and OfficeAttachmentPlaceholders defined within the template, the inline content is inserted into all OfficeHtmlPlaceholders, and the source document is inserted as an attachment into all OfficeAttachmentPlaceholders.

• If there are no OfficeHtmlPlaceholders in the template, the content will be inserted into the first HtmlPlaceholder defined within a template for inline publishing. If there are no OfficeHtmlPlaceholders and no HtmlPlaceholders within a template, no inline content will be published on the page.

• If there are no OfficeAttachmentPlaceholders in the template, the document will be inserted as an attachment into the first AttachmentPlaceholder defined within a template. If there are no OfficeAttachmentPlaceholders and no AttachmentPlaceholders within a template, the source document is not inserted as an attachment into the page.

NOTE: The formatting of text inserted into an OfficeHtmlPlaceholder depends on the properties of the placeholder, the original text formatting in Word, and the mapping of the styles definition within the template to styles in Word. We will look into preserving formatting later in this chapter.

The next step is to configure the page properties. First of all, the Authoring Connector displays a Page Information dialog, shown in Figure 7-14, which provides the ability to specify the page name, title, and description. The page name will be used as a part of a URL pointing to the new page. The title sets up the Display Name property as we know it in the Web Author. By default, the Authoring Connector displays the first 128 characters of the text as both the page name and title; this can be changed. The Page Description property allows the author to provide a meaningful description of the page; this property is optional and is limited to 256 characters in length.

Figure 7-14. Page Information dialog

Clicking Next displays a Publishing Dates and Times dialog, as shown in Figure 7-15; this dialog allows an author to specify the desired publishing schedule for the page. As we have seen in the previous chapter, this schedule can be changed by editors and moderators after the page has been submitted to the publishing workflow.

Figure 7-15. Publishing Dates and Times dialog

There is also an "Advanced page properties" check box, which allows the author to display the Advanced Page Properties dialog, shown in Figure 7-16. It provides the ability to set up the page attributes, as well as to specify values for custom properties for a page if they are defined in the template.

Figure 7-16. Advanced Page Properties dialog

The page attributes are the same settings as the page publishing properties presented in the Web Author, Page Properties dialog. However, be warned that the names for the settings in the Authoring Connector are very close but not exactly the same as in the Web Author, as follows:

• Mark page as special page: This setting is the same as Important Page in the Web Author; it is not selected by default.

• Allow Web robots to crawl links: This is the same as Web Robots Can Crawl Links in the Web Author; it is selected by default.

• Hide page from subscriber when published: This setting is the same as Hide When Published in the Web Author; it is not selected by default.

• Allow Web robots to index this page: This is the same as Web Robots Can Index This Page in the Web Author; it is selected by default.

Custom properties are defined by template designers and will therefore be displayed by the same names and provide the same default values in both the Authoring Connector and the Web Author. The author can change the values of the custom properties. If no custom properties are specified in the template, the "Custom properties" table is not displayed in the Advanced Page Properties dialog.

The final step of the wizard allows the author to preview the page, and provides a summary of the configuration in the Page Submission dialog, as shown in Figure 7-17.

Figure 7-17. Page Submission dialog

A Preview Page button displays the page in a default browser window; the author may be required to log on to the site.

The following items are presented in this screen for reviewing: page name; page display title, which is the same as the Display Name property in the Web Author; channel where the page will be published; and template on which the page will be based. To make changes to any of these items, click Back until you reach the dialog where you need to change the required information.

The Page Submission dialog also provides an indication of how the document content will be inserted into the resulting page: as inline text and images, as an attachment, or both. As we have already seen, these options are not controlled by the author; they are defined within the template by the type of the available placeholders.

Clicking Next in the Page Submission dialog submits the page for publication and then displays the final wizard dialog, shown in Figure 7-18. The final dialog allows you either to finish and go back to Word or to launch the Web Author. The status of the page displayed in the Web Author is WaitingforEditorApproval. In order for the page to become available on the live site, it should be approved for publishing by going through the workflow as configured on the channel where it is submitted.

Figure 7-18. Authoring Connector Wizard final dialog

As we have already mentioned, upon completion of the wizard two properties are added to the Word document: the CmsServerUrl property, which contains the URL pointing to the location of the OC.aspx file on the CMS server; and the CmsPostingGuid, which contains the GUID for the newly created posting (Figure 7-19).

Figure 7-19. Word XP document properties

It is worth mentioning that these two properties are available in the Word document regardless of where the document is located. You can copy the Word document or send it in an e-mail. Anyone editing the new copy of the document would be able to publish it to the proper location because of the CMS properties stored in the document.

Updating a Page

The CmsServerUrl and the CmsPostingGuid properties allow you to update a page that was previously created using Word and the Authoring Connector. In this case, you are not required to specify the channel and template by selecting a publishing task or manually. Instead, the wizard goes straight to the Page Information screen, which provides the ability to modify the page properties.

To update an existing page, in the Word document select the content you'd like to publish, if required, and then choose the File > Send to MCMS > Update Same Page menu option. If you have not yet saved your work, you will be prompted to do so.

After the Authoring Connector Wizard starts, it points to the OC.aspx location as defined in the CmsServerUrl property of the document; click Next.

NOTE: Whether you submit an entire Word document or a selected part, the submitted content will overwrite all of the inline content in the target page that originates from Word. If there is a Word attachment in the target page, it will be changed to the new version of the document.

In the Page Information dialog, change the page properties if necessary, and click Next; in the Publishing Dates and Times dialog, change the publishing schedule if required, and then click Next. In the Page Submission screen, review the page information, and preview the page by clicking Page Preview if desired. Clicking Next submits the page and displays the Completing the Authoring Connector Wizard page, where you can go back to Word or start the Web Author.

NOTE: If your page includes dynamic navigation, in the page preview you may see two postings listed under the same display name: the original one that you are replacing and the new one that you are submitting. This is only a temporary issue: After you've submitted the page, the original one will be replaced with the new one. If you look at the submitted page in the Web Author, only the new page will be displayed in dynamic navigation.

Replacing a Page

Replacing a page using the Authoring Connector allows you to change the content of any existing page, regardless of whether it was originally created from Word. In this case, the new page will be placed in the same channel and will be based on the same template as the original page. The wizard allows you to navigate to the page and then takes you straight to the Page Information dialog.

To replace an existing page, in the Word document select the content you'd like to publish, if required, and then choose the File > Send to MCMS > Replace Any Page menu option. If you have not yet saved your work, you are prompted to do so.

After the Authoring Connector Wizard starts, it points to the default OC.aspx location; you can change it if required and then click Next. The Authoring Connector Wizard displays the Page to Replace dialog, which allows you to select a page to be replaced (Figure 7-20). In the "Select page" area, expand Channels and navigate to the page to be replaced, or type the full path to the page in the "Web page path" box; then click Next.

Figure 7-20. Page to Replace dialog

NOTE: As before, the submitted content will overwrite all of the inline content in the target page that originates from Word. If there is a Word attachment in the target page, it will be changed to the new source document.

In the Page Information dialog, change the page properties if necessary you are allowed to change the page name and other properties then click Next. In the Publishing Dates and Times dialog, change the publishing schedule if required, and then click Next. In the Page Submission screen, review the page information and preview the page by clicking Page Preview if desired. As we have seen already, clicking Next submits the page and displays the Completing the Authoring Connector Wizard page, where you can go back to Word or start the Web Author.

NOTE: As before, if your page includes dynamic navigation, in the page preview you may see two postings listed under the same display name instead of the one you are submitting. However, in the Web Author, only the new page display name will be displayed in dynamic navigation.

Preserving Word Formatting and Styles

Content authors who are used to rich formatting in Word XP may expect the formatting of the content to be preserved in the resulting CMS pages when it is displayed inline. Although it is usually possible to set up the properties of the placeholders in the page templates and/or cascading style sheets to preserve formatting, it has to be pointed out that not all the content on a CMS page will be displayed exactly as it is shown in Word; this may be caused by additional user-defined settings in the client browser options and/or differences in the implementation of cascading style sheets in different browsers.

In Word, there are two types of formatting styles, as follows:

• Inline styles are formatting options stored inline together with the text to which they are applied. For example, font and color applied to the selected section of the document text using Word formatting options represent an inline style. The formatting options that define the style are wrapped around the content and therefore can be represented in HTML.

• Document styles are named formatting options stored in the header of the document; they can be applied and changed globally. For example, Heading 2 represents a document style. Authors can select document styles from the Word styles and formatting toolbar or a side bar. A reference to a style encapsulates the selected content. However, the style information in the document header is not carried over by the Authoring Connector; therefore, the intended formatting cannot be applied.

A template designer can allow inline styles by setting the Formatting property of an OfficeHtmlPlaceholder to Full Formatting. If other formatting is selected, inline styles may be partially or fully lost when the content is inserted in the placeholder.

Preserving document styles requires more work. A good technique for preserving the document styles is to have a corresponding external cascading style sheet attached to the template. This style sheet has to provide the style definitions for the named styles used within Word documents.

NOTE: It is also possible to define document styles in an embedded style sheet in the <head> section of a template. In this case, the styles will only be preserved within pages based on this particular template.

The name of the style is wrapped around the content published by the Authoring Connector; therefore, if the style is defined within a cascading style sheet, it will be applied within a page. This technique will work just fine for capturing document styles that are used widely within an organization for example, within corporate templates. However, if an author defines new document styles or updates existing ones in an existing Word document, the change will not be reflected on the site until the cascading style sheet is updated to reflect the changes.

To import a style definition from Word XP, in Word apply a particular style to the selected content, and save the document as Web page, filtered. Open the resulting .htm file in Notepad, go to the <head> section of the document, and locate the <style> container and the relevant style definition. Copy the style definition to an external cascading style sheet. If an embedded style sheet is used, copy the definition into the <style> container in the <head> section of an appropriate tempalte.

In some cases, template designers may be required to disable both document and inline styles. To achieve this, the template designers must set the Formatting property of OfficeHtmlPlaceholder must be set to NoFormatting. In this scenario, all style and formatting information will be stripped from the document content.