[MGNLCT-59] References to other CT should be explicit Created: 10/Sep/18  Updated: 25/Feb/19  Resolved: 05/Feb/19

Status: Closed
Project: Content Types
Component/s: None
Affects Version/s: 1.0
Fix Version/s: 1.1

Type: Story Priority: Critical
Reporter: Christopher Zimmermann Assignee: Dai Ha
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: 0d
Time Spent: 2d 0.5h
Original Estimate: Not Specified

Issue Links:
Cloners
is cloned by MGNLCT-93 Investigate ability to override model... Closed
Problem/Incident
is caused by MGNLUI-4537 Define relationships between content ... Closed
causality
is causing MGNLCT-95 DOC: References to other content type... Closed
dependency
is depended upon by MGNLCT-97 References to other CT should use the... Closed
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)
Documentation update required:
Yes
Date of First Response:
Epic Link: Content Types finalization
Sprint: Features 3, Features 4, Features 5
Story Points: 5

 Description   

User story

As a developer I want references to another Content Type that are in a YAML Content Type definition file to be explicitly defined as a reference so that everyone has a clear understanding of the content model.

 

Acceptance Criteria:

  • The syntax of a CT reference in the YAML file is clearly identifiable as such, maybe the type has the name "reference".
  • Developers coming from other products will find the references familiar, and easy to identify.
  • The reference could accept additional properties in the future that are typical on Magnolia link-fields today - such as which chooser dialog to use. 

Rationale:

As currently implemented, references to other content types look the same as declarations of standard properties and the same as references to subModels. 

//currently. Asset is another content type, but it looks like a data primitive, like String.

model:
  properties:
    address:
      type: String      
    slideshow:
      type: Asset
      multiple: true


But the field does not actually store the type - it stores a reference to the type. This is different from submodels, and it is different from the "basic types".

Referencing another contentType should be explicit to avoid any confusion and to highlight the references which are a key aspect of a projects content model. This is especially important for developers and for information architects. The content model is an important part of a project that non-developers should also understand.

Developers need to know that the type stores references as they will need to include specific code to resolve the reference before working with the referenced content.

References will eventually need more properties: Such as which UI to use (select vs chooser dialog) which chooser dialog to use, which subpath to access, which items to filter out, etc.

 



 Comments   
Comment by Christopher Zimmermann [ 30/Jan/19 ]

dai.ha OK.

Comment by Christopher Zimmermann [ 30/Jan/19 ]

I think we should use the syntax:

type: reference:TourGuide

instead of 

type: ct:TourGuide

as it is currently implemented.

 

Reasoning:

The intention of this ticket is to make the content model very clear to developers. The important thing is that a developer (and other stake holders in the project) should know when a field is a reference, as this will impact the UI, the templating, configuring REST endpoints and working with REST responses.

The word "reference" is a good choice for this as it is easy to read, it is plain english, and it is consistant with how most CMS call reference fields. (Please see the table at the top of this page: https://wiki.magnolia-cms.com/display/TH2/Competitor+Research+-+Content+types )  

I appreciate the reasoning mentioned in the review session that 'ct' is much shorter than 'reference': We do strive to make a compact content type definition. But in this case I think the benefit of a shorter syntax is outweighed by readability, ease of comprehension, and familiarity.

 

 

 

 

 

Comment by Christopher Zimmermann [ 31/Jan/19 ]

Re-opening for the reason mentioned in the previous comment about "ct" and "reference".

Comment by Dai Ha [ 11/Feb/19 ]

Hi mgeljic,

In this case, for me, both "ct" or "reference" are ok because they have their own good reasons. Just want to get your opinions before any further step

Comment by Mikaël Geljić [ 11/Feb/19 ]

No strong reason, I agreed with Topher that the "ct:" prefix went a bit far, and did not really meet the acceptance criterion as "clearly identifiable".

Comment by Christopher Zimmermann [ 11/Feb/19 ]

dai.ha I created a followup ticket (https://jira.magnolia-cms.com/browse/MGNLCT-97) for the renaming from "ct" to "reference", so if it passes QA, you could go ahead and close this ticket with the "ct".

On the other hand - I'm happy if you want to go ahead and change it to "reference" in the context of this ticket, and then I'll close that followup ticket.

Whatever you prefer.

Comment by Dai Ha [ 11/Feb/19 ]

I think I still have effort in this sprint to finalize this ticket so I will do it in the context of this one. Thank you all for input!

Generated at Mon Feb 12 00:36:45 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.