Managing OS/OT Website in ExpressionEngine

Composing and Formatting Content This document describes how to compose and format textual content for the OS/OT website using ExpressionEngine.

Paul Bailey paul@northgare.net April 30, 2012

2

Contents 1. Keep it Simple! 3 2. Plain Text Paragraphs 4 3. Plain Text with Line Breaks 5 4. Simple Text Styles 6 5. Section Headings 8 6. Lists 10 7. Hyperlinks 13

External Links 13 Internal Links 14 Mailto Links 15 Use the Title Attribute 17 User-friendly Link Text 17 Don’t Use “Click Here” Links 19 Applying Links to Content Other Than Text 20

8. Quoted Material 21 Blockquotes 21 Quotations 22

9. Tables 23 Data Tables 23 Tables for Layout 24

10. What If...? 26 Keep Content Simple 26 Add Explicit Line Breaks 26 Disable Auto-XHTML Conversion 26 Add New CSS Styles, or Modify Existing Styles 27

11. See Also... 29 12. Change Log 30

3

1. Keep it Simple! When you’re composing content in ExpressionEngine for the OS/OT site, it’s important to keep things simple and clear. Remember that you’re not working with a WYSIWYG word processor. Don’t expect to be able to have the freedom to lay out every page differently, and with all of the bells and whistles you might use if you were creating a printed document. The techniques and tags described in this document should be fine for the great majority of page content. The goal is to create content that’s easy to read/work with, and which conforms to the XHTML standard — XHTML is a modern take on HTML which emphasizes a consistent and standard use of tags, and which focuses on the logical structure of a web page, while moving formatting details into CSS style sheets. Don’t worry if you don’t know what that means; the formatting techniques described below stick to XHTML. Don’t get caught up worrying about text sizes, colors and fonts, for example. Those issues are defined in external style sheets for the whole site, which keeps everything looking consistent. ExpressionEngine itself also helps with formatting. It takes the content you create, and then tries to add the tags necessary to turn the content into valid XHTML — that’s what the “Formatting: XHTML” setting to the bottom-right of the composition window (see below) means. Mostly it does a good job, but it succeeds more often when the content is simple, and the XHTML tags you use are clear and standard. Work with EE, and it’ll make your life easier. If the content you’re creating consists of paragraphs of plain text, you’ll need to use very few formatting tags, if any at all.

ExpressionEngine set to automatically format content as XHTML

4

2. Plain Text Paragraphs Plain text paragraphs don’t need any additional formatting tags. Just enter each paragraph with no line-breaks, and separate one paragraph from the next with a completely blank line. Example

Plain text paragraphs in ExpressionEngine composition window

Plain text paragraphs as displayed on OS/OT website

5

3. Plain Text with Line Breaks Any line-breaks you add to content in ExpressionEngine are retained on the rendered page. This is most useful for paragraphs of text broken into shorter lines, like address and contact information. You don’t need to add any XHTML tags to make this work — just hit the return/enter key to add a line-break (but be careful not to add any line-breaks where you don’t want a line to break on the web page). Example

Plain text with line-breaks in ExpressionEngine composition window

Plain text with line-breaks as displayed on OS/OT website

6

4. Simple Text Styles You can use XHTML tags to add simple styling to text. Use <strong> and </strong> either side of text to style it using a bold font. Use <em> and </em> either side of text to style it using an italic font. Check with other pages on the OS/OT site to see how similar text has been styled, to keep things consistent. Use the “B” and “i” buttons above the composition window to add the <strong></strong> and <em></em> tags quickly:

(Note: the <b></b> tag can also be used in place of <strong></strong>, and the <i></i> tag in place of <em></em>, and these will have the same effect in almost all situations, but <strong></strong> and <em></em> are the standard XHTML tags for representing bold and emphasized text.) Try to avoid using any other explicit text styling — underlining, for example, or tags used to make text a different color or a different size. Example

Styled text in ExpressionEngine composition window

7

Styled text as displayed on OS/OT website

8

5. Section Headings If you need to break a page into sections, use the <h2></h2>, <h3></h3> and <h4></h4> tags to define section headings. (The <h1></h1> tag is reserved for the main title of each page, so don’t use this for section headings.) Use <h2> and </h2> either side of the headings for the major sections on the page. Use <h3> and </h3> either side of the headings for any subsections you need to create within the major sections, and <h4></h4> if you need to subdivide any of the subsections further. In most cases, a page should only need major section headings, using <h2> and </h2>, and perhaps occasional use of <h3> and </h3> to define subsections. Use the “h2”, “h3”and “h4” buttons above the composition window to add the <h2></h2>, <h3></h3> and <h4></h4> tags quickly:

If you find that a page has many sections, subsections, and subsubsections, consider whether it might make sense to distribute its content among more than one page.

9

Example

Section headings in ExpressionEngine composition window

Section headings as displayed on OS/OT website

10

6. Lists You can easily create numbered and bulleted lists using a combination of three XHTML tags. Use the <li></li> (“list item”) tag to enclose each list item. Then, use the <ul></ul> (“unordered list”) tag to enclose the entire list of items, in order to create a bulleted list; or use the <ol></ol> (“ordered list”) tag to enclose the entire list of items, in order to create a bulleted list. Use the buttons above the composition window to add the <li></li>, <ul></ul> and <ol></ol> tags quickly:

11

Examples

Bulleted list in ExpressionEngine composition window

Bulleted list as displayed on OS/OT website

Numbered list in ExpressionEngine composition window

Numbered list as displayed on OS/OT website

12

Since any item within a list can also include a complete list, it’s possible to define multi-level lists.

Multi-level list in ExpressionEngine composition window

Multi-level list as displayed on OS/OT website

13

7. Hyperlinks Use the <a></a> tag to create hyperlinks — clickable links to other websites and other locations on the same website. The three most common hyperlink forms are:

1. Links to different websites (“external links”); 2. Links to other locations on the same website (“internal links”); 3. Links which open an e-mail program to send e-mails to specific addresses

(“mailto” links). These forms are described separately below. External Links The XHTML form for an external link is:

<a href=“external url”>Link on page</a> For example, an external link to Google.com, which is displayed on the page with the text “Google”, would be:

<a href=“http://google.com”>Google</a> (Make sure to include the http:// prefix for external links.) Use the link button above the composition window to add the <a></a> tag quickly:

14

Type the URL into the popup box which appears, after the http:// prefix, click OK, and it will automatically be added to the tag:

Finally, add the link text to appear on the page:

Internal Links The XHTML form for an internal link to another page within an ExpressionEngine site is:

<a href=“{path=internal page path}”>Link on page</a> where internal page path is basically the section of the page URL which comes after the website domain. For example, on the OS/OT website, the internal page path of the page http://ot.usc.edu/faculty/directory is just /faculty/directory:

<a href=“{path=/faculty/directory}”>Faculty Directory</a>

15

Use the link button above the composition window to add the <a></a> tag quickly:

In the popup box which appears, delete the http:// prefix, and then add the internal page path, using the form {path=internal page path}:

Finally, add the link text to appear on the page:

Mailto Links The XHTML form for a “mailto” link which opens an e-mail program to send to a specific e-mail address is:

<a href=“mailto:e-mail address”>Link on page</a>

16

For example, a mailto link which opens an e-mail program to send an e-mail to paul@northgare.net might be:

<a href=“mailto:paul@northgare.net”>E-mail Paul Bailey</a> Use the link button above the composition window to add the <a></a> tag quickly:

In the popup box which appears, delete the http:// prefix, and then add the e-mail address, using the form mailto:e-mail address:

Finally, add the link text to appear on the page:

17

Use the Title Attribute It’s optional, but a very good idea, to add the title=“title text” attribute to any hyperlinks. This attribute can be used to label a hyperlink with useful text — to help with screen readers for accessibility, for example. On the OS/OT site, set the title attribute of a hyperlink to the destination URL (you don’t need to include the http:// prefix):

<a href=“http://google.com” title=“google.com”>Google</a> Another nice effect of the title attribute is that browsers typically display its value when the user hovers over a link — allowing them to see where the link goes, without actually going there:

This is a way of showing the user the URL without needing to put it on the actual page, which is especially useful when URLs are long and complicated. User-friendly Link Text The text displayed on the page for an external link can be anything, and doesn’t have to be the URL itself. Unless it’s important to communicate a URL to the reader of a page (for example, as part of a list of contact/address information), use other, more user-friendly text. URLs are often long and complicated, and it’s usually not important to display them in full on the page. Long URLs can also often break page formatting, since some web browsers don’t know how to display them effectively. Use readable, summary text on the page, which describes where a link goes, rather than its URL. For example, imagine a hypothetical external link to a piece entitled “A Story About OT”, on a web page whose URL is:

http://hypothetical.domain.edu/2012/january/12/a-story-about-ot.html

18

A clumsy way to code this link would be to put the URL on the page as the link text:

This would be displayed on the OS/OT site as:

Note how difficult this is to read, and how the URL is split awkwardly between lines. A much better way to code the link is to use the title of the piece as the link text (it does still make sense to use the URL as the value of the title attribute, since this isn’t displayed as part of the page content):

This is displayed on the OS/OT site as:

Note that the URL is visible when the user hovers over the link, but the link text on the page is clear and simple.

19

Don’t Use “Click here” Links Avoid using links which ask the user to “Click here”, or variants of that style. “Click here” links are an antiquated form that isn’t well-regarded these days. For example:

would be displayed on the OS/OT site as:

There are a couple of problems here. Asking a user to “click” a link should be redundant if content is presented well. The very idea of “clicking” on a link is also changing, now that input devices are many and varied — including, for many people using mobile devices, tapping a finger on a screen. Also, separating the link text from the text which describes where the link goes is unclear, and presents accessibility issues. A far better approach is to use the text which describes the destination of a link as the link text itself; for example:

This is displayed on the OS/OT site as:

20

Applying Links to Content Other Than Text Links don’t have to be displayed on a page using text. For example, they can be attached to images.

But stick to using text for hyperlinks unless you have a very good reason not to.

21

8. Quoted Material Blockquotes Use the <blockquote></blockquote> tag to “quote” a block of text by indenting it from the left-hand page margin. You can use the double-quote button above the composition window to add the <blockquote></blockquote> tag quickly:

Example

A blockquoted paragraph in ExpressionEngine composition window

A blockquoted paragraph as displayed on OS/OT website

22

Quotations Use the tag/attribute <div class=“quotation”></div> to create a block of text that’s designed specifically for quotations. The quotation class — a custom class for the OS/OT site — hooks into some external style controls which cause the content to be displayed with a large, bold font, right-justified, and with a light-gray background. Example

A quotation in ExpressionEngine composition window

A quotation as displayed on OS/OT website

23

9. Tables Use four related XHTML tags to create content in a tabular form:

• Use <table></table> to define a table, by enclosing the rows which belong in the table.

• Use <tr></tr> (“table row”) to define a single row within a table, by enclosing the table cells which belong in that row.

• Use <td></td> (“table data”) to define a single cell within a table. A similar tag, <th></th> (“table header”) defines a cell which is intended to be displayed as a header.

Data Tables The best use of table content on the OS/OT site is to display data which naturally belong in that form — fees and other numerical values arranged by year or semester, for example. Create a data table for the OS/OT site by adding two attributes to the opening <table> tag:

• class=“datatable” hooks into some custom external style controls which determine how the table is displayed. A thin, light-gray border is used for all table cells, table header cells use a bold font and a gray background, and the table is set to fill the full width of the available space.

• cellspacing=“0” is a necessary addition for data tables. It makes sure that no additional space is added between table cells.

24

Example

A data table in ExpressionEngine composition window (note the use of <th></th> for the header cells)

A data table as displayed on OS/OT website (note the formatting of the header cells)

Tables for Layout Without any additional attributes (such as class=“datatable”), a table on the OS/OT site is displayed with no borders. This makes it possible to use tables to define content layout on the page. The example below shows how to create a rudimentary two-column page. This technique is not recommended except for very simple uses, however. Content organized in tabular form can present accessibility difficulties for people using screen-readers, for example. Also, the space available on the OS/OT site for page content doesn’t lend itself to complicated layout structures, and the resulting variation of page layout across the site would work against a consistent tone. Avoid using XHTML tables for layout unless you have a clear and compelling reason to do so.

25

Example

A two-column layout table in ExpressionEngine composition window

A two-column layout table as displayed on OS/OT website

26

10. What If...? ExpressionEngine takes the content you create, and attempts to add the additional tags necessary to convert the content into valid XHTML code. Mostly it does a good job, but sometimes the code it creates doesn’t display on the page as you expect, and/or doesn’t validate as correct XHTML. Below are some suggested techniques to help ExpressionEngine get it right, or to fix things if it doesn’t. Keep Content Simple Split content into smaller, simpler blocks, and don’t use any more XHTML tags than you really need. ExpressionEngine is most likely to trip up when the code structures you give it are already quite complicated (“a blockquote within a list within a table cell within...”), so it helps to minimise and simplify the use of tags. Add Explicit Line-Breaks If the problem is that ExpressionEngine is failing to add line-breaks where you want them, consider adding line-break tags explicitly. This is basically a hack, which will make your content less clear, so only use it if you’ve tried to simplify the code first. Note that the correct XHTML tag for a line-break is <br />, not <br>. Disable Auto-XHTML Conversion If the ExpressionEngine automatic XHTML conversion just isn’t working on the page content, you can disable it partially, or entirely. Doing this is a last resort, since it means that you’ll have to add all or almost all of the tags necessary to create valid XHTML. To disable automatic XHTML conversion:

• Switch the “Formatting” option, to the bottom-right of the composition window, to “Auto <br />“. This disables all automatic XHTML conversion,

27

except that line-breaks in the original content are translated into <br /> XHTML line-breaks.

• Switch the “Formatting” option, to the bottom-right of the composition window, to “None”. This disables all automatic XHTML conversion.

If the reason that automatic XHTML conversion isn’t working is that your content by necessity contains elaborate code already, consider whether it might make sense to create the content as a template, rather than as a page. Templates are intended to contain the machinery necessary to make pages look right, so that page content can be simple and clear. If you think you might need to create a new template for a specific page or page type, ask for help. Add New CSS Styles, or Modify Existing Styles The XHTML tags and techniques described in this document should be sufficient to implement the great majority of page content on the OS/OT site. If you’re trying to develop content whose structure is non-standard, or unusually complex, and for which the standard tags/techniques genuinely aren’t adequate, try to avoid hacking, which produces content that’s hard to read and edit, and is more likely to be rendered in unpredictable ways by browsers. In such a situation, as well as considering whether the content can be simplified, or whether developing a custom template for the page content might be a better approach, look into whether a custom CSS style solution might help — the custom styles currently used for data tables and quotations are good examples of how external style definitions

28

can greatly simplify the code that’s used in content. Moving layout and formatting specifications into external CSS style sheets has a couple of significant advantages:

1. It keeps content separate from details of layout and formatting, allowing it to be clean and clear.

2. If defined in a general fashion, external CSS styles can be re-used throughout the OS/OT site, making content development quicker and easier, and keeping the look and feel of the site consistent.

A hacked solution to a content coding problem isn’t re-usable, and risks producing content that clashes with the rest of the site. This document doesn’t cover solutions which involve creating/modifying either templates or CSS styles. If you’re sure that you can’t achieve what you’re looking for using the techniques described here, ask for help. CSS solutions need to be considered carefully, since they can create changes across the entire site.

29

11. See Also...

30

12. Change Log

• April 30, 2012: First version.