Javlo2 Remote API

Developer reference for the ContentAction, NavAction and TemplateAction remote APIs, with full component data-structure documentation. All actions are invoked via /ajax/{lang}/ using POST with a webaction parameter.

ContentAction API #

Source: org.javlo.remote.ContentAction

POST /ajax/{lang}/?webaction=content.add

Create a new component on a page.

Parameter	Type	Req	Description
page	String	✓	Target page — ID, name, or path.
type	String	✓	Component type string (e.g. `wysiwyg-paragraph`).
area	String	✓	Template area key (e.g. `content`, `hero`, `footer`).
previous	String	–	Component ID after which to insert. `0` = prepend. Default: `0`.
value	String	–	Initial value (see component data-structure above).
style	String	–	CSS style class for the component.
layout	String	–	Layout flags — combination of: `l`=left `r`=right `c`=center `j`=justify `b`=bold `i`=italic `u`=underline `t`=line-through; append `#font-family` for custom font (e.g. `lcb#Arial`).
renderer	String	–	Renderer key as defined in the component's config file.
columnSize	Integer	–	Grid column width (e.g. `6` for half-width in a 12-column grid).
columnStyle	String	–	CSS class applied to the column wrapper element.

POST /ajax/{lang}/?webaction=content.edit

Update value, style, layout, renderer, or column settings of an existing component.

Parameter	Type	Req	Description
id	String	✓	Component ID (returned by content.add).
value	String	–	New value (replaces existing).
style	String	–	New style class.
layout	String	–	New layout flags (same format as content.add). Empty string clears the layout.
renderer	String	–	New renderer key. Empty string resets to default.
columnSize	Integer	–	New grid column width.
columnStyle	String	–	New CSS class for the column wrapper. Empty string clears it.

POST /ajax/{lang}/?webaction=content.remove

Delete a component from its page.

Parameter	Type	Req	Description
id	String	✓	Component ID to delete.

POST /ajax/{lang}/?webaction=content.move

Move a component to a different position, area, or page.

Parameter	Type	Req	Description
id	String	✓	Component ID to move.
previous	String	✓	Component ID after which to insert. `0` = move to first position.
area	String	–	Target area key. Defaults to current area.
page	String	–	Target page. Defaults to current page.

POST /ajax/{lang}/?webaction=content.publish

Publish the site: synchronises the preview navigation tree to the view tree and copies content files. Must be called after any content or navigation change to make it visible to visitors.

No parameters required.

POST /ajax/{lang}/?webaction=content.clearPage

Remove all components from a page. Returns the page ID and the list of deleted component IDs.

Parameter	Type	Req	Description
page	String	✓	Page to clear — ID, name, or path.

NavAction API #

Source: org.javlo.remote.NavAction

POST /ajax/{lang}/?webaction=nav.add

Add a new page to the navigation tree.

Parameter	Type	Req	Description
name	String	✓	Slug of the new page (URL-safe, e.g. `my-page`).
parent	String	–	Parent page — ID, name, or path. Default: root.
top	boolean	–	Insert at the top of sibling list. Default: `false`.

POST /ajax/{lang}/?webaction=nav.remove

Remove a page and all its sub-pages from the navigation tree.

Parameter	Type	Req	Description
page	String	✓	Page to remove — ID, name, or path.

POST /ajax/{lang}/?webaction=nav.move

Move a page to a different parent in the navigation tree.

Parameter	Type	Req	Description
page	String	✓	Page to move — ID, name, or path.
parent	String	✓	New parent page — ID, name, or path.

TemplateAction API #

Source: org.javlo.remote.TemplateAction

Requires global admin role. All actions use webaction=template.{action}.

POST /ajax/{lang}/?webaction=template.upload

Upload a template from a zip file (URL or multipart). Creates the template folder if absent, overwrites files if it already exists. Call template.commit afterwards to deploy the new files into the webapp.

Parameter	Type	Req	Description
name	String	✓	Target template ID / folder name.
url	String	–	URL of a `.zip` file to download. Ignored when a multipart `file` field is present.
file	File (multipart)	–	Zip file uploaded as `multipart/form-data` field named `file`. Takes priority over `url`.

# URL-based upload
curl -X POST http://localhost/javlo2/claude/ajax/fr/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "webaction=template.upload&name=my-theme&url=https://example.com/my-theme.zip"

# Multipart file upload
curl -X POST http://localhost/javlo2/claude/ajax/fr/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "webaction=template.upload" \
  -F "name=my-theme" \
  -F "file=@/path/to/my-theme.zip"

POST /ajax/{lang}/?webaction=template.commit

Clears the renderer cache and re-imports the template from its source folder into the webapp. Equivalent to the commit-template macro. Use after editing template files on disk.

Parameter	Type	Req	Description
name	String	✓	Template name or ID.

POST /ajax/{lang}/?webaction=template.commitAll

Commits a template and all its child templates (full descendant tree). Useful when a parent template change must propagate to all derived themes.

Parameter	Type	Req	Description
name	String	✓	Parent template name or ID.

GET /ajax/{lang}/?webaction=template.download

Download the entire source folder of a template as a zip file. Unlike the other actions this endpoint returns a binary application/zip response, not a JSON envelope.

Parameter	Type	Req	Description
name	String	✓	Template name or ID to download.

The response Content-Disposition header is set to attachment; filename="{name}.zip". On error Javlo falls back to the standard JSON error envelope.

curl -OJ "http://localhost/javlo2/claude/ajax/fr/?webaction=template.download&name=my-theme" \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication #

All Remote API actions require an authenticated session. Three authentication modes are supported (evaluated in priority order):

1. Authorization: Bearer header recommended

Send the token in the standard Authorization HTTP header. This is the preferred approach for API clients and the MCP server.

POST /ajax/fr/
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

webaction=content.add&page=presentation&type=wysiwyg-paragraph&area=content&value=<p>Hello</p>

2. X-Javlo-Token header

Alternative header for environments where Authorization is reserved.

POST /ajax/fr/
X-Javlo-Token: YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

webaction=content.add&page=presentation&type=wysiwyg-paragraph&area=content

3. Token parameter (`j_token`) — legacy

Pass the token as a POST body parameter. Supported for backwards compatibility but the header approach is preferred.

POST /ajax/fr/
Content-Type: application/x-www-form-urlencoded

webaction=content.add&j_token=YOUR_TOKEN&page=presentation&type=wysiwyg-paragraph&area=content&value=<p>Hello</p>

4. Session cookie

Perform a standard form-login first, then reuse the JSESSIONID cookie in subsequent API calls.

The token is generated in the Javlo admin under Users → API token. The loginWithToken option must be enabled in the global static config.

Required permissions

Action group	Required role
content.*	Global admin or `content` role
nav.*	Global admin or `content` role

Response Format #

All actions return a JSON envelope from the AjaxServlet:

{
  "messageType": "info" | "error" | "warning",
  "messageText": "human-readable message or null",
  "data": {
    // action-specific result object
  },
  "insideZone": "...",
  "zone": "..."
}

content.add / content.edit / content.move → `data.component`

{
  "id":          "177435215683329856118",
  "type":        "wysiwyg-paragraph",
  "area":        "content",
  "style":       null,
  "layout":      "lcb#Arial",
  "renderer":    "default",
  "columnSize":  "6",
  "columnStyle": "col-highlight",
  "pageId":      "177434753288331935111",
  "pagePath":    "/presentation",
  "value":       "<p>Hello</p>"
}

content.remove → `data`

{
  "removed": "177435215683329856118",
  "type":    "wysiwyg-paragraph"
}

content.publish → `data`

{
  "published":  true,
  "publisher":  "admin",
  "date":       "Tue Mar 24 17:00:00 CET 2026"
}

content.clearPage → `data`

{
  "pageId":  "177434753288331935111",
  "removed": ["177435215683329856118", "177435587252612684640", "177436146640444725247"],
  "count":   3
}

nav.add → `data`

{
  "pageId":   "177434753288331935111",
  "pagePath": "/my-new-page",
  "pageName": "my-new-page"
}

template.upload / template.commit → `data`

{
  "template": {
    "id":     "my-theme",
    "name":   "my-theme",
    "parent": "base-bootstrap"
  }
}

template.commitAll → `data`

{
  "committed": ["base-bootstrap", "my-theme", "my-theme-dark"],
  "count": 3
}

template.download → binary

This action returns a raw application/zip binary stream, not a JSON envelope. On error it falls back to the standard JSON error response.

Content-Type: application/zip
Content-Disposition: attachment; filename="my-theme.zip"

<binary zip data>

When messageType is "error" the data key is absent. Always check messageType before reading data.

Component Reference #

The table below describes every component type recommended for use with the Remote API. For each component the type string matches the type parameter sent to content.add. The value column describes what must be passed to content.add (value param) and what is stored by content.edit.

Heading #

Heading heading

org.javlo.component.title.Heading

Renders a semantic heading tag (<h1>–<h6>). Supports an optional sub-text and an optional hyperlink on the heading text.

Java Properties format (key=value pairs)

Fields (passed as Java `Properties` in value)

Key	Type	Req	Description
depth	int (1–6)	✓	Heading level: 1 = <h1>, 6 = <h6>. Defaults to 1.
text	String	✓	Main heading text. Auto-links are applied.
smtext	String	–	Small secondary text rendered below or beside the heading.
link	URL / path	–	Makes the heading a hyperlink pointing to this URL.

Example value

#Javlo heading
depth=2
text=Our Mission
smtext=since 2010
link=/about

When creating via content.add you may pass the heading text directly as value — Javlo stores it in the text property automatically.

Wysiwyg Paragraph #

WysiwygParagraph wysiwyg-paragraph

org.javlo.component.text.WysiwygParagraph

Rich-text HTML block edited with TinyMCE (light mode). The raw value is HTML/XHTML. Javlo parses the HTML to extract a title (first <h1>) and a description (first <img> alt) for SEO metadata.

Raw HTML string in getValue()

Value format

Field	Type	Req	Description
value	HTML	✓	Full HTML fragment. May include any block/inline elements. Javlo post-processes auto-links.

Example value

<h1>Welcome</h1>
<p>A paragraph with <strong>bold</strong> and a
<a href="/about">link</a>.</p>
<img src="/files/hero.jpg" alt="Hero image">

FullWysiwygParagraph (type full-wysiwyg-paragraph) uses the same format but opens the full TinyMCE toolbar in the editor.

Paragraph #

Paragraph paragraph

org.javlo.component.text.Paragraph

Plain-text paragraph. The text is wrapped in a <p> tag on render. Basic markers (*bold*, _italic_) and auto-links are applied.

Plain text string in getValue()

Value format

Field	Type	Req	Description
value	String	✓	Plain text. Newlines become <br>. Supports bold and _italic_ markers.

Example value

This is a *simple* paragraph with an auto-linked URL: https://example.com

Internal Link #

InternalLink internal-link

org.javlo.component.links.InternalLink

A link pointing to another page in the same Javlo site. The target is identified by its page ID (not path, which may change). Supports various display styles and an optional image/description block.

Java Properties format — header: link storage V.1.0

Properties

Key	Type	Req	Description
link	page ID	✓	Target page ID (numeric string, e.g. `177434753288331935111`).
label	String	–	Display text. Falls back to the target page's title.
title	String	–	HTML title attribute of the <a> tag.
image	path	–	Path to an image file for the title+image display styles.
description	String	–	Short description shown below the label in rich styles.
reverse-link	enum	–	Reverse-link mode: `none` \| `first` \| `this-page` \| `previous-component`.

Style values

Pass one of these strings as the style parameter to content.add / content.edit:

title | title+image | title+description | title+image+description | image | hidden

Example value

#link storage V.1.0
link=177434753288331935111
label=Read our presentation
reverse-link=none

External Link #

ExternalLink external-link

org.javlo.component.links.ExternalLink

A hyperlink pointing to an external URL or an email address. Email addresses are automatically prefixed with mailto:. Javlo can optionally validate that the URL is reachable.

Java Properties format — header: link storage V.1.0

Properties

Key	Type	Req	Description
link	URL / email	✓	External URL (https://…) or email address. Emails auto-get `mailto:`.
label	String	–	Anchor text. Falls back to the URL if omitted.
reverse-link	enum	–	Same reverse-link options as internal-link.

Example value

#link storage V.1.0
link=https://www.example.org/resources
label=External resources

Global Image #

GlobalImage global-image

org.javlo.component.image.GlobalImage

Displays an image from the Javlo media library. The image path is stored as a relative reference within the site's data folder. Supports filters (crop, resize), an optional link, and EXIF-style metadata.

Java Properties format

Properties

Key	Type	Req	Description
file-name	path	✓	Relative path to the image in the Javlo media library, e.g. `/files/hero.jpg`.
file-name-over	path	–	Override image path. When set, replaces file-name during rendering.
title	String	–	Caption / alt text for the image.
link	URL	–	Wraps the image in a hyperlink pointing to this URL.
image-filter	enum	–	Filter type: `raw` (no processing) or a custom filter class name.
location	String	–	Textual location metadata (e.g. "Paris, France").
date	date string	–	Date the photo was taken (displayed as metadata).

The image file must already be uploaded to the Javlo media library before referencing it here. Use the file manager module or the media upload endpoint.

Page Reference #

PageReferenceComponent page-reference

org.javlo.component.links.PageReferenceComponent

Renders a list of references to other pages in the site. The list can be statically defined (explicit page IDs) or dynamically filtered and sorted. Supports date ranges, taxonomy filters, and multiple display templates.

Java Properties format

Key Properties

Key	Type	Req	Description
page-ref	String	✓	Semicolon-separated list of target page IDs, e.g. `111;222;333`. Leave empty for dynamic mode.
order	enum	–	Static sort order: `priority` \| `creation-date` \| `modification-date` \| `name`.
dynamic-order	boolean	–	When `true`, applies dynamic order based on page date components.
page-start	date	–	Include only pages with a date component >= this value (ISO-like).
page-end	date	–	Include only pages with a date component <= this value.
display-first-page	boolean	–	When `true`, shows the first (current) page in the list.

Date #

DateComponent date

org.javlo.component.meta.DateComponent

Stores a date value associated with a page. The display format is controlled by the component's style. Also used by page-reference for chronological filtering.

Date string in getValue()

Value format

Field	Type	Req	Description
value	date string	✓	Date in the format stored by Javlo, typically `dd/MM/yyyy HH:mm` or `dd/MM/yyyy`.

Style values (display format)

date                  → context default format
userfriendly-date     → "yesterday", "3 days ago" …
medium-date           → 24 Mar 2026
short-date            → 24/03/2026
short-date-width-day  → Mon 24/03/2026
visible-date          → visible in reader mode
visible-month         → month + year only
visible-time          → time only (HH:mm)
date-taxonomy         → used as taxonomy axis
not-visible           → hidden (metadata only)

Example value

24/03/2026

Debug Note #

DebugNote debug-note

org.javlo.component.core.DebugNote

An internal annotation visible only in preview mode (never rendered to end users). Useful for editorial notes, TODO items, or ticket references attached to a specific page location.

Java Properties format

Properties

Key	Type	Req	Description
text	String	✓	Note content (plain text or simple HTML).
status	enum	–	Ticket-style status: `open` \| `in-progress` \| `done` \| `rejected`.
user	CSV string	–	Comma-separated list of assigned Javlo usernames.
priority	int (0–3)	–	0 = none, 1 = low, 2 = medium, 3 = high.
modif_date	timestamp	–	Last modification timestamp (set automatically on save).

This component is never rendered in view mode. It is only visible to logged-in editors in preview mode.

Extended Widget (JSP) #

ExtendedWidget extendedWidget

org.javlo.component.text.ExtendedWidget

A custom HTML + CSS widget whose XHTML and stylesheet are stored in the component value. At render time Javlo generates a JSP file from the content and executes it server-side. JSP scriptlets (<% %>) are blocked for security.

Java Properties format (multi-line values)

Properties

Key	Type	Req	Description
xhtml	HTML	✓	HTML fragment rendered by the generated JSP. May use Javlo EL expressions.
css	CSS	–	Scoped CSS injected into a <style> block above the xhtml.
file	path	–	Path to an external XHTML resource file (overrides inline xhtml).

Render pipeline

On first render Javlo calls createRenderer(ctx) which writes the JSP to:
/jsp/view/component/extendedWidget/view_[componentId].jsp

Scriptlets are stripped. Use JSTL / EL only. The generated JSP is cached and regenerated when the value changes.

Smart Generic Form #

SmartGenericForm smart-generic-form

org.javlo.component.form.SmartGenericForm

A configurable web form that stores submissions as CSV data files in the Javlo data folder. Supports file uploads, event registrations, reCAPTCHA, email notifications, and database storage. Fields are defined in a Java Properties value; the rendering JSP is smart-generic-form.properties. The Field helper class that serialises each field is org.javlo.component.form.Field.

Java Properties in getValue() · field rows keyed field.{name} · submissions in CSV files

Global configuration keys

Key	Type	Description
title	String	Form heading displayed above the fields.
filename	String	Base name of the CSV data file (without extension). Defaults to the component ID.
captcha	boolean	Enable simple captcha (`true` / `false`).
recaptchakey	String	Google reCAPTCHA v2 site key.
recaptchasecretkey	String	Google reCAPTCHA v2 secret key.
mail.to	email	Recipient address for the submission notification email.
mail.cc / mail.bcc	email	CC / BCC recipients.
mail.subject	String	Fixed email subject line.
mail.subject.field	field name	Use the value of this field as the email subject.
mail.from	email	Fixed sender address.
mail.from.field	field name	Use the value of this field as the sender address.
message.thanks	String	Confirmation message shown after submission.
message.required	String	Label shown next to required field indicator (*).
error.generic / error.required	String	Generic / required-field validation error messages.
file.max-size	int (bytes)	Maximum allowed upload size for `file` fields.
event.limit	int	Maximum number of event registrations (0 = unlimited).

Field definition format — `field.{name}`

Each field is a Properties entry whose key is field.{fieldName} and whose value is a pipe-separated (|) string with 11 columns, matching Field.toString():

field.{name} = label|type|defaultValue|rawList|order|registeredList|order|width|condition|role|autocomplete

Required flag: a field is marked required when its name starts with an uppercase letter — e.g. Email is required, phone is optional.

Column index	Attribute	Type	Description
0	label	String	Human-readable label shown in the form.
1	type	enum	Field type (see table below).
2	defaultValue	String	Pre-filled value. Usually empty.
3	rawList	String	Newline-separated options for `list`, `list-multi`, `radio`. Prefix item with `.` to make it a non-selectable title. Use `>listName` to pull from a registered ListService list.
4	order (unused)	int	Legacy slot — set to `0`.
5	registeredList	String	Name of a ListService list (for `registered-list` type).
6	order	int	Display order (ascending). Fields with order 0 fall back to alphabetical sorting.
7	width	int (1–12)	Bootstrap grid column width. Fields accumulate left-to-right; a new row starts when the total exceeds 12. Default: `12`.
8	condition	String	Conditional display rule: `otherField==value`. Operators: `===`, `==`, `=`, `>`, `<`, `in` .
9	role	enum	Auto-fill role: `user_firstName`, `user_lastName`, `user_email`, `user_phone`, `user_organization`, `count-participants`, etc.
10	autocomplete	String	HTML `autocomplete` attribute value (e.g. `email`, `name`).

Field types

type value	Rendered as	Needs rawList?
text	`<input type="text">`	–
email	`<input type="text">` + email validation	–
vat	`<input type="text">` + VAT validation	–
read-only	`<input type="text" readonly>`	–
number	`<input type="number">`	–
date	`<input type="date">`	–
large-text	`<textarea>`	–
yes-no	Radio pair: Yes / No	–
true-false	Radio pair: True / False	–
radio	Inline radio buttons from list	✓
list	`<select>` dropdown from list	✓
list-multi	`<select multiple>` with SlimSelect. `condition` column sets the selection limit.	✓
registered-list	`<select>` populated from a ListService list; set `registeredList` column.	–
file	`<input type="file">` with existing-file display	–
validation	`<input type="checkbox">` (e.g. GDPR consent)	–
static-title	`<h3>` section divider — label is the heading text	–
static-text	`<p>` informational paragraph — label is the text	–
bloc	Bootstrap collapse toggle — label is the toggle text	–
hidden	`<input type="hidden">` — excluded from grid width calculation	–

Complete example

#comp:<componentId>
title=Contact us
filename=contact-form
mail.to=info@example.org
mail.subject=New contact message
message.thanks=Thank you\! We will get back to you soon.
captcha=false

# field.{name} = label|type|defaultValue|rawList|order|registeredList|order|width|condition|role|autocomplete
field.Name=Your name|text|||0||1|6|||name
field.Email=Your email|email|||0||2|6|||email
field.Subject=Subject|list|||0||3|12|Option A\nOption B\nOption C||
field.Message=Message|large-text|||0||4|12|||
field.privacy=I accept the privacy policy|validation|||0||5|12|||

In a Java Properties file, literal newlines inside a value must be escaped as \n. The rawList column uses \n as the item separator when stored.

Submission storage

Form submissions are stored in:
{data-folder}/dynamic-form-result/{componentId}/data.csv

Accessible programmatically via getData(ctx) → List<Map<String,String>>.

Javlo2 Remote API

ContentAction API #

NavAction API #

TemplateAction API #

Authentication #

1. Authorization: Bearer header recommended

2. X-Javlo-Token header

3. Token parameter (j_token) — legacy

4. Session cookie

Required permissions

Response Format #

content.add / content.edit / content.move → data.component

content.remove → data

content.publish → data

content.clearPage → data

nav.add → data

template.upload / template.commit → data

template.commitAll → data

template.download → binary

Component Reference #

Heading #

Fields (passed as Java Properties in value)

Example value

Wysiwyg Paragraph #

Value format

Example value

Paragraph #

Value format

Example value

Internal Link #

Properties

Style values

Example value

External Link #

Properties

Example value

Global Image #

Properties

Page Reference #

Key Properties

Date #

Value format

Style values (display format)

Example value

Debug Note #

Properties

Extended Widget (JSP) #

Properties

Render pipeline

Smart Generic Form #

Global configuration keys

Field definition format — field.{name}

Field types

Complete example

Submission storage

3. Token parameter (`j_token`) — legacy

content.add / content.edit / content.move → `data.component`

content.remove → `data`

content.publish → `data`

content.clearPage → `data`

nav.add → `data`

template.upload / template.commit → `data`

template.commitAll → `data`

Fields (passed as Java `Properties` in value)

Field definition format — `field.{name}`