# Embedding in an ASP.NET (ASPX / Web Forms / MVC) page — no npm, no React This guide is for teams whose site is a classic **ASP.NET** app (Web Forms `.aspx`, or Razor/MVC `.cshtml`) with **no Node build step**. You don't need npm, a bundler, or React on your page. You add **one ` ``` ### MVC / Razor (`.cshtml`) Identical, minus the `runat="server"` form: ```cshtml ``` The element self-registers when the script loads — no init call required. --- ## 3. Getting JSON *in* (server → editor) `fb.form` takes a **JavaScript object** (a `PopupModal`). Inject it as raw JSON from the server. **Do not** HTML-encode it — it's a JS literal, not markup. **Code-behind (Web Forms):** ```csharp using System.Web.Script.Serialization; // or Newtonsoft.Json / System.Text.Json public partial class PopupEditor : System.Web.UI.Page { protected string FormJson; // referenced by <%= FormJson %> protected void Page_Load(object sender, EventArgs e) { // Load from your DB, or "null" for a blank editor. object popup = LoadPopupFromDb(Request["id"]); FormJson = popup == null ? "null" : new JavaScriptSerializer().Serialize(popup); } } ``` If `fb.form` is `null` the editor shows nothing until you assign a form, so pass a real object to start editing. To start from a blank template, store a starter `PopupModal` JSON server-side and serve that. **Prefer fetching over inlining?** Leave the element empty and load JSON client-side from an endpoint you already have: ```javascript fetch('/api/popups/123') .then(r => r.json()) .then(json => { fb.form = json; }); ``` --- ## 4. Getting edits *out* (editor → server) The editor is JS-driven and **never uses ASP.NET postback**, so don't expect the form JSON to arrive in `Page_Load` / a submit handler. Capture it from the `change` (or `publish`) event and POST it yourself. A generic handler (`.ashx`), a `[WebMethod]`, or a Web API / MVC controller all work. ```javascript function savePopup(popup) { fetch('/SavePopup.ashx', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(popup), }); } ``` `change` fires on **every keystroke/edit**, so debounce before hitting the server if you save on change: ```javascript var t; fb.addEventListener('change', function (e) { clearTimeout(t); t = setTimeout(function () { savePopup(e.detail); }, 800); }); // ...or only persist on 'publish', and treat 'change' as "unsaved" state. ``` **Generic handler (`SavePopup.ashx`):** ```csharp public class SavePopup : IHttpHandler { public void ProcessRequest(HttpContext ctx) { string json; using (var r = new StreamReader(ctx.Request.InputStream)) json = r.ReadToEnd(); SavePopupToDb(json); // store the raw PopupModal JSON ctx.Response.StatusCode = 204; } public bool IsReusable => true; } ``` ### Check the form before you store it `validatePopup(form)` returns a list of `{ path, message, level }`; an empty list, or one with no `level: 'error'` entries, means the form is structurally sound. **Publish is the moment to run it.** A form stored with an error in it is a form that fails in front of a visitor, and the errors it catches are exactly the ones nothing else will: an endpoint that can't be dialled, a redirect with no destination, two fields fighting over one submit key. The editor bundle exposes it on the same global the element registers under (`CreaditorFormBuilder.validatePopup` / `.isValidPopup`), so an ASPX page needs nothing beyond the ` ``` `mountPopup(popup, opts?)` returns a handle: ```javascript var handle = CreaditorPopup.mountPopup(popupJson, { onClose: function () { /* dismiss analytics */ }, fetchImpl: undefined, // optional: your own fetch for the submit request container: undefined // optional: an element to render inside, overriding htmlId }); // handle.unmount(); // tear it down (e.g. SPA navigation) ``` - It wires the **trigger**, **frequency cap**, and **placement**, then renders when appropriate — you don't manage when it shows. - The popup submits to the endpoint authored in its Setup tab (plus any hidden mailing-list targets); nothing else to configure here. - **`htmlId` page gate:** if the `PopupModal` has an `htmlId`, the popup renders only on pages that contain an element with that id — otherwise it renders nothing. A popup with no `htmlId` renders on every page it's loaded on. Use this to scope a popup to specific pages. - **`htmlId` as the inline anchor:** for a form with `placement: "inline"` (the builder's default), that same element is also *where* the form renders — it's appended inside it, in the page flow, with no overlay. So put an empty `
` where you want the form to sit. An `inline` form with no `htmlId` has nowhere to embed and lands at the end of ``. A `modal` ignores the element's position and always covers the page. Other globals on `CreaditorPopup` if you need them: `PopupContent` / `PopupMount` (React components, for a bundler host), `validatePopup(json)` and `isValidPopup(json)` (sanity-check JSON before mounting). For plain ASPX, `mountPopup` is all you need. ### Where a form appears A form can carry a list of page addresses (`urls` on its JSON, written by the author in the popover that follows Publish). `mountPopup` honours it: on a page the list doesn't cover, it renders nothing. A form with **no** list runs everywhere, so if your customers paste the embed exactly where the form belongs, this stays empty and nothing changes. Your ASPX side can ask the same question, which is the point of the list being plain data: ```javascript // Which of these forms belong on the page we're on? var forHere = allForms.filter(function (f) { return CreaditorPopup.matchesPage(f, window.location.href); }); ``` Simple enough to reimplement in C# if you'd rather decide server-side which forms to send to a page at all. The whole rule: - Compare the **host and path**. Ignore the scheme, a leading `www.`, a trailing slash, the `#fragment`, and case — none of those make a different page, and treating them as differences is how a form silently fails to appear. - A **star** matches any run of characters. - An entry written as a bare path (`/pricing`) is matched against the path only, ignoring the host. - An entry with **no query string** ignores the page's. - An **empty list** means every page. See [EMBEDDING.md](./EMBEDDING.md#where-a-form-appears). ### Where the submission goes (`form.url`) A form submits to `form.url` with `form.method`. **Set it on every form your app creates** — the editor writes what the author types into the "Endpoint URL" field, and if you hide that field with `show-endpoint="false"` (below), nobody types anything and whatever the record was created with is what ships. It can be relative, which is usually what you want on a server-rendered site: ```json { "url": "AddUserFromSite.aspx", "method": "GET" } { "url": "/handlers/FormProApi.ashx", "method": "POST" } ``` `GET` puts the fields in the query string (`?email=…`, which `Request.QueryString` reads); `POST` sends them as a JSON body. Cross-origin either way needs `Access-Control-Allow-Origin` on the response — a same-origin handler like the two above needs nothing. > **A placeholder is worse than an empty field.** `"https://"` is a scheme with no site attached. It > passes every "is it filled in" check, then fails inside `fetch` while the URL is being parsed — > *before* a request object exists. Nothing appears in **DevTools → Network**, not even a red row, > and the visitor just sees your `onError` message. Call `validatePopup(form)` before you store a > form and it's reported as an error on `url`; at runtime the renderer logs > `[creaditor] Form "…" could not submit to …` to the console. **A redirect is not a substitute.** `onSuccess: { type: "redirect" }` decides where the visitor's browser goes *after* `form.url` has already answered successfully. It is not a way to deliver the submission — with no working `form.url` the submit fails first and the redirect never runs. If you want your `.aspx` to receive the data, put its address in `form.url`. ### What your backend still has to do Two things an author can configure in the editor are **declarations the frontend never acts on** — if your ASPX side ignores them, they silently do nothing: | On the form JSON | Your backend's job, when the submission arrives | | --- | --- | | `emailAutomations[]` — `{ id, to, subject? }` | **Send the mail.** The builder and renderer never send anything; this is stored intent only. | | `submitTargets[]` with `fireFromClient: false` (what mailing-list automations compile to when you configure them that way) | Perform the subscribe/unsubscribe. `readMailingListAutomations(form, config)` decodes them back into `{ listId, action }`. | Both keep the visitor's submit to a single request and keep your endpoints and credentials off the public page, which is the reason to prefer them on a server-rendered site. > **Editor vs renderer bundles:** the editor (`creaditor-form-builder.js`) is for the admin > page where staff author forms; the renderer (`creaditor-renderer.js`) is for the public > pages where visitors see them. They're separate files — don't load the (much larger) > editor bundle on public pages. --- ## 6. Publish → copy the embed Clicking **Publish** in the editor fires the `publish` event (§4) and opens a popover with a copy button. What it offers for copying is **yours**: your script tag, your element, and the id your own database knows the form by. Set it with `embed-snippet` or `fb.embedSnippet`. If the form already has an id (the author is editing a saved form), emit the snippet from the server and you're done — no JavaScript at all: ```aspx ``` `{{id}}` is filled in from the form. Note the single quotes: the snippet contains double quotes of its own. A **new** form has no id yet, and publishing is what creates it. For that, set the property to a function. It may return a promise, so the save and the id it hands back both happen before the snippet appears (the popover shows a loading line meanwhile): ```html ``` > The `'` inside an inline > `