Troubleshooting Tips & Tricks!

The Macromedia Dreamweaver newsgroup is receiving quite a few issues with respect to updating UltraDev and Dreamweaver 4 templates with the new Dreamweaver MX format.  Similarly, Library Items and includes seem to be quite issue intensive also.

Both Murray and I use Templates, Library Items, and Includes with very few issues on our web sites. Based on the questions raised in the newsgroup and on their respective resolution, we have decided to provide this troubleshooting tutorial in the hopes that it will assist you with tracking down and squashing issues you may have in bringing your templates into DMX.

We'll break it down into 3 main headings: Library Items, Templates & General Tips

Libraries

There are a few issues with Libraries that are unique to Dreamweaver MX. The very first thing that we must mention is that because you could do it in Dreamweaver 4 or UltraDev 4 does not mean that it was correct in those versions.  What it means is that you got away with something that was not detected as an error in those applications but IS detected as an error in Dreamweaver MX.  This detection doesn't always come in the form of an error message, it can come as a display issue or a functionality issue as well.

Issue 1:

Duplication of non-editable region library in nearest editable region

Problem Description: This was a bug in the preview release of Dreamweaver MX and unreleased Betas of the software.  If you are encountering such an issue with your Library Items, chances are you are using an old copy of the software.

Resolution: Download and install the latest available download of the trial version or the full retail version to overcome this issue (make sure you completely uninstall any previous version you may have had installed).

Issue 2:

Irregular placement on the page

Problem Description: When viewing your page in DMX's Design View, the library item is shown out of its intended position, displayed erratically, or not displayed at all.

Resolution(s):

  1. This is typically caused because the library item has <head> element tags in it and/or a javascript block with opening body tag.  Open the library item for editing and verify that there are no <html>, <head> or <body> tags in its code using Code view.  If these elements are present in your library item, then remove them, save the Library Item and update the associated pages; your issue should be resolved.
  2. Did you hand code your library item and add a template region inside it? That is a mistake on your part.  Library items cannot contain template regions because they are static elements and locked when used on a page.  Remove the region coding, save the library and update the pages that use it.

Issue 3:

Can't apply CSS styles to your library

Problem Description: I want to be able to apply my CSS custom classes and styles to my Library Item but I cannot attach a CSS file to it because I am not allowed to have a head block in the library item.  So, what do I do?

Resolution: Applying CSS to the page elements in a Library Item can be tricky. Since Library Items shouldn't have <head> or <body> tags, you cannot put this CSS where you would ordinarily put it. You could, of course, just drop the embedded CSS in the HTML code of the Library Item, but this is sort of messy, and it *may* be redundant with code that is already present on the receiving page.

To solve such dilemmas, Macromedia has added new functionality to Dreamweaver MX called Design Time Style sheets.  And, they do it very nicely, too! To use this feature, open the Library folder, select the Library Item to which you want to assign classes. Select the menu item Text > CSS Styles > Design Time Style Sheets...

Select the plus sign above the Show Only at Design Time:, then select your CSS file that you wish to associate to the library item.  Follow the prompts from there and when finished, click the Design Time Style Sheets dialog OK button.

Now, you can assign your sitewide custom classes and styles to anything in the library item with ease as you normally would on a regular page, by using the Text > CSS Styles menu item, using the Tag Selector or by context menu of the selected content.

NOTE: This feature uses Design Notes, so make sure if you are sharing files that Maintain Design Notes is enabled for this web site or issues could be encountered when using this method.

Issue 4:

I want to reuse the Library Item on the page but each Library Item instance must be unique.

Problem Description: How can I do this?

Resolution: Create a Snippet of the base code instead and insert the snippet in each location desired.  The problem with this is that Snippets are not managed by Dreamweaver MX at all, unfortunately, so any future modifications would have to be manually updated by using the Find and Replace methodology.

Issue 5:

Library doesn't maintain set link paths.

Problem Description: If I use a url link such as index.html in my library item, the inserted library item changes the link path to Library/index.html. Why?

Resolution: Library items are managed by the same asset manager that controls all links, templates, assets, images, etc. If you want this sort of functionality, the only methods you have are server-side Includes or a custom Snippet.  Library Items were not created to function in this manner. To see an example of the functionality, download the sample.

Return to Top of Page

Templates

There are a few issues with Templates that are unique to Dreamweaver MX. The very first thing that we must mention is that EVEN THOUGH you could do it in Dreamweaver 4 or UltraDev 4, this does not mean that it was correct in those versions!  What it may mean is that you got away with something that was not detected as an error in those applications but IS detected as an error in Dreamweaver MX.  This detection doesn't always come in the form of an error message, it can come as a display issue or a functionality issue as well.

First Step:

The very first thing you should do when any error is encountered in your template or child page is to validate the page's markup and the template syntax.  It's really easy and will find most if not all of the issues that you may encounter.

Issue 1:

Erroneous Error Messages

Problem Description: When I update the template's associated pages, various error messages are displayed. Most often these take the form of "The changes entered would require changing a region that is locked...". This seems to be a more generic error message than we would like, and could reflect coding errors that have nothing to do with changing locked code. In fact, it appears that this message often reflects a deeper 'displeasure' with the template code itself.

Resolution(s):

  1. Check that your template is syntactically correct by using the menu item Modify > Templates > Check Template Syntax.  If all is well there, then chances are it is a library item or include that is causing the issue.  Check those for issues.
  2. You could have inadvertently added regions using the same name. Each template region must have a unique name.
  3. Dreamweaver 4 and UltraDev 4 were famous for adding multiple doctitle editable regions, so using Code View verify that only one doctitle editable region is wrapping your <title> tag.

Issue 2:

Templates just don't function well for me

Problem Description: When creating a template or a child page, I am unable to get the child to update with changes to the template.

Resolution(s):

  1. When you created your template child page, did you use the menu entry FILE | New > Templates Tab (Category=current site | desired template from Template list).
  2. Does your child page have a .dwt extension? If yes, then see resolution #1 under this issue. The .dwt extension indicates that you are working with a template page, not a child page, and may have, therefore, used the improper method for creating the child page. :)
  3. Are you making changes to the editable region of the template and expecting them to show in child pages?  Templates ONLY update non-editable regions.  However, any NEW pages will be created with the modified editable region content ONLY when initially created.
  4. Is your Templates folder in the site's root directory?  It MUST be for automatic updating and link management to work properly.
  5. Is your Templates folder actually called something other than "Templates?" It must not be renamed for automatic updating and link management to work properly.

Problem Description: I want to be able to use the same editable content on multiple areas of the same page.  How do I do that?

Resolution: Add a template parameter, with a type of text, in the head region of the code using our Template Snippets extension.

<!-- TemplateParam name="ReusableContent" type="text" value="Some Text" -->

On the child page, use the menu item Modify > Template Properties... to customize the content (a pseudo-editable region).  Insert a template expression using the Template Snippets extension wherever you want this repeatable content displayed on your page.

@@(ReusableContent)@@

In other words, you are entering some content into the parameter's value, and the expression is then writing this content to the page.

Issue 3:

'Editing Code outside HTML - changes will not be saved' errors

Problem Description: When editing child pages in code view, I am happily typing away when all of a sudden this error displays and my changes are lost.  What can I do?

Resolution(s):

  1. Go into preferences and enable auto tag completion in the Edit > Preferences (Code Hints Category).  The problem is that Dreamweaver validates the template and code on the fly... so if you type in an opening <p> tag without a closing </p> tag, Dreamweaver MX thinks that the closing editable region is out of context and hence throws the error message.  The <P> tag was only used as an example but this occurs for almost all tags and almost all web languages including asp, php, cfm, jsp, etc.
  2. If you are using the Code Inspector (F10), this is a known bug in Dreamweaver MX and hopefully will be rectified in an update.

Issue 4:

Copy and Paste is causing issues in child pages

Problem Description: Whenever I try to copy & paste or cut & paste, Dreamweaver MX throws an error message and closes the page which causes me to lose my changes.

Resolution(s):

  1. If you are performing this function in the Code Inspector to the Code view window, this is a known issue and hopefully will be rectified in an update.
  2. Make sure that you are copying or cutting a complete code block because Dreamweaver MX validates on the fly, so if you do not have the proper tag structure in your paste, Dreamweaver MX thinks that the editable region closing markup is out of context and throws the error message.

Issue 5:

Templates and Includes don't work well together

Problem Description: My includes aren't working properly when used with template source files and child pages, what is the problem?

Resolution(s): I've used includes without issue in both HTML & CFML templates.  There are, however, some things that you need to be aware of when using includes with templates.

  1. Do not have any base tags in the include files themselves.  The tags include the opening and closing <html>, <head>, <body>.
  2. Includes can be used for head block content but not the tags themselves.  For instance, you could have all your meta data tags as an include file.
  3. Do not have unbalanced tags in the include as this can totally mess with Dreamweaver's engine :)  What I mean by this is that you should not use includes that contain only partial code blocks such as the code listing below. 
    <table width="100% align="center" cellspacing="0" cellpadding="0">
  <tr>
    <td><p>content here for row 1, cell 1</p></td>
    <td><p>content here for row 1, cell 2</p></td>
    This is invalid code and can cause you issues since Dreamweaver MX does partial validation on the fly for code coloring purposes.  If it finds the unbalanced tags (Missing </tr> and </table>) then you will get error messages and improper functioning of the template and its child pages.

Return to Top of Page

General Troubleshooting

A good general approach if you are having problems and don't have any idea why is to "divide and conquer," i.e., divide your page into smaller components (areas where you expect problems could occur). Once you do that then dealing with each in turn is much easier.

Validate it!

Have you used a validator on your page to make sure that your HTML and CSS syntax are correct? This is the very first thing you should do prior to asking for a site check or for help in troubleshooting your site.

Locations where you can test your pages online and/or offline are given in the following URL's.

Bookmark these pages, as you should use these with every page that you create prior to starting your troubleshooting if a problem occurs. A small note to you is that even if your pages works the way you want it to, you should still validate them to make absolutely sure that there are no syntactical errors in your code. And we are talking *ERRORS* not warnings....

Layers

Layers themselves are not that tricky once you get the hang of them. But there are some issues that you need to be aware of and that will save you many hours of troubleshooting and frustration.

1. Is there an ID/Name conflict?
As with any named page element, each Layer name and/or ID must be unique. It cannot be the same as any other object on the page, including other images, other layers, tables, etc.

2. Do you have layers inside of table cells?
Due to the nature of layers, and for full cross-browser support and cross-platform compliance, you must NOT have any layers inside of table cells. Simply use your code view and move the tabled layer out of the cell, and just above the closing body tag </body>. Make sure that you move all of the layer's code, i.e., from its opening <div> to its closing </div>, inclusive.

3. Are the layers nested within each other?
Although this will work fine in IE and in Netscape 6.X, Netscape 4.X chokes on it big time. What you need to do is move the nested layers' inline style declarations into a CSS entry in your head section (making it a 'fully qualified CSS layer, i.e., a layer that is completely specified in the stylesheet, not in the body code. If you're using Dreamweaver 3+ then Jaro has a great extension for you called Layer2Style (unfortunately it is not yet functional on Macs with OSX), which will automatically move this style information (in either direction) for you.

4. Does your Cascading Style Sheet(s) have conflicting styles defined that are applied to the layer or to the layer content?
Simply detach the style sheet or remove the style block from the head of your document and test the page, if the problem still persists, then it is something in the layer or another layer that is causing a conflict on the page, simply remove the layers one at a time and test each time to see if the problem is resolved.

5. Are you unable to add layers to a child page?
In the child page's associated template, change this -

</body>

to this -

<p>&nbsp;</p></body>

and then in DMX's Design View, click in the space created by this &nbsp; and insert an editable region. Name this editable region "LayerPad" or something descriptive like that. After saving this template page, this new editable region will now propagate to all child pages.

Now, to insert one or more layers on any child page of this template, click in the editable region called LayerPad, and use INSERT | Layer to insert a new layer. Position this layer as desired, and you are off and running....

CSS

There are two people that we personally consider to be extremely knowledgeable with respect to Cascading Style Sheets. The first is Erik A. Meyer. Eric has written respected books on the subject (notably: Cascading Style Sheets: The Definitive Guide and CSS Packet Reference, both by O'Reilly) and is a frequent contributor to the W3C CSS initiative (I believe he still is). The second is Martina Kosloff. Martina has authored several CSS tutorials and is a frequent troubleshooter in the Dreamweaver and Project Seven support forums. We are grateful to both of them for their continuing patience and support!

Sites of Interest:

Cascading Style Sheets (CSS) is a completely different world than HTML, although the CSS is based primarily on HTML attributes, styles can be used to fancy up your content or even position your elements on the page. CSS has its issues too though, mostly with the differences in level of support between Netscape and IE, but there are usually workarounds/solutions.

1. Are multiple style blocks in the head of your document?
Combine them if possible down to 2 or 3 maximum style blocks in your document head section.

2. Have you tried removing the associated Style(s) from the page?
Remove/disable the style blocks altogether to determine if it is a style issue or a page content issue. If it's a style issue, replace with your last known good style sheet or start from scratch as troubleshooting can be a nightmare even for the skilled.

3. Is the font not showing as expected?
Do you have both CSS and font tags in your document? Remove the font tags as they are deprecated by the W3C, i.e., not required to be supported in future browsers.

JavaScript

Also known as behaviors and commands for the Dreamweaver users can cause some issues with pages if they are modified by hand or someone else's code is used in conjunction with Dreamweaver behaviors and commands. The best thing to do here is to make sure that your Javascript is actually supported in the problem browser. Try removing the JavaScripts one at a time until the page renders properly. This verifies or clears the Javascript as the source of the issue.

General troubleshooting notes

Of course, there are many other things to consider so I am still building my database of common errors and how to resolve them. When all else fails do the following.

Return to Top of Page

Home | Privacy Statement | Link to Us

Copyright © 2002, Brad Halstead & Murray R. Summers