# Defining a global

A global is content that exists once and appears on many pages: the header, the footer, the company's contact details. You declare it in code; editors edit it in one place under Globals.

## Two kinds

`smoodly.global()` takes a name, a title, and exactly one of `section` or `fields`:

File: `smoodly/globals.ts`

```ts
import { f, smoodly } from "smoodly";
import { headerSchema } from "@/components/sections/Header.schema";
import { footerSchema } from "@/components/sections/Footer.schema";
import { quoteSchema } from "@/components/sections/Quote.schema";

export const header = smoodly.global({ name: "header", title: "Header", section: headerSchema, layout: true });

export const footer = smoodly.global({ name: "footer", title: "Footer", section: footerSchema, layout: true });

export const contact = smoodly.global({
  name: "contact",
  title: "Contact details",
  fields: {
    email: f.text(),
    phone: f.text().optional(),
    address: f.text().localized(),
  },
  layout: true,
});

export const quote = smoodly.global({ name: "quote", title: "Quote", section: quoteSchema });

export const globals = [header, footer, contact, quote];
```

- A **visual global** takes a registered section's schema. Its fields, settings and styles are the section's, and it renders through the section's view. The starter's header, footer and quote are visual.
- An **object global** takes fields of its own and renders nowhere by itself; your code reads it. The starter's contact details are one, read by the footer.

Register the list in the config's `globals`. A visual global's section must be in the `sections` list too, which is why the starter's header and footer sit in `smoodly/sections.ts` although no zone lists them.

## Layout globals

`layout: true` says a global is part of every page: the header, the footer, the contact details the footer shows. On Astro the page's own read brings every layout global along, so the layout's `getLiveEntry` calls cost nothing; a page that hides the header simply does not read it. Leave the flag off a global that editors place in zones or that one view reads, such as the starter's quote or a form section used on a few pages: it is resolved into each page that places it, and a view that reads it pays one call. In development, a page render that reads an unflagged global prints a hint naming it, once. On Next the flag changes nothing: its data cache keeps every global until that global is published again.

## In the admin

*Globals*, under ⋮ in the admin's top bar, lists every global with its kind, *Visual* or *Fields*, and its status in the selected language. A *Fields* global opens a form like an entry's, the fields in schema order. A *Visual* global opens on a canvas: a page of the site that shows it, the home page for a `layout` global and otherwise the first page that places it, with the global selected and the rest of the page dimmed. Its fields sit beside the canvas under *Content* and *Settings*, text marked for inline editing can be typed in place, and when several pages place it, *Shown on* picks the page. A visual global no page shows yet opens as a form. Either way the page autosaves, and carries the same *Publish* control, *History* and *Discard changes* as a page.

A global exists in every language from the start, so there is nothing to add or delete. Publishing is per language, as for pages. A field's value is shared across languages unless it chains `.localized()`: the starter's contact email is one value, its address is translated.

## Reading a global

Your code reads a global by name and language, through the [reads](https://smoodly.io/docs/collections/queries.md). It is `null` until the global is published in that language, so the caller renders nothing rather than an empty header.

**Astro**

A global item is its own live collection, `globalLoader(footer)` in `src/live.config.ts`, read with `getLiveEntry("footer", { locale })`; the value is the entry's `data`:

File: `src/layouts/Layout.astro`

```astro
---
// …
const [{ entry: header }, { entry: footer }, { entry: contact }] = await Promise.all([
  getLiveEntry("header", { locale }),
  getLiveEntry("footer", { locale }),
  getLiveEntry("contact", { locale }),
]);
// …
---
// …
    {footer && <Footer {...footer.data.fields} settings={footer.data.settings} styles={footer.data.styles} contact={contact?.data.fields} />}
```

**Next.js**

`getGlobal` reads it:

File: `app/[locale]/layout.tsx`

```tsx
  const [footer, contact] = await Promise.all([
    q().getGlobal("footer", { locale }),
    q().getGlobal("contact", { locale }),
  ]);
  // …
          {footer && <FooterView {...footer.fields} settings={footer.settings} styles={footer.styles} contact={contact?.fields} />}
```

A global resolves to `{ locale, fields }`, and a visual global adds `settings` with defaults filled, and `styles`. Spread `fields` onto the section's view, with `settings` and `styles` beside it, and the section renders with the spacing steps an editor chose and the id the canvas uses to select it.

## Placing a global on a page

A visual global can also be placed in a zone. `z.locked(quote)` binds a zone to it, so every page of that type shows the one quote; in a freeform or sections zone that allows the global's section, the *Add section* picker offers it under *Global*. A placed global is a link, not a copy: editing it anywhere changes it everywhere, and the canvas tags it *global*.

A page cannot be published in a language while a global it shows is unpublished there. Publishing the page does not publish the global; that is a click of its own, in the global's canvas card or on its page.

Next, [Header and footer](https://smoodly.io/docs/globals/header-and-footer.md) walks through the starter's layout.
