Site widgets

Open Widgets and press Add a widget. The setup takes a few steps:

Added widgets are listed on the Widgets page. Each one has a switch to turn it on or off straight away, Edit (the same steps again, without picking the widget) and Remove. Removing takes it off your site at once and puts its settings back to the defaults; you can add it again any time.

Widgets are ready-made pieces for a website or app you host yourself: sign-in, a cart, checkout and order history today, with forms and more on the way. They talk to your project’s public API, so any project with one can use them, websites and APIs alike. Find them in the panel under Site → Widgets (websites) or next to the Public API (other projects).

<script src="https://mint-c5e1255519fc.herokuapp.com/public/mint.js" data-key="<project key>" async></script>

The Widgets page has this tag ready with your project filled in. Put it in <head> or just before </body>. Then place a widget with its snippet, such as <div data-mint="login"></div>, or as a tag: <mint-login></mint-login>.

• A widget shows only once it’s added and switched on. Switch it off (or remove it) and it disappears from your site within a minute.
• Each widget’s code loads only on pages that use it.
• Widgets draw in their own sealed area: your CSS can’t break them and theirs can’t touch your page.
• Widgets added to the page later (single-page apps, pop-ups) are picked up too.

The Look panel appears once you’ve added a widget, and has its own Save. Each widget’s setup ends with a live preview on a light or dark page, showing your settings before anything goes live.

It uses the same customer accounts as the public API’s signed-in endpoints. See Customers for how those accounts work.

Under Texts you can reword every title, button and link, for example into your own language. In the signed-in text, {name} becomes the customer’s name.

To change an option on one page only, add it to the element as a data- attribute:

<div data-mint="login" data-layout="button"></div>
<mint-login data-start-with="signup"></mint-login>

Out of the box, everyone who signs up is on your Customers page. If you have a model of your own for customers, for example Members or Customers, first open it to sign-in: switch on People can sign up and sign in on the model’s Advanced tab. Only models switched on there are offered. Then pick it in the widget setup’s Customers step, choose which fields hold the email, name and phone, then choose how:

Either way, passwords never go into your model: MINT keeps them safely (scrambled, never shown to anyone), along with staying signed in and signing out everywhere. When a customer changes their name or phone on your site, their record changes too.

The model must be a list (not a single record), and any other required field needs a default value, because the record is made from the sign-up form alone. The panel says so if it doesn’t fit. If you later remove a field you picked, sign-up keeps working; the setup then tells you to pick the fields again.

Your own code sees the record’s ID as Mint.auth.user.record. With your model’s public API on, signed-in and owner-only, a customer can read and update the record their sign-up made, and nobody else’s. A record your team made earlier is linked but not handed over, because an email address alone doesn’t prove who someone is.

A project has one sign-in model. Rather than a model each for customers, members and staff, give that model an Options field such as Customer role (Customer, Seller, Picker…) and choose it as the Customer role in the widget’s Customers step. Everyone signs in the same way, with one password, and an email belongs to one account.

• New sign-ups get the field’s default. Give it one, such as Customer.
• Only your team changes a customer role, on the record in the panel. Your site and the API can’t, so nobody can make themselves a seller.
• These are your customers’ roles. Your team’s roles (Project → Members → Roles) are separate and don’t mix with them.
• A change counts straight away. The customer doesn’t need to sign in again.
• On an endpoint for signed-in customers, tick Which customer roles to let in only those (see Who can call it). A rule can also compare a field with their customer role.
• Your own code sees it as Mint.auth.user.customerRole.
• A record your team made before the person signed up (linked by email) gives them no customer role. An email address alone doesn’t prove who someone is. Set the customer role on their record once you know.

Details that only some customers have, such as a seller’s shop name, can live in a model of their own that links to the sign-in model.

Put a login on a page for one customer role with data-customer-role, or set the widget’s Customer role (this login) for every page:

<div data-mint="login" data-customer-role="seller"></div>

• Only accounts with that customer role sign in there. Anyone else is told it’s for another kind of account, and gets no session.
• Its Create an account makes that role, but only for roles you switch on under Who can sign up as each customer role in the widget’s Customers step. The default role is always on. For the others (pickers, staff), the link doesn’t show, and your team gives the role on the record.
• Protect what each role uses with endpoints: give sellers their own paths (/seller/orders) and tick Which customer roles on them.
• Your own form can do the same: Mint.auth.signIn(email, password, { customerRole: 'seller' }) and Mint.auth.signUp({ …, customerRole: 'seller' }).
• Signing up with the email of a record your team already made links that record but gives no customer role. Set it on the record once you know who they are.

Under the sign-in form there’s a Forgot your password? link. The customer types their email and is told a link is on its way. They see the same message whether or not that email has an account, so nobody can use it to find out who your customers are. It works the same for accounts in MINT’s Customers and accounts your own model holds.

• The email comes from your project’s own email account (Project → Email, or your organization’s). Until one is set up, visitors are told the email can’t be sent.
• The link leads back to the page they asked from, as long as it’s on one of your project’s domains. Anywhere else, it opens a Choose a new password page hosted by MINT, so a link never goes to a site that isn’t yours.
• The link works once, for an hour. Setting the new password signs them in there and signs them out on every other device.

The email shows in your email log as Password reset, using your email design. To hide the link, switch off Show “Forgot your password?” in the widget’s options. Building your own form? Use Mint.auth.forgotPassword and resetPassword.

Widgets don’t assume what your models are called. In a selling widget’s setup (its Shop step), or under Shop on the Widgets page once one is added, pick the model that holds your products and say what its fields mean. If your project came from the E-commerce or Products & orders template, this is filled in for you: check it and save.

Set up the Shop first, then switch the Cart on. Put the cart where it should show, and data-mint-add on any button with the product’s ID (the ID on its record page):

<div data-mint="cart"></div>

<button data-mint-add="PRODUCT_ID">Add to cart</button>
<button data-mint-add="PRODUCT_ID" data-mint-variant="Large" data-mint-quantity="2">Add two, large</button>

A product with variants opens a picker that shows each variant’s price and which ones are sold out. Name the variant with data-mint-variant to skip it.

Guests and accounts. A guest’s cart is kept in their browser. When they sign in or create an account, it joins their account’s cart, and from then on it follows them between phone and laptop. Signing out leaves an empty cart on that browser.

Stock and prices. If someone asks for more than you have, the quantity is cut to what’s in stock and the cart says so. Sold-out products stay in the cart, marked, and aren’t counted in the subtotal. Products you stop selling disappear from carts.

Put it on your checkout page and set the Cart’s Checkout page to that address. It needs the Shop’s orders and a way to pay switched on in Payments.

<div data-mint="checkout"></div>

With more than one provider switched on, the buyer picks how to pay (card through Stripe, SSLCommerz, bKash). Pay writes the order as waiting for payment and sends the buyer to that provider’s page. If something in the cart changed meanwhile (a price, sold out), the widget says so and shows the cart as it is now.

<div data-mint="thanks"></div>

It reads the payment’s reference from the page’s address (?ref=…), waits for the provider’s confirmation — usually a second or two — and shows the order number and what was bought. A guest’s cart is emptied then.

<div data-mint="login"></div>
<div data-mint="orders"></div>

Each order shows its number, date, status (as your team sets it — Paid, Packed, Shipped…), total and items.

<script>
  document.addEventListener('mint:auth', e => {
    document.body.classList.toggle('signed-in', !!e.detail);
  });
  async function myOrders() {
    await Mint.auth.ready;
    if (!Mint.auth.user) return [];
    const res = await Mint.api('orders?sort=-createdAt');
    return (await res.json()).doc;
  }
</script>

window.MintAuth still works and is the same object as Mint.auth.

• More ways to pay: cash on delivery and bank transfer everywhere, and refunds. Stripe works now, and in Bangladesh SSLCommerz and bKash too — which ones you can use depends on your organization’s country, set in organization settings; see Payments.
• Forms: contact and newsletter forms built from your models, with spam protection.
• Booking: free slots worked out on the server, so there are no double bookings.
• WhatsApp button, cookie consent and search.