BT SVG Viewer

Embed large SVG diagrams in WordPress with zoom, pan, center, and authoring tools. Recent releases add a visual preset editor, icon-based controls, deeper shortcode options, and configurable button colors.

• Contents
• Installation
• Quick Start
• Shortcode Reference
  • controls_buttons Cheat Sheet
• Admin Preset Editor
  • Location
  • Fields
  • Preview Pane
  • Preset Shortcodes
  • Defaults Tab
• Using Presets in Posts/Pages
• Preview Workflow
• Examples
• Styling (CSS Hooks)
• Tips & Troubleshooting
  • SVG Preparation
  • Common Issues
  • Debugging
• Changelog Highlights (1.1.0)
• License & Credits

1. Unzip the plugin archive
   • Download bt-svg-viewer.zip.
   • Unzip it locally; you will get a folder named bt-svg-viewer.
2. Upload the plugin
   • Copy the entire bt-svg-viewer folder into your WordPress installation at /wp-content/plugins/.
3. Activate
   • In the WordPress admin, navigate to Plugins and click Activate on ???BT SVG Viewer???.

[svg_viewer src="/wp-content/uploads/diagrams/system-map.svg"]

• Place the shortcode in a classic editor, Gutenberg shortcode block, or template.
• The SVG renders with default height (600px), zoom controls, pan/scroll behaviour, keyboard shortcuts, and responsive layout. Zoom buttons now gray out at the minimum/maximum zoom to make the limits obvious to visitors.

Changing the interaction defaults automatically inserts a helper caption (e.g. ???Cmd/Ctrl-click to zoom in??????) above your custom caption so visitors know the gesture.

controls_buttons="MODE,ALIGNMENT,BUTTON_1,BUTTON_2,..."

Mode keywords (optional):

• both (default)
• icon
• text
• compact
• labels_on_hover
• minimal
• hidden / none

Alignment keywords (optional, anywhere in list):

• alignleft
• aligncenter
• alignright

Additional keywords:

• slider ??? replaces zoom buttons with a live-updating range input. Combine with icon/text/both for layout. Use custom:slider,zoom_in,zoom_out to show both slider and buttons.

Button names (pick any order):

• zoom_in, zoom_out, reset, center, coords (coords button only renders if show_coords="true")

Example:

[svg_viewer
  src="/uploads/system-map.svg"
  controls_position="right"
  controls_buttons="slider,icon,aligncenter,reset,center"
]

WordPress Dashboard ??? BT SVG Viewer ??? Presets

• Load / Refresh Preview: Injects the SVG using the current field values.
• Use Current View for Initial State: Captures the visible zoom level and center point from the preview and writes them back into the form (ideal for fine-tuning coordinates visually).
• Copy Center: When show_coords is enabled, the button copies coordinates to the clipboard.
• Zoom controls in the preview (and front end) now snap to their minimum/maximum, disable the corresponding buttons, and keep your pointer-focused zoom locked to the selected point???what you see in the preview is exactly what site visitors experience.

• At the top of the preset editor and in the presets list table you???ll find a copy-ready snippet in the form of [svg_viewer id="123"].
• Click Copy to put the shortcode on the clipboard without selecting manually.

• Visit BT SVG Viewer ??? Presets ??? Defaults to seed the fields used when creating a new preset.
• The panel now includes Enable asset cache busting for debugging, which appends a time-based suffix to scripts and styles. It is automatically active on hosts that start with dev. or wptest. and can be toggled manually when you need to defeat browser caching.

1. Create or edit a preset as described above.

2. Copy the generated shortcode ([svg_viewer id="123"]).

3. Paste into:

   • Classic editor (Visual tab: use Shortcode block or paste directly).
   • Block editor (Shortcode block or HTML block).
   • Template files via do_shortcode().

4. Override on a per-use basis if needed:

   [svg_viewer id="123" controls_buttons="icon,alignright,zoom_in,zoom_out"]
   

1. Load / Refresh Preview once the SVG path is entered.
2. Drag or scroll the SVG to the desired default view.
3. Use Current View for Initial State to stash those coordinates/zoom.
4. Optionally toggle show_coords to display the current x/y values of the viewport center.
5. Save/publish the preset and test the shortcode on the front end.

[svg_viewer src="/uploads/floorplan.svg"]

[svg_viewer
  src="/uploads/system-map.svg"
  height="100vh"
  controls_position="bottom"
  controls_buttons="compact,aligncenter,zoom_in,zoom_out,reset,center"
  zoom="175"
  min_zoom="50"
  max_zoom="400"
]

[svg_viewer
  id="42"
  controls_buttons="custom:slider,zoom_in,zoom_out,reset"
]

[svg_viewer
  src="/uploads/mind-map.svg"
  show_coords="true"
  controls_buttons="icon,alignleft,zoom_in,zoom_out,reset,center,coords"
]

[svg_viewer
  src="/uploads/campus-map.svg"
  button_bg="#2f855a"
  button_border="#22543d"
  button_fg="#ffffff"
  controls_buttons="both,aligncenter,zoom_in,zoom_out,reset,center"
]

Wrapper classes added by the plugin:

• .bt-svg-viewer-wrapper ??? outer container
• .bt-svg-viewer-main ??? wraps controls and SVG container
• .svg-controls ??? control bar
• .controls-position-{top|bottom|left|right}
• .controls-mode-{icon|text|both|compact|labels-on-hover|minimal}
• .controls-align-{alignleft|aligncenter|alignright}
• .bt-svg-viewer-btn, .btn-icon, .btn-text
• .svg-container, .svg-viewport, .coord-output, .zoom-display
• .zoom-slider-wrapper, .zoom-slider

Button colors are powered by CSS custom properties on the wrapper. Shortcode attributes and preset color pickers set these values, but you can override them manually:

.bt-svg-viewer-wrapper {
  --bt-svg-viewer-button-fill: #1d4ed8;
  --bt-svg-viewer-button-border: #1d4ed8;
  --bt-svg-viewer-button-hover: #1e40af;
  --bt-svg-viewer-button-text: #ffffff;
  --bt-svg-viewer-slider-width: 240px;       /* optional: tweak slider width */
}

Example overrides:

.bt-svg-viewer-wrapper.custom-map {
  border-radius: 12px;
  overflow: hidden;
}

.bt-svg-viewer-wrapper.custom-map .svg-controls {
  background: #111;
  color: #fff;
  gap: 6px;
}

.bt-svg-viewer-wrapper.custom-map .bt-svg-viewer-btn {
  background: rgba(255,255,255,0.1);
  border: 1px solid rgba(255,255,255,0.3);
}

.bt-svg-viewer-wrapper.custom-map .bt-svg-viewer-btn:hover {
  background: rgba(255,255,255,0.25);
}

• Remove hard-coded width/height if possible; rely on viewBox.
• Ensure the SVG renders correctly when opened directly in a browser.
• Compress large SVGs to keep loading snappy.

• Blank viewer: check for 404 on the SVG path, confirm the file is accessible without authentication.
• Scaling looks wrong: verify the SVG has an accurate viewBox.
• Controls disappear: check controls_buttons for hidden or empty button list.
• Clipboard errors: Some browsers require user interaction for Copy Center; the plugin falls back to a prompt.

• Toggle show_coords="true" or inspect window.svgViewerInstances['viewer-id'] to troubleshoot zoom, center, or scroll behaviour.
• Use the Defaults tab???s Enable asset cache busting for debugging switch if your browser clings to stale copies of the viewer script or styles.

• Pan/Zoom Interaction Modes: Shortcode and presets can now request pan_mode="drag" or zoom_mode="scroll" / click", with the front end auto-explaining gesture hints to visitors.
• Smooth Cursor-Focused Zoom: Wheel, slider, and modifier-click zoom animate between stops and keep the point under the pointer locked in place.
• Responsive Drag Panning: Dragging now tracks 1:1 with the pointer and ignores stray wheel events so diagonal swipes stay fluid.
• Dev-Friendly Cache Busting: The Defaults tab adds an ???Enable asset cache busting??? switch (also auto-enabled for dev.* and wptest.* hosts) to force fresh JS/CSS while testing.

Full changelog lives in the repository???s CHANGELOG.md.

• License: GPL-2.0 (same as WordPress).
• Built to make large interactive diagrams pleasant to navigate inside WordPress.