SVG Viewer Element
SVG Viewer elements render crisp, dynamic, clickable 2D images in your configurator as it runs on-screen. These images are called "scalable vector graphics" or SVGs.
About SVG Viewer Elements
SVG graphics are built from a block of text that describes the image in a human-readable way. When your configurator is run, that text description is processed by the user's web browser and the resulting 2D image appears on-screen inside the SVG element, like the pie chart here.
SVG Image Benefits
SVG images have a number of benefits:
-
Appear without pixelation.
Well-built SVG images are built from descriptions of mathematical shapes, drawn when needed. Since they are drawn in the browser itself, they can appear clearly with no jagged edges or pixelation, no matter how much you zoom into the image. -
Can update as your configurator updates.
Since these descriptions of mathematical shapes are simple text properties of the SVG Viewer element, you can use Snap rules to update those properties real-time. Your image can change with every click your user makes, or at specific moments you specify. It's all up to you and the Snap rules you write. -
Can zoom in and out.
The image size is not directly linked to the size of the SVG viewer element. Your user can zoom in to areas of detail. -
Can include clickable and draggable areas.
If you give any shape in the image an ID, then a user clicking on that shape creates an event you can catch and use. With a click rule associated with the SVG Viewer element, you can send that information into the configurator, where you can use it like any other input from the user. Dragging events can allow you to detect and respond to moving the mouse while the button is depressed for better user interaction.
Common uses for SVG images
SVG images in a configurator can help to:
- express a complex concept with an easy-to-understand 2D visual. For example, take a PDF line drawing, convert it to an SVG, and show that SVG within your configurator.
- add your own UI "widgets", like pie charts, dials, or other ways to gather and express complex information.
- make any part of the SVG image interactive, so your configurator can react to a click or drag just like it would react to a button click.
To learn about creating SVG graphics, try one of many free online sources. Usually, you would create an SVG graphic using a design tool, or from an existing SVG file, and paste the resulting SVG text into your SVG element or use the SVG text in Snap code. Rarely would you write all the text-based description of an SVG image from scratch.
SVG Viewer Element Properties
Remember that any of these properties (usually, the "value" property) can be modified run-time through Snap rules. Snap offers many ways to manipulate text.
| Property | Description |
|---|---|
| Name | A name which is appears in the design tree and can be used in rules. The name must be unique within the configurator. |
| Visible | Specifies whether this element and its contents are shown to the user by default or not. This property can be changed in the visibility rules. |
| Definitions | Definitions, or "Defs", can describe reusable portions of your image, such as a color gradient with specific colors, a filter with a blur effect, or other such manipulations. Rather than repeating the same description of an SVG element over and over, that portion of the image can be described as a definition with a specific ID. This makes the repeating portion easy to re-use many times, and makes your SVG image easy to maintain. |
| Value | The actual code of the SVG. If you want your image to be dynamic, you would use a Snap rule to write this value dynamically during run-time. |
|
Min Zoom Max Zoom Zoom Level |
Use these 3 parameters to control how the SVG element responds to zoom commands from the user. Depending on the user's device, these zoom commands come from the mouse (rolling the scroll wheel towards/away) or touch gestures (pinching/spreading). Set the minimum allowed zoom level, the maximum, and the default zoom level which is used when the element is first rendered on-screen.
|
| Disable Mouse Wheel Zoom | By default, rolling the mouse wheel can control the zoom. Disable the mouse wheel by setting this checkbox. |
| Disable Drag Panning | By default, holding the scroll wheel (specifically, the third mouse button) allows the user to pan the image within the viewer. Disable panning by setting this checkbox. |
| SVG Viewbox Width & Height |
The dimensions of the entire SVG Viewer element itself in your user interface. These parameters are the actual space shown on-screen. Units: % or px |
|
Width Height |
The dimensions of the image canvas (the logical area where items can be drawn). Any items drawn outside the canvas dimensions will not appear in the image. Note that the canvas size does not have to equal the size of the viewer: it is usually scaled automatically to fit within the viewer, which the user can then zoom or pan to adjust. Units: % or px |
| SVG Style | Define any CSS properties for elements in the SVG. |
Examples
Example 1: a basic static image
| Property | Example |
|---|---|
| Definitions | none |
| Value | <ellipse cx="100" cy="70" rx="85" ry="55" fill="black" /> <text fill="#ffffff" font-size="32" font-family="Verdana" x="25" y="82">Company</text> |
| SVG Style | none |
Example 2: using definitions
| Property | Example |
|---|---|
| Definitions |
|
| Value |
<linearGradient id="blue_fade" x1="0%" y1="0%" x2="100%" y2="0%">
<stop offset="0%" style="stop-color:rgb(8, 72, 96); stop-opacity:1" />
<stop offset="100%" style="stop-color:rgb(119, 221, 217);stop-opacity:1" />
</linearGradient>
|
| SVG Style | none |
Example 3: dynamic SVG images
Since the properties of the SVG are simply text, you can create a rule to update that text, then write it into the SVG Viewer element's "value" property or other properties. For example, consider this new version of Example 1 above, where the SVG Viewer element is named "mySvgViewer". The format text block replaces the dynamic portion of the SVG.
Example 4: using styles
Use CSS styles to give a hover effect to elements within the SVG.
| Property | Example |
|---|---|
| Definitions |
<style>
.Chassis {fill: #ff0000; }
.ChassisSlot {fill-opacity: .1;}
.ChassisSlotSelectable {fill-opacity: .3;}
.ChassisSlotSelectable:hover {fill-opacity: .8; stroke: rgb(52,152,220); stroke-width: 2; cursor: pointer;}
</style>
|
| Value |
<g class="Chassis">
<rect id="Chassis01" class="ChassisSlot" x="10" y="10" width="30" height="75" ></rect>
<rect id="Chassis02" class="ChassisSlotSelectable" x="50" y="10" width="30" height="75"></rect>
<rect id="Chassis03" class="ChassisSlotSelectable" x="90" y="10" width="30" height="75"></rect>
</g>
|
| SVG Style | none |
Example 5: saving clicks
Extend the previous example by adding an SVG Viewer Rule. If an SVG Viewer Element has a rule associated with it, then that rule will be run whenever the SVG element is clicked. In this rule, you can use the Get block to find the id of the element clicked, and then use it (such as save it to a field, where the update to the field will trigger the full rule cycle and all logic in your confgurator).
For example:
- Create a new text field. Here, we name it "LastClicked" with a field label of "Last SVG element clicked".
- Create a new rule for your SVG viewer element (click the "+" symbol next to the SVG Viewer Element in the design tree: a new rule will appear).
- Add logic that should be run only when this element is clicked. The "get" block in the context of a SVG Viewer Rule has options not found in other contexts, such as elementId:
- Watch the rule run with each click on the SVG. In the animation below, the yellow dot represents a click.
SVG Viewer Events
Click
When one clicks their mouse on the SVG Viewer, it will invoke this rule. The rule is aware of the cursor position and the id of the element within the SVG that was directly clicked on, if any id was set. See the example above.
Unlike most other UI events, this event does not invoke a rule cycle. However, if the click event sets the value of a field, the rule cycle is run due to the field update.
While 90% of all interactivity with an SVG is best performed with the click event, other events are also available. Before using these other events, consider how they would be performed on mobile or touch devices.
Drag Start
As part of the full 'drag' event functionality for an SVG Viewer, this will be invoked as soon as a user depresses their mouse button in the SVG. A variable, 'commitDrag' is injected which needs to be set to 'true' if the subsequent drag events should be invoked. Otherwise, if this is set to its default 'false' value dragging will instead invoke the default panning functionality if panning is enabled. In addition, there are variables that has the cursor position stored.
Unlike most other UI events, this event does not invoke a rule cycle.
Drag Move
If the user depressed their mouse and the 'drag start' rule had set 'commitDrag' to true, this rule will be invoked repeatedly as the user moves the mouse. In addition, there are variables that has the cursor position stored (as well as the original cursor position representing where the cursor was when the user first depressed the mouse button).
Unlike most other UI events, this event does not invoke a rule cycle.
Drag End
When the user releases the mouse button, if the drag start rule had set 'commitDrag' to true, this rule will be invoked. There are variables that has the cursor position stored (as well as the original cursor position representing where the cursor was when the user first depressed the mouse button). Upon drag end, this will invoke a rule cycle, allowing one to set whatever fields are necessary that resulted from the overall action of a user depressing the mouse button, moving the mouse around, and then releasing the mouse button.
While we invite innovative use of this element, be aware that...
- The use of some SVG features which work today may be disabled in the future if they cause performance, usability, or security problems. Subscribe to our release notes to watch for updates, and use our preview site to test platform updates safely.
- The Epicor CPQ platform works across all modern browsers and devices. (from mobile devices to tablets to desktops). Your SVG may not. You should carefully test your SVG code on all of those browsers and devices as well, to prevent any surprises when you deploy your new code.
- If you plan on using your SVG image not only on-screen, but also as an output document, test your SVG code in both on-screen and output contexts.
- Epicor CPQ is built on Snap, our easy-to-use visual language. We cannot support or troubleshoot questions you may have in other languages you use alongside or within Epicor CPQ, such as SVG or CSS.
Related Topics
- You can learn more about manipulating text with Snap.
- SVG graphics can also be used in output documents.
Position
Container-based position properties appear for this interface element when it is placed within a container, giving you more control over it's position. If you place this UI element within a container, the following properties will appear. Remove it from the container, and these properties will disappear. Furthermore, the actual position properties themselves change, depending on that parent container's Item Layout.
- Not seeing any of the "Position" properties below for this UI element?
Place this element into a container, and then return to this element's properties list. The "Position" accordion will now appear in the properties list.
- Not seeing the right kinds of "Position" properties for this UI element?
Change the parent container's item layout to horizontal, vertical, or absolute. Then return to this UI element. The position properties available for items within that layout (marked by green checkmarks below) will appear.
| Property | Available in a horizontal layout | Available in a vertical layout | Available in an absolute layout | Available in an absolute layout |
|---|---|---|---|---|
Relative Size |
When using relative sizes, try setting all items within the container to the relative size of "x1" as a starting point, and then adjust the xN levels as necessary. Mixing items with "auto" and "xN" settings is allowed, but may be difficult to manage. |
|||
Alignment |
Controls how this item within a container is aligned in the cross axis of the container's layout.
|
|||
|
Left Top Right Bottom Width Height |
The distance between the edge of the parent container and this element. By default, each is "auto". Usually, you would set only 2 of these properties, leaving the rest to "auto", or you may distort this image or element. For example, to align an item's upper-right corner to the upper-right corner of the parent container, set "Top" to 0px, and "Right" to 0px, leaving all other distances to "auto". |
|||
Opacity |
The visibility of items or backgrounds behind this item. Use any decimal number from 0 to 1. Set to 0 to make this item completely transparent. Set to 1 to make the item completely opaque. |
|||
Order |
Specifies the order in which this item is drawn in the container. Use a whole number, such as 0 or 132. Default: 0. Larger numbers are drawn later, and appear closer to the user.
|
|||
| Use Zero Padding | By default, UI elements have some padding around them for legibility on all devices, and for ease of use on touch-enabled devices. However, in some cases you may want specific UI elements to have no padding around them at all (to touch each other). This can be useful to create a portion of your UI which needs a very high information density. For example, to create a grid of fields that appear like cells in a spreadsheet. |