FileIconRenderer (SiteVision API)

```
@Requireable(value="FileIconRenderer")
public interface FileIconRenderer
```
FileIconRenderer is a stateful utility interface that can be used to render valid xhtml img elements based on the file icons of the website.
An instance of the SiteVision class implementing this interface can be obtained via Utils.getFileIconRenderer(). See Utils for how to obtain an instance of the Utils interface.

FileIconRenderer is very suitable when rendering more than one file icon (for instance when rendering a search result where different icons should be displayed for different types of hits) or if you don't want to bother about how to get file icons from the icon repository of the site.

FileIconRenderer has few attributes:
- icon - The file icon that should be rendered. Default is null. If you try to load a new file icon and it fails, the previously loaded icon will be cleared (i.e. the renderer will not contain any icon to render).
- defaultIcon - The fallback file icon that should be rendered if no icon is loaded. Default is null. If you try to load a new default file icon and it fails, the previously loaded default icon will be cleared (i.e. the renderer will not contain any default icon to render).
- useSmallIcons - Whether to use small icons or not (i.e. true == use small icons, false == use large icons). Default is true.
- useDescriptions - Whether to render the file icon description or not (i.e. put text in alt attribute of the rendered img element or not). Default is true.
- locale - What locale to use when deciding which file icon description to use. Default is the locale of the currently executing portlet.
- fontClass - The CSS class to use when rendering (the class attribute of the img element). Default is sv-noborder (i.e. border-style:none).
----------------------------------------------------------------------------------------------------

Using the FileIconRenderer is pretty straightforward, if you remember that it is stateful and that previously loaded icons will be cleared whenever you try to load new ones. Conceptually you would typically use it like this:
1. Get the FileIconRenderer
2. Possibly init the renderer with rendering settings (locale, useSmallIcons, description)
3. Possibly load the renderer with a default icon
4. Load a file icon
5. Do render
When you have rendered once, you can re-use the FileIconRenderer until you are done. Something like:
1. Load a new icon.
2. Do render.
Loading of an icon can be done using:
- The file extension.
- The file uri.
- The file content type. Note! The term content type is also known as mime type, but since "content type" is the term typically used by web programmers it is used as terminology in this interface.
  Some information about content type mappings:
  A precise file extension (pdf, doc, png etc.) is always needed to extract a file icon from a web site. To enable file icon extraction via content types, a "content-type-to-extension" mapping will be used. Please be aware that not all content types will be mapped due to the sheer amount of existing types. Some content types can't be mapped since they doesn't have a single well-defined extension (a typical example is "application/octet-stream" that is used for a variety of file types, i.e. file extensions).
Whenever you try to load the renderer with an icon, the (possibly) previously loaded icon will be cleared. If loading fails, no result will be rendered by default (i.e. an empty string will be the output when calling the render method). If a default icon has been loaded successfully, it will be the output if the renderer contains no icon. (Note that the result of every icon loading is cached for best performance, hence no need for you to do the same in your code.)

Please note that all load methods return a boolean! To prevent the boolean to be part of the page output you might in some cases need to do a workaround. The set statement for $ignore in below example demonstrates a simple workaround.

Example of how this strategy could be implemented in Velocity:
(You want to do a simple listing of all nodes in a collection/iterator "$items" and use FileIconRenderer to render the file icons of all items that has a configured file icon
```
   ## Get PropertyUtil to ease Node property fetching
   #set ($propertyUtil = $sitevisionUtils.propertyUtil)

   ## Get FileIconRenderer
   #set ($iconRenderer = $sitevisionUtils.fileIconRenderer)

   ## Iterate through items and render the names and file icons (if they exist)
   <ul style="list-style:none">
   #foreach ($item in $items)
      ## Try to load the renderer by the item's uri (e.g. "/aPath/aFile.pdf")
      #if (!$iconRenderer.loadIconByURI(${propertyUtil.getString($item, 'URI')}))
         ## If loading failed, try to load the renderer by the item's content type instead (e.g. "application/pdf")
         #set ($ignore = $iconRenderer.loadIconByContentType(${propertyUtil.getString($item, 'mimeType')}))
      #end

      <li>
         ## Render the name of the node
         $propertyUtil.getString($item, 'displayName', '')
         ## Render the file icon of the node (if no icon was loaded, an empty string will be rendered)
         $iconRenderer.render()
      </li>
   #end
   </ul>
 
```
Tip! If you use Velocity and call a load method, you must suppress the boolean result so it doesn't get a part of the rendered output. The above example contains an assignment workaround to suppress the load result:
```
   #set ($ignore = $iconRenderer.loadIconByContentType(${propertyUtil.getString($item, 'mimeType')}))
```
This type of workaround can also be achieved via the swallow method of ScriptUtil as:
```
   $scriptUtil.swallow($iconRenderer.loadIconByContentType(${propertyUtil.getString($item, 'mimeType')}))
```
Since FileIconRenderer is stateful and likely will be used in Velocity frequently, there are some "shortcuts" that might be useful. Due to the lack of proper boolean support in Velocity, the boolean attributes has corresponding force/clear methods to set the boolean to true/false. For example:
- Executing forceUseSmallIcons() results in an execution of setUseSmallIcons(true)
- Executing clearUseSmallIcons() results in an execution of setUseSmallIcons(false)
Since:

SiteVision 2.6.1_08

Author:

Magnus Lövgren

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`clearDefaultIcon()` Removes loaded default icon (does nothing if no default icon is loaded)
`void`	`clearFontClass()` Removes the CSS class name(-s).
`void`	`clearIcon()` Removes loaded icon (does nothing if no icon is loaded)
`void`	`clearUseDescription()` Utility method for executing `setUseDescription(false)`, i.e.
`void`	`clearUseSmallIcons()` Utility method for executing `setUseSmallIcons(false)`, i.e.
`void`	`forceUseDescription()` Utility method for executing `setUseDescription(true)`, i.e.
`void`	`forceUseSmallIcons()` Utility method for executing `setUseSmallIcons(true)`, i.e.
`boolean`	`isDefaultIconLoaded()` Whether or not a default icon is loaded.
`boolean`	`isIconLoaded()` Whether or not an icon is loaded.
`boolean`	`loadDefaultIconByContentType(String aContentType)` Uses a content type to load the fallback icon that should be used when rendering if no icon is loaded.
`boolean`	`loadDefaultIconByFileExtension(String aFileExtension)` Uses a file extension to load the fallback icon that should be used when rendering if no icon is loaded.
`boolean`	`loadDefaultIconByURI(String aURI)` Uses a URI to load the fallback icon that should be used when rendering if no icon is loaded.
`boolean`	`loadIconByContentType(String aContentType)` Uses a content type to load the icon that should be rendered.
`boolean`	`loadIconByFileExtension(String aFileExtension)` Uses a URI to load the icon that should be rendered.
`boolean`	`loadIconByURI(String aURI)` Uses a URI to load the icon that should be rendered.
`String`	`render()` Builds a html img element based on current state.
`void`	`setFontClass(String aFontClass)` Sets the CSS class name(-s) to use when rendering.
`void`	`setLocale(java.util.Locale aLocale)` The locale to use when extracting the decription of file icons.
`void`	`setUseDescription(boolean aUseDescription)` If file icon descriptions should be used or not.
`void`	`setUseSmallIcons(boolean aUseSmallIcons)` Which type if file icons (small or large) that should be rendered.

- Method Detail
  - setLocale
```
void setLocale(java.util.Locale aLocale)
```
    The locale to use when extracting the decription of file icons.
    Default is the locale of the currently executing portlet.
    
    Note! Icons (icon and default icon) that has been loaded with a different locale will be removed whenever an invocation of this method changes the locale.
    
    Parameters:
    
    aLocale - the locale to use when extracting the icon description
  - setUseSmallIcons
```
void setUseSmallIcons(boolean aUseSmallIcons)
```
    Which type if file icons (small or large) that should be rendered.
    Default is true.
    
    Note! Icons (icon and default icon) that has been loaded with a different useSmallIcons state will be removed whenever an invocation of this method changes the useSmallIcons state.
    
    Parameters:
    
    aUseSmallIcons - whether or not to use small icons (true == "use small icons", false == "use large icons")
  - clearUseSmallIcons
```
void clearUseSmallIcons()
```
    Utility method for executing setUseSmallIcons(false), i.e. "use large icons when rendering".
    
    See Also:
    
    setUseSmallIcons(boolean)
  - forceUseSmallIcons
```
void forceUseSmallIcons()
```
    Utility method for executing setUseSmallIcons(true), i.e. "use small icons when rendering".
    
    See Also:
    
    setUseSmallIcons(boolean)
  - setUseDescription
```
void setUseDescription(boolean aUseDescription)
```
    If file icon descriptions should be used or not.
    Default is true.
    
    Note that file icon descriptions may be locale-dependent, see setLocale(java.util.Locale).
    
    Parameters:
    
    aUseDescription - whether or not a file icon description should be used when rendering
  - clearUseDescription
```
void clearUseDescription()
```
    Utility method for executing setUseDescription(false), i.e. "don't use description when rendering".
    
    See Also:
    
    setUseDescription(boolean)
  - forceUseDescription
```
void forceUseDescription()
```
    Utility method for executing setUseDescription(true), i.e. "use description when rendering".
    
    See Also:
    
    setUseDescription(boolean)
  - loadDefaultIconByContentType
```
boolean loadDefaultIconByContentType(String aContentType)
```
    Uses a content type to load the fallback icon that should be used when rendering if no icon is loaded.
    
    Parameters:
    
    aContentType - the content type (mime type) that decides what file icon to load
    
    Returns:
    
    true if a default file icon was loaded, false if not
  - loadDefaultIconByURI
```
boolean loadDefaultIconByURI(String aURI)
```
    Uses a URI to load the fallback icon that should be used when rendering if no icon is loaded.
    This method tries to extract a file extension from the URI and use that extension to load the default file icon. If the URI doesn't end with a file extension, default icon loading will fail.
    
    Parameters:
    
    aURI - the uri that decides what file icon to load
    
    Returns:
    
    true if a default file icon was loaded, false if not
  - loadDefaultIconByFileExtension
```
boolean loadDefaultIconByFileExtension(String aFileExtension)
```
    Uses a file extension to load the fallback icon that should be used when rendering if no icon is loaded.
    
    Parameters:
    
    aFileExtension - the file extension that decides what file icon to load
    
    Returns:
    
    true if a default file icon was loaded, false if not
  - isDefaultIconLoaded
```
boolean isDefaultIconLoaded()
```
    Whether or not a default icon is loaded.
    
    Returns:
    
    true if a default icon is loaded, false if not.
  - clearDefaultIcon
```
void clearDefaultIcon()
```
    Removes loaded default icon (does nothing if no default icon is loaded)
  - loadIconByContentType
```
boolean loadIconByContentType(String aContentType)
```
    Uses a content type to load the icon that should be rendered.
    
    Parameters:
    
    aContentType - the content type (mime type) that decides what file icon to load
    
    Returns:
    
    true if a file icon was loaded, false if not
  - loadIconByURI
```
boolean loadIconByURI(String aURI)
```
    Uses a URI to load the icon that should be rendered.
    This method tries to extract a file extension from the URI and use that extension to load the icon. If the URI doesn't end with a file extension, icon loading will fail.
    
    Parameters:
    
    aURI - the URI that decides what file icon to load
    
    Returns:
    
    true if a file icon was loaded, false if not
  - loadIconByFileExtension
```
boolean loadIconByFileExtension(String aFileExtension)
```
    Uses a URI to load the icon that should be rendered.
    
    Parameters:
    
    aFileExtension - the file extension that decides what file icon to load
    
    Returns:
    
    true if a file icon was loaded, false if not
  - isIconLoaded
```
boolean isIconLoaded()
```
    Whether or not an icon is loaded.
    
    Returns:
    
    true if an icon is loaded, false if not.
  - clearIcon
```
void clearIcon()
```
    Removes loaded icon (does nothing if no icon is loaded)
  - setFontClass
```
void setFontClass(String aFontClass)
```
    Sets the CSS class name(-s) to use when rendering.
    
    Parameters:
    
    aFontClass - the CSS class name(-s) expression. An empty string is equivalent to null - no class attribute will be rendered
    
    Since:
    
    SiteVision 3.0
  - clearFontClass
```
void clearFontClass()
```
    Removes the CSS class name(-s). No class attribute will be rendered until a fontClass is set again.
    
    Since:
    
    SiteVision 3.0
  - render
```
String render()
```
    Builds a html img element based on current state.
    
    Returns:
    
    a html img element based on current state, or empty string if no icon and no default icon was loaded

SiteVision - Portal and Content Management Made Easy
SiteVision is an advanced Java enterprise portal product and a portlet container (JSR 286) that implements Java Content Repository (JSR 283).

Interface FileIconRenderer

Method Summary

Method Detail

setLocale

setUseSmallIcons

clearUseSmallIcons

forceUseSmallIcons

setUseDescription

clearUseDescription

forceUseDescription

loadDefaultIconByContentType

loadDefaultIconByURI

loadDefaultIconByFileExtension

isDefaultIconLoaded

clearDefaultIcon

loadIconByContentType

loadIconByURI

loadIconByFileExtension

isIconLoaded

clearIcon

setFontClass

clearFontClass

render