...
+ ...
- …
Header
Content
{% endblock %} +``` + +```jsx +Header
} + main={Content
} +/> +``` + +`` and `})
+ );
+}
+```
+
+Note `srcset` lowercase — `srcSet` is not translated.
+
+## Raw HTML
+
+```nunjucks
+{{ data.widget.content | safe }}
+```
+
+```jsx
+
+```
+
+The attribute name is deliberately alarming; treat it that way. Never pass
+untrusted input through it. Nunjucks `SafeString` values returned from helpers
+pass through unescaped without needing this.
+
+## Localization
+
+`__t` is on the helper object and matches the Nunjucks global:
+
+```jsx
+export default function(data, { __t }) {
+ return {__t('project:articleBlurb')}
; +} +``` + +## Filter substitutions + +| Filter | JSX equivalent | +| --- | --- | +| `build` | `apos.url.build(...)` | +| `escape` | Unnecessary — JSX auto-escapes | +| `safe` | `dangerouslySetInnerHTML={{ __html: value }}` | +| `nlbr` | `value.split('\n').map((line, i) => <>{i > 0 &&}{line})` | +| `date` | Import `dayjs` — **verify format tokens and locale**, they differ | +| `striptags` | No safe one-liner; a regex mishandles attributes containing `>` and comments. Prefer stripping server-side in a module method | +| `clonePermanent`, `css`, `json`, `jsonAttribute`, `merge`, `nlp`, `query` | No documented equivalent — leave marked as TODO rather than inventing one | +```` + +## What this will not do for you + +The instructions make an assistant substantially more reliable on Apostrophe-specific mechanics. They do not make it correct. + +Expect to review carefully around: anything touching template filters or `super()`, where no clean equivalent exists and the assistant is guessing; macro conversions, where the whole importer set has to move together; and attribute-level details, which are exactly what silent failures look like. + +If your project is large, convert one module, review it thoroughly, and only then continue. The first module tells you how much you can trust the rest. diff --git a/docs/guide/jsx-templates.md b/docs/guide/jsx-templates.md index 56e8c4a6..74edfb7c 100644 --- a/docs/guide/jsx-templates.md +++ b/docs/guide/jsx-templates.md @@ -1,6 +1,6 @@ # JSX templates -Apostrophe page, widget, and component templates can be written in **JSX** as an alternative to [Nunjucks](/guide/templating.md). For developers already comfortable with React or another JSX-aware framework, this means modern editor support, real JavaScript control flow, and accurate error reporting with source maps, without standing up a separate front-end project. +Apostrophe page, widget, and component templates can be written in **JSX** as an alternative to [Nunjucks](/guide/nunjucks-templates.md). For developers already comfortable with React or another JSX-aware framework, this means modern editor support, real JavaScript control flow, and accurate error reporting with source maps, without standing up a separate front-end project. ::: info This guide assumes you have written JSX before. It focuses on the Apostrophe-specific equivalents of Nunjucks features rather than on JSX itself. @@ -10,6 +10,10 @@ JSX templates are a server-side rendering option. They do **not** imply React: t JSX interoperates with Nunjucks in one direction: a `.jsx` template can extend or include a `.html` template (with block overrides where appropriate), but a `.html` template cannot extend or include a `.jsx` template. In practice this means you migrate a project from the leaves up, converting individual page and widget templates to JSX while keeping `layout.html` and the core Nunjucks templates in place. See [Migration order](#migration-order) for the rules. +::: tip Converting an existing project? +[Migrating templates with an AI assistant](/guide/jsx-migration-assistant.md) provides instructions you can copy into your project's `CLAUDE.md` or `AGENTS.md`, so a coding assistant follows the rules on this page instead of guessing at them. +::: + ::: info Right now, the easiest way to get a peek at a working project with JSX templates is: ```bash @@ -18,6 +22,7 @@ cd public-demo-jsx git checkout jsx npm install npm run dev +``` ::: ## File location and naming @@ -160,7 +165,7 @@ React-flavored attributes like `key` and `ref` are accepted but ignored. They ex
` emits **two** `class` attributes and browsers keep only the first.
+:::
+
+Everything else reaches the HTML exactly as you typed it. `data-*` and `aria-*` attributes pass through unchanged, which is what you want. But React's wider alias table is not implemented, so these do **not** become their HTML equivalents:
+
+```jsx
+![]()
+```
+
+```jsx
+
+```
+
+Write the HTML attribute name instead:
+
+```jsx
+![]()
+```
+
+```jsx
+
+```
+
+`srcSet` is a special case worth calling out: it appears to work, because HTML parsing is case-insensitive about attribute names. Write `srcset` anyway — the casing is meaningless here and it misleads the next reader.
+
+React's form conventions are likewise absent. Use the real HTML attributes:
+
+```jsx
+
+```
+
+### Event handler props do not work
+
+There is no event system and no hydration. A function passed as a prop is stringified into the attribute value:
+
+```jsx
+
+```
+
+Attach behavior from browser-side JavaScript instead, targeting the element by class or data attribute:
+
+```jsx
+
+```
+
+A lowercase inline `onclick="…"` **string** still works, because it passes through verbatim like any other attribute. That is ordinary HTML, not React — leave existing `onclick` attributes lowercase when converting a template rather than "tidying" them into `onClick`.
+
+### `style` takes a string, not an object
+
+```jsx
+
+```
+
+renders `style="[object Object]"`. Pass a string instead:
+
+```jsx
+
+```
+
+### `false`, `null`, and `undefined` remove the attribute entirely
+
+Any prop whose value is `false`, `null`, or `undefined` is omitted. A value of `true` renders the bare attribute. This matches HTML's boolean attributes and is usually what you want:
+
+```jsx
+
+```
+
+It differs from React for `aria-*`, where the string `"false"` is meaningful and an absent attribute is not the same thing:
+
+```jsx
+
+```
+
+drops the attribute entirely. Pass the string yourself:
+
+```jsx
+
+```
+
+### Non-string values are coerced, not validated
+
+An object used as a child renders as `[object Object]` rather than raising an error. Void elements given children serialize as malformed markup — `![]()
…` — instead of being rejected. The runtime will not catch these for you.
+
+### Absent entirely
+
+Hooks, state, context, refs, portals, hydration, class components, `memo`, and `forwardRef` do not exist. `key` and `ref` props are accepted and silently discarded — they exist in React to help the client-side reconciler, and there is no reconciler here. Don't bother adding them.
+
+::: info
+The useful mental model is **HTML written with JSX syntax**, plus function components and Apostrophe's async template helpers — not server-rendered React.
+:::
+
## Extending templates
JSX has no concept of named blocks. Markup the parent should render is passed in as **props**, including the implicit `children` prop made up of markup between the opening and closing tags, matching React conventions.
@@ -295,14 +408,117 @@ modules/default-page/views/page.jsx
::: info
-`` and `` differ only when the target is a `.html` file:
+`` and `` differ only when the target resolves to a Nunjucks file:
-- `` is **include semantics**: `foo` arrives in `data.foo` and `{% block %}` declarations in `layout.html` are not overridden.
-- `
+
+```jsx
+export default function({ beforeMain, children }, { Template }) {
+ return (
+
+ {children} }
+ />
+ );
+}
+```
+
+
+views/layout.jsx
+
+
+
+A page now passes only its own header, and never learns what the navigation is — which was the point of the original `super()` call:
+
+```jsx
+
+
+``` nunjucks
+{% block beforeMain %}
+ {% render navigation.navigationArea() %}
+ {% block pageHeader %}{% endblock %}
+{% endblock %}
+```
+
+
+views/layout.html
+
+
+
+Note this is *nesting*, not moving the markup out of the block — a template that uses `{% extends %}` can only contribute through blocks, so there is no "outside" available to it.
+
+::: warning
+Subdividing a block changes the parent's contract. Any Nunjucks child still overriding the **outer** block will drop or duplicate the shared markup, so convert those children first.
+:::
+
+### When you cannot edit the parent
+
+Hoist the parent's default into a component named after **the block**, not after its current contents, and let the parent's block body contain nothing else:
+
+```jsx
+// Right: names the block's default, so later changes to it still reach the child
+`. This is the intended steady state, not a limitation.
:::
@@ -366,6 +586,41 @@ export default function({ product }) {
This is in addition to ``, which exists for parity with Nunjucks's string-based lookup and to support Apostrophe's `module:file` cross-module syntax. Use direct `import` when the partial is co-located and you do not need name-based resolution; use `` when you do.
+### Coming from macros and fragments
+
+Nunjucks offers two ways to package reusable markup, and **both become function components here**.
+
+A [macro](/guide/nunjucks-templates.md#macros) is a reusable block of markup that cannot run asynchronous code. A [fragment](/guide/fragments.md) is Apostrophe's answer to that limitation — the same idea, but able to contain `{% area %}` and async components. JSX templates are real JavaScript, so a function component can already do async work. The distinction the two features existed to draw does not apply, and there is no separate construct to learn.
+
+| Nunjucks | JSX |
+| -------- | --- |
+| `{% macro x() %}` or `{% fragment x() %}` | `function X() { … }` |
+| `{% render x() %}` | `
+ Fun fact: {page.funFact}
+
+ );
+}
+```
+
+::: warning
+A macro or fragment and every template that imports it must convert **together**. The moment `file.html` becomes `file.jsx`, any remaining `.html` template importing it breaks — Nunjucks cannot load a JSX template. Count the importers before you start. See [Migration order](#migration-order).
+:::
+
## Widget templates
Widget templates work the same way as page templates: a default-exported function receiving `data` and the helper object. The widget data is on `widget`, and options and context options arrive as you would expect:
diff --git a/docs/guide/layout-template.md b/docs/guide/layout-template.md
index 8bef9839..e7554fa2 100644
--- a/docs/guide/layout-template.md
+++ b/docs/guide/layout-template.md
@@ -70,7 +70,7 @@ The most important templates blocks from that core layout template are:
| `afterMain` | A block after the `main` content block. Usually used for the website footer. |
| `extraBody` | A block at the end of the `body` tag. |
-The layout template and any page, index page, or show page template could use these blocks to overwrite them or add to them ([using the `super()` tag](/guide/templating.md#the-super-tag)).
+The layout template and any page, index page, or show page template could use these blocks to overwrite them or add to them ([using the `super()` tag](/guide/nunjucks-templates.md#the-super-tag)).
::: info NOTES
The `beforeMain`, `main`, and `afterMain` blocks are inside the section that Apostrophe refreshes regularly during content editing. Any `script` tags inside those blocks will run an indeterminate number of times during editing. Be especially careful when using event handlers. As a reminder, any widget-related JavaScript belongs in a [widget player](/guide/custom-widgets.md#client-side-javascript-for-widgets).
@@ -80,3 +80,66 @@ The `beforeMain`, `main`, and `afterMain` blocks are inside the section that Apo
**RTL language support:** The `outerLayout` template automatically applies the correct text direction (`dir` attribute) to the `` element based on your locale configuration. See the [localization guide](/guide/localization/overview.md#right-to-left-rtl-language-support) for more information.
:::
+
+## Writing a layout in JSX
+
+A layout can be written as `views/layout.jsx` instead. The block-based shape above doesn't translate directly — a JSX layout doesn't override `outerLayoutBase`'s blocks piecemeal, it renders the whole invariant part itself and exposes props for what each page needs to supply. This also resolves a case the Nunjucks version above can't express cleanly: `beforeMain` and `afterMain` open and close a single `
-
- {% endfor %}
-
- {{ pager.render({
- page: data.currentPage,
- total: data.totalPages,
- class: 'blog-pager'
- }, data.url) }}
-{% endblock %}
+```jsx
+/* modules/article-page/views/index.jsx */
+import Pager from './pager.jsx';
+
+export default function(
+ { page, pieces, currentPage, totalPages, url },
+ { Extend }
+) {
+ return (
+
+
+
+ ))}
+
+
-{% endfor %}
+))}
```
-Index page templates have access to `data.pieces`, which is an array of piece docs. Since it's an array, we use the [Nunjucks `for` tag](https://mozilla.github.io/nunjucks/templating.html#for) to loop over the pieces.
+Index page templates have access to `pieces`, which is an array of piece docs. Since it's an array, we use `.map()` to loop over the pieces.
The `data` object properties unique to index pages are:
@@ -181,33 +194,105 @@ The `data` object properties unique to index pages are:
### Pagination
-``` nunjucks
-{% import '@apostrophecms/pager:macros.html' as pager with context %}
+By default, index pages will include up to *ten* pieces on `pieces` at a time. **You can change the number of pieces in each page of results** by setting [the `perPage` option](/reference/module-api/module-options.md#perpage-1) on the module. The data passed to templates will update, so you don't need to make any other adjustments.
-{{ pager.render({
- page: data.currentPage,
- total: data.totalPages,
- class: 'blog-pager'
-}, data.url) }}
-```
+The `@apostrophecms/pager` module supplies the arithmetic for basic, unstyled pagination through three [helper methods](/reference/modules/pager.md#helpers). They return plain data — an array of page numbers and two booleans — so you write the markup yourself as an ordinary component:
-By default, index pages will include up to *ten* pieces on `data.pieces` at a time. **You can change the number of pieces in each page of results** by setting [the `perPage` option](/reference/module-api/module-options.md#perpage-1) on the module. The data passed to templates will update, so you don't need to make any other adjustments.
+
+
+```jsx
+export default function(
+ { page, total, url, className },
+ { apos, helpers, __t }
+) {
+ if (!(page > 1 || total > 1)) {
+ return null;
+ }
-Apostrophe's pager macro adds basic, unstyled pagination to view more. The pager macro is a special template using the [Nunjucks macro](https://mozilla.github.io/nunjucks/templating.html#macro) feature. This particular macro accepts two arguments:
+ // Normalize `shown` before calling any of the three helpers. They do not
+ // default it themselves, and an undefined `shown` makes both gap checks
+ // return false.
+ const options = { page, total, shown: 5 };
-1. an object with the `currentPage` and `totalPages` values, described above, as well as an optional CSS class for the pager wrapper
-```javascript
-{
- page: data.currentPage,
- total: data.totalPages,
- class: 'my-pager-class' // Optional
+ const pages = helpers.pager.pageRange(options);
+ const showHeadGap = helpers.pager.showHeadGap(options);
+ const showTailGap = helpers.pager.showTailGap(options);
+
+ const itemClass = className ? `${className}__item` : '';
+ const gapClass = className ? `${className}__gap` : '';
+
+ function Gap() {
+ // Decorative: the surrounding numbers already imply the skipped pages.
+ // Must be the string 'true' — see the note below.
+ return ;
+ }
+
+ function Page({ number }) {
+ const active = number === page;
+ const classes = [
+ itemClass,
+ number === 1 && 'is-first',
+ number === total && 'is-last',
+ active && 'is-active'
+ ].filter(Boolean).join(' ');
+
+ return (
+
+ {active
+ ? number
+ : (
+
+ {number}
+
+ )}
+
+ );
+ }
+
+ return (
+
+ );
}
```
-2. the page URL, `data.url`
+
+
+ modules/article-page/views/pager.jsx
+
+
+
+The three helpers are reached through **`helpers.pager`**, the template-helper object supplied as part of the second argument — not through `apos.pager`, which is the module instance and does not expose them directly. `apos.url.build()` builds each page's URL.
+
+`shown` controls how many interior page numbers appear, not counting the separately rendered first and last pages.
+
+### Accessibility notes
+
+Pagination is easy to render in a way that looks right but tells assistive technology nothing. Four details in the example above are doing that work:
+
+- **`
-## Alphabetical Apostrophe filter reference
+## Alphabetical ApostropheCMS filter reference
### `| build(url, path, data...)`
diff --git a/docs/guide/templating.md b/docs/guide/templating.md
index b81c6d37..d8ea31ee 100644
--- a/docs/guide/templating.md
+++ b/docs/guide/templating.md
@@ -1,171 +1,41 @@
# Working with templates
-Templates are where code and content turn into web pages people can actually see and use. Apostrophe templates are most commonly written in the Nunjucks templating language, looking like normal HTML markup with special tags and variables sprinkled throughout to render data, though Apostrophe also supports writing templates as JSX.
+Templates are where code and content turn into web pages people can actually see and use.
-::: tip
-JSX templates run on the server with no client-side JavaScript required. Nunjucks remains the default in our starter kits, but we're gradually expanding our documentation to show JSX examples alongside Nunjucks. See the [JSX templates](/guide/jsx-templates.html) guide to get started.
-:::
+Apostrophe supports two template languages, and a single project can use both at once:
-Template files go in `views` directories, either as module subdirectories or at the project root.
-
-
-
-The root `views` directory will usually contain [a layout template](/guide/layout-template.md) and often [fragment templates](/guide/fragments.md). Templates in modules' `views` directories will usually be used only for their respective modules. [Widget](/guide/custom-widgets.md#widget-templates), [page](/guide/pages.md#page-template-essentials), and [piece page](/guide/piece-pages.md#the-index-page-template) templates are the main examples of that.
-
-## How templates work together
-
-To paraphrase [John Donne](https://en.wikipedia.org/wiki/John_Donne), no template is an island. Templates will always be used as a system. We do this with the **`extends`**, **`include`**, and **[`import`](/guide/fragments.md)** tags.
-
-### Extending templates
-
-When you use the `{% extends %}` tag in a template, it will inherit all of the markup and template blocks of the template it is extending. Any template blocks used in the *extending* template will replace matching blocks in the *extended* template.
-
-For example, the layout template will often be structured like this:
-
-``` nunjucks
-{# views/layout.html #}
-{% extends data.outerLayout %}
-
-{% block beforeMain %}
- {# Page header markup and the main content area opening tag... #}
-{% endblock %}
-
-{% block main %}{% endblock %}
-
-{% block afterMain %}
- {# The main content area closing tag and page footer... #}
-{% endblock %}
-```
-
-Individual page type templates will extend that layout:
-
-
-
-``` nunjucks
-{% extends "layout.html" %}{# 👈 Our template extension #}
-
-{% block main %}
- {% area data.page, 'mainContent' %}
-{% endblock %}
-```
-
-modules/default-page/views/page.html
-
-
-
-`page.html` *inherits* all of the markup and template blocks of `layout.html`. When it uses the `main` block, that *replaces* only the matching block from `layout.html`.
-
-::: info
-You may have noticed that the layout template above also extends another template. `data.outerLayout` is a core, base level template. See the [layout template](/guide/layout-template.md) guide for more on that.
-:::
+- **[JSX templates](/guide/jsx-templates.md)** — the recommended choice for new work. A template is a JavaScript module exporting a function that returns markup. It runs entirely on the server; no client-side JavaScript is involved and there is no React runtime.
+- **[Nunjucks templates](/guide/nunjucks-templates.md)** — HTML with tags and variables sprinkled through it. Fully supported, and what existing projects and the starter kits use today.
-#### The `super()` tag
+A `.jsx` template can extend or include a `.html` one, so you can move a project across a file at a time. The reverse does not work — a Nunjucks template cannot extend a JSX one — which is why migrations run from the leaves up. See [migration order](/guide/jsx-templates.md#migration-order).
-**You can also *add to* template block content, rather than completely replace it.** To do this, include a `super()` render tag at the beginning of a block. `super()` will render as the contents of the inherited block.
+## Where templates live
-For example, this may be in your layout file:
-
-
-
-``` nunjucks
-{% block main %}
-
-
-In my home page template I could extend the layout template and use `super()` to include that `h1` tag before new content markup:
-
-
-
-``` nunjucks
-{% block main %}
- {{ super() }} {# 👈 That will render the tag above #}
-
-
-See another example [in the Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html#template-inheritance).
-
-### Including templates
-
-The `{% include %}` template tag pulls one template *into* another template. This can be useful to break large template files into pieces. For example, you might write your site footer in a template file: `views/footer.html`. The layout template could include that like so:
-
-
-
-``` nunjucks
-{% block afterMain %}
- {# Closing tag for the main block #}
- {% include "footer.html" %}
-{% endblock %}
-```
-
-views/layout.html
-
-
-
-That footer template would render as part of the layout template.
-
-See more about including templates [in the Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html#include).
-
-### Referencing templates across modules
-
-The `include` and `extends` tags in the examples above name "global templates," which are in the root `views` directory. As such, we can simply reference by file name: e.g., `{% extends "layout.html" %}` or `{% include "footer.html" %}`. You could do the same thing if both templates were in the *same* module directory (both in our `modules/default-page/views` directory).
-
-In some cases, **we will need to extend or include a template file that belongs to a separate module**. In that case, we need to provide additional information so Apostrophe can find that template.
-
-For example, we may have a default page type that includes a sidebar we want to use in other page types:
+Template files go in `views` directories, either as module subdirectories or at the project root.
-
+
-``` nunjucks
-{% extends "layout.html" %}
+The root `views` directory will usually contain [a layout template](/guide/layout-template.md) and often [fragment templates](/guide/fragments.md). Templates in modules' `views` directories will usually be used only for their respective modules. [Widget](/guide/custom-widgets.md#widget-templates), [page](/guide/pages.md#page-template-essentials), and [piece page](/guide/piece-pages.md#the-index-page-template) templates are the main examples of that.
-{% block main %}
- {# 👇 Sidebar that we'll reuse. #}
-
+When you name a template without an extension, Apostrophe walks the module's view-folder override chain, preferring `.jsx` then `.njk` then `.html` **within each folder** — so a template in a nearer override folder wins regardless of its extension. See [`render()`](/reference/modules/module.md#async-render-req-template-data).
-Let's extend it in a contact page type to reuse that sidebar. We will only replace the `content` block. To do this, the `{% extend %}` tag must include the name of the default page module:
+## How templates work together
-``` nunjucks
-{% extends "default-page:page.html" %}
+To paraphrase [John Donne](https://en.wikipedia.org/wiki/John_Donne), no template is an island. Templates are always used as a system, composed three ways:
-{% block content %}
- `](/guide/jsx-templates.md#extending-templates) | [`{% extends %}`](/guide/nunjucks-templates.md#extending-templates) |
+| **Including** | One template is pulled *into* another | [``](/guide/jsx-templates.md#including-another-template) | [`{% include %}`](/guide/nunjucks-templates.md#including-templates) |
+| **Cross-module references** | Naming a template that belongs to a different module, as `module-name:file` | [``](/guide/jsx-templates.md#including-another-template) | [`{% extends "module:file.html" %}`](/guide/nunjucks-templates.md#referencing-templates-across-modules) |
-`{% extends "default-page:page.html" %}` tells Apostrophe that we are using the `page.html` template file that belongs to the `default-page` module. The same pattern applies when using the `include` tag.
+The composition model is the same in both languages. What differs is the syntax: a Nunjucks template declares `{% block %}` regions that a child overrides by name, while a JSX template passes those same named regions as **props**, so a block's content is an expression rather than a tag pair.
-::: tip
-The Nunjucks templating language includes many tags and tools you can use in Apostrophe templates. These include:
+Almost every page template extends a layout, which in turn extends Apostrophe's core outer layout. See the [layout template](/guide/layout-template.md) guide for how that chain fits together.
-- Adding conditional checks
-- Looping over arrays
-- Declaring variables
-- Comparison and math operators
+## Further reading
-See the official [Nunjucks templating documentation](https://mozilla.github.io/nunjucks/templating.html) to see what is available.
-:::
+- [JSX templates](/guide/jsx-templates.md) — syntax, the Nunjucks-to-JSX cheat sheet, and what does not carry over from React
+- [Nunjucks templates](/guide/nunjucks-templates.md) — syntax, tags, filters, macros, and `super()`
+- [Template data](/guide/template-data.md) — what is available inside a template
+- [Areas and widgets](/guide/areas-and-widgets.md) — rendering editable content
diff --git a/docs/guide/users.md b/docs/guide/users.md
index 3ddf0965..4414e13b 100644
--- a/docs/guide/users.md
+++ b/docs/guide/users.md
@@ -49,7 +49,7 @@ node app @apostrophecms/user:change-password username
You can [read more about permissions and content workflows](/guide/permissions-and-workflow.md) to see how these roles work together in practice.
-## Logging into an Apostrophe website
+## Logging into an ApostropheCMS website
Users can log into Apostrophe websites at the `/login` URL path for the website. If the website base URL (homepage) is `https://example.rocks`, the login page will be `https://example.rocks/login`.
diff --git a/docs/guide/vite.md b/docs/guide/vite.md
index 89c1a542..8edd350c 100644
--- a/docs/guide/vite.md
+++ b/docs/guide/vite.md
@@ -422,7 +422,7 @@ In most cases, any **server** options shouldn't be touched in the Vite config. F
### Conditional Code Injection
-When building UI components, you may want certain elements to appear only during development or when HMR is active. ApostropheCMS's Nunjucks components system makes this easy to manage.
+When building UI components, you may want certain elements to appear only during development or when HMR is active. ApostropheCMS's async components system makes this easy to manage.
### Component Setup
@@ -430,15 +430,15 @@ First, create your component template:
-```njk
-
` across two separate blocks, which has no equivalent when there's no block system — a JSX layout renders that wrapping `
- ``` nunjucks
- {# In a page template or widget #}
-
@@ -133,13 +133,13 @@ You can also use it for conditional logic:
- ``` nunjucks
-
@@ -213,34 +213,47 @@ Here is an example of `data.localizations` for the page from the screenshots abo
Here is an example of using the `data.localizations` array to generate a locale switcher for a page.
-``` nunjucks
-
- ``` nunjucks
- {# More article template stuff above ⤴ #}
-
-
+ ```jsx
+ export default function({ piece }) {
+ /* More article template stuff above ⤴ */
+ return (
+
+
+ );
+ }
```
- /modules/article-page/views/show.html
+ /modules/article-page/views/show.jsx
-Localizing that string is as easy as wrapping it in a template helper: `__t()`. Make sure the string passed to the helper is in quotes and any matching quotes in the string are escaped (e.g., `__t('Gritty\'s friends')`).
+Localizing that string is as easy as wrapping it in a template helper: `__t()`. It arrives on the second argument of the template function, alongside `apos` and the `Area`/`Extend`/`Template` helpers. Make sure the string passed to the helper is in quotes and any matching quotes in the string are escaped (e.g., `__t('Gritty\'s friends')`).
- ``` nunjucks
- {# More article template stuff above ⤴ #}
-
-
+ ```jsx
+ export default function({ piece }, { __t }) {
+ /* More article template stuff above ⤴ */
+ return (
+
+
+ );
+ }
```
- /modules/article-page/views/show.html
+ /modules/article-page/views/show.jsx
@@ -54,8 +62,8 @@ In that example, we passed the actual text to the localization helper. This has
Our other option is to use a **localization key that is different from the original text**. Taking our example, that heading tag might instead look like:
-``` nunjucks
-
- ``` nunjucks
- {{ __t('Contact the {{ city }} office', {
- city: data.piece.city
- }) }}
+ ```jsx
+ {__t('Contact the {{ city }} office', {
+ city: piece.city
+ })}
```
- /modules/office-page/views/show.html
+ /modules/office-page/views/show.jsx
@@ -136,13 +144,13 @@ The arguments would look essentially identical in server-side or a UI file, usin
- ``` nunjucks
- {{ __t('contactOffice', {
- city: data.piece.city
- }) }}
+ ```jsx
+ {__t('contactOffice', {
+ city: piece.city
+ })}
```
- /modules/office-page/views/show.html
+ /modules/office-page/views/show.jsx
@@ -225,8 +233,8 @@ Although you can set the `i18n.ns` option of the module instead to define the na
Then when you use the localization keys in template files (or elsewhere), start each key with the namespace:
-``` nunjucks
-
-``` nunjucks
-{% area data.piece, 'photo' %}
+```jsx
+
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
@@ -95,13 +95,15 @@ For non-image attachments, simply pass the attachment object into the method.
-``` nunjucks
-{% set fileUrl = apos.attachment.url(data.piece.fileUpload) %}
+```jsx
+export default function({ piece }, { apos }) {
+ const fileUrl = apos.attachment.url(piece.fileUpload);
-Download
+ return Download;
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
@@ -110,30 +112,42 @@ For image attachments, doing the same thing will return the URL for the `full` i
-``` nunjucks
-{% set imgUrl = apos.attachment.url(data.piece.photoUpload, {
- size: 'one-third'
-}) %}
+```jsx
+export default function({ piece }, { apos }) {
+ const imgUrl = apos.attachment.url(piece.photoUpload, {
+ size: 'one-third'
+ });
-
+ return 
;
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
[Responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) are very important for cross-device support these days. Getting each image size to populate the `srcset` attribute for an image would get repetitive very quickly even using the `apos.attachment.url()` method. For that, there is a dedicated `apos.image.srcset()` method. Pass in the attachment object as an argument and it will return a `srcset` value with all sizes included.
-
+Write the attribute as `srcset`, not React's `srcSet`. Apostrophe's JSX templates pass attribute names through to HTML unchanged apart from `className` and `htmlFor`.
-``` nunjucks
-{% set srcset = apos.image.srcset(data.piece.photoUpload) %}
+
- }})
+```jsx
+export default function({ piece }, { apos }) {
+ const srcset = apos.image.srcset(piece.photoUpload);
+
+ return (
+ })
+ );
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
@@ -174,15 +188,17 @@ Since relationship fields can accept multiple values (e.g., connecting multiple
-``` nunjucks
-{% set filesObject = apos.attachment.all(data.piece._files) %}
+```jsx
+export default function({ piece }, { apos }) {
+ const filesObject = apos.attachment.all(piece._files);
-{% for file in filesObject %}
- Download file
-{% endfor %}
+ return filesObject.map((file) => (
+ Download file
+ ));
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
@@ -191,13 +207,21 @@ When the relationship field has the `max: 1` limit, or when we only want the fir
-``` nunjucks
-{% set imageObject = apos.attachment.first(data.piece._image) %}
+```jsx
+export default function({ piece }, { apos }) {
+ const imageObject = apos.attachment.first(piece._image);
+
+ if (!imageObject) {
+ return null;
+ }
- }})
+ return (
+ })
+ );
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
@@ -207,29 +231,36 @@ When working with images, additional helpers are available. As an example, see t
-``` nunjucks
-{% set attachment = apos.image.first(data.widget._image) %}
-
-{% if attachment %}
-  }})
-{% endif %}
+```jsx
+export default function({ widget, options }, { apos }) {
+ const attachment = apos.image.first(widget._image);
+
+ if (!attachment) {
+ return null;
+ }
+
+ return (
+ 
+ );
+}
```
- modules/article-page/views/show.html
+ modules/@apostrophecms/image-widget/views/widget.jsx
diff --git a/docs/guide/migration/overview.md b/docs/guide/migration/overview.md
index bddda70d..dc0b5665 100644
--- a/docs/guide/migration/overview.md
+++ b/docs/guide/migration/overview.md
@@ -5,7 +5,7 @@ next:
prev: false
---
-# Changes from Apostrophe 3 to Apostrophe 4
+# Changes from ApostropheCMS 3 to ApostropheCMS 4
Apostrophe 4.x (A4) differs from Apostrophe 3 in just one major area: the admin UI has been updated to use Vue 3,
the current major supported version of the Vue frontend framework.
@@ -16,7 +16,7 @@ some minor changes.
For more information, see the [3 to 4 upgrading guide](/guide/migration/upgrading-3-to-4.md).
-# Changes from Apostrophe 2 to Apostrophe 4
+# Changes from ApostropheCMS 2 to ApostropheCMS 4
**While upgrading from 2.x to 3.x is possible, there is no benefit in not going directly to 4.x because
differences between 3.x and 4.x are very minor, 3 will reach its end of life for security updates in 2025,
diff --git a/docs/guide/migration/upgrading-3-to-4.md b/docs/guide/migration/upgrading-3-to-4.md
index 14f6276f..868dfde2 100644
--- a/docs/guide/migration/upgrading-3-to-4.md
+++ b/docs/guide/migration/upgrading-3-to-4.md
@@ -1,10 +1,10 @@
---
next:
- text: 'Upgrading from A2 to A4'
- link: '/guide/migration/upgrading.html'
+ text: 'Upgrade apostrophe-astro to v1.13'
+ link: '/guide/migration/upgrading-apostrophe-astro.html'
---
-# Migration from Apostrophe 3 to Apostrophe 4
+# Migration from ApostropheCMS 3 to ApostropheCMS 4
## Introduction
@@ -88,7 +88,7 @@ In Apostrophe, admin UI components are found in `ui/apos/components` subdirector
The names of the props and events automatically used by the `v-model` feature have changed. If you have implemented the `v-model` pattern yourself, you will need to update your code:
-```nunjucks
+```vue
diff --git a/docs/guide/migration/upgrading-apostrophe-astro.md b/docs/guide/migration/upgrading-apostrophe-astro.md
index 8e640fc3..dd12d02b 100644
--- a/docs/guide/migration/upgrading-apostrophe-astro.md
+++ b/docs/guide/migration/upgrading-apostrophe-astro.md
@@ -1,6 +1,6 @@
---
prev:
- text: 'Upgrade From Apostrophe 3'
+ text: 'Upgrade From ApostropheCMS 3'
link: '/guide/migration/upgrading-3-to-4.html'
next: false
---
diff --git a/docs/guide/migration/upgrading.md b/docs/guide/migration/upgrading.md
index 58d32caa..a380d11e 100644
--- a/docs/guide/migration/upgrading.md
+++ b/docs/guide/migration/upgrading.md
@@ -1,7 +1,7 @@
---
next: false
---
-# Migration from Apostrophe 2 to Apostrophe 4 with AI
+# Migration from ApostropheCMS 2 to ApostropheCMS 4 with AI
While many foundational patterns from Apostrophe 2 (A2) were maintained in Apostrophe 3 and now in the latest versions of Apostrophe, there are significant breaking changes to both the database document structure and site-building APIs. This guide will summarize those and cover how to begin upgrading website and standalone module projects from A2 to the newest Apostrophe. Importantly, it will also introduce [tools for developers to automate most of the necessary migration work with AI](#migration-tools-and-process).
diff --git a/docs/guide/nunjucks-templates.md b/docs/guide/nunjucks-templates.md
new file mode 100644
index 00000000..d81a3188
--- /dev/null
+++ b/docs/guide/nunjucks-templates.md
@@ -0,0 +1,269 @@
+# Nunjucks templates
+
+Apostrophe page, widget, and component templates can be written in **Nunjucks** (`.html`) or [JSX](/guide/jsx-templates.md) (`.jsx`). Both are fully supported and coexist in the same project.
+
+The documentation's code examples use JSX, which is the recommended choice for new projects. This page is the reference for Nunjucks: the syntax, the Apostrophe-specific tags, and how templates compose. Nunjucks is a supported feature, not deprecated — existing projects can stay on it indefinitely.
+
+::: tip Migrating an existing project?
+See [JSX templates](/guide/jsx-templates.md) for the equivalents of everything below, and [Migrating templates with an AI assistant](/guide/jsx-migration-assistant.md) for instructions you can hand to a coding assistant.
+:::
+
+## File location and naming
+
+Templates live in `views` directories, either in module subdirectories or at the project root.
+
+The root `views` directory usually holds [the layout template](/guide/layout-template.md) and shared partials. Module `views` directories hold templates used by that module — [widget](/guide/custom-widgets.md#widget-templates), [page](/guide/pages.md#page-template-essentials), and [piece page](/guide/piece-pages.md#the-index-page-template) templates being the main cases.
+
+Apostrophe finds templates by filename, with no registry to update:
+
+| Template | Path |
+|---|---|
+| Widget | `modules/{module-name}/views/widget.html` |
+| Regular page | `modules/{module-name}/views/page.html` |
+| Piece index | `modules/{module-name}/views/index.html` |
+| Piece show | `modules/{module-name}/views/show.html` |
+
+When both `page.html` and `page.jsx` exist in the *same* views folder, the `.jsx` version wins. Across folders it is the override chain that decides — a nearer folder's `.html` beats a parent module's `.jsx`. See [`render()`](/reference/modules/module.md#async-render-req-template-data).
+
+## Template data
+
+Apostrophe populates a `data` object available in every Nunjucks template:
+
+| Variable | Contents |
+|---|---|
+| `data.page` | The current page document |
+| `data.piece` | The current piece on show pages; `null` elsewhere |
+| `data.global` | Site-wide Global Settings — always available |
+| `data.home` | The home page; `_children` holds top-level nav pages |
+| `data.widget` | The current widget document (widget templates only) |
+| `data.user` | The logged-in user, if any |
+
+Output a value with `{{ }}`:
+
+``` nunjucks
+{{ product.title }}
+{% else %}
+ No products yet.
+{% endfor %}
+
+{% set attachment = apos.image.first(data.widget._image) %}
+```
+
+The [official Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html) covers the full language — conditionals, loops, variables, comparison and math operators, and more.
+
+## ApostropheCMS template tags
+
+Beyond the Nunjucks language, Apostrophe adds tags of its own. The most common:
+
+``` nunjucks
+{# Render an editable area #}
+{% area data.page, 'main' %}
+
+{# Render an async component #}
+{% component 'blog:recent' with { max: 5 } %}
+```
+
+`{% area %}` takes the document the field belongs to and the field name. In edit mode Apostrophe wraps it in editing controls; in view mode it renders the widget templates directly.
+
+Context options can be passed to specific widget types with the `with` keyword:
+
+``` nunjucks
+{% area data.page, 'main' with {
+ '@apostrophecms/image': {
+ sizes: '(min-width: 600px) 45vw, (min-width: 1140px) 530px'
+ }
+} %}
+```
+
+See the [template tag reference](/reference/template-tags.md) for the complete list, including `fragment`, `render`, and `rendercall`.
+
+## Filters
+
+Filters transform a value before output, applied with the pipe operator and applied left to right:
+
+``` nunjucks
+
+
+``` nunjucks
+{% extends "layout.html" %}
+
+{% block main %}
+ {% area data.page, 'mainContent' %}
+{% endblock %}
+```
+
+modules/default-page/views/page.html
+
+
+
+`page.html` inherits everything from `layout.html`, and its `main` block replaces only the matching block.
+
+::: info
+`data.outerLayout` is a core, base-level template. See the [layout template](/guide/layout-template.md) guide for more.
+:::
+
+### The `super()` tag
+
+You can *add to* a block's inherited content rather than replacing it, by calling `super()` inside the block. It renders the contents of the block being overridden.
+
+Given this in the layout:
+
+``` nunjucks
+{% block main %}
+
+
+``` nunjucks
+{% block main %}
+ {{ super() }} {# 👈 renders the above #}
+
+
+::: warning
+`super()` has no JSX equivalent, and one is not planned. Blocks are inheritance; JSX props are composition, and a prop cannot carry the parent's version of itself.
+
+The migration is not to find a replacement but to **make the block additive**, so nothing needs to call `super()` in the first place — the parent renders the shared part itself and exposes a finer block, or slot, for what the child adds. See [Coming from blocks and `super()`](/guide/jsx-templates.md#coming-from-blocks-and-super) for both the target shape and the transitional one.
+
+Leaving such a template in Nunjucks remains a valid fallback — JSX templates can extend a Nunjucks layout, so it never blocks migrating the rest of a project.
+:::
+
+### Including templates
+
+`{% include %}` pulls one template into another, which is useful for breaking large files into pieces. A site footer in `views/footer.html` can be included from the layout:
+
+
+
+``` nunjucks
+{% block afterMain %}
+ {# Closing tag for the main block #}
+ {% include "footer.html" %}
+{% endblock %}
+```
+
+views/layout.html
+
+
+
+### Macros
+
+`{% macro %}` defines a reusable markup function, imported where needed. Each template that uses a macro must import it — macros are not inherited through `extends`.
+
+``` nunjucks
+{% import 'link.html' as link %}
+
+{{ link.render({
+ label: item.linkText,
+ path: apos.helper.linkPath(item),
+ class: 'button'
+}) }}
+```
+
+See [fragments](/guide/fragments.md) for Apostrophe's related construct, which can perform async operations that macros cannot.
+
+### Referencing templates across modules
+
+The examples above name templates in the root `views` directory, so a bare filename is enough. The same applies between templates in the same module directory.
+
+To extend or include a template belonging to a *different* module, prefix it with the module name:
+
+``` nunjucks
+{% extends "default-page:page.html" %}
+
+{% block content %}
+
-
- {% area data.page, 'main' %}
-{% endblock %}
+```jsx
+/* modules/default-page/views/page.jsx */
+export default function({ page }, { Area, Extend }) {
+ return (
+
+
+
+
+
+ }
+ />
+ );
+}
```
There are a number of things at work here.
-### The template is extending a `layout.html` template
+### The template is extending a layout template
-``` nunjucks
-{% extends "layout.html" %}
+```jsx
+`) is a base-level template placed in `views/`. It adds markup for things that belong on every page, such as the website navigation and footer. It extends the `outerLayout` template from Apostrophe core, but provides a layer to customize the page wrapper without overwriting `outerLayoutBase.html`.
-The layout template might look something like this:
+Each prop passed to `` fills a slot the layout exposes — `main={…}` above provides the page's content. This is the recommended way to migrate an existing project: convert page templates to JSX one at a time; a JSX page template extends an existing Nunjucks `layout.html` unchanged, no layout changes required first.
+
+A JSX layout renders its own invariant markup and exposes a single slot for the page body, rather than splitting a wrapper across separate regions:
+
+
+
+```jsx
+export default function(data, { Extend }) {
+ return (
+
+ {/* Page header code: logo, navigation, etc. */}
+ {data.main}
+
+
+ }
+ />
+ );
+}
+```
+
+
+views/layout.jsx
+
+
+
+For the full walkthrough — including the transitional shape while a layout is still Nunjucks, and a trap worth knowing about before converting one — see [Writing a layout in JSX](/guide/layout-template.md#writing-a-layout-in-jsx). The Nunjucks equivalent, for reference:
``` nunjucks
{% extends data.outerLayout %}
@@ -136,48 +169,47 @@ The layout template might look something like this:
{% endblock %}
```
-### We are inserting page template markup in a template block
+Note how `beforeMain` opens the `` in one place, as one component.
+
+
+
+```jsx
+function Header({ user }) {
+ return (
+
+ 
+
+ {!user && Login}
+
+ );
+}
+
+function Footer() {
+ return (
+
+ );
+}
+
+export default function(data, { Extend }) {
+ return (
+
+ {data.main}
+
+
+ }
+ />
+ );
+}
+```
+
+
+views/layout.jsx
+
+
+
+A page template then extends it and passes only its own content as `main` — it never needs to know what the header or footer render, which is what the Nunjucks version's `super()` calls would otherwise be for:
+
+```jsx
+
+
+ {!user && Login}
+
- {# Component content will flow in the correct direction #}
-
+ ```jsx
+ {/* In a page template or widget */}
+
+ {/* Component content will flow in the correct direction */}
+
```
- views/widget.html
+ views/widget.jsx
- {# Hero content #}
-
+ ```jsx
+
+ {/* Hero content */}
+
```
- views/layout.html
+ views/layout.jsx
- {# A button to open the list of locales (nothing special here) #}
-
-
+```jsx
+export default function({ localizations }) {
+ return (
+ -
- {# List of locales, looping over data.localizations #}
- {% for localization in data.localizations %}
-
- - {# - Linking the locale name only when it exists in the locale and it's - not the current locale - #} - {% if localization._url and not localization.current %} - - {% endif %} - {# Using both the label and the locale code #} - {{ localization.label }} ({{ localization.locale }}) - {% if localization._url and not localization.current %} - - {% endif %} - - {% endfor %} -
+ {/* A button to open the list of locales (nothing special here) */}
+
+
+ );
+}
```
+Note the structural change from the Nunjucks version. Nunjucks could open an `` tag inside one `{% if %}` and close it inside another; JSX has no equivalent, because every element must be balanced within a single expression. Instead, pull the shared content into a variable and use a ternary that renders the element two complete ways.
+
### RTL support in external frontends
When using external frontends like Astro with the `@apostrophecms/apostrophe-astro` integration, RTL support is automatically handled by the `AposLayout` component.
diff --git a/docs/guide/localization/overview.md b/docs/guide/localization/overview.md
index 405cb98b..c22dbe2d 100644
--- a/docs/guide/localization/overview.md
+++ b/docs/guide/localization/overview.md
@@ -1,4 +1,4 @@
-# Localization in Apostrophe
+# Localization in ApostropheCMS
For Apostrophe, "localization," often abbreviated as **l10n**, is the process of adapting the Apostrophe user interface and Apostrophe website content for different "locales," or groups of people (usually based on language and country). This can include text translation, date formats, content variation, and much more.
diff --git a/docs/guide/localization/static.md b/docs/guide/localization/static.md
index f383ae48..d3b8916c 100644
--- a/docs/guide/localization/static.md
+++ b/docs/guide/localization/static.md
@@ -14,39 +14,47 @@ That section of our show page template might look like this:
-
+ {/* List of locales, looping over localizations */}
+ {localizations.map((localization) => {
+ /* Using both the label and the locale code */
+ const label = `${localization.label} (${localization.locale})`;
+
+ return (
+
- + {/* + Link the locale name only when it exists in that locale and is + not the current locale + */} + {localization._url && !localization.current ? ( + + {label} + + ) : ( + label + )} + + ); + })} +
Related articles
{# 👈 We need to localize this. #} --
- {% for post in data.piece._related %}
-
- {{ post.title }} - {% endfor %} -
Related articles
{/* 👈 We need to localize this. */} +-
+ {piece._related.map((post) => (
+
- {post.title} + ))} +
{{ __t('Related articles') }}
{# 🎉 It's localized! #} --
- {% for post in data.piece._related %}
-
- {{ post.title }} - {% endfor %} -
{__t('Related articles')}
{/* 🎉 It's localized! */} +-
+ {piece._related.map((post) => (
+
- {post.title} + ))} +
{{ __t('relatedArticles') }}
+```jsx +{__t('relatedArticles')}
``` This method is better if your team prefers to maintain all hard-coded strings in the same way across locales (treating the default locale the same as others). Using the original text as the key, as in our previous example, might be better so that translators can see the original text alongside their translations in the JSON files. It mostly depends how you prefer to work. The important thing is to be consistent. @@ -110,13 +118,13 @@ Template example:__t('ourTeam:relatedArticles')
+```jsx +{__t('ourTeam:relatedArticles')}
``` Apostrophe will then treat keys with the namespace differently from the same key without the namespace (`ourTeam:relatedArticles` vs. `relatedArticles`). If someone uses the version *without* the namespace it will not overwrite the version *with* the namespace. @@ -237,7 +245,7 @@ Avoid using namespaces that begin with `apos`. The core team uses namespaces tha As a reminder, namespacing is primarily necessary for *installable modules* and not for project-level localization. ::: -## Localizing the Apostrophe user interface +## Localizing the ApostropheCMS user interface ### Core UI localization diff --git a/docs/guide/logging.md b/docs/guide/logging.md index 7c98b09b..ed87a873 100644 --- a/docs/guide/logging.md +++ b/docs/guide/logging.md @@ -1,4 +1,4 @@ -# Logging in Apostrophe +# Logging in ApostropheCMS Logging is a fundamental aspect of any web application, especially those that require user authentication. It serves as a vital tool for monitoring system behavior, troubleshooting issues, and maintaining security. By recording various events and transactions within the system, logs provide insights into user interactions, system performance, and potential errors. diff --git a/docs/guide/media.md b/docs/guide/media.md index a47d34cd..87152568 100644 --- a/docs/guide/media.md +++ b/docs/guide/media.md @@ -42,15 +42,15 @@ module.exports = { ### Using an image widget in templates -If presenting an image using the image widget and its template, the process is not different from rendering any other area in a template. Use the `area` template tag, including the context reference and the area field name. +If presenting an image using the image widget and its template, the process is not different from rendering any other area in a template. Use the `Area` component, including the context reference and the area field name.
+ return ;
+}
```
- modules/article-page/views/show.html
+ modules/article-page/views/show.jsx
+ );
+}
```
- modules/article-page/views/show.html
+ modules/@apostrophecms/image-widget/views/widget.jsx
{{ data.page.title }}
+``` + +Values are HTML-escaped by default. To render trusted markup unescaped, use the `safe` filter: + +``` nunjucks +{{ data.widget.content | safe }} +``` + +## Core syntax + +Nunjucks statements use `{% %}`, output uses `{{ }}`, and comments use `{# #}`. + +``` nunjucks +{# A comment — not rendered #} + +{% if data.user %} + Log out +{% else %} + Log in +{% endif %} + +{% for product in data.products %} +{{ data.page.headline | replace("foo", "bar") | upper }}
+``` + +Nunjucks supplies a set of [built-in filters](https://mozilla.github.io/nunjucks/templating.html#filters), and Apostrophe adds its own — `build`, `date`, `nlbr`, `striptags`, `json`, and others. You can register project-specific filters with `self.apos.template.addFilter()`. + +See [template filters](/guide/template-filters.md) for the full reference and for how to write your own. + +::: info +Filters are a Nunjucks feature. They are not available in JSX templates, which use ordinary JavaScript function calls instead. If you are planning a migration, note that project-specific filters registered with `addFilter()` are most portable if the underlying function is also exposed as a helper via `addHelpers()`. +::: + +## How templates work together + +No template is an island. Templates compose through the `extends`, `include`, and [`import`](/guide/fragments.md) tags. + +### Extending templates + +`{% extends %}` inherits all the markup and blocks of the template it extends. Blocks defined in the extending template replace matching blocks in the extended one. + +A layout template is typically structured like this: + +``` nunjucks +{# views/layout.html #} +{% extends data.outerLayout %} + +{% block beforeMain %} + {# Page header markup and the main content area opening tag... #} +{% endblock %} + +{% block main %}{% endblock %} + +{% block afterMain %} + {# The main content area closing tag and page footer... #} +{% endblock %} +``` + +Page type templates extend that layout: + +{{ data.piece.title or data.page.title }}
+{% endblock main %} +``` + +a home page template can extend the layout and keep that `h1`: + + above #}
+
+ {# ... additional home page content #}
+
+{% endblock %}
+```
+
+modules/@apostrophecms/home-page/views/page.html
+
+
Contact info
+{% endblock %} +``` + +That tells Apostrophe to use the `page.html` file belonging to the `default-page` module. The same pattern works with `include`. + +## Working alongside JSX + +The two template languages interoperate in **one direction**: + +> A `.jsx` template can extend, include, or import a `.html` template. A `.html` template **cannot** extend, include, or import a `.jsx` template. + +Nunjucks has no way to invoke the JSX renderer. In practice this means a project migrates from the leaves up: individual page and widget templates become JSX while `layout.html` and the core Nunjucks templates stay in place. Apostrophe's core `outerLayoutBase.html` remains Nunjucks for the foreseeable future. + +If you are not migrating, none of this affects you — a wholly Nunjucks project continues to work exactly as before. + +## Further reading + +- [Template tag reference](/reference/template-tags.md) — every Apostrophe tag in detail +- [Template filters](/guide/template-filters.md) — built-in and custom filters +- [Fragments](/guide/fragments.md) — Apostrophe's async-capable alternative to macros +- [Layout template](/guide/layout-template.md) — the root layout and `data.outerLayout` +- [Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html) — the language itself +- [JSX templates](/guide/jsx-templates.md) — the alternative, and what migration involves diff --git a/docs/guide/pages.md b/docs/guide/pages.md index a1a683ab..8478ff27 100644 --- a/docs/guide/pages.md +++ b/docs/guide/pages.md @@ -82,35 +82,68 @@ We can add functionality to the default home page type by adding a configuration Each page type requires a template. The only exception to that rule is if a page type extends another page type that already has a template. -Page templates are added in a `views` directory for the page type as `page.html`. The template for the previous example's default page would be `modules/default-page/views/page.html`. A very simple page template for the Default page might look like this: +Page templates are added in a `views` directory for the page type as `page.jsx`. The template for the previous example's default page would be `modules/default-page/views/page.jsx`. A very simple page template for the Default page might look like this: -``` nunjucks -{# modules/default-page/views/page.html #} -{% extends "layout.html" %} - -{% block main %} -{{ data.page.title }}
- {% if data.page.subtitle %} -{{ data.page.subtitle }}
- {% endif %} -{page.title}
+ {page.subtitle &&{page.subtitle}
} +` and `` tags that `afterMain` closes — Nunjucks blocks are textual, so a tag may be opened in one block and closed in another. JSX has no equivalent to reopen a tag block-by-block, but it doesn't need one: the JSX layout above sidesteps the problem entirely by rendering the whole wrapper in one place and taking the page body as a single `main` slot.
-``` nunjucks
-{% block main %}
-{% endblock %}
+### We are inserting page template markup in a named block
+
+```jsx
+`**, and the prop name is the block name — so `main={…}` overwrites the layout template's `main` block. Because a block's content is a prop rather than a tag pair, it must be a single expression: wrap multiple elements in a fragment (`<>…`), as the example above does.
-### Page data is on `data.page`
+### Page data is the first argument
-``` nunjucks
-{{ data.page.title }}
+```jsx
+{page.title}
```
-Templates have access to a `data` object containing information about the Apostrophe application and current context data. In page templates, `data.page` contains data for the active page. For our Default page, that includes the title, subtitle, "main" area, and lots of other information.
+Templates have access to the same data that Nunjucks templates reach through `data`. It arrives as the **first argument of the exported function**, so destructure the properties you need rather than reaching through a `data` object. In page templates, `page` contains data for the active page — for our Default page, that includes the title, subtitle, "main" area, and lots of other information.
-Naming specific properties in the double brackets syntax, `{{}}`, prints them in the template.
+Naming specific properties inside curly braces, `{}`, prints them in the template.
-``` nunjucks
-{% if data.page.subtitle %}
-
+
+
+
+ {main}
+
+ }
+ />
+ );
+}
+```
-With that available data, we could construct navigation for the website header using the Nunjucks `{% for %}` loop tag. The `layout.html` `beforeMain` block could look like:
+In a Nunjucks layout, the same navigation uses a `{% for %}` loop inside the `beforeMain` block:
``` nunjucks
{# views/layout.html #}
diff --git a/docs/guide/piece-pages.md b/docs/guide/piece-pages.md
index 80759bed..72aeb802 100644
--- a/docs/guide/piece-pages.md
+++ b/docs/guide/piece-pages.md
@@ -83,12 +83,14 @@ When using the [official CLI](/guide/development-setup.md#installing-the-apostro
```bash
apos add piece article --page
```
+
+It scaffolds the templates as Nunjucks, so rename the generated `index.html` and `show.html` to `.jsx` and write them as function components — see the [CLI note](/guide/development-setup.md#installing-the-apostrophe-cli).
:::
| Template file name | What is it? |
| ------------------ | ----------- |
-| `index.html` | Template for listing pieces (the **"index page**) |
-| `show.html` | Template to display an individual piece (a **"show page"**) |
+| `index.jsx` | Template for listing pieces (the **"index page**) |
+| `show.jsx` | Template to display an individual piece (a **"show page"**) |
We'll review each template's features next.
@@ -129,46 +131,57 @@ You've reviewed the [page type guide](/guide/pages.md), right? The sections belo
Index page templates look very similar to other page templates.
-``` nunjucks
-{# modules/article-page/views/index.html #}
-
-{% extends "layout.html" %}
-{% import '@apostrophecms/pager:macros.html' as pager with context %}
-
-{% block main %}
- {{ data.page.subtitle }}
-{% endif %} +```jsx +{page.subtitle &&{page.subtitle}
} ``` -Nunjucks offers additional tags, including the [`{% if %}` conditional tag](https://mozilla.github.io/nunjucks/templating.html#if), to help work with data in templates. +Conditionals are ordinary JavaScript. `&&` renders the right-hand side only when the left is truthy, and a ternary covers if/else. See [Conditionals](/guide/jsx-templates.md#conditionals) for the full set of idioms. ::: tip If you want to know what is available in a template object, you can log it in your terminal using the template method `apos.log()`. This looks like: -``` nunjucks -{{ apos.log(data.page) }} +```jsx +{apos.log(page)} ``` ::: -### The widget area is added using the `area` tag +### The widget area is added using the `Area` component -``` nunjucks -{% area data.page, 'main' %} +```jsx + ``` -This is a special tag in Apostrophe used to let editors add and manage content widgets to the page. After the `area` tag name, we pass the tag the field's context, which is our page, followed by the field name. We [configured it in the `index.js` file](#creating-a-page-type) to use two widget types. While editing the page, the user will have access to a menu to add widgets of those types. +`Area` is one of the helpers on the second argument of the template function. It lets editors add and manage content widgets on the page. Pass the field's context as `doc`, which is our page, and the field name as `name`. We [configured it in the `index.js` file](#creating-a-page-type) to use two widget types. While editing the page, the user will have access to a menu to add widgets of those types.  @@ -235,16 +267,44 @@ Pages can be organized into a page tree hierarchy while adding them or through t Apostrophe templates have data available to add navigation based on the page tree. This includes: -| Data object | What is it? | -| ------ | ------ | -| `data.home` | Home page data. It is similar to the data on `data.page`, but always references the home page. | -| `data.home._children` | Page data for pages one level below the home page in the page tree. | -| `data.page._ancestors` | Page data for the ancestors of the active page, starting with the home page. | -| `data.page._children` | Page data for pages one level *below* the active page. | - -By default, one level of children are available on each ancestor, as well as on the home page and `data.page`. +| Data property | Nunjucks | What is it? | +| ------ | ------ | ------ | +| `home` | `data.home` | Home page data. It is similar to the data on `page`, but always references the home page. | +| `home._children` | `data.home._children` | Page data for pages one level below the home page in the page tree. | +| `page._ancestors` | `data.page._ancestors` | Page data for the ancestors of the active page, starting with the home page. | +| `page._children` | `data.page._children` | Page data for pages one level *below* the active page. | + +By default, one level of children are available on each ancestor, as well as on the home page and `page`. + +With that available data, we could construct navigation for the website header. In JSX this is a `.map()` over the children — and `home` arrives the same way `page` does, as a property of the data object passed to every template, layout included: + +```jsx +export default function({ home, main }, { Extend }) { + return ( +{{ data.page.title }}
- - {% for article in data.pieces %} -{page.title}
+ + {pieces.map((article) => ( ++ {article.title} +
+- {{ article.title }} + {article.title}
{{ data.piece.title or data.page.title }}
-{% endblock main %} -``` - -modules/default-page/views/page.html - - tag above #}
-
- {# ... additional home page content #}
-
-{% endblock %}
-```
-
-modules/@apostrophecms/home-page/views/page.html
-
-
Contact info
- {# Contact information... #} -{% endblock %} -``` +| | What it does | JSX | Nunjucks | +| --- | --- | --- | --- | +| **Extending** | A template inherits another and replaces named blocks of it | [`
-
-
+
+```jsx
+export default function({ widget }, { apos }) {
+ const styles = apos.styles.prepareWidgetStyles(widget);
+
+ return (
+ <>
+
+
+
+
+ );
+}
+```
+
+
+ modules/custom-widget/views/widget.jsx
+
+
+
+
+::: warning
+`getWidgetAttributes()`'s return object uses literal HTML attribute names (`class`, `style`), not JSX names (`className`). Spread it as-is — don't also pass `className` on the same element, or you'll emit two `class` attributes. The same applies to `additionalAttributes`: pass `{ class: '...' }`, not `{ className: '...' }`, or the merge silently misses it.
+:::
+
+### Template helpers (Nunjucks) / module methods (JSX)
+
+**`apos.styles.render(widget)`** (Nunjucks) / **`apos.styles.prepareWidgetStyles(widget)`** (JSX)
- Prepares styles for the widget
- Returns a styles object for use with other helpers
-**`apos.styles.elements(styles)`**
+**`apos.styles.elements(styles)`** (Nunjucks) / **`apos.styles.getWidgetElements(styles)`** (JSX)
- Generates the `
HMR Active
- Force Refresh
+```jsx
+
+ {/* Your development-only UI here */}
+
```
- modules/devTools/views/devTools.html
+ modules/devTools/views/devTools.jsx
diff --git a/docs/guide/why-apostrophe.md b/docs/guide/why-apostrophe.md
index 464f2d38..739005d2 100644
--- a/docs/guide/why-apostrophe.md
+++ b/docs/guide/why-apostrophe.md
@@ -1,4 +1,4 @@
-# Why Apostrophe?
+# Why ApostropheCMS?
diff --git a/docs/guide/widget-styles.md b/docs/guide/widget-styles.md
index 365cbee5..1d19c3e8 100644
--- a/docs/guide/widget-styles.md
+++ b/docs/guide/widget-styles.md
@@ -343,22 +343,59 @@ Then use the template helpers in your widget template:
-### Template helpers
+In a JSX widget template, reach for the same logic as plain `apos.styles` module methods rather than the `apos.styles.render/elements/attributes` Nunjucks helpers — the helpers are thin wrappers over these for use inside Nunjucks specifically:
-**`apos.styles.render(widget)`**
+HMR Active
+ Force Refresh