Skip to main content

​
Sources

Docs: Panes, Perceptions, and Plots Web App: Rename a Pane or Plot in Pieces; open a Pane’s code afterwards to see the new handle already in place.

​
Story

Every named Page, Package, Pane, and Plot in a Parable has a handle: a camelCase name, unique within the Parable, that code and SQL use. Underneath, every Piece and slot also has a permanent identifier that never changes, and that identifier is what the Parable actually stores, including inside Pane code. Perceptions accept handles for references and save the stable identifier, so renaming a Piece preserves its references.

​
Where handles appear in code

The editor shows and accepts handles in exactly these places, and Parable translates them to identifiers when it saves and back to handles when it reads:
  • the import specifier @parable/<parable>/<pane>;
  • the string that is the first argument of preferences.get('...') and plots.run('...');
  • the handle inside preferences.set({ handle: '...', value }); and
  • the bracket access plots['...'] and panes['...'].
Always write those positions as string literals. Dotted access such as plots.salesQuery is not part of the generated module, and a handle built at run time cannot be translated. A handle that the Pane does not declare is refused at save. The refusal names the handle, lists the handles the Pane may use, and, when the same save renamed that handle, names the rename.

​
In SQL

Plot SQL is never rewritten. The workspace.preferences relation a Plot reads carries the handle beside the slot’s identifier, so WHERE handle = 'salesQuery' selects by the current handle. If that handle changes, update a literal SQL condition that still names the old handle.

​
What a rename does

A rename is an identity edit. It touches no code and no stored value: values set at Person and Workspace scope stay attached to the slot’s identifier, and the editor rewrites any open draft that still used the old handle before its next save. Teammates editing the same Parable see the new handle in their drafts without losing their changes. A Piece handle must be unique across the Parable. Perception binding names are local to their own panes or plots map; they can differ from the referenced Piece’s handle and do not claim a global Piece handle.

​
Reference

Generated Workspace API reference for this Piece: