[PAGES-1557] As a frontend developer I want to get page template definitions by path Created: 14/Dec/23  Updated: 02/Feb/24

Status: Discovery
Project: Magnolia pages module
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Story Priority: Neutral
Reporter: Canh Nguyen Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: 3d
Original Estimate: Not Specified

Issue Links:
Cloners
documentation
to be documented by PAGES-1569 DOC: As a frontend developer I want t... Reopened
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Release notes required:
Yes
Documentation update required:
Yes
Date of First Response:
Epic Link: SPA Editor Backlog
T-Shirt Size: Medium
Team: DeveloperX
Work Started:

 Description   

Context

Use case

To manage a grid layout of an component with nested areas. We need to create a JS field that stores multilple columns config. The number of columns will be changed by viewport. We need to define multiple viewports in the definition and the grid field needs to get configured viewports from the definition.

Problem

The dialog only provides node path when edit a component, so it is inconvenient to use the template definitions endpoint version 1 (which is deprecated).

Acceptance Criteria

  • Find a definition by a given path
  • Find the closest parent definition by a given path and node type
  • Find a definition by definition ID


 Comments   
Comment by Christopher Zimmermann [ 14/Dec/23 ]

Can you please provide more detail about the use case? I don't understand "In a SPA project, it's required to fetch definitions by path to create JS field forms. ".

Comment by Canh Nguyen [ 18/Dec/23 ]

czimmermann I've updated the description.

Comment by Canh Nguyen [ 20/Dec/23 ]

This new endpoint uses jackson to serialize TemplateDefinition, so it merely converts TemplateDefinition to JSON without processing data.

Comparison

 

Functionality Template Definition v1 Template Definition v2
Fetch TemplateDefinition by node path  Not supported Supported
Fetch TemplateDefinition of the parent node by the given node path and parent node type Not supported Supported
Fetch TemplateDefinition by template ID Supported Supported
Process TemplateDefinition and serialize nested TemplateDefinitions Supported Returns nested template IDs only. SPAs need to fetch nested template by ID.
Configurable endpoint path Not supported Supported
Configurable workspace Not supported because query by path is not supported Supported. "website" is default value
Is it automatically provisioned - like the templateAnnotations - or does a developer specifically configure it? Yes. Default path:
"/
templateDefinition/v1" or "/template-definitions/v1"
Yes. Default path:
"/
template-definitions/v2"
Are there any security concerns? Is it public by default - or must a user be authenticated to use it? with certain permissions? Public by default. Not configured yet. Should be similar to v1 and template-annotations endpoint.

Template Definition v2 APIs

  • /{nodePath}: Return TemplateDefinition by given node path
  • /{nodePath}?parentNodeType={nodeType}: Find TemplateDefinition of the closest parent by given node type and child node path.
  • /?templateId={templateId}: Return TemplateDefinition by template ID e.g. "foo:components/bar"

 

Comment by Christopher Zimmermann [ 20/Dec/23 ]

Thank you! Looks pretty good

Comment by Christopher Zimmermann [ 04/Jan/24 ]

I have a small discussion point. 

Typically for a REST API I would expect the url to take the templateId in the path - like:

/{templateId}

But I guess there are good reasons for the way you described above. The main usecase is to get the template for a specific path. And the way you described works more like the template-annotations and delivery APIs.

Also a question - why does v2 "Returns nested template IDs only. SPAs need to fetch nested template by ID.".

Maybe I dont understand the usecase properly... but wouldnt a developer want to get the definitions for the page, the area, and the available components - all in one go?

Comment by Christopher Zimmermann [ 04/Jan/24 ]

What is the usage for "Find the closest parent definition by a given path and node type"?

Generated at Mon Feb 12 06:29:14 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.