LIGHTWEIGHT TEMPLATES
Not to be confused with Events, which cover DOM handlers inside a template (onClick, onInput, etc.). This page is about events the template sends out of the widget.
What an external event is
An external event is a named notification a template sends out of the widget when the user interacts with it, optionally carrying a bag of parameters. Firing one does two things:
-
logs an auto micro conversion with event type
EXTERNAL_EVENTand the event name as its event group id; this is what appears in the Conversion Report; -
calls the publisher's
customEventhandler on the host page with the event name and the params object.
tp.push(["addHandler", "customEvent", function (event) {
event.eventName; // the name you passed
event.params; // the params object you passed
}]);
This is the same customEvent handler classic templates used, so an existing publisher integration keeps receiving events after a migration. What changes is the shape of params; see Coming from classic templates below.
What can fire one
|
Mechanism |
Use it when |
Documented in |
|---|---|---|
|
|
you need to fire an event from arbitrary markup, a plain |
|
|
|
you are already using a Piano button component |
Both are current, and both are the same mechanism underneath. Pick whichever fits the markup you already have. There is no third way: the classic external-event-* HTML attributes do nothing in a Lightweight template, whether written in the JSX tab or set from the JS tab with setAttribute().
Buttons that accept externalEventName / externalEventParams
-
PianoCloseButton (and the compound CloseButton)
PianoExternalEvent
|
Attribute name |
type |
required / optional |
default value |
description |
|---|---|---|---|---|
|
|
string |
required |
|
external event name |
|
|
object |
optional |
|
parameters sent with the event |
|
|
JSX.Element |
required |
|
the markup whose clicks fire the event |
|
|
N/A |
optional |
|
applied to the wrapper element |
PianoExternalEvent renders a wrapper <div> around its children and listens for clicks on it in the capture phase. Two consequences worth knowing up front:
Any click inside the wrapper fires the event, not only a click on the button; keep the wrapper tight around the element you mean.
The event is sent before the click handlers of the wrapped content run.
<PianoExternalEvent name="cta-click" style={{ display: "contents" }}>
<button type="submit">Continue</button>
</PianoExternalEvent>
Example 1: static parameters
Everything is known at authoring time, so only the JSX tab is involved.
<PianoExternalEvent
name="cta-click"
params={{ placement: "sidebar", campaign: "[%% campaign_id %%]" }}
>
<button type="button">Continue</button>
</PianoExternalEvent>
Example 2: parameters read from the form at click time
This is the case that needs both tabs. The JSX tab declares the markup and the params; the JS tab declares the variables the markup binds to and any helpers the params call. Two kinds of binding appear here: ref, when the value is read straight off the DOM at fire time, and a signal, when the template has to render the value as well.
JS tab
// read off the DOM at fire time
let comment;
let topicA;
let topicB;
// a signal, because the subject is rendered as well as sent
const [subject, setSubject] = createSignal("");
const selectedTopics = () =>
[
topicA?.checked ? "[%% topic_a_id %%]" : "",
topicB?.checked ? "[%% topic_b_id %%]" : "",
]
.filter(Boolean)
.join(",");
JSX tab
<form>
<label for="comment">Comment</label>
<input id="comment" type="text" ref={comment} required />
<label>
<input type="checkbox" ref={topicA} /> Topic A
</label>
<label>
<input type="checkbox" ref={topicB} /> Topic B
</label>
<label for="subject">Subject</label>
<input
id="subject"
type="text"
maxlength="60"
onInput={(e) => setSubject(e.currentTarget.value)}
/>
<p>{subject().length} / 60</p>
<PianoExternalEvent
name="[%% event_name %%]"
params={{
comment: comment?.value,
topicIds: selectedTopics(),
subject: subject(),
formId: "[%% form_id %%]",
}}
style={{ display: "contents" }}
>
<button type="submit">Send</button>
</PianoExternalEvent>
</form>
How the two tabs connect
-
The JS tab is the component body. Your JS tab and the JSX tab are compiled into the same function, in that order. Anything you declare at the top level of the JS tab is visible to the JSX; anything you hide inside an IIFE is not. FAQ: How does the JS tab interact with the JSX tab?
JavaScript// ✅ visible to the JSX let comment; // ❌ invisible to the JSX (function () { let comment; })(); -
ref={x}assigns the DOM element tox. It is a plain assignment, not a signal setter, soxmust be declared withletorvarat the top level of the JS tab.constthrows, and so does an undeclared name: the template code runs as an ES module, in strict mode, so the assignment throws aReferenceErrorat render time instead of creating a global. FAQ: What is ref and how do I use it? and Which variables from the JS tab can the JSX see, and how do I declare them? -
A signal is the other option, and the one to pick when the value also drives rendering; the character count above cannot be written with a
ref.createSignaland the other Solid primitives the JS tab receivesbatch,catchError,createComputed,createDeferred,createEffect,createMemo,createReaction,createRenderEffect,createResource,createSelector,mapArray,mergeProps,on,onCleanup,onMountandsplitProps- are already in scope, so no import is needed; other Solid primitives, such asuntrack, are not in scope. -
paramsis evaluated when the event fires, not when the template renders. That is what makescomment?.value,subject()andselectedTopics()return what the user actually typed and picked. You do not need to mirror form state into variables on everyonChange; read it insideparams. -
[%% field %%]content fields are substituted in the JS tab too. Substitution runs over all three tabs, HTML/JSX, CSS and JS, before the template reaches the browser, and the editor offers content-field autocompletion in all three. FAQ: Are content fields substituted in the JS tab too?
Buttons
A Piano button fires the event on its own click, before your onClick runs. No wrapper element is added.
<PianoPrimaryButton
onClick={(e) => context.login()}
externalEventName="header-login"
externalEventParams={{ placement: "header" }}
>
<T>Log in</T>
</PianoPrimaryButton>
The example uses PianoPrimaryButton, but externalEventName and externalEventParams work the same way on every button in the list above. PianoStartCheckoutButton and PianoBuyAsAGiftButton also add termId, taken from their term prop, to externalEventParams, so you don't have to pass it yourself.
Runtime parameters work exactly as they do for PianoExternalEvent; externalEventParams is evaluated at click time, so it can read live DOM values bound with ref:
JS tab
let promoCode;
JSX tab
<input type="text" ref={promoCode} placeholder="Promo code" />
<PianoPrimaryButton
onClick={(e) => context.startCheckout({ term: item })}
externalEventName="promo-applied"
externalEventParams={{ code: promoCode?.value, termId: item.termId }}
>
<T>Subscribe</T>
</PianoPrimaryButton>
Note. The example above uses PianoPrimaryButton, but externalEventName and externalEventParams behave identically on every button listed above: PianoPrimaryButton, PianoSecondaryButton, PianoOutlineButton, PianoGhostButton, PianoIconButton, PianoCloseButton / CloseButton, PianoBackButton, PianoStartCheckoutButton and PianoBuyAsAGiftButton.
Two of them add a parameter of their own: PianoStartCheckoutButton and PianoBuyAsAGiftButton merge termId (taken from their term prop) into externalEventParams, so you do not have to pass it yourself.
Coming from classic templates
In a classic (AngularJS) template, an external event was an attribute directive:
<button external-event="cta-click"
external-event-event-label="sidebar"
external-event-plan="{{ selectedPlan }}">
Continue
</button>
The classic runtime read every attribute whose name began with external-event-, turned the dash-separated suffix into a camelCase key with a lowercased first letter, and used the attribute's (interpolated) string value:
|
Classic attribute |
params key |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Because these were HTML attributes, every classic parameter was a string, and the browser lowercases attribute names, so external-event-eventLabel produced the key eventlabel, not eventLabel. In a Lightweight template, params is a real JavaScript object: keys keep their case, and values keep their types.
The classic directive also fires on submit as well as click, on the element itself. PianoExternalEvent listens for click only, on its wrapper. Clicking a submit button (including implicit submission by pressing Enter in a field) still fires it; a form submitted from JavaScript does not.
Mapping table
Every classic form with its Lightweight equivalent, written out as code. Both Lightweight columns do the same thing: the PianoExternalEvent wrapper in one, the externalEventName / externalEventParams props on a Piano button in the other; pick whichever fits the markup you already have. Rows about a single attribute show only the lines that differ, and where a row needs template-side state, the JS tab snippet follows the JSX one.
|
Classic (piano-vx) |
Lightweight PianoExternalEvent equivalent |
Lightweight Button ExternalEvent equivalent |
|---|---|---|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
JavaScript
|
React JSX
JavaScript
|
|
HTML
|
React JSX
JavaScript
|
React JSX
JavaScript
|
|
HTML
|
React JSX
JavaScript
|
React JSX
JavaScript
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
Not applicable; a button does not navigate. Use the wrapper with |
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
JavaScript
|
React JSX
JavaScript
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
|
HTML
|
React JSX
|
React JSX
|
Gotchas
-
A parameter expression that throws swallows the event.
comment.valuewherecommentwas never bound (the input is inside a<Show>that has not rendered) throws at click time; the click still does whatever else it does, but no event and no conversion are recorded. Use optional chainingcomment?.valueinsideparams. Optional chaining does not help when the name itself is not visible to the JSX (declared inside an IIFE, for example): reading an undeclared name throws aReferenceErrorwith or without?., so declare it at the top level of the JS tab. A Piano button is different: it readsexternalEventParamsbefore its ownonClick(and beforePianoCloseButton,PianoBackButton,PianoStartCheckoutButtonandPianoBuyAsAGiftButtondo their own work: close, back, checkout), so a throw there cancels the whole click. It also readsexternalEventParamswhile it renders, so use optional chaining insideexternalEventParamstoo. -
paramsis not reactive state. It is read once per fire. Do not expect acreateEffectto re-send anything. -
Wrapper vs. button. If both
PianoExternalEventand a button'sexternalEventNameare present around/on the same element, two events fire. Pick one.
Tracking IDs & conversion attribution (_ptid)
External events are also how a Lightweight template feeds conversion attribution; a template on the article starts a journey, the visitor converts later on a separate landing page, and the tracking ID is what ties that later conversion back to the experience and variant that started it. This section covers the two auto micro conversions a template can log, how the tracking ID reaches a link, and how to read it yourself.
This is the Lightweight-template counterpart to the Classic page How to record conversions with the tracking parameter _ptid when a button inside a Piano template is clicked. The Classic recipe, a Run JS card reading params.trackingId from the checkoutCustomEvent callback and wiring external-event-* attributes, does not work in LWT (the external-event-* attributes do nothing here). Use what is below instead.
Two auto micro conversions: EXTERNAL_EVENT and EXTERNAL_LINK
A template can log two different auto micro conversions; keep them apart:
|
Event type |
Logged by |
|
|---|---|---|
|
|
|
the event name you chose |
|
|
the |
the destination URL (without query or hash) |
Both are stamped with the widget's tracking ID automatically; you never attach it yourself. EXTERNAL_EVENT is the one described everywhere above on this page; EXTERNAL_LINK is new here and belongs to the <A> component.
Link to a Piano landing page: <A> adds _ptid for you
<A href="https://your-landing-page.example/subscribe">Subscribe</A>
<A> appends _ptid=<trackingId> to the destination and logs an EXTERNAL_LINK on click. _ptid is added only when all of these hold:
-
the
hrefis an absolutehttp(s)://URL, lowercasehttp; uppercaseHTTP://does not match; -
the widget's tracking ID is present when the link renders;
-
noptidis not set.
If any fails, the link still works but carries no _ptid (and logs no EXTERNAL_LINK). This is the recommended path whenever the destination is a Piano offer/checkout opened on the landing page: the landing-page SDK reads _ptid and uses it as the tracking ID (see The landing page below), so you never handle the ID yourself. Don't also add ?_ptid=… by hand; <A> does it. A promoted <A> opens in _blank unless you set target to _self, _parent or _top.
Record the article-side click
To make the article-side click appear in the Conversion Report, wrap the CTA (see PianoExternalEvent, above):
<PianoExternalEvent name="subscribe-cta">
<A href="https://your-landing-page.example/subscribe">Subscribe</A>
</PianoExternalEvent>
An <A> inside the wrapper logs both events: the wrapper's EXTERNAL_EVENT (fired in the capture phase, first) and the link's own EXTERNAL_LINK. So one text-link click produces two conversions; a plain <button> inside the wrapper produces one. Account for this when reading reports.
Read the tracking ID yourself
These are standard context members on every Lightweight template, read straight from the widget:
|
Member |
Type |
Notes |
|---|---|---|
|
|
string |
The Piano tracking ID used for |
|
|
string |
The Piano browser ID, optional: can be empty until the SDK has seeded one, so guard for the empty case if your URL requires it |
|
|
string |
The Composer experience ID, filled when the widget is shown by an experience, empty otherwise |
Use them when <A>/_ptid doesn't fit, a non-<A> redirect (e.g. a <button> that navigates with custom JS), or your own checkout/landing page that expects the ID under your own parameter name:
// a button that redirects to your own checkout:
const url = `https://your-checkout.example/subscribe`
+ `?piano_tracking_id=${context.trackingId}`
+ `&browser_id=${context.browserId}`;
For a plain link to a Piano landing page, prefer <A>; it adds _ptid for you, and the landing page reads it automatically. Reach for context.trackingId only when you need the raw value on a non-<A> redirect or under a custom parameter name.
Converting a Classic template
The converter resolves the Classic tracking placeholders on their own, no manual edit:
|
Classic placeholder |
After conversion |
Result |
|---|---|---|
|
|
|
resolved; the real Piano tracking ID |
|
|
|
resolved; the converter promotes the old |
|
|
|
resolved; the Composer experience ID |
So a converted tracking link such as ?piano_tracking_id={{params.trackingId}}&browser_id={{custom.browserId}} keeps working with no edit.
One edge case.browserId is the only key the converter lifts out of the publisher custom bag. If you deliberately kept your own custom field literally named browserId for something unrelated, it is now read as Piano's browser ID; rename your own field. The rewrite is recorded in the conversion report; every other custom.* key is left untouched.
The landing page
-
The landing page must load
tinypass.min.js. -
The SDK reads
_ptidfrom the page URL and uses it as the tracking ID for any offer/checkout opened on that page; it never writes_ptid. The article-side<A>(or your own URL above) is what puts it there. -
As with Classic, this applies to a Piano checkout/offer opened on the landing page, not to an external checkout.
Pitfalls
-
noptidmust benoptid={true}. A barenoptidcollapses to an empty string (falsy) in a template, so_ptidis still added; the opposite of what you intended. -
Empty tracking ID at render. If the tracking ID isn't available when an
<A>first renders, the href is set without_ptid. The same caution applies to a URL you build fromcontext.trackingId, which can be empty at first render; guard for it. -
Only absolute
http(s)links track. Relative paths,#anchors,mailto:/tel:, protocol-relative//cdn…and uppercaseHTTP://get no_ptidand noEXTERNAL_LINK. -
Double events. An
<A>insidePianoExternalEventlogs two conversions (above); account for it when reading reports.