10 Working With Native Documents

In addition to using Contributor to create and edit web pages, you can use your own third-party application to create and edit native documents (for example, Microsoft Word). Site Studio converts these documents into web pages that seamlessly appear on the Web site with other web pages.

The following sections describe the use of native documents on a Site Studio Web site in more detail:

10.1 About Native Documents

A native document is a document created in a third-party application, like Microsoft Word, Excel, or PowerPoint. The document is intended to be viewed and edited in the application that was used to create it (its "native application"). It is not usually viewable as a web page.

Site Studio Contributor assigns the native document to a contribution region just like it does a contributor data file. However, whereas a contributor data file can be viewed instantly on a web page (because it is written in XML), a native document must be converted into HTML and then pulled into the web page.

Site Studio uses a conversion engine (Dynamic Converter) to convert the document into a web-viewable rendition. As such, any rules or templates set up in Dynamic Converter are automatically applied on the Site Studio Web site.

There are several reasons why you may want to use native documents on your site. For one, you can add documents that you may be using for another purpose in your organization. For example, you could add a policy document from your HR department or a product specification from your development department and make those documents part of the Web site without having to create two versions of the documents.

You may also be familiar with a certain application, like Microsoft Word, and prefer to edit the contents of your site in that application. When you have finished, you simply save and close the document. The document is converted into HTML and appears on the site right away.

10.2 Requirements for Native Documents

In order to use native documents on a Site Studio Web site, the content server must have Dynamic Converter configured and running. Your site designer or site manager should have completed these steps for you.

Native documents also must be checked in with the appropriate metadata assigned to them so that they are recognized as part of the site. See "Metadata for Native Documents" for more information. Your system administrator may also be able to provide assistance.

10.3 Metadata for Native Documents

With native documents, you often have control over the metadata that is assigned to them when you check them in (unlike contributor data files, which often are assigned metadata by Site Studio Contributor). This is especially true if you use the check-in page on the content server or the Desktop Integration Suite client to add native documents to the site (see "Checking In Native Documents Using Content Server").

The metadata values are particularly important in case your site is ever moved, backed up, published, or used to generate reports. These values are what tell Site Studio that the document belongs to the site.

Metadata Field Definition
Web Sites Identifies the Site Studio Web sites in the content server.
Web Site Section Identifies a Site Studio Web site section in the content server.
Web Site Object Type Identifies a type of file on a Site Studio Web site.

Choose Native Document as the Website Object Type when checking in native documents.


Please note the following:

  • In addition to the above metadata, you may need to enter custom metadata values that are required for your document to appear in a dynamic list on the Web site. Contact your site designer or site manager for details.

  • If you use the features in Site Studio Contributor to add a native document to a Web site, all of these metadata values are automatically assigned to the document for you. If you use another method to check in native documents (for example, the Content Server check-in page or the Desktop Integration Suite client), then you must ensure that this metadata gets assigned to the document. For more information, see "Adding Native Documents to a Web Site".

  • To update the "Web Sites" and "Web Site Section" metadata for a native document, you can open the content information update page for the native document on the content server, click Browse beside one of those metadata values, and select the appropriate Web site or Web site section.

10.4 Adding Native Documents to a Web Site

There are several ways to add native documents to a Site Studio Web site. You can choose the method you are most comfortable with. This section describes some ways that you can add native documents to a Web site. Your site may be different, however, and you may be adding native documents in an entirely different way (depending on how the designer set up the site).

This section covers the following topics:

10.4.1 Assigning a Native Document to a Web Page

You can add a native document to a Web site by assigning it to a web page (more specifically, to a contribution region on the page). You do this using the contribution graphic just as you would when assigning a contributor data file to the page.

See "Assigning Content to a Contribution Region" for more information.

10.4.2 Adding a Native Document When Creating a Link

You can add a native document to a Web site by creating a hyperlink in Contributor that points to the native document. When you create a hyperlink in Contributor, you have the opportunity to both create the link and the file that the link points to (its target) at the same time.

See "Creating a Link to an Existing File on the Content Server" for more information.

10.4.3 Adding a Native Document to a Dynamic List

You can add a native document to a Web site by adding it to a dynamic list (that was set up on the site by the designer). The dynamic list performs a search in the content server and displays all of the files that match that search on a web page. As a result, you see a list of items on the page with a link to each one.

To add native documents to a dynamic list, you can check the document in using one of these methods:

10.4.4 Checking In Native Documents Using Content Server

While Site Studio Contributor includes the option to add new and existing native documents to your Web site (see "Adding Native Documents to a Web Site"), you may be more comfortable using one of the traditional methods in the content server to check in native documents. This includes the following:

  • Content Server check-in page

  • Desktop Integration Suite client

  • folders functionality on the content server

When checking in a document using one of these methods, however, you must ensure that the metadata for the native document matches the metadata used by the Web site and the dynamic list (see "Metadata for Native Documents").

Note:

See the Content Server user documentation for more information about checking items into the content server.

10.5 Opening and Editing Native Documents

After you add native documents to your Web site, you can then start opening and editing each one. Working on a native document on a Site Studio Web site is very similar to working on a native document in any other situation.

The main difference is that the document is stored on a Web site, and therefore the content server. For this reason you must open the document from that location, save it to that location, use styles a little differently (if you use styles), and create links a little differently.

You can open and edit native documents from a Site Studio Web site in the same way that you open and edit a contributor data file using Contributor. You can also use the content server and various add-on components to check out and edit native documents.

Opening and Editing a Native Document Using Site Studio Contributor

When you follow these steps, instead of Contributor opening, the native document opens in the application used to originally create the file (for example, a .doc file opens in Microsoft Word). When you check out documents this way, each time you save the document, a revision is created in the content server. When you close the document, it is checked into the content server.

Opening and Editing Native Documents Using Content Server

In addition to using the available features in Site Studio Contributor, you can use the Content Server interface and various add-ons (Desktop Integration Suite, folders functionality, and so on) to open and edit native documents.

To do so, simply follow the typical steps outlined in those products to check out, open, and check in a content item; in this case, a native document (see "Checking In Native Documents Using Content Server"). You must search for the native document in the content server rather browse the site as you normally would when using Site Studio Contributor features.

Important:

When you use the content server to browse a Site Studio Web site, you may discover files that you are not familiar with, such as those with a .xml, .hcsp, .js, or .css extension. These files are used by the Web site and should not be edited by contributors. You typically edit only those files with known extensions, such as .doc (Microsoft Word), .xls (Microsoft Excel), and .ppt (Microsoft PowerPoint).

10.6 Using Styles in Native Documents

With native documents, you have tremendous freedom regarding how you format and edit the content in the document. This can be both good and bad. You can edit the native document without limitations. However, if you introduce a new typeface or font size, increase the line spacing, and so on, the resulting web page looks different from the other web pages on the Web site.

Therefore, the designer of your site may have set up style names that are mapped to HTML tags when the document gets converted into a web page. (These mappings are actually stored in the Dynamic Converter template that is used to convert the document.)

Instead of manually formatting the content in your document, you would apply a style to it.

Figure 10-1 Styles Menu in Microsoft Word 2003

Styles menu in Microsoft Word.
Description of "Figure 10-1 Styles Menu in Microsoft Word 2003"

For example, styles for "Title," "Body," and "Footer" may be mapped to corresponding tags in HTML or in a customized cascading style sheet. You must coordinate with your site designer or site manager to see whether such styles are in place and how you should be using them.

10.7 Creating Hyperlinks in Native Documents

One task you perform as you work in a native document is creating hyperlinks. The hyperlink may point to another Web site, to another section on your site, to another web page on your site, and so on.

Creating a hyperlink in a native document is different from creating a hyperlink in Contributor. In Contributor, you use the Link wizard, which walks you through the process of creating a hyperlink and introduces you to the different types of links that you can create (see "Link Wizard").

In a native document, you use the method available in the application that is associated with that document to create a link. For example, in Microsoft Word 2003, you click Insert, then select Hyperlink, enter the address to link to, and click OK. The process may vary from one program to another. Therefore, this section does not explain how to create a link in a native document, but, rather, what to put in as a value for the link (which, in your application, may be referred to as the link address, URL, or target file).

There are three ways to create a link to another part of your Web site:

10.7.1 Using a Path-Based URL for the Link

A path-based URL is a simple way to read a web address. You usually have a domain name (mywebsite.com), followed by a slash (/), the name of a section (news), and possibly a file name (news1.htm).

To use a path-based URL, perform these tasks:

  1. Open a web browser, and browse to the location on your Web site where you want your link to go.

  2. In the web browser's address bar, copy the address that displays there (for example, "http://www.mywebsite.com/news/").

Figure 10-2 Address Bar in Web Browser

Address bar in web browser with a Site Studio URL.
Description of "Figure 10-2 Address Bar in Web Browser"

  1. Paste this address into the hyperlink in your native document (see Figure 10-3 for an example in Microsoft Word 2003).

Figure 10-3 URL-Based Link Target in Microsoft Word

Hyperlink in a Word document with a Site Studio URL.
Description of "Figure 10-3 URL-Based Link Target in Microsoft Word"

  1. Close the hyperlink feature and save your document.

You can also use relative paths instead of the full path in your hyperlinks (for example "../products/myfile"). Keep in mind, however, that if you reuse the native document on another part of the site, the link does not work there. (This is because the relative path changes depending on where a document is located.)

If you want to create a link to a file and you know the file's content ID and the section where it is stored, you can predict its web address without going to the site. Simply enter the Web site address (for example, "http://www.mywebsite.com"), followed by a slash (/), followed by the section (for example, "News"), followed by a slash (/), and then the content ID (for example, "NewsID"). The complete address would be:

http://www.mywebsite.com/news/NewsID

10.7.2 Using a Site Studio Contributor Token for the Link

As an alternative to path-based URLs, you can use a special token called "ssLINK" provided by Site Studio. The token makes it simple to create a link to another document without having to know the details of the Web site or where the document is stored. The token resolves to an actual web address when the page is served up in a web browser.

To use a Site Studio Contributor token, perform these tasks:

  1. Open the hyperlink in the native document.

  2. Enter the text ssLINK followed by a slash (/) and the content ID of the document. Thus, for a document with the content ID "MyDoc1," enter:

    ssLINK/MyDoc1
    

Figure 10-4 Token-Based Link Target in Microsoft Word

Site Studio token in a hyperlink address target.
Description of "Figure 10-4 Token-Based Link Target in Microsoft Word"

  1. Close the hyperlink feature and save your document.

When you create a link this way, the document displays in the section of the Web site defined by the xWebSiteSection metadata field of the document. If you want to change this so that the document appears in a section of your choosing, you could append the ID of the desired section to the ssLINK token, followed by the content ID of the document.

Say you want to create a link to a document with the content ID "MyDoc1" which you want it to appear in the section containing the ID "23." In that event, you would use:

ssLINK/23/MyDoc1

To create a link to another section of your site, you can also use the "ssNODELINK" token. To use this, you must know the ID of the section you want to link to. For example, to create a link to a section containing the ID "23," you would use:

ssNODELINK/23

To identify the ID of a section or Web site, open the content check-in page on the content server and click Browse next to "Web Site Section." In the Choose Web Site Section window, select your Web site and note the ID in parentheses next to each section (Figure 10-5).

Figure 10-5 Section or Web Site ID

Dialog to choose a web site section from a list.
Description of "Figure 10-5 Section or Web Site ID"

10.7.3 Using Client-Side JavaScript for the Link

As an alternative to path-based URLs and Site Studio Contributor tokens, you can use client-side JavaScript to form the link. While this option may not be the simplest or most intuitive, it makes your links compatible with previous versions of Site Studio Contributor and the Web sites created in those versions. (Contact your site designer or site manager for more information.)

To use client-side JavaScript, perform these tasks:

  1. Open the hyperlink in the native document.

  2. Enter the text javascript:link followed by an opening parenthesis, a single quote, the content ID of the document, a single quote, a closing parenthesis, and semicolon (this is JavaScript syntax). Thus, for a document with the content ID "MyDoc1," enter:

    javascript:link('MyDoc1');
    

Figure 10-6 JavaScript-Based Link Target in Microsoft Word

JavaScript entry in the address field of a hyperlink.
Description of "Figure 10-6 JavaScript-Based Link Target in Microsoft Word"

  1. Close the hyperlink feature and save your document.

When you create a link this way, the document displays in the section of the Web site where it is stored. If you want to change this and have the document appear in a section of your choosing, then you would append the ID of the desired section to the content ID of the native document. Say you want to create a link to a document with the content ID "MyDoc1" to appear in the section containing the ID "23." In that event, you would use:

javascript:link('MyDoc1','23');

To create a link to another section of your site, you can also use the syntax "javascript:nodelink." To use this, you must know the ID of the section you want to link to. If you were linking to a section containing the ID "23," you would use:

javascript:nodelink('23');

To identify the ID of a section or Web site, open the content check-in page on the content server and click Browse next to "Web Site Section." In the Choose Web Site Section window, select your Web site and note the ID in parentheses next to each section.