Export layout customization will be done through project-specific plugins which can cater to their individual export image requirements. An export plugin is expected to take over the mid-point of the image generation process during export.
Unlike table plugins, an export plugin does not have any UI component (except for possible options added to the export settings panel) and reuses the default export dialogue. Also, an export plugin is not involved in the last stage of merging separate images into a single export file (this includes checking for tainted canvases according to the config options and providing feedback to the user if the image cannot be saved automatically).
This is intended to simplify development of export plugins, since they don't need to generate their own UI (which generally should stay generic) and deal with tainted images. This, however, does not preclude a plugin develop from disabling the default export functionality and writing a full-replacement export plugin with its own custom UI dialogue and image fusion logic.
- An export plugin (plugin) registers with RAMP on map load
- Export is triggered by a user or through the API
- The export service detects the presence of a plugin and halts the default process
- The export service passes the
exportComponentsService
to the plugin - The plugin can modify the
exportComponentsService
which is by default controlled through the config- The plugin can add or remove any of the default export components (title, map, mapElements, legend, textblock (new component), timestamp)
- The plugin can modify the configurations of component (for example, specifying legend width and desired column width; or modifying the existing legend structure (map.legendBlocks) to exclude/include certain layers)
- The plugin can add new, custom generators to the
exportComponentsService
- The plugin can reorder the components to control the image overlap, if necessary
- The plugin executes the
exportComponentsService
to generate export images for corresponding components - The plugin returns the full size of the export image (this is the size of the canvas where all component images will be placed) to export service
- The plugin returns the generated images to the export service along with their x,y pixel coordinates relative to the full canvas (which creates the desired layout) for the final merging
- The export service displays images in the export dialog
- The user is satisfied and triggers the download
- The export service merges the images into a single canvas and attempts to auto-save the file (depending on the
cleanCanvas
setting it might be impossible if any of the images are tainted)
Right now, we only have a footnote text generator which is a plain text generator. We think that the HTML to Canvas library should be able to handle any simple HTML (and maybe even complex HTML, but plugin authors need to ensure the end result matches their expectations) and that we can build a generic text block generator to replace the footnote generator. An export plugin can use it several times to generate several text blocks and place them in different sections of the final export image.
Plugins can either import that library themselves or it can be provided internally.
A plugin can add a function returning an SVG/canvas wrapped in a promise to the exportComponentsService
to include any arbitrary image (like a watermark or a logo) into the final export image.
- Even though the export service is going to perform the final merging of export images, this does not stop an export plugin from merging images by itself and just returning a single canvas to the export service to "merge" again.
- The order in which a plugin returns component images should be bottom-up - it's easier to figure out what overlaps what in this case, I think. Overlapping of components could be intentional, like when you want your two-layer legend to be displayed on top of the map image, or if you want the scale bar/north arrow to be rendered on the map.
- By default, the export dialog will give the user an option to turn on/off certain export components (based on the config settings). The same behaviour should apply to any custom generators added by a plugin, unless explicitly prohibited.
- Create a generic Text-Block generator
This is important. If we cannot reliably convert HTML into SVG/canvas, we would need to keep the plain-text generator and make export plugins responsible for any fancy text blocks they want to add to the final export image (conceivably, they can do it through the custom generators, but it will be more effort for plugin developers).
-
Allow export plugins to register with the Export Service
-
Modify the Export Service's default logic to invoke an export plugin if present and accept returned component images (including the overall canvas size and components' relative coordinates)
-
Ensure users are still able to interact with certain components like the
title
component through (or custom component created by a plugin, like a text field), if required -
Modify the
exportComponentsService
to accept new custom generators and changes to the existing service configuration (which generators should be used and in what order) -
Modify the legend export generator to accept legend with/column number configurations as well as the legendBlocks collection from the plugin
-
Create a sample export plugin (CCCS request) which renders the map and legend side-by-side and a text blurb underneath
- A Text-Block generator creates a close-enough representation of the source HTML code
- An export plugin can be registered with RAMP and is activated when the export functionality is engaged
- An export plugin accepts the
exportComponentsService
and returns- the overall canvas size
- individual export SVG/canvas images with relative pixel coordinates
- It is still possible for users to interact with export components like the
title
and modify them - Snacks for all dietary restrictions are available in the web-mapping pod