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
File / Path | Description |
|---|---|
resource/edit-macros.ftl | macros for edit pages / forms |
resource/list-macros.ftl | macros common among the various list.ftl pages |
resource/navigation-macros.ftl | macros for rendering some of the nav elements on a tDAR page, such as the toolbar, controller actionErrors |
resource/view-macros.ftl | macros used on the view / detail pages |
search/search-macros.ftl |
|
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
Stand-alone
For tooltips that require added markup or styling, specify an ID in the TOOLTIPCONTENT field.
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
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:
Use double quotes when interpolating in attributes
Sanitize strings in javascript using ?js_string built-in
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.
Labels