search

silverstripe / silverstripe-linkfield

Silverstripe module for managing links
BSD 3-Clause "New" or "Revised" License
4 stars 13 forks source link

Update linkfield developer doc regarding fluent #237

Open maxime-rainville opened 4 months ago

maxime-rainville commented 4 months ago

Context

We've reviewed the high level compatibility of Fluent with LinkField.

We've identified some upstream problems that make it difficult to fully accommodate Fluent with LinkField. Althought the simpler use case seemed to work pretty well.

User story

As a Fluent developer, I want clear guidance on how to get simple LinkField usage to work with Fluent so I can build interfaces that meet needs of my content authors.

Acceptance criteria

Related card

PRs

GuySartorelli commented 4 months ago

The docs for this should really just link to fluent docs - if even that. Really i don't think we need anything more than "has_one relations are compatible with fluent, but has_many relations are not" and a link to fluent.

maxime-rainville commented 4 months ago

I could live with a simple "Fluent compatibility" section that make clear what works and doesn't work with Fluent.

maxime-rainville commented 4 months ago

@emteknetnz identified a potential Gridield issue during refinement that would block this card. He will create a matching card for it.

emteknetnz commented 3 months ago

These AC's just don't seem good. This really does not belong in the 5.2.0 change log IMO.

I have this currently ([!Note] section is new):


...

Once the above have all been resolved, you can use that documentation and copy the relevant `BuildTask` code into your projects if you need it. These will be included in `silverstripe/linkfield` directly in the next minor release.

> [!NOTE]
> When using the optional [fluent module](https://github.com/tractorcow-farm/silverstripe-fluent) you can only translate `has_one` single `Link` relations and not the `has_many` multi-relations.
> If using content blocks you can make a `has_many` relation translatable without the `Link` relation itself being translatable. (Each localised instance of the block will have a different `Link` DataObject) 
> Read more about [configuring fluent](https://github.com/tractorcow-farm/silverstripe-fluent/blob/7/docs/en/configuration.md).

Check out [the linkfield documentation](/optional_features/linkfield/) for more information about this module.

...

It seems wildly out of place in the rest of the linkfield section of the changelog having specific information about fluent while we do not mention any other optional modules

Also I have no idea what the AC "Make a custom content block with an has_many Link relation translatable with Fluent without the Link relation itself being translatable. (Each localised instance of the block will have different Link DataObject)" even means. It sounds like a very specific fluent customisation to try and work around the lack of has_many support, but at the same time we're mentioning one line that has_many is not supported just one line above.

I think we should modify the AC's in two ways:

I'm going to move this back to refinement for discussion.

GuySartorelli commented 2 months ago

Back in refinement as per https://github.com/silverstripe/silverstripe-linkfield/pull/273#issuecomment-2046546921

I think this one needs to go back in refinement for discussion to work out what we want to do with fluent since it sounds like there's a bunch more work to do.

TL;DR there are some UX issues with fluent when archiving links for both has_one and has_many.

maxime-rainville commented 2 months ago

I would like to see if the issue is fixable before we document it as something that needs to be worked around.

GuySartorelli commented 1 month ago

Validation for this is going to be done in https://github.com/silverstripe/silverstripe-linkfield/issues/285