05 · Formulários — datas e valores

PlacementStage

imagem com caixa tracejada · clicar, arrastar e redimensionar · on_place / on_resize

Imagem com uma caixa tracejada que o usuário posiciona por clique ou arraste e redimensiona pela alça do canto.

Arrastar, clicar e redimensionar

Página 1 do contrato
Assinatura

Clique na página para pôr a caixa, arraste e use a alça do canto. Com a caixa em foco, as setas movem 1% (Shift: 10%).

left
10%
bottom
14%
width
30%
último evento
nenhum
.heex
<%!-- clique na página para pôr a caixa, arraste, redimensione pela alça; o servidor guarda o box (em % da imagem) --%>
<.live_component module={LedgerShowcaseWeb.Demos.PlacementDemo} id="ps-default" />

Sem alça (resizable={false})

Página 1 do contrato
Assinatura

Clique na página para pôr a caixa, arraste e use a alça do canto. Com a caixa em foco, as setas movem 1% (Shift: 10%).

left
10%
bottom
14%
width
30%
último evento
nenhum
.heex
<%!-- resizable={false}: sem a alça, só posiciona --%>
<.live_component module={LedgerShowcaseWeb.Demos.PlacementDemo} id="ps-fixed" resizable={false} />

Desabilitada (disabled)

Página 1 do contrato
Assinatura

Clique na página para pôr a caixa, arraste e use a alça do canto. Com a caixa em foco, as setas movem 1% (Shift: 10%).

left
10%
bottom
14%
width
30%
último evento
nenhum
.heex
<%!-- disabled: mostra a caixa e tira os gestos --%>
<.live_component module={LedgerShowcaseWeb.Demos.PlacementDemo} id="ps-disabled" disabled />

Uso

<.placement_stage id="pdf-stage" src={@image} alt="Página 1" box={%{left: 10, bottom: 14, width: 30, height: 7.7}}
  on_place="place_signature" on_resize="resize_signature">
  Assinatura
</.placement_stage>

Regras

  • box é em % da imagem: left e bottom (da borda esquerda e de baixo), width e height.
  • on_place leva o centro da caixa (x da esquerda e y do topo, de 0 a 1); on_resize leva a largura (de 0 a 1).
  • A caixa se move na hora, no navegador; o servidor é avisado no fim do gesto e a palavra final é dele.
  • A caixa é focável: as setas movem 1% da imagem (Shift, 10%).

Referência da API

Todos os function components, atributos, valores e slots que este componente cobre.

An image (a rendered PDF page, a photo) with a dashed box on it that the user positions by clicking or dragging, and resizes from a corner handle.

<.placement_stage
  id="pdf-stage"
  src={@image}
  alt="Page 1"
  box={%{left: 10, bottom: 20, width: 30, height: 8}}
  resizable
  on_place="place_signature"
  on_resize="resize_signature"
>
  Signature appears here
</.placement_stage>

The box

box is a map of percentages of the image: left (from the left edge), bottom (from the bottom edge), width and height, which is how the CSS is written (left:10%;bottom:20%). A nil box draws no box. The slot is the content of the box (a label, an icon).

Events

The LedgerUI.PlacementStage hook (priv/static/ledger_ui/hooks/placement_stage.js) moves the box at once, in the browser (optimistic), limited to the edges of the image, and tells the server at the end of the gesture (pointer up or click):

  • on_place, %{"x" => x, "y" => y}: the centre of the box, as fractions 0..1 of the image; x counts from the left edge and y from the top edge. The centre is the one of the box as it is shown, already limited so the box stays inside the image.
  • on_resize, %{"width" => w}: the new width, a fraction 0..1 of the image width. The handle keeps the centre and the proportions of the box (so the height follows), and the width is never less than 5% nor more than the image allows around the centre.

Event names are strings; phx-target (for a live component) is read from the component.

Pointer events cover mouse, pen and touch (touch-action: none on the stage, pointer capture). Pressing the image puts the centre of the box under the pointer. The box is focusable: the arrow keys move it by 1% of the image (Shift: 10%) and every key press pushes on_place. label is its aria-label.

The server wins: a new box replaces what the browser shows, except in the middle of a gesture (it is ignored until the pointer is released) and while an event of this component has not been answered yet (an unchanged box does not undo a move that is on its way to the server).

resizable={false} removes the handle; disabled shows the box and takes away the gestures.

<.placement_stage>

Attr Type Default Values / notes
id (required) :string
src (required) :string
alt :string ""
box :map nil %{left, bottom, width, height}, in % of the image.
resizable :boolean true
disabled :boolean false
on_place :string nil
on_resize :string nil
label :string "Placement box: arrow keys move it, Shift moves it by 10%"
class :any nil

Any other HTML/phx attribute goes to the root element, including phx-target.

Slots:

  • <:inner_block>