# From a model

Source: https://material.spynejs.com/components/from-a-model
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

The model keys at work: a hero, a call-to-action banner, a split feature and a contact form, each one of the Shell's own page items drawn from the model as a generated app would write it, and each with the piece of the model that draws it written out beside it. This is the page to copy from.

## In an app model

Four things, and where each is written in a model. Each one’s model is written out in full below, as the page shows it.

| Key | Means |
| --- | --- |
| `hero` | on a page’s own node: the page’s hero |
| `pageItems` | on a page’s node: the list of what the page shows under its hero, in order |
| `viewClass` | in a page item: `ViewStream` for one that is a template and data; `ContactUsView` for the contact form |
| `isPrototype` | in a page item: `false` where `props.template` is a file’s name. Without it the name is taken for the template’s own text and drawn as words. |
| `props.template` | in a page item: which of the template’s page items it is, by its file’s name, such as `cta-banner.tmpl.html` or `split-feature.tmpl.html` |
| `props.data` | in a page item: its words, and its `button` key where it has a call to action |
| `props.class` | in the contact form’s page item: `contact-us`, the class its styles go by |
| `container` | in a page item: `{ "isEnabled": true }` for the surface it sits on |

- A key that names an attribute starts with `attr`: `attrCtaHref`, `attrImageSrc`, `attrId`. A key that is words does not: `ctaText`, `headline`, `label`. One exception, which is the Shell’s: a split feature’s row writes its link as `ctaHref`.
- Each row of a split feature has its own `ctaText`, so each may have its own `button` key.
- In the contact form the `button` key sits beside `formFields`. The form always adds a Message field after the entries of `formFields`.
- A banner’s button is a link of the app’s router and goes by `attrPageId`, the `pageId` of the page it leads to; `attrCtaHref` is the same place as an address. A hero’s button and a row’s button are plain links and take only the address.
- The form on this page is a placeholder: it sends to the Shell’s mock endpoint, which answers only while a dev build is running.

## The keys each one reads

From each one’s template. Each is written out in full, with its values, in the page as it is shown below.

| Thing | Where | Keys |
| --- | --- | --- |
| Hero | `hero`, on the page’s node | `eyebrow`, `headline`, `subheadline`, `ctaText`, `attrCtaHref`, `attrImageSrc`, `attrImageAlt`, `button` |
| Call-to-action banner | `props.data` | `headline`, `text`, `ctaText`, `attrCtaHref`, `attrPageId`, `button` |
| Split feature | `props.data.rows`, a list | each row: `headline`, `text`, `attrImageSrc`, `ctaHref`, `ctaText`, `button` |
| Contact form | `props.data` | `title`, `subtitle`, `formFields`, `messageLabel`, `attrMessagePlaceholder`, `button`; and `successMessage` in `props` |

- A row’s picture takes the row’s `headline` for its words; a row has no key for them.
- Give `ctaText` no words (`""`) and no button is drawn.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/app/components/page-items/templates/hero.tmpl.html` | the hero |  |
| `src/app/components/page-items/templates/cta-banner.tmpl.html` | the call-to-action banner |  |
| `src/app/components/page-items/templates/split-feature.tmpl.html` | the split feature and its rows |  |
| `src/app/components/page-items/templates/contact-us.tmpl.html` | the contact form |  |
| `src/app/traits/page/page-item-core-traits.js` | makes a page item from its entry in the model, and gives a call to action its button’s look | `pageItemCore$GiveButtonLook` |
| `src/app/traits/utils/page-item-template-lookup.js` | every template in that folder by its file’s name: what a model’s `props.template` can name |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

What it rests on in `@spynejs/grammar`: `op:author-pageitem-spec`, `op:author-app-model-node`.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

From a model

### The keys at work

Everything on this page is one of the Shell’s own page items, drawn from the model as a generated app would write it. Nothing here has code of its own.

- [The button’s keys](https://material.spynejs.com/components/buttons.md)

#### The hero above

A page’s hero is the key hero on the page’s own node. Its button is tonal and medium: the button key, beside ctaText.

```json
{
  "hero": {
    "eyebrow": "From a model",
    "headline": "The keys at work",
    "subheadline": "Everything on this page is one of the Shell’s own page items, drawn from the model as a generated app would write it. Nothing here has code of its own.",
    "ctaText": "The button’s keys",
    "attrCtaHref": "/components/buttons",
    "attrImageSrc": "imgs/gallery/from-a-model.svg",
    "attrImageAlt": "",
    "button": {
      "variant": "tonal",
      "size": "md"
    }
  }
}
```

#### A call-to-action banner

Its button is elevated and large, because its model says so.

- [All components](https://material.spynejs.com/components.md)

##### The banner above

A page item. The button key is in its data, beside ctaText.

```json
{
  "viewClass": "ViewStream",
  "isPrototype": false,
  "props": {
    "template": "cta-banner.tmpl.html",
    "data": {
      "headline": "A call-to-action banner",
      "text": "Its button is elevated and large, because its model says so.",
      "ctaText": "All components",
      "attrCtaHref": "/components",
      "attrPageId": "components",
      "button": {
        "variant": "elevated",
        "size": "lg"
      }
    }
  },
  "container": {
    "isEnabled": true
  }
}
```

##### A row with the key

Its button is outlined and square.

- [Button](https://material.spynejs.com/components/buttons.md)

##### A row without it

Its button is as the Shell has always written it.

- [Text field](https://material.spynejs.com/components/text-fields.md)

##### The two rows above

One page item. Each row has its own ctaText, so each row may have its own button key. The second row has none.

```json
{
  "viewClass": "ViewStream",
  "isPrototype": false,
  "props": {
    "template": "split-feature.tmpl.html",
    "data": {
      "rows": [
        {
          "headline": "A row with the key",
          "text": "Its button is outlined and square.",
          "attrImageSrc": "imgs/gallery/buttons.svg",
          "ctaHref": "/components/buttons",
          "ctaText": "Button",
          "button": {
            "variant": "outlined",
            "shape": "square"
          }
        },
        {
          "headline": "A row without it",
          "text": "Its button is as the Shell has always written it.",
          "attrImageSrc": "imgs/gallery/text-fields.svg",
          "ctaHref": "/components/text-fields",
          "ctaText": "Text field"
        }
      ]
    }
  },
  "container": {
    "isEnabled": true
  }
}
```

#### A contact form

Five fields from the model, then the message field the Shell’s form always has.

Field: Name

Field: Email

Field: Phone

Field: Notes

Field: Reference

Field: Message

Button: Send Message

##### The form above

Name and Email say attrRequired. Phone says nothing, so it need not be filled in. Notes says multiline. Reference says attrDisabled. The button key sits beside formFields. Sending goes to the Shell’s mock endpoint, which answers only while a dev build is running.

```json
{
  "viewClass": "ContactUsView",
  "isPrototype": false,
  "props": {
    "class": "contact-us",
    "template": "contact-us.tmpl.html",
    "data": {
      "title": "A contact form",
      "subtitle": "Five fields from the model, then the message field the Shell’s form always has.",
      "formFields": [
        {
          "attrId": "model-name",
          "label": "Name",
          "attrName": "fullName",
          "attrPlaceholder": "Your name",
          "attrType": "text",
          "attrRequired": true
        },
        {
          "attrId": "model-email",
          "label": "Email",
          "attrName": "email",
          "attrPlaceholder": "you@example.com",
          "attrType": "email",
          "attrRequired": true
        },
        {
          "attrId": "model-phone",
          "label": "Phone",
          "attrName": "phone",
          "attrPlaceholder": "If you would like a call",
          "attrType": "tel"
        },
        {
          "attrId": "model-notes",
          "label": "Notes",
          "attrName": "notes",
          "attrPlaceholder": "Anything we should know",
          "multiline": true
        },
        {
          "attrId": "model-reference",
          "label": "Reference",
          "attrName": "reference",
          "attrPlaceholder": "Filled in by us",
          "attrType": "text",
          "attrDisabled": true
        }
      ],
      "messageLabel": "Message",
      "attrMessagePlaceholder": "What would you like to say?",
      "button": {
        "variant": "tonal"
      }
    }
  },
  "container": {
    "isEnabled": true
  }
}
```
