Managing custom HTML styling

About customizing HTML

This site provides several opportunities for users to add HTML content to screens. For instance, the Community, Project home, and My start pages might include custom HTML content.

Custom HTML generally inherits the styling from the page's Cascading Style Sheet (CSS) files. Styles and formatting defined in the style sheet will apply also to user-supplied content, adding to or possibly overriding any formatting specified in it. For instance, the stylesheet might specify that table heading (th) content is to be aligned left. Table headings in user-supplied HTML that appear center-aligned before inclusion will automatically be left-aligned after inclusion. Similarly, the fonts and colors will match that of other HTML appearing in the same page.

In most cases, this is desirable for the sake of consistency and ease of HTML authoring; however, if it is not, you can use the tips that follow to help eliminate unwanted styling differences.

If the desired CSS styles do not apply...

To make user-supplied HTML more consistent with SourceCast formatting, try to remove the formatting-related elements and attributes from the included HTML. For instance, remove all font tags, style, bgcolor, and align attributes, and use structural HTML elements like headings (e.g., h3), paragraphs, and list constructs instead of breaks (br), images of text, tables for layout, spacer images, and so on.

The most likely cause for SourceCast style application failure is that the HTML fails to identify the structural significance of the text, instead describing its desired appearance. To remedy, convert this sort of HTML:

<font size="4" face="Arial, Helvetica">
  Welcome to project foo!
<img src="../images/spacer.gif" height="1" width="1" vspace="4" alt="">
 <font size="2">
  This is only a picture of a paragraph.
<Br> this:

  Welcome to project foo!
  This is a real paragraph.

Note that the HTML best suited for application of CSS is also the simplest to write and edit by hand, and results in smaller (faster) files. Furthermore, it tends to remain accessible when rendered outside the context of a desktop PC, such as WebTV or a hand-held browsing device.

A useful tool for automating cleanup of HTML produced by software such as MS Office, FrontPage, or Netscape 4.x Composer is HTML Tidy. A suggested configuration file for Tidy appears in HTML Tidy Configuration below.

If SourceCast styles are overriding desired custom styling...

To preserve custom styling in user-supplied HTML, use inline CSS; i.e., HTML's style attribute instead of the various style-related attributes and elements such as FONT, bgcolor, align, or valign that CSS superseded in 1996.

For instance, the following HTML may not render with the intended styling in the context of a SourceCast screen:

<h2 align="center">
 <font face="Times" color="#cc0000">
   Welcome to project foo!

To preserve such styling, the various formatting properties should be expressed using CSS:

<h2 style="text-align:center; font-family:Times; color:#c00">
  Welcome to project foo!

This inline CSS will override any conflicting styling provided by the SourceCast stylesheet. To learn more about CSS usage, check the following sources:

More complex or extensive style customization may call for appendices to the SourceCast stylesheets themselves and requires a deeper understanding of CSS in SourceCast than this document aims to provide. Please provide feedback to CollabNet about your expectations in this area.

HTML Tidy configuration

The following is a suggested configuration file for HTML Tidy. This utility will clean up many HTML syntax and usage problems that can lead to unexpected results with SourceCast in various browser/platform contexts. For best results, use Tidy on all HTML you intend to integrate into SourceCast screens.

tidy-mark: no
markup: yes
wrap: 0
wrap-attributes: no
wrap-script-literals: no
wrap-asp: yes
wrap-jste: yes
wrap-php: yes
literal-attributes: no
tab-size: 1
indent: auto
indent-spaces: 1
indent-attributes: no
hide-endtags: no
input-xml: no
output-xml: yes
add-xml-pi: no
add-xml-decl: no
output-xhtml: no
doctype: auto
char-encoding: ascii
numeric-entities: yes
quote-marks: no
quote-nbsp: yes
quote-ampersand: yes
assume-xml-procins: no
fix-backslash: yes
break-before-br: no
uppercase-tags: no
uppercase-attributes: no
word-2000: yes
clean: yes
logical-emphasis: no
drop-empty-paras: yes
drop-font-tags: yes
enclose-text: yes
enclose-block-text: no
fix-bad-comments: yes
add-xml-space: no
alt-text: ""
write-back: yes
keep-time: no
show-warnings: no
quiet: yes
gnu-emacs: yes
split: no