Screenplay outlets: item lists a template offers
An outlet is a named list of items a layout or template offers: the buttons of a toolbar, the filters above a list, the tabs of a detail pane, the figures of a dashboard, the destinations of a sidebar. The template says what kind of items the list holds and which it shows by default. A module, feature or screen changes the list for the screens beneath it - without copying the template.
An outlet is not a slot. A slot is a region content is placed in; an outlet is a list of items, which in <slot> can tie to the slot that shows it.
Declare an outlet on a layout or template
Section titled “Declare an outlet on a layout or template”outlet <name> of actions|filters|tabs|stats|navigation [for item|for screen] [in <slot>] default <id> title "<text>" …| Part | Meaning |
|---|---|
of <kind> |
The kind of item the outlet holds - see Item kinds. |
for item / for screen |
What the items act on: one item of the screen’s data, or the screen as a whole. Leave it out when it does not matter. |
in <slot> |
The slot that shows the outlet. |
default |
An item the outlet shows unless a lower level changes it, written in the outlet’s item form without the item’s keyword. |
module Catalog screen template ListPage category List fits slot content header main detail pane routed by sku optional outlet toolbar of actions in header default refresh title "Refresh" runs refresh default export title "Export" outlet rowActions of actions for item outlet filters of filters in header outlet stats of stats in header outlet detailTabs of tabs in detailA layout, screen template and dialog template declare outlets; a component does not. Declaring an outlet anywhere else is PLAY0897, and declaring the same outlet twice is PLAY0904. A default button with no slice is a placeholder: it does not warn (PLAY0763), because a lower level gives it its hook.
Item kinds
Section titled “Item kinds”| Kind | Items | Form |
|---|---|---|
actions |
button, group |
button <id> title "…" [slice <Module>.<Feature>.<Slice>] [emphasis primary|secondary|quiet] [icon <name>] [runs close|submit|refresh], with optional confirm "…" and authorize lines under it. group <id> title "…" [icon <name>] holds button lines. |
filters |
filter |
filter <id> title "…" [sets <Query>.<param>] - a control that sets a parameter of the query the screen shows. |
tabs |
tab |
tab <id> title "…" [shows <Screen>] - a screen shown in the slot the outlet is in. |
stats |
stat |
stat <id> title "…" [value from <Query>.<field>] - a figure read from a single-result query. |
navigation |
item |
item <id> title "…" [icon <name>] [target <Module>[.<Feature>]] [slot <name>], nesting sub-items. See Navigation. |
An item of the wrong kind for its outlet is PLAY0900. The checks follow what each item names:
- A button’s
slicemust be a State Change slice the document declares (PLAY0761,PLAY0762). - A filter’s parameter must be a
byorfilterparameter of the query (PLAY0901). - A stat’s query must return a single result, not a list (
PLAY0902). - A tab’s screen must exist (
PLAY0197).
A navigation outlet on a layout also carries the application’s one logo image "…" title "…".
Dialog and drawer buttons
Section titled “Dialog and drawer buttons”A dialog or drawer template declares its buttons as an actions outlet. The built-ins runs close and runs submit close the dialog and submit the screen’s command, so the template needs no slice:
module Invoicing dialog template TaskDialog category Dialog body footer outlet actions of actions in footer default cancel title "Cancel" runs close default save title "Save" emphasis primary runs submitruns refresh reloads the screen’s data.
A button that names a State Change slice is a hook. It opens the slice’s screen in its first fit the page has free, or where it says, and it can run the slice without a form:
module Catalog screen template ListPage category Lists main detail pane routed by sku optional outlet rowActions of actions for item
feature Products outlet rowActions extends button price title "Set price" slice SetProductPrice opens in slot detail button withdraw title "Withdraw" slice WithdrawProduct runs enabled when item.status == "onSale" confirm "Withdraw this product?"
slice StateChange SetProductPrice command SetProductPrice sku String identifier price Decimal produces PriceSet for sku event PriceSet sku String screen SetProductPrice fits pane, drawer action SetProductPrice for screen
slice StateChange WithdrawProduct command WithdrawProduct sku String identifier produces ProductWithdrawn for sku event ProductWithdrawn sku Stringopens dialog,opens drawerandopens in slot <name>name where the slice’s screen opens; without one it opens in the screen’s first fit the page has free.for itemorfor screenon the button says what it acts on, overriding the outlet’s.- A
runsline issues the command directly. A slice issued only by arunshook needs no screen, and a hook counts as issuing its slice’s commands forPLAY0533. enabled when <condition>andconfirm "<text>"go under the button.
PLAY0907-PLAY0911 and PLAY0915 check hooks; see Placement, hooks and bindings.
Change an outlet below the template
Section titled “Change an outlet below the template”A module, feature or slice screen writes outlet <name> inherits|extends|overrides. It names an outlet the layout or template declares; an unknown outlet is PLAY0903. A level that mentions nothing keeps what it inherits.
| Mode | Shows |
|---|---|
inherits |
The inherited items, unchanged. It lists nothing of its own (PLAY0897). |
extends |
The inherited items, then the level’s own. |
overrides |
The level’s own items only. Overriding with none warns (PLAY0752). |
Under the outlet line:
hide <id>drops an inherited item.before <id>orafter <id>under an item places it next to an inherited item instead of after them.
Each must name an item the inherited outlet has (PLAY0899). An extending level’s own item may not repeat an inherited id (PLAY0905).
module Catalog screen template ListPage category List header main outlet toolbar of actions in header default refresh title "Refresh" runs refresh default export title "Export" outlet filters of filters in header outlet stats of stats in header
feature Products outlet toolbar extends hide export button add title "Add product" slice DraftProduct emphasis primary icon plus before refresh group more title "More" icon dots button withdraw title "Withdraw" slice WithdrawProduct outlet filters extends filter status title "Status" sets AllProducts.status outlet stats extends stat drafts title "Drafts" value from ProductStats.drafts
slice StateChange DraftProduct command DraftProduct sku String identifier produces ProductDrafted for sku event ProductDrafted sku String screen DraftProduct action DraftProduct
slice StateChange WithdrawProduct command WithdrawProduct sku String identifier produces ProductWithdrawn for sku event ProductWithdrawn sku String screen WithdrawProduct action WithdrawProduct
slice StateView ProductCatalog readmodel ProductRow sku String status String readmodel ProductStats drafts Int query AllProducts => ProductRow[] filter status String query ProductStats => ProductStats screen ProductCatalog template ListPage outlet toolbar inheritsThe levels apply in order - the template’s defaults, then the module, the feature and its parent features, then the screen - so a screen sees what every level above it left.
Add to an outlet from anywhere
Section titled “Add to an outlet from anywhere”contribute to <outlet> adds items to an outlet from any module or feature, without the level that owns the screens listing them. See Contributions.
module Invoicing feature Payments contribute to detailTabs tab payments title "Payments" shows InvoicePaymentsContributions shows the same contribution with the template that declares detailTabs.
Checks and the TypeScript compiler
Section titled “Checks and the TypeScript compiler”Both compilers read a module’s, feature’s and screen’s outlets and report their form: PLAY0896, PLAY0897, PLAY0898 and PLAY0904; a malformed hook part (opens, for, runs) is PLAY0760 in both. Layouts, templates and contributions stay opaque to the TypeScript compiler, so the declarations and the checks that need them - PLAY0895, PLAY0899-PLAY0903 and PLAY0905 - are reported by the C# compiler. See Outlets diagnostics.
Outlets are authoring syntax and are not part of the executable model, like every screen construct; the semantic binder reports a module’s outlets as deferred.
From Screenplay 5
Section titled “From Screenplay 5”Screenplay 6 turned three Screenplay 5 forms into outlets. Each old form is an error whose message names the replacement and screenplay migrate --from 5 --to 6, which rewrites them for you:
| Screenplay 5 | Screenplay 6 | Code |
|---|---|---|
navigation topbar|sidebar on a layout |
outlet topbar|sidebar of navigation with default items; its buttons move to outlet topbarActions|sidebarActions of actions |
PLAY0894 |
navigation sidebar extends on a module |
outlet sidebar extends; its buttons move to outlet sidebarActions extends |
PLAY0894 |
<slot> contributes <Point> |
outlet <Point> of navigation in <slot> |
PLAY0895 |
toolbar <name> on a feature or module |
outlet <name> extends |
PLAY0896 |
See also
Section titled “See also”- Layouts and templates for slots and their roles.
- Navigation for navigation outlets.
- Contributions for
contribute to. - Screens for a screen’s own toolbar buttons.