Understanding paths in Dreamweaver templates

Dreamweaver templates

When an HTML page is saved as a template, Dreamweaver creates a template folder at the root level of the local root folder and generates a .dwt file that becomes the source for all the pages that are applied to it. Every time a HTML page is applied to a template, (File > New from template or Modify > Template > Apply template to page) it creates a site root-relative link to the .dwt file. The reason why this site relative link will always link correctly is because the .dwt file will always be in the Templates folder at the root level of the site's folder structure. If the .dwt file is moved from the Templates folder, or if the Templates folder is moved or renamed, the link will be broken. It is very important to keep the .dwt file in the Templates folder where Dreamweaver creates it. To avoid confusion, it is good practice NOT to save other elements of your site (image source files or HTML documents) inside the Templates folder.

How are pages linked to the template files?

When a file is applied to an existing page or created new from a template, the following code is inserted in the source:

<!-- #BeginTemplate "/Templates/templateName.dwt" -->

To view the HTML source code that Dreamweaver generates, choose Window> HTML.

The path above replaces the normal HTML source that would appear on a new page. Instead of starting out with the usual tags that new file would generate, it is specifying that one level inside the local root folder, inside a folder called Templates, a .dwt file exists that contains all the information not inside the editable regions of that page. This path sends the browser to look in the correct location for the file which will provide the page properties, layout and graphics - all the content that exists only in the .dwt file. This is why changes outside the editable regions of a page must be made directly to the .dwt file. When the .dwt file itself is opened and revised all the pages applied to the template are linked to the file in the same location as before. All the pages applied to the template are all automatically updated with the new information.

Document-relative versus site root-relative

The path linking an HTML page to a template is a site root-relative path. It is called site root-relative because it starts from the top level of the directory structure (the local root folder), and then follows through the next folder down (Templates), and finally links to the .dwt file. Dreamweaver automatically generates a site root-relative path to the templates in the Templates folder, because it knows exactly where the template will be located, no matter what other file folders exist in the site structure.

For more information, see Site Root Relative - Why? (TechNote 13129).

Document-relative creates a path specific from one file to another. Rather than starting from the top level (site root) of your file folder structure, it generates a path that starts at one file, goes through whatever file folders (directories) necessary, and stops at the location of the other file. It is imperative that both files be saved inside the local root folder BEFORE creating a document relative link from one to another.

If you wish to be able to preview your pages in a browser locally, before you have uploaded the files to a remote server, they must be document relative. Both Internet Explorer and Netscape browsers have no way of understanding what local root folder has been defined (as Dreamweaver does) so it can only follow a path that is relative to the document it is currently viewing. Because most users prefer to view their pages locally in a browser prior to uploading them, Dreamweaver defaults to being document relative whenever a file is linked or an image is inserted. If the file has not been saved BEFORE attempting to insert an image or a link to another HTML page, Dreamweaver has no reference for the location of the current page, therefore it will generate a path that looks something like:

file:///HardDrive/Desktop Folder/localRootFolder/subfolder/subfolder/images/content.htm

or

file:///C:/Desktop/localRootFolder/subfolder/subfolder/images/content.htm

These paths are specific to your workstation ONLY and will not work when you upload files to a remote server.

The chart below gives a graphic explanation of the difference between document-relative and site root-relative. In the example below, the page bio.htm has a graphic named logo.jpg inserted into it using alternate path choices.

Document-relative paths in the template

Inserting images and links into the .dwt file directly can be confusing. Remember when working in the .dwt file any link that you create as document-relative will be exactly that - relative to the .dwt file. The path that is generated is specific from that HTML page or image source to the .dwt file. Dreamweaver keeps a record of where the referenced pages applied to the template live, and it automatically adjusts the path to the referenced HTML file to be correct for the current page. If you look at the HTML source for both the .dwt and a page applied to the template, the paths will be different, and this is how it should be. If Dreamweaver did not automatically adjust the path for each page's specific location, the document-relative path would be broken on all files except for the .dwt file.

Here's an example of the way Dreamweaver might adjust your document-relative path:

Dreamweaver does not adjust site root-relative or absolute (http://) paths from the template to the pages applied to the template, because it is not necessary to revise them.

Document-relative paths in the pages applied to the template

Inserting images and links inside the editable region of a page attached to a template work exactly the same as inserting images or links in a page that is not attached to a template. If you follow the procedure of selecting File > New from Template, then File > Save (choosing a location inside the local root folder) BEFORE creating any links to other pages or images, Dreamweaver will default to Document relative in both the Select HTML Page or Select Image Source dialog boxes. As long as the "Relative To" pop-up menu is not manually changed to select Site Root, the images and links will be available when you preview your work in the browser locally.

Site root-relative paths in the template

When working on a template file to create links to other pages or to reference the image source of graphics, the pop-up menu in the Select HTML File and Select Image Source dialog boxes allow you to choose between document-relative and site root-relative. As shown in the chart above, selecting Site Root creates a path from the local root folder directly to the file being selected, independent of the .dwt file that is currently open in Dreamweaver. Using site root-relative links may be beneficial when the content in the site directory structure is likely to move within the local root folder, because the link will remain unbroken even if the files are moved from their original location.

Dreamweaver does not adjust site root-relative or absolute (http://) paths from the template to the pages applied to the template, because it is not necessary to revise them. The location of the document (whether it is the .dwt file or an HTML file attached to the template) is irrelevant to a site root-relative path.

Site root-relative paths in the pages applied to the template

Using site root-relative links can be helpful if the site is complex, involves a team of developers working together, or has a site directory structure that will be revised on a regular basis. To create a site relative link, simply select Site Root from the pop-up menu next to the words "Relative To" located on both the Select Image Source and Select HTML File dialog boxes.

Because the path created will be starting from the local root folder, through any number of subfolders, and ultimately end at the page or image that it is linked to, developers are allowed the flexibility of moving the pages or assets one or more subfolders up in the site directory structure without breaking the links. Forexample, in the chart above, if the logo.jpg file were to be moved from the images folder into the features folder and the link was a site root-relative link, the browser would still have no problem locating the graphic. If the path is a document-relative link, both the logo.jpg and the bio.htm files MUST remain in the folder structure that they lived in when the document-relative path was created. Moving either file after the path is created will result in a path that is broken.

As mentioned above, only document-relative links can be previewed locally in the browser. If you choose to use site root-relative links, there are only two ways to view your pages in the browser.

The first is to upload (Put) the files up on the remote server, and then use your browser to go to the page by typing in the absolute path in the URL locator field. Using this method, the pages are being viewed just as others on the Web will see them. To make revisions to the pages, open up the local copy of the files, make changes, save the HTML pages, connect to the ftp server and"Put" the new files up on the remote server. Files with the same name in the same folder will overwrite the older versions of the file on the remote server.

The second way to preview site relative links in browser is by using a personal web server. On Windows only, this option can be set by going into Dreamweaver using File > Preview in Browser > Edit Browser List and selecting Preview Using Local Sever. Setting this option will allow Dreamweaver to preview documents using a personal web server.

Note:For the Macintosh, a personal web server is set at the system level. Check the system documentation for further assistance.