OPF

Search docs

Loading documentation…
    OpenPresentation/opf
    Browse docs
    On this page
    View source

    Overlay Anchor

    Places an overlay shape against a composed block's box, so the shape follows the block wherever composition puts it. 'edge' puts the shape outside that edge, centered along it ('start' and 'end' follow the deck's direction: left and right in a left-to-right deck, right and left in a right-to-left one); 'center' puts it on the block's center. A block id that is not on the slide is a finding (opf/shape-anchor-missing) and the shape is not drawn. With point, block must carry a supported classic chart. point selects a category label or zero-based row; series selects an exact unique plotted value-column name or zero-based plotted-series index (default first). The selected mark location centers the overlay, and offset moves along its outward normal; whole-block anchors retain their existing outside-edge placement. Unknown, ambiguous, unplotted or unsupported references report opf/shape-anchor-missing and draw no shape.

    Metadata

    Definition
    #/$defs/OverlayAnchor
    Form
    object · 2 combined constraints (allOf)
    Source
    spec/schemas/opf.schema.json

    Field index

    FieldTypeReq.Description
    blockstringyesThe id of a block on this slide (a content payload or a group, at any depth).
    edgeenumyesThe edge of the block the shape sits outside of, or its center.
    edge · Allowed values
    "top""bottom""start""end""center"
    offsetnumber—The gap between the block's edge and the shape, in reference pixels at a 720-pixel short edge; a negative offset overlaps the block. Default 0. Ignored for 'center'.
    widthnumber—The shape's width as a fraction of its target's width: the block's box, or with 'point' the chart mark's bounds. 1 is the target's own width and 1.08 a frame 8% wider, up to 8. For a size in pixels use 'widthPx'; not both. Default: the preset's natural proportions with the shape's shorter side at 15% of the target's shorter side (at least 12 reference pixels on a chart mark).
    heightnumber—The shape's height as a fraction of its target's height, up to 8. For a size in pixels use 'heightPx'; not both. Default as for width.
    widthPxnumber—The shape's width in reference pixels at a 720-pixel short edge, whatever size its target has: a badge or a ring of a fixed size. Instead of 'width'.
    heightPxnumber—The shape's height in reference pixels at a 720-pixel short edge. Instead of 'height'.
    pointstring | integer—Exact unique category label or zero-based data row index of the chart. Numeric strings name labels; numbers index rows. Empty/duplicate labels can be selected by index. Requires a supported classic chart block.
    seriesstring | integer—Exact unique plotted value-column name or zero-based plotted-series index; omission selects the first plotted series. Requires point. Scatter X is not a value series.

    block

    typestringrequiredyesdefault—

    The id of a block on this slide (a content payload or a group, at any depth).

    edge

    typeenumrequiredyesdefault—

    The edge of the block the shape sits outside of, or its center.

    edge · Allowed values
    "top""bottom""start""end""center"
    edge.json
    {
      "edge": "top"
    }

    offset

    typenumberrequirednodefault—

    The gap between the block's edge and the shape, in reference pixels at a 720-pixel short edge; a negative offset overlaps the block. Default 0. Ignored for 'center'.

    width

    typenumberrequirednodefault—

    The shape's width as a fraction of its target's width: the block's box, or with 'point' the chart mark's bounds. 1 is the target's own width and 1.08 a frame 8% wider, up to 8. For a size in pixels use 'widthPx'; not both. Default: the preset's natural proportions with the shape's shorter side at 15% of the target's shorter side (at least 12 reference pixels on a chart mark).

    height

    typenumberrequirednodefault—

    The shape's height as a fraction of its target's height, up to 8. For a size in pixels use 'heightPx'; not both. Default as for width.

    widthPx

    typenumberrequirednodefault—

    The shape's width in reference pixels at a 720-pixel short edge, whatever size its target has: a badge or a ring of a fixed size. Instead of 'width'.

    heightPx

    typenumberrequirednodefault—

    The shape's height in reference pixels at a 720-pixel short edge. Instead of 'height'.

    point

    typestring | integerrequirednodefault—

    Exact unique category label or zero-based data row index of the chart. Numeric strings name labels; numbers index rows. Empty/duplicate labels can be selected by index. Requires a supported classic chart block.

    series

    typestring | integerrequirednodefault—

    Exact unique plotted value-column name or zero-based plotted-series index; omission selects the first plotted series. Requires point. Scatter X is not a value series.

    allOf 1 · restriction

    Exact constraints for allOf 1
    allOf 1 schema
    {
      "not": {
        "required": [
          "width",
          "widthPx"
        ]
      }
    }

    allOf 2 · restriction

    Exact constraints for allOf 2
    allOf 2 schema
    {
      "not": {
        "required": [
          "height",
          "heightPx"
        ]
      }
    }
    Complete definition constraints
    Schema constraints
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "block",
        "edge"
      ],
      "description": "Places an overlay shape against a composed block's box, so the shape follows the block wherever composition puts it. 'edge' puts the shape outside that edge, centered along it ('start' and 'end' follow the deck's direction: left and right in a left-to-right deck, right and left in a right-to-left one); 'center' puts it on the block's center. A block id that is not on the slide is a finding (opf/shape-anchor-missing) and the shape is not drawn. With point, block must carry a supported classic chart. point selects a category label or zero-based row; series selects an exact unique plotted value-column name or zero-based plotted-series index (default first). The selected mark location centers the overlay, and offset moves along its outward normal; whole-block anchors retain their existing outside-edge placement. Unknown, ambiguous, unplotted or unsupported references report opf/shape-anchor-missing and draw no shape.",
      "properties": {
        "block": {
          "type": "string",
          "minLength": 1,
          "description": "The id of a block on this slide (a content payload or a group, at any depth)."
        },
        "edge": {
          "type": "string",
          "enum": [
            "top",
            "bottom",
            "start",
            "end",
            "center"
          ],
          "description": "The edge of the block the shape sits outside of, or its center."
        },
        "offset": {
          "type": "number",
          "minimum": -720,
          "maximum": 720,
          "description": "The gap between the block's edge and the shape, in reference pixels at a 720-pixel short edge; a negative offset overlaps the block. Default 0. Ignored for 'center'."
        },
        "width": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 8,
          "description": "The shape's width as a fraction of its target's width: the block's box, or with 'point' the chart mark's bounds. 1 is the target's own width and 1.08 a frame 8% wider, up to 8. For a size in pixels use 'widthPx'; not both. Default: the preset's natural proportions with the shape's shorter side at 15% of the target's shorter side (at least 12 reference pixels on a chart mark)."
        },
        "height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 8,
          "description": "The shape's height as a fraction of its target's height, up to 8. For a size in pixels use 'heightPx'; not both. Default as for width."
        },
        "widthPx": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1280,
          "description": "The shape's width in reference pixels at a 720-pixel short edge, whatever size its target has: a badge or a ring of a fixed size. Instead of 'width'."
        },
        "heightPx": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1280,
          "description": "The shape's height in reference pixels at a 720-pixel short edge. Instead of 'height'."
        },
        "point": {
          "oneOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "integer",
              "minimum": 0
            }
          ],
          "description": "Exact unique category label or zero-based data row index of the chart. Numeric strings name labels; numbers index rows. Empty/duplicate labels can be selected by index. Requires a supported classic chart block."
        },
        "series": {
          "oneOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "integer",
              "minimum": 0
            }
          ],
          "description": "Exact unique plotted value-column name or zero-based plotted-series index; omission selects the first plotted series. Requires point. Scatter X is not a value series."
        }
      },
      "examples": [
        {
          "block": "team-photo",
          "edge": "top",
          "offset": 8
        },
        {
          "block": "revenue-chart",
          "edge": "end",
          "widthPx": 160,
          "heightPx": 64
        },
        {
          "block": "quote",
          "edge": "center",
          "width": 1.08,
          "height": 1.08
        },
        {
          "block": "costs",
          "series": "Cost ($B)",
          "point": "United States",
          "edge": "end",
          "widthPx": 80,
          "heightPx": 80
        }
      ],
      "dependentRequired": {
        "series": [
          "point"
        ]
      },
      "allOf": [
        {
          "not": {
            "required": [
              "width",
              "widthPx"
            ]
          }
        },
        {
          "not": {
            "required": [
              "height",
              "heightPx"
            ]
          }
        }
      ]
    }