com.smartgwt.client.docs

Interface SCSpriteConfig

All Superinterfaces:

SCImgURL, URI, URL

public interface SCSpriteConfig
extends SCImgURL

Using Sprites

Image sprites are a technique to minimize server http requests when displaying media to a user. Given a series of small images (icons, say), instead of having a separate image file be loaded for each icon, the server can provide a single large composite image to the client, and the client can use CSS to display sections of this larger image to the user.
See also the "spriting" discussion in the skinning overview documentation.

The Smart GWT framework supports the SCSpriteConfig format for sprited images.

Note that SCSpriteConfig is just a special class of image URL, and as such any component attribute of type SCImgURL may be set to a sprite configuration.

SCSpriteConfigs have the following format:
"sprite:<image URL>;offset:<Left>,<Top>;size:<Width>,<Height>;cssClass:<className>"

This format allows developers to specify the image source and the native size and offset of the sprite within the image.

The media to load will be retrieved from the specified image URL. Standard SCImgURL directory prefixes such as "[SKIN]" can be included in this URL.

Developers may also specify an image data URL - for example "sprite:data:image/jpeg;base64,<data>;offset:-120,0;size:20,20;".

An explicit URL is not required. Developers may instead specify a css class which can include an explicit background-image attribute.

The offset: property specifies the left and top coordinate to apply to the composite image element such that the desired sprite is visible. The size: property indicates the size of the sprite in pixels.
For example, a sprite configuration of "sprite:composite.png;offset:0,-20;size:20,20;" would load the image file "composite.png", and display a 20 pixel square from it. The origin of the larger image would be offset vertically by -20px, so the sprite actually visible to the user would have its y-origin at 20px within the larger image.
As with the image URL, explicit size and offset are not required - a developer may use css properties (width, height and background-offset) from the specified class to specify the specific sprite to display.

The cssClass: denotes the css class to apply to the rendered element displaying the sprite. This is optional - a sprite can be specified with an image URL and explicit sizing and offset coordinates, in which case no css class is actually required.
(Of course for a valid sprite, it is expected that the image URL and size are specified either explicitly in the string, or within the css class definition. If the offset is omitted, it will be assumed to be zero on both axes).

Sprites will scale automatically. If a spriteConfig is used to provide an image for an icon and some other property is used to configure the drawn size of the icon in question (Button.iconSize,for example), the sprite image will be scaled to render at the appropriate size.

Sprited image configuration and "stateful" images

Many image URLs in Smart GWT are "stateful", meaning that variants of the image should be displayed to the user depending on the current state of the widget. (For example a custom button icon may be displayed on roll over, or a selection checkbox icon in a treeGrid may appear disabled for unselectable nodes).

There are a couple of approaches to display stateful versions of sprited images.

Wherever SCStatefulImgConfig objects are supported, a developer may include spriteConfig strings as entries for specific states.
For example, the following SCStatefulImgConfig definition would display different sprites from "compositeImg.png" for base and "Over" states:
{ _base:"sprite:compositeImg.png;offset:-100,-100;size:20,20",
Over:"sprite:compositeImg.png;offset:-100,-120;size:20,20" }

Alternatively, if a property that behaves as the base URL for a stateful image (such as Button.icon) is set to a sprite configuration string, the framework will use the state name as a suffix to apply to the source URL or the css class specified in the sprite.
As with standard stateful images, if a URL was specified for the sprite, the stateful suffix will be applied with a preceding "_" character.
So if the state "Over" was applied to a sprite configuration of "sprite:compositeImg.png;offset:100,100;size:20,20", the generated HTML would attempt to load an image from the URL "compositeImg_Over.png" (and display a sprite from that image with the specified size/offset).
If a class name was specified in the sprite, the stateful suffix would be appended with no leading underscore, similar to how state suffixes are applied to the baseStyle of a StatefulCanvas.
For example a sprite config of "sprite:cssClass:buttonIcon" would display styling from "buttonIconOver" when the "Over" state was applied.

SVG sprites

If you have a collection of SVG graphics, you can combine them into a single <svg> container, and then use the sprite: mechanism to access them. The <svg> container can be defined externally in a .svg file or inline in your HTML, but it must conform to the following 3 rules:

• top-level graphics elements in the container must be declared in <symbol> tags with ids, instead of <svg> tags, because <symbol>s are template document fragments, reusable by id - children of these elements need not be <symbol>s
• the <symbol> elements must be declared inside the <defs> tag, because browsers don't render elements in this tag
• the outer <svg> must not declare a <style> tag, because it won't be available in the main document when the <symbol> fragments are reused in different contexts. If your <symbol>s are styled by CSS classes, these must be defined in a separate .css file, which should be loaded in your page. See Styling SVG below.

A valid <svg> container for reusable <symbol> fragments might look like this:

  <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
      aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" 
  >
     <defs>
         <symbol id="icon-play" viewBox="0 0 32 32">
             <path d="M6 4l20 12-20 12z"></path>
         </symbol>
         ...
     </defs>
  </svg>
  

An <svg> container structured in this way will not be rendered in the browser, but the <symbol>s it defines are made available as a set of templates which can be re-used later in src strings. The format of src strings differs slightly according to where your <svg> container is defined. If it's defined inline in the HTML, only the fragment-id is required - for example

src: "sprite:usesvg:#icon-play"

If it's defined in a separate file, you must also specify which file:

src: "sprite:usesvg:path/to/fileName.svg#icon-play"

When the external file-name is specified in this way, there is no need for the developer to explicitly load the file.

Note that this mechanism is not explicitly supported in any version of Internet Explorer, since that browser has never had full SVG support.

Styling SVG

As with regular SVG, it's possible to modify the colors and other styles of <symbol>s at runtime. However, browsers render <symbol>s inside <use> tags, and these elements keep their content separate from the main document, in DocumentFragments in the browser's shadow DOM. These fragments are not subject to the main document's scope/CSS cascade so, while it's possible to modify the styles of complex/multi-color <symbol>s, it does rely on your graphics having been carefully constructed to include no direct styling, or to ensure that styling is applied via CSS classes which are declared externally and loaded directly.

At its most basic, individual graphics elements in a <symbol> which do not specify styles inline can be easily modified. If all child elements are unstyled (ie, the symbol is single-color, even if it has multiple child graphics), the image-color can be changed as a whole by applying external CSS. If some child elements have inlined styles, they will not be modified by such external CSS - this means that certain parts of a <symbol> can be of a fixed-color, via inlined styles, while other parts can be left unstyled and can be customized via external CSS later, to highlight only those unstyled parts.

Another way to apply two colors at once is to have parts of your <symbol> use the special currentColor CSS value, like fill=currentColor. This value is always equal to the current/inherited CSS color and can be referenced by graphics elements. If your CSS class sets fill and color to different values, graphics elements that use currentColor will assume the color value.

As noted above, it's also possible to fully re-style more complex, multi-color SVG - but this involves ensuring that all styling is externalized and backed by CSS; these details are highly dependent on the graphics and as such are the responsibility of the graphics designer or generator tool.

Simple Icons Example

Consider a set of single-color SVG <symbol>s that you want to leverage as re-usable icons in your projects. You may want to show them in different colors in different contexts such as buttons, menus or formItems, and you may want them to be stateful, changing color as you roll over or disable them. This is easily achieved by simply not specifying colors in your graphics definitions - browsers will use their default fill and stroke colors when rendering your symbols (typically, both black), but you can modify these defaults by applying a simple CSS class. SmartGWT skins provide a builtin svgIcon style that you can use or modify for this purpose, or you can create your own custom styles:

  // filled icons, no outline
  .icon { fill: grey; stroke: none; }
  .iconOver { fill: green; stroke: none; }
  .iconDown { fill: lightgreen; stroke: none; }
  .iconDisabled { fill: lightgrey; stroke: none; }
  
  // outline icons, no fill
  .iconOutline { stroke: grey; stroke-width: 1px; fill: none; }
  .iconOutlineOver { stroke: green; stroke-width: 1px; fill: none; }
  .iconOutlineDown { stroke: lightgreen; stroke-width: 1px; fill: none; }
  .iconOutlineDisabled { stroke: lightgrey; stroke-width: 1px; fill: none; }
  

This class can then be applied to a stateful widget via its baseStyle or similar, by including it directly in src strings, or as separate per-state URLs in an SCStatefulImgConfig object.

  isc.Img.create({
      // show stateful styles
      showRollOver: true,
      showDown: true
 
      // use baseStyle for statefulness
      src: "sprite:usesvg:fileName.svg#icon-id;",
      baseStyle: "icon"
 
      // or, use cssClass in config-strings for statefulness
      src: "sprite:usesvg:fileName.svg#icon-id;cssClass:icon;"
 
      // or, use a specific cssClass for each state, in an SCStatefulImgConfig block
      src: {
          _base: "sprite:usesvg:fileName.svg#icon-id;cssClass:icon;",
          Over: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconOver;",
          Down: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconDown;",
          Disabled: "sprite:usesvg:fileName.svg#icon-id;cssClass:iconDisabled;"
      }
  })
  

Developers can also override fill, stroke and stroke-width on a per usage basis, by specifying them directly in sprite-config src strings

  // apply settings in the sprite-config string - this modifies the style 
  // attribute, and will override presentation attributes on svg symbol elements
  isc.Img.create({
      src: {
          _base: "sprite:usesvg:fileName.svg#icon-id;fill:grey;",
          Over: "sprite:usesvg:fileName.svg#icon-id;fill:green;",
          Down: "sprite:usesvg:fileName.svg#icon-id;fill:lightgreen;",
          Disabled: "sprite:usesvg:fileName.svg#icon-id;fill:lightgrey;"
      }
  })
  

Some UI elements also provide default colors for SVG graphics - for example, an unstyled SVG used as the icon in a MenuItem will show skin-appropriate stateful colors automatically. MenuItem.icon is not itself a stateful attribute, but its colors will be inherited from the menu's stateful icon-field if not specified.

  isc.Menu.create({
      items: [
          { title: "Option 1", icon: "sprite:usesvg:fileName.svg#icon-id" }
      ]
  })