About This Page

This purpose of this page is to point out some of the conventions, snippets, and assumptions used in the tDAR codebase.

Web Conventions

Location / Purpose of Some common macro files

Unless otherwise noted, macro files are located in

src/main/webapp/WEB-INF/macros

Edit Pages  

HOWTO: Add Sidebar Tooltips To a Page Element

Sidebar tooltips  are the popup labels/descriptions that appear on edit pages beside certain fields as you hover over them.  You can create tooltips in two ways: stand-alone and inline

Inline

For simple tooltip text. Give any element a tooltip by specifying TIPLABEL and TOOLTIPCONTENT custom attributes

<input name=addr1 tiplabel='Address' tooltipcontent='Enter street address' />

Stand-alone

For tooltips that require added markup or styling,  specify an ID in the TOOLTIPCONTENT field.

<input name="addr1" tiplabel="Address" tooltipcontent="#divAddressEntryTooltip" />


<div id="divAddressEntryTooltip">
    Enter street address followed by <em>city</em> and <em>state</em>
</div>

Sanitize User-Generated Content in Web Pages

When rendering web pages, this it is important to sanitize untrusted, user-generated content.  The primary concern is preventing against users injecting harmful HTML and/or javascript code (aka XSS attacks), however, even user content that comes from a trustworthy source should be sanitized so as to prevent html symbols from inadvertently corrupting breaking the display/behavior of a page.

This is no small task.  Fortunately,  freemarker provides some useful features to assist in this respect.  Here are some guidelines to follow when creating or editing FTL pages

Sanitize strings in HTML using ?html built-in

<!-- not safe -->
<div>Hello ${displayName}, please don't hack our site</div>
 
<!--safe -->
<div>Hello ${displayName?html}, please don't hack our site</div>

Note: When sanitizing strings that are placed inside of html tags, you must take the extra step of using the double quote character instead of a single quote:

<!-- unsafe! untrusted string can inject a malicious event attribute -->
<div title='Informtation for ${username}'> ... </div>
 
<!-- use double-quoted attributes -->
<div title="Information for ${username}"> ... </div>

Sanitize strings in javascript using ?js_string built-in

<#assign name= "bob's donuts</script>" />
 
<script>
//unsafe
var greeting = 'hello ${name}';
 
//safe
var name = 'hello ${name?js_string}';
</script>

Sanitize En-masse Using the <#escape> Directive

It's not uncommon for a freemarker page to contain dozens of expressions, and it can be cumbersome to escape them all.   Fortunately in freemarker you can simplify this with <#escape>.  Note that the directive will only apply to expressions contained in that same file. In other words, a call to an externally defined macro will not be escaped; you'll need to use the escape directive in the file that defines the macro as well.

Also handy is <#noescape>, which allows you to exclude expressions within an <#escape> section.

 
<#escape _untrusted as _untrusted?html>
 
<!-- safe -->
<p>hello ${planet}</p>
 
<!-- safe -->
<div title="Information for ${username}"> ... </div>
 
<#noescape>
<script>
  //exclude this section because we need to sanitize it for javascript, not html
  var title = "${project.title?js_string}";
</script> 
</#noescape>
 
<!-- not safe!  the escape directive does not extend to macro calls -->
<#edit.displayUserName /> 
 
</#escape>
 
<!-- not safe! the expression is outside of the escape tags
<p>hello ${planet}</p>