WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Publishing Images from the NetKernel Documentation System

There's a simple trick to accessing an image resource from your own module within a slideset (or indeed any NK document).

Make an entry for the image resource in your module's etc/system/Docs.xml file. Like this...

<docs>
  <doc>
    <id>doc:mymodule:some:image</id>
    <uri>res:/path/in/your/modules/space/to/your/docs-n-images/some-image.png</uri>
  </doc>
</docs>

The uri is the resources identifier within your modules address space. Note this does not have to be exported to the Front-End fulcrum - it only has to be resolvable and the same public rootspace as your other document resources.

This "document entry" will be aggregated into the set of all document id's and so be a known resource in the NK document system.

Doc Source Wormhole Service

The documentation system provides a useful public REST service /doc/source/[document identifier] which serves the raw binary stream of any specified document identifier in the doc system.

Its operational pattern is to lookup the full resource identifier for a given document id, it also discovers the resource's home address space. It then performs a wormhole request for the resource and serves it as a BinaryStream.

It follows that if you create an image link with this service as the URL - you can get direct wormhole access to images from deep inside your module.

Here's how we might embed "some-image.png" (as registered in the example entry above) in a slide (or document)...

{image}/doc/source/doc:mymodule:some:image{/image}

It follows that you can use this service directly as the URL in HTML image links too. Here's the same thing done with raw HTML...

{html} {/html}

Example

Here's an example that shows the readme install image, with id img:readme:install from the core system docs...

{image}/doc/source/img:readme:install{/image}

Here's the embedded image.

Content Type

This trick works for any bitmap images. But of course these are just binary stream resources coming from your module - so you can use the same trick for any resource - for example an SVG image (or even source code, zip files, you name it - anything that's a resource in your module that can provide a binary stream - even live services! Everything's a resource).

The service will relay through the mimetype of the resource you serve - but if you're serving exotic stuff then you can help browsers along by including the file extension as the end of the registered id. In which case the /doc/source resource will be a public url that ends with the file extension and so will provide a clue for a dumb browser.

Internal SVG reference

If you use the {svg} macro to reference embedded SVG resources then, since this service is inside the ROC domain it can go direct to the internal address of the wormhole service res:/doc/source/xxxx. There's no need to go outside to HTTP. So for example you'd do this..

{svg}res:/doc/source/doc:mymodule:some:svg:image{/svg}

Where the SVG would have a entry like this...

<docs>
  <doc>
    <id>doc:mymodule:some:svg:image</id>
    <uri>res:/path/in/your/modules/space/to/your/docs-n-images/some-vector-image.svg</uri>
  </doc>
</docs>

The demo slides show an example of this usage pattern.

The same might be true if you're serving live data resources from your module.