DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:svgembed

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
plugin:svgembed [2019-06-22 00:58] – [Uploading SVG files via Media Manager] Restlessplugin:svgembed [2023-12-06 21:25] (current) – [svgEmbed Plugin] Restless
Line 2: Line 2:
  
 ---- plugin ---- ---- plugin ----
-description: Allows the use of the standard media syntax, but SVG files are placed with the <embed> tag, not the <img> tag. +description: Allows the use of the standard media syntax (with some extensions), but SVG files are placed with the <object> or <embed> tag, not the <img> tag 
-author     : Michael Bowers +author     : Emma Bowers 
-email      : restlessmind@gmail.com +email      : emb@pobox.com 
 type       : helper, syntax type       : helper, syntax
-lastupdate : 2019-06-22 +lastupdate : 2021-06-09 
-compatible : Greebo+compatible : Igor, Hogfather, Greebo, Jack Jackrum 
 depends    :  depends    : 
 conflicts  :  conflicts  : 
 similar    :  similar    : 
-tags       : svg, media, images, image+tags       : svg, media, image, images, diagram
  
 downloadurl: https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/archive/master.zip downloadurl: https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/archive/master.zip
-bugtracker : # eg. http://github.com/Restless/dokuwiki-plugin-svgembed/issues+bugtracker : https://github.com/restlessminded/dokuwiki-plugin-svgembed/issues
 sourcerepo : https://github.com/restlessminded/dokuwiki-plugin-svgEmbed sourcerepo : https://github.com/restlessminded/dokuwiki-plugin-svgEmbed
 donationurl:  donationurl: 
  
-screenshot_img : +screenshot_img : https://www.w3.org/Icons/SVG/svg-logo-h.svg 
 ---- ----
 +
 +===== Requirements =====
 +
 +PHP 7+ and [[https://www.php.net/manual/en/book.libxml.php|libxml libraries]] required.
 +
 +==== Compatibility with Igor release candidates ====
 +
 +As of this writing (June 27, 2022), this plugin is compatible with the Igor RC2 release without changes.  It is my aim to keep it compatible since, although Dokuwiki supports SVG in that release, it still uses the ''<img>'' tag and so it will not make use of embedded links.  Further, I intend to refactor it somewhat for a couple of requests and a bug report on the Github, but its number has not come up yet.
  
 ===== Installation ===== ===== Installation =====
  
 Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually. Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.
 +
 +
 +===== Configuration =====
 +
 +Under the "Configuration Settings" page in the admin panel, the plugin has a section with a few values:
 +
 +^        Setting name ^ Description ^  Default value  ^
 +| **max_svg_width**   | Maximum width for SVG file size if no sizes are specified in the wiki page. |  1024  |
 +| **default_width**   | Default fall-through width of an SVG file. |  300  |
 +| **default_height**  | Default fall-through height of an SVG file. |  150  |
 +| **default_print**  | Make all SVG files in your wiki have a print button. ([[#printing_svgs|About printing]]) |  False  |
 +
 +See below for discussion about how these values interact with your SVG file for display.
 +
  
  
 ==== Uploading SVG files via Media Manager ==== ==== Uploading SVG files via Media Manager ====
  
-As of this writing, DokuWiki does not allow you to upload SVG files by default,  This plugin will only embed SVG files that are uploaded to the wiki via the Media Manager for security's sake.  To do this, you may need to create or edit the ''mime.local.conf'' file for your wiki by adding this line:+As of this writing, DokuWiki does not allow you to upload SVG files by default.  This plugin will only embed SVG files that are uploaded to the wiki via the Media Manager for security's sake.  To do this, you may need to create or edit the ''mime.local.conf'' file for your wiki by adding this line:
  
 <code - conf/mime.local.conf> <code - conf/mime.local.conf>
Line 42: Line 65:
  
 <code> <code>
-{{:some:ns:myfile.svg?<arguments>|<Title>}}+{{:some:ns:myfile.svg?<Arguments>|<Title>}}
 </code> </code>
  
-The SVG will be placed into your wiki page via an <embed> tag rather than an <img> tag.  This allows for things such as elements with hyperlinks in the SVG to be clickable, etc., whereas embedding SVG as an image does not.  (Note that this depends on support in your browser.)+The SVG will be placed into your wiki page via an ''<object>'' or ''<embed>'' tag rather than an ''<img>'' tag.  This allows for things such as elements with hyperlinks in the SVG to be clickable, etc., whereas embedding SVG as an image does not.  (Note that this depends on support in your browser.)
  
 +
 +==== Arguments ====
 +
 +There are a number of arguments you can use.  These include:
 +
 +  * [[:wiki:syntax#media_files|The normal image formatting arguments for media files]], although there are some [[#formatting|caveats and modifications documented below]]
 +  * [[#setting_responsive_units|Setting responsive units]] instead of normal ''px'' "pixel" units that DokuWiki normally uses
 +  * [[#additional_css_classes|Adding additional CSS classes]] to the SVG file
 +  * [[#printing|Printing]] SVGs from the page
 +
 +=== Formatting ===
 +
 +When you specify a width and height for your image in your media link in the wikitext, it should do its best to render at that size, as long as the width is the same or less than the maximum set for SVG files.  If it is greater than the defined maximum then it will render the SVG file with the maximum width and scale the height proportionally.
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg?800x600|}}</code> will render the file at 800x600, although the height may vary based on requirements passed by the SVG rendering engine to keep the aspect ratio correct.
 +
 +If you do not specify any size information in your media link the SVG file will be inspected to determine the dimensions (subject to scaling if above the maximum width, as above).
 +
 +  * If the ''width'' and ''height'' attributes are set, then those will be used for the image.  If your ''width'' or ''height'' attributes are in an [[https://www.w3.org/TR/css-values-3/#absolute-lengths|absolute length unit]] the XHTML output will be scaled for 96 DPI (screen viewing).
 +  * If they are not available but the ''viewBox'' attribute is set then it will be parsed to get the dimensions.
 +  * If neither is available, the defaults specified in the admin panel is used.
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg|}}</code> will render the file using the embedded dimensions, but with a maximum width configured by the admin.  If the SVG file does not have dimensions in it that can be determined it will use default values specified by the admin.
 +
 +If you specify only a width (as you can for an image) in your media link this actually sets a new maximum width for that embedding of the SVG file only.  It will determine the size to render at from the SVG file as above.
 +
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg?2000|}}</code> will render the file using the embedded dimensions, but with a maximum width of 2000 pixels.
 +
 +
 +=== Setting "responsive" units ===
 +
 +If you use ''units:<unit>'' as a parameter, you can call for "responsive" units for an image.  This allows the SVG file to resize automatically based on the user's browser, and resize automatically.  These override the normal pixels that are normally used in Dokuwiki layout.  These are called in conjunction with the normal width specification for a media file.
 +
 +There are two options that can be specified for the unit type:
 +
 +^ Unit type  ^ Notes  ^
 +| **%**      | **Percentage width.**  This sets the width of the SVG image to a fixed percentage of the available space.  |
 +| **vw**     | **Viewport units.**  This sets the width of the SVG image to a number of viewport units equal to the media file width specified.  |
 +
 +This tag will use percentage width:
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg?20&units:%|}}</code> will render the file using 20% of the width available.
 +
 +
 +This tag will use the viewport width:
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg?20|units:vw}}</code> will render the file at 20% of the size of the viewport region width.
 +
 +
 +=== Additional CSS classes ===
 +
 +You can also add additional CSS classes to your SVG file to change the style on it.  You do this with ''class:<classname>''.  This parameter may be called more than once to add more than one class.
 +
 +For example, to add the CSS classes ''redborder'' and ''bluecircle'' you could do the following:
 +
 +> <code - Example>
 +{{:some:ns:myfile.svg&class:redborder&class:bluecircle|}}</code>
 +
 +
 +=== Printing ===
 +
 +Printing of individual SVG files from the page has been implemented.  Please see the [[#printing_svgs|section on printing]] for configuration or arguments to allow for this.
 +
 +
 +
 +
 +
 +
 +==== Links in SVG files ====
 +
 +The SVG file isn't just an image, but rather it's another document.  It's contained within the tag that embeds it into the page.  As such, if you open a link in your SVG file without a target specified, it will open within the bounds of the embedded SVG document.  This is by design.
 +
 +If you want a link to open full-page, you should specify the ''target'' attribute on your links in your SVG file.  In particular, if you specify the ''_top'' target then your links will open in the current page at the top level.
 +
 +**Visio produced SVG files**
 +
 +You can produce an SVG from Visio however it doesn't populate the title tag with anything useful so the link will just show something meaningless on hover, it is made worse if your shape is a 'group'since each item in the group will have a 'title'. The basic workflow from Visio is as follows:
 +
 +In Visio:
 +  - Draw and save the Visio diagram.
 +  - Add hyperlinks to the shapes - this means the item (the linked to page or image) must exist on the wiki , or use a placeholder; use the full URL and populate the description field (this becomes the xlink 'title).
 +  - For the given diagram select all the shapes then Save As an SVG and untick the Visio properties (can set as a general option in settings) as they simply add bulk.
 +
 +
 +In a text editor (e.g. Notepad++):
 +  - If you have added hyperlinks search for 'xlink' then add a target tag (see example below), sadly It seems there is no way to force this in Visio which means you need to edit the SVG file on every revision.
 +  - To solve the 'title' issue remove extraneous Alt text: find all lines with the title tag (Regex would be <title>(.*?)</title>) replace with nothing. If you don't do this then hovering over any shape will show meaningless titles like 'Sheet.235' which is no help to anyone, and removing title doesn't seem to have any untoward consequences. Note it doesn't change the xlink titles you created when entering the Description field in the hyperlinks.e
 +  - Save the file.
 +
 +In the Wiki:
 +  - Upload
 +  - Add to a page using SVGEmbed
 +
 +//Example and notes//
 +
 +  * The links must exist or be known prior to existence so that you can edit them in the Visio produced SVG file. 
 +  * Always used the full URL in the link
 +  * The SVG xml code for the hyperlink will look something like this once edited:
 +
 +<code>
 + xlink:href="http://mysite.com/doku.php?id=ns:mypage"
 + xlink:title="My Page Title"
 + target="_top">
 +</code>
 +
 +The target value of "_top" must be added to ensure that the link opens in the current page properly (or use an other target tag value).
 +
 +
 +
 +==== Malformed or unusual SVG files ====
 +
 +If your SVG file does not have dimensions specified in ''width'' and ''height'' or ''viewBox'' attributes then it can still be rendered, but scaling is handled by the browser's engine.  In most cases this means that whatever dimensions are set in the wikitext or calculated by the plugin only renders a viewport on the file so it may be clipped in undesirable ways.
 +
 +You may be able to fix this by loading the file into an SVG-capable editor (such as [[https://inkscape.org|Inkscape]]) and setting a size or even saving the file and letting it impose one on it.
 +
 +
 +==== Printing SVGs ====
 +
 +Often you may want to include SVG files in your wiki but want to be able to make them printable by users (org charts, data center configurations, maps, etc.).  When an SVG file is printable you will see a small button below the picture in the wiki that, upon clicking, will open a popup with the SVG file in and automatically call for the file to be printed (tested in Google Chrome and Mozilla Firefox).
 +
 +You may set this in a couple ways:
 +
 +  - Affirmative printing:  you may make all SVG files printable by default globally in the admin Configuration Settings panel under the svgEmbed plugin section.  If the ''default_print'' box is checked, all SVG files placed by this plugin will be considered printable unless disabled in the wikitext.
 +  - Selective printing:  you may decline to make all SVG files printable by default globally in the admin Configuration Settings panel under the svgEmbed plugin section.  If the ''default_print'' box is unchecked, no SVG files placed by this plugin will be considered printable unless explicitly configured in the wikitext.
 +
 +To configure the wikitext, you can include the argument ''print:<setting>''.
 +
 +^  Setting  ^ Configuration setting  ^
 +|  Enable   | One of:  1, true, yes, on  |
 +|  Disable  | One of:  0, false, no, off  |
 +
 +Additionally, as a special case, the default meaning of the naked argument ''print'' with no setting value is the equivalent of enabled.
 +
 +//Examples://
 +
 +  - To set an SVG for printing: ''%%{{ :my:svg:file.svg?print:true |Test!}}%%''
 +  - To set an SVG to suppress printing (if configured to make all SVGs printable):  ''%%{{ :my:svg:file.svg?print:false |Test!}}%%''
 +
 +Of course, these arguments can be combined with any other arguments this plugin accepts.
 +
 +
 +
 +=== Styling SVG print button ===
 +
 +The class for the SVG printing button is ''svgprintbutton_table'', and the SVG itself is wrapped in ''svgembed_print_border''; on my particular wiki using the [[template:monobook|Monobook]] template I am styling using the following CSS:
 +
 +<code css>
 +/* SVG printing button */
 +.dokuwiki div.svgprintbutton_table button {
 +  font-family: Arial, sans-serif;
 +  background: transparent;
 +  border-top: none;
 +  border-left: 1px dashed #ccf;
 +  border-right: 1px dashed #ccf;
 +  border-bottom: 1px dashed #ccf;
 +  border-radius-bottom: 4px;
 +  color: #ccc;
 +  font-size: 80%;
 +  padding: 3px;
 +}
 +
 +.dokuwiki div.svgprintbutton_table:hover button {
 +  border-left: 1px solid #fcc;
 +  border-right: 1px solid #fcc;
 +  border-bottom: 1px solid #fcc;
 +  color: #f99;
 +}
 +
 +.svgembed_print_border {
 +  background: rgba(0, 0, 0, 0.1);
 +}
 +</code>
 +
 +With this code I get a small button that is dim when normal, slightly grey-pink when hovered, and while it's hovered the JavaScript for this plugin triggers the last set of rules to slightly darken the background of the SVG file to show what would be printed if the button is pressed.
 +
 +==== Export to PDF with DW2PDF ====
 +
 +Export with [[plugin:dw2pdf|DW2PDF]] is now supported.  For this functionality ''<img>'' tag is used for output since the [[https://mpdf.github.io/html-support/html-tags.html|documentation for mPDF's HTML support]] specifies that ''<embed>'' and ''<object>'' are not supported tags for rendering to PDF.
 +
 +Unfortunately, due to this it means that links in SVG files cannot realistically be supported in the PDF output.
 +
 +This may not be in final form.  Further testing is needed, but does not affect anything if you are not using DW2PDF.
 +===== Development =====
  
 === Change Log === === Change Log ===
  
 +  * **2021-06-09**
 +    * Added initial support for [[plugin:dw2pdf|DW2PDF plugin]] ([[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/9|GitHub issue #9]]).  See [[#export_to_pdf_with_dw2pdf|the section on this]] for more information.
 +  * **2020-06-07**
 +    * Made change to make compatible with Hogfather RC2.
 +  * **2020-06-05**
 +    * Changes to fix [[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/6|issue #6]], an enhancement request to support responsive images.  I added new parameters that allows a user to set responsive (''%'' and ''vw'') units instead of the default ''px'' units.  At the same time, I added another parameter to support adding CSS classes to the SVG image.
 +  * **2020-05-12**
 +    * Changes to fix [[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/5|issue #5]] from Github.  Alterations to handle dimensions from SVG files that use [[https://www.w3.org/TR/css-values-3/#absolute-lengths|absolute length units]].  This is resolved.
 +  * **2020-01-17**
 +    * Updated to embed the SVG with an ''<object>'' tag rather than an ''<embed>'' tag, and use ''<embed>'' as a fall-through.  Should support more browsers and give more options to style or extend in the future.
 +  * **2019-11-26**
 +    * Changes to fix [[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/3|issue #3]] from Github; I wasn't handling metadata rendering so the media manager didn't know if a file was in use or not.  This is resolved.
 +  * **2019-11-25**
 +    * Changes to fix Github issues [[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/1|#1]] and [[https://github.com/restlessminded/dokuwiki-plugin-svgEmbed/issues/2|#2]].
 +  * **2019-07-10**
 +    * Change to fix conflict with [[plugin:imagemap|Imagemap]] plugin.
   * **2019-06-21**   * **2019-06-21**
     * Initial release     * Initial release
 +
 +
 +=== Limitations ===
 +
 +SVGZ (compressed SVG) files are not supported because of the way the plugin operates.  This does not limit DokuWiki functionality since, technically, it doesn't support SVGZ either.
 +
  
 === Known Bugs and Issues === === Known Bugs and Issues ===
  
-None.+  * Currently, SVG file positioning may be an issue with the DW2PDF integration.  I will be working on this at a future date.
  
-===== Discussion =====+If you find a bug, please [[https://github.com/restlessminded/dokuwiki-plugin-svgembed/issues|submit a bug]] at the [[https://github.com/restlessminded/dokuwiki-plugin-svgembed|project's github]].
  
  
 +===== Discussion =====
 +
 +> <del>Great plugin! But I have two points that could be optimized:</del>
 +> <del>When printing a page with SVG file, the SVG image is greatly reduced in size.</del>
 +> <del>The section edit function gets a bit confused when this section contains an SVG image.</del>
 +> <del> --- [[user>juergen_aus_zuendorf|Juergen_aus_Zuendorf]] //2019-11-25 16:13//</del>
 +>> <del>I see your issues you submitted on the github page.  Thanks for the heads up!</del>
 +>>
 +>> <del>What browser are you using?  Are you setting width and height on the SVG images?  I don't have the problem with scaling when printing if I set a width and height on the image in Chrome or Firefox.</del>
 +>>
 +>> <del>I have confirmed your other issue reported on github regarding flickering when you try to edit a section; that one is confusing, I'm going to have to look into that one some more.  I have seen it with some other plugins and certain stylesheet alterations, too.</del>
 +>> 
 +>> <del>--- [[user>Restless|Emma Bowers]] //2019-11-25 19:11//</del>
 +>>> <del>I think these issues are fixed in my latest commit.  Please update and test.</del>
 +>>>  <del>--- [[user>Restless|Emma Bowers]] //2019-11-26 01:55//</del>
 +> <del>One more thing: The media manager indicates that the SVG file is not in use. Therefore, there is a certain danger that it will be accidentally deleted. \\  --- [[user>juergen_aus_zuendorf|Juergen_aus_Zuendorf]] //2019-11-26 12:54//</del>
 +>> <del>You are a harsh taskmaster... and I appreciate it!  :-)</del>
 +>>
 +>> <del>I'll get on it when I get to the office.</del>
 +>>
 +>>  <del>--- [[user>Restless|Emma Bowers]] //2019-11-26 14:56//</del>
 +>>
 +>> <del>Fixed it in a new commit.  Let me know what else you may find!</del>
 +>>
 +>>  <del>--- [[user>Restless|Emma Bowers]] //2019-11-26 22:32//</del>
  
  
plugin/svgembed.1561157880.txt.gz · Last modified: 2019-06-22 00:58 by Restless
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links