Background fill color via --bg or svgtiler.background (fix #57)

README.md

@@ -348,6 +348,13 @@ The top-level code of your .js or .coffee mapping file can also call:
   overall size of the rendered drawing.
   During the callback, `render` has properties about the rendering's
   bounding box: `xMin`, `xMax`, `yMin`, `yMax`, `width`, `height`.
+* `svgtiler.background(fillColor)` to set the default background color
+  for the SVG drawing (implemented via a `<rect>` underneath the bounding box).
+  Roughly equivalent to
+  `svgtiler.afterRender((render) => <rect fill="white" z-index="-99999" x={render.xMin} y={render.yMin} width={render.width} height={render.height}/>`.
+  You can also call `svgtiler.background` within a tile definition function or
+  a `beforeRender`/`afterRender` callback to set the background dynamically,
+  or set the global default via the `--bg`/`--background` command-line option.
 
 Like other [NodeJS modules](https://nodejs.org/api/modules.html),
 .js and .coffee files can access `__dirname` and `__filename`,
@@ -819,6 +826,7 @@ Optional arguments:
   -m / --margin         Don't delete blank extreme rows/columns
   --uneven              Don't make all rows have same length by padding with ''
   --hidden              Process hidden sheets within spreadsheet files
+  --bg BG / --background BG  Set background fill color to BG
   --tw TILE_WIDTH / --tile-width TILE_WIDTH
                         Force all symbol tiles to have specified width
   --th TILE_HEIGHT / --tile-height TILE_HEIGHT

examples/chess/map.coffee

@@ -20,9 +20,11 @@ read = (filename) ->
   #  {dom.props.children}
   #</symbol>
 
-svgtiler.afterRender (render) ->
-  <rect fill="white" z-index="-2"
-   x={render.xMin} y={render.yMin} width={render.width} height={render.height}/>
+svgtiler.background 'white'
+## Equivalent:
+#svgtiler.afterRender (render) ->
+#  <rect fill="white" z-index="-2"
+#   x={render.xMin} y={render.yMin} width={render.width} height={render.height}/>
 
 [
   background

examples/chess/map.jsx

@@ -11,10 +11,12 @@ function read(filename) {
   return dom.props.children;
 }
 
-svgtiler.afterRender((render) =>
-  <rect fill="white" z-index="-2"
-   x={render.xMin} y={render.yMin} width={render.width} height={render.height}/>
-);
+svgtiler.background('white');
+// Equivalent:
+//svgtiler.afterRender((render) =>
+//  <rect fill="white" z-index="-2"
+//   x={render.xMin} y={render.yMin} width={render.width} height={render.height}/>
+//);
 
 (key, context) => {
   // Map blanks to empty string

examples/tetris/Makefile

@@ -1,5 +1,5 @@
 all: txt coffee
 txt:
-	svgtiler -f -P NES_level7.txt example.asc
+	svgtiler -f -P --bg black NES_level7.txt example.asc
 coffee:
 	svgtiler -f -P NES_level7.coffee example.asc

examples/tetris/NES_level7.coffee

@@ -7,9 +7,13 @@ kind =
   L: 'other'
   Z: 'other'
 
+svgtiler.background 'black'
+
 (key) ->
   if key.trim() == ''
-    <rect fill="black" width="8" height="8"/>
+    # allocate space for black background instead of lots of tiny rects
+    <symbol width="8" height="8"/>
+    #<rect fill="black" width="8" height="8"/>
   else
     # could just return "./NES_level7_#{kind[key]}.png" here
     # and SVG Tiler will do the same thing;

examples/tetris/NES_level7.txt

@@ -5,5 +5,5 @@ J NES_level7_filled.png
 S NES_level7_filled.png
 L NES_level7_other.png
 Z NES_level7_other.png
-  <rect fill="black" width="8" height="8"/>
- <rect fill="black" width="8" height="8"/>
+  <symbol width="8" height="8"/>
+ <symbol width="8" height="8"/>

src/svgtiler.coffee

@@ -172,6 +172,8 @@ defaultSettings =
   ## `href` behaves better in web browsers, but `xlink:href` is more
   ## compatible with older SVG drawing programs.
   useHref: window?
+  ## Background rectangle fill color.
+  background: null
   ## renderDOM-specific
   filename: 'drawing.asc'  # default filename when not otherwise specified
   keepParent: false
@@ -1500,6 +1502,7 @@ class Render extends HasSettings
   constructor: (@drawing, @settings) ->
     super()
     @settings ?= @drawing.settings
+    @backgroundFill = @getSetting 'background'
     @idVersions = new Map
     @mappings = new Mappings @getSetting 'mappings'
     @styles = new Styles @getSetting 'styles'
@@ -1542,6 +1545,11 @@ class Render extends HasSettings
       content.setId @id content.defaultId 'def'
       @defs.push content
       content
+  background: (fill) ->
+    ## Sets current background fill to specified value; `null` to remove.
+    ## Returns current background fill.
+    @backgroundFill = fill unless fill == undefined
+    @backgroundFill
   makeDOM: -> runWithRender @, => runWithContext (new Context @), =>
     ###
     Main rendering engine, returning an xmldom object for the whole document.
@@ -1689,6 +1697,14 @@ class Render extends HasSettings
         updateSize()
       @layers[overlay.zIndex].push dom.documentElement
 
+    ## Background fill, now that size has settled
+    if (@backgroundFill ?= @getSetting 'background')?
+      @layers['-Infinity'] ?= []
+      @layers['-Infinity'].unshift (new SVGContent "background",
+        """<rect x="#{@xMin}" y="#{@yMin}" width="#{@width}" height="#{@height}" fill="#{@backgroundFill}"/>""",
+        @settings
+      ).makeDOM()
+
     ## Check for global <defs> used by the symbols so far.
     usedIds = new Set
     globalIdMap = new Map
@@ -1963,6 +1979,16 @@ globalDef = (content) ->
     globalDefs.set content.id, content
     content
 
+globalBackground = (fill) ->
+  ## Sets current/default background fill to specified value; `null` to remove.
+  ## Returns current background fill.
+  if currentRender?
+    currentRender.background fill
+  else if currentMapping?
+    beforeRender (render) -> render.background fill
+  else
+    throw new SVGTilerError "svgtiler.background called outside of render of mapping context"
+
 class Context
   constructor: (@render, i, j) ->
     @drawing = @render.drawing
@@ -2102,6 +2128,7 @@ Optional arguments:
   -m / --margin         Don't delete blank extreme rows/columns
   --uneven              Don't make all rows have same length by padding with ''
   --hidden              Process hidden sheets within spreadsheet files
+  --bg BG / --background BG  Set background fill color to BG
   --tw TILE_WIDTH / --tile-width TILE_WIDTH
                         Force all tiles to have specified width
   --th TILE_HEIGHT / --tile-height TILE_HEIGHT
@@ -2202,6 +2229,9 @@ main = (args = process.argv[2..]) ->
           settings.forceHeight = arg
         else
           console.warn "Invalid argument to --tile-height: #{args[i+1]}"
+      when '--bg', '--background'
+        skip = 1
+        settings.background = args[i+1]
       when '-s', '--share'
         skip = 1
         [key, ...value] = args[i+1].split '='
@@ -2282,22 +2312,21 @@ main = (args = process.argv[2..]) ->
 
 svgtiler = {
   SVGContent, SVGTopLevel, SVGSVG, SVGSymbol, unrecognizedSymbol,
-  Mapping, ASCIIMapping, JSMapping, CoffeeMapping,
+  Mapping, Mappings, ASCIIMapping, JSMapping, CoffeeMapping,
   getMapping, runWithMapping,
   Drawing, AutoDrawing, ASCIIDrawing,
   DSVDrawing, SSVDrawing, CSVDrawing, TSVDrawing,
   Drawings, XLSXDrawings,
-  Style, CSSStyle, StylusStyle,
+  Style, CSSStyle, StylusStyle, Styles,
   SVGFile,
-  extensionMap, Input, DummyInput, ArrayWrapper, Mappings,
+  extensionMap, Input, DummyInput, ArrayWrapper,
   Render, getRender, runWithRender, beforeRender, afterRender,
-  id: globalId, def: globalDef,
+  id: globalId, def: globalDef, background: globalBackground,
+  static: wrapStatic,
   Context, getContext, getContextString, runWithContext,
   SVGTilerError, SVGNS, XLINKNS, escapeId,
-  main, renderDOM, convert,
+  main, renderDOM, convert, require: inputRequire,
   defaultSettings, getSettings, cloneSettings, getSetting, getOutputDir,
-  require: inputRequire
-  static: wrapStatic
   share: globalShare
   version: metadata.version
 }