Implement a macro to create a page from a template

Hi everyone,

Today, a user has two ways to create a page from a template:

  • by picking the template in the page creation UI (when it’s shown, which depends on the template provider’s configuration),
  • by following a hand-crafted URL with a template parameter (this is what the AppWithinMinutes “Add new entry” button does).
    Neither allows an advanced user to easily add a simple “create a new X here” button on a page for less experienced users.

As a result, some applications build such a form themselves, each with its own CSRF handling, page naming and redirect: for example, the Blog (blogpostcreate macro) and Security Advisory applications.

Loading... proposes to add a new wiki macro that renders a small form: a title field, an optional space field, and a Create button. Clicking the button creates a page from the given template provider.

Parameters

  • templateProvider (mandatory): reference of a template provider (XWiki.TemplateProviderClass). We reuse what it already defines: terminal or not, action on create, creation restrictions and the required rights check.
  • space (optional): the space where the page is created. See Location below for the default.
  • allowLocationChange (optional, default false): when true, the form also shows a space picker, so the user can choose where to create the page.
  • buttonLabel (optional): the label of the button, e.g., “Create a new meeting note”. Would default to a localized string: “Create new ”.

Location

  • The page is created in the space parameter if set. Otherwise, it goes in the first space listed in the template provider’s creation restrictions, or in the current space if the provider has none. This is the same behavior as AWM.
  • When allowLocationChange is true, a space picker appears in the form and is prefilled with that space.

Title

  • The title field could either be mandatory or optional.
  • If a page with that name already exists, we could either add a number to the name (same as Blog) or show an error message (same as AWM).
  • If we want to keep it optional, we need to decide if we want to use a unique name (UUID, $xwiki.getUniquePageName with the template’s title or a defaultTitle parameter for the macro).

How it works

  • The form posts to the existing create action with title, spaceReference, name, templateprovider, tocreate and the CSRF token, so we reuse all existing checks.
  • If anything goes wrong (the name is invalid, the template isn’t allowed in the chosen space), the create action already falls back to the standard create UI, prefilled and showing the error. So the macro doesn’t need its own error handling.
  • If the current user can’t create pages in the target space, the macro renders nothing, or disables the button if the user is allowed to change the location.
  • It would be a wiki macro in the new xwiki-platform-pagetemplate module (see XWIKI-12386: Introduce a new module for Page Templates by pjeanjean · Pull Request #6930 · xwiki/xwiki-platform · GitHub).

Open questions

  1. Name of the macro: createPage, createFromTemplate, createPageForm? Note that if it ends up generic enough, the templateProvider could be optional to support regular page creation in a given space.
  2. Should the title be mandatory or optional? If optional, how do we name the page when it’s empty?
  3. If a page with that name already exists, should we add a number to the name or show an error?

My preferences:

  1. createPage with optional template provider
  2. optional, relying on $xwiki.getUniquePageName if a default title is present, UUID otherwise
  3. add a number like the Blog application does

WDYT?

Thanks,
Pierre

Hi Pierre,

Thanks for the proposal, +1 for the general idea. A few points below.

Could you add some mockups of what the macro renders? I know the topic, but I think it would make the proposal easier to understand.
Also, I think this deserves a design page.

A few questions/remarks

  1. createPage sounds ok, I could also go for createPageForm to convey what he macro output is.
  2. I would start with a mandatory title, and to move to an optional title later as it adds complexity, unless you identify a strong need for it
  3. The create action does not derive the page name from the title: it needs a name (see CreateActionRequestHandler). The create UI computes it client-side. So the macro has to compute the name itself. Live Data already solves this with the newRowNamingStrategy source parameter. The title strategy applies the wiki name strategy and adds a -1, -2 suffix when the page exists. The uuid strategy is also available. What about a namingStrategy parameter reusing these components, with title as the default? The LiveTableNewRowNamingStrategy role is unstable and lives in xwiki-platform-livedata-livetable, so we would move it to a more generic module. This would also help make the title optional later.

Also, you mention that AWM shows an error when the page exists. From what I see in LiveTableViewSheet, the “Add new entry” button builds a direct edit or save URL from the raw title. It does not go through the create action, does not apply the naming strategy (Loading...) and has no collision handling. Which error did you have in mind?

Rights and feedback

  • For the right check, I assume EDIT on the target space, as AWM and CreateAction do?
  • In terms of usability, I would suggest giving feedback as soon as possible, before clicking on submit (e.g., directly in the form, or after the location is changed for instance). Possibly, render nothing when the user cannot create in the target space and cannot change it,
  • Also for accessibility, it would be best if we can flag/fix invalid titles inline

A few links identified

I guess you have in mind that once the macro exists, it could replace the AWM “Add new entry” popup, the NewPage panel form and blogpostcreate (non exhaustive list).

Thanks

While I was testing, I ended up with this “page already exists” error:

But after rechecking, this actually only happens if the existing page has content, the “normal” behavior is to simply open the existing page with the new object otherwise (it its content is empty), or the existing one if it already has one. So, indeed, no check in AWM directly.

This topic seems to be brought up by many users who are migrating from Confluence which has such a macro while in XWiki this is covered by the native create button. I don’t think such a macro belongs in XWiki as in XWiki the native “Create” button should be used, and we shouldn’t confuse users by offering a separate way for creating a page from a template. So to me, this belongs in a contrib extension, not in XWiki itself.

So before we discuss the technical details, I think this needs a proper proposal that explains why we need such a macro and why it belongs in XS.

To go in @MichaelHamann’s direction: we already decided in the past to remove the custom Create buttons/forms from apps and to keep only the main “Create” button for everything, with the app providing a template that the Create UI recommends.

The history:

  • 2017 – devs list, Templates exposure: after Loading... (the Create UI pre-selects the template recommended for the current location), the goal was to remove the AWM “Add new entry” action and rely on the Create button. Caty, answering the idea of letting apps hide the main Create button in favor of their own: “I want to remove the custom buttons and rely on a single button that recommends a template.”
  • 2020 – vote, No custom create UI in data apps when users create entries: passed. Recommended apps that create entries named by the user must not provide a custom create UI but rely on the standard page creation UI by offering a template. In that thread I also proposed to go further and have a single, more generic Create button for everything (“whenever you wish to create something you click on the Create button”, e.g. Create > Application), see post 3, which I restated in Restyling of app actions (AWM).
  • Documented in the Application Development Best Practices: for data apps, “as a general rule (exceptions need to be discussed), do not provide a custom UI and instead rely on the Page Template feature”, with FAQ, Blog and Forum as examples.
  • 2024-2026 – applied to AWM in Restyling of app actions (AWM) and the resulting AWM Actions design: the “Add new entry” button goes away and the main Create button creates the app entry from the right template. In the same spirit, Single Click Page Creation is about making that single Create button faster/lighter, not about adding other ones.

So a macro to put “Create a new X” forms in pages would go against this decision. The custom forms Pierre mentions (Blog’s blogpostcreate, Security Advisory, AWM’s “Add new entry”) are precisely the ones we decided to migrate but haven’t migrated yet (see Loading... for FAQ). I’d rather we spend the time on that migration, and improve the Create UI (lighter UI when the template/location is known, faster creation) wherever it doesn’t cover these apps’ needs.

Thanks

PS: This post was co-written with Claude Code.

I agree that, in its current form, the proposed macro goes against our best practice to use the standard Create UI for creating new pages.

Why does the advanced user think less experienced users need this simple “create a new X here” button when there is a Create button already in the page menu? Probably because:

  • they want to force a specific page template, so simple users don’t have to select it or forget to select it
  • they want to force a specific location, when the location is not enforced by the page template provider
  • they want to force a specific page name (strategy)

My feeling is that the advanced user wants to limit or prefill the options from the Create UI. Their need is not to show a custom create page form inline, but to:

  • either open the standard Create UI with some fields prefilled and/or hidden
  • or go directly to the new page in edit mode (with a generated name, skipping the Create UI)

Prefilling and skipping the Create UI should be already possible. We’re probably lacking support for hiding some fields (e.g. hide the template field). A macro that shows only a “Create X” button that does what I mentioned above, could be useful. On the other hand, if this macro is called only once per page most of the time, then it might be better to extend (UIXP) the standard Create button and have a dropdown on it like for the Edit button.

Regarding the inline create form, maybe one reason some users prefer it over the standard Create UI is that the latter is forcing you to change the context (leave the current page). We already show the standard Create UI in a modal for wanted links. We could do the same for the standard Create button, i.e. make it open a modal instead of leaving the page.

Thanks,
Marius

Hi everyone, and thank you for your replies.
Reading them, there seem to be two main points that go against the current best practices:

  1. We want to keep a single creation workflow to avoid improperly handled side-effects (e.g., wiki page naming rules being ignored)
  2. From a UX point of view, we wish to not confuse users with multiple creation mechanisms at the same time.

Considering this, I would like to suggest a slightly different proposal:

  • Instead of having a form like the initial post mentioned, we could consider a macro that relies fully on the current create page UI, but limits and pre-fills the fields. It would simply be a single “Create XXX” button opening the page creation assistant with a pre-selected template and space, both read-only (or hidden, TBD) if set as such, and possibly a default page name.
  • Like @mflorea proposed, this would open the page creation UI in a modal.

This version should handle point 1, and thus stays within the 2020 decision (only a single Create UI).
Since every button opens the same creation UI, users don’t have a new mechanism to learn, the button is only a shortcut to it and the context of using one button over the others can be integrated in the page itself.

Now, the reasons I still want to push on having this in XS is that there is, I believe, value in having multiple creation buttons in a single page. The main point is context (similarly to what we have right now in the release notes application): this would allow to design a page guiding users to create content with a specific template depending on what they are trying to achieve.

With a single page creation button, this is simply not as straightforward and, I would argue, more error prone: consider a page explaining to a user how to create and fill out information for a new “Movie” page, this may also require first creating a “Director” page. Once they are done reading all the details, they then need to scroll back to the top to click the “New Page” button, select the template for a “Director” (that needs to be allowed manually on the current space), then possibly go back to the previous page to do the same but with the “Movie” template this time (because the “Movie” template is likely not allowed in the space where Directors are stored).

Having multiple context-specific page creation buttons makes this a lot more streamlined, without getting in the way of the “normal” workflow.

Also, this would technically impact the current page creation UI (e.g., by adding read-only fields) so even if it were to end up as a contrib extension there are still XS changes to discuss.

Thanks.

Hi :slight_smile: I would like to support the creation of a macro to create a page from a template. Here are my arguments and vision.

Motivation

Often in an XWiki instance you have two types of pages:

  1. Pages with data (documentation, procedures, how tos)
  2. Navigation or landing pages - a way to guide navigation and content creation

On the latter, administrators or power users usually need a way to guide content creation. For example, think of a page that lists all the clients and projects of an organization. You can envision the following structure of the landing page:

  • List of all projects
    • button - click here to create a new project
  • List of all clients
    • button - click here to create a new client

The proposed create from template macro pairs well with the new records macro to create navigation or landing pages and guide content creation. The main reason why I believe this macro would be valuable is because the user would be able to create a page from a location lower in the page, after reading instructions or seeing examples.

This is a need that organizations usually address through custom code.

Examples:

  1. https://www.extensions.xwiki.org - contribute extension
  2. https://design.xwiki.org/xwiki/bin/view/Proposal/ - add proposal
  3. https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ - add release note or add release change

Page creation flow proposals:

  1. click on button
  2. fill in page name

Option A. On creation screen - you see the title, you see the prefilled location (and you can not edit it), and you don’t see the option to select a template (similar to the current /create/sandbox/?template=MyApp.CodeMyAppTemplate screen)

OR

Option B. like add AWM entry - popup to fill in only the title

OR

Option C. like in extensions.xwiki.org title field next to create button

  1. redirect on new page and fill in data (same as it is today, nothing to change)

Macro needs:

  • template (chosen by the person that inserted the macro in the page)
  • button can be placed in any location in the page - you can put it in a table, in between text, in a list etc. (user reads content and click - creates page)
  • multiple buttons can be placed in the same page
  • define location to create pages into in button

Macro parameters:

  • template provider
  • location
  • button label

Additional notes:

I agree that a custom creation button is redundant in the context of a single app, namely the “Create an entry” button for AWMs.

However, if you are in a location where multiple templates can be used, you need a way to give a content organiser the possibility to guide its users towards the correct way to create content and minimise errors. This usecase is not contradicting the top Create button.

In similar knowledge management software the usecase where you have landing (navigation) pages with listings and the option to create multiple types of pages is very common.

I look forward to your feedback on these ideas.