Custom fields API

[remidej]

This PR introduces a proposal for the custom fields API (view the formatted RFC here).

It is a follow-up to the non-technical custom fields RFC previously published.

Please, share your feedback and ideas 🙂

---

Co-authored by @markkaylor @remidej @soupette

[strapi-cla]

All committers have signed the CLA.

[magick93]

type: "text", // store the color as a text in 

Does the text type refer to the database type?

I know a lot of requestors, myself included, are wanting to surface additional database types, for example money, in postgres, is a popular, and useful type, which I'm sure a lot of Strapi users would also like to be able to access. And there are many others, especially when you add postgis to the mix.

[actarian]

Waiting for this feature in order to adopt Strapi as headless cms, but we plan in many cases to use 'json' as base type.

So will be extremely useful to extend the CustomFieldAdminOptions Interface with a value formatter function, and a value query function, in order to allow the custom Field to be exposed on the Listing View even if is of base type 'json' (or other types).

es

interface CustomFieldAdminOptions {
  // The settings to extend in the Content Manager List View
  decorators?: {
    valueFormatter: (value: CMValue) => Promise<string> | string;
    valueQuery: (value: CMValue, searchParams: CMSearchParams) => Promise<boolean> | boolean; 
  }
}

If the interface does offer a proper way to formatting and query the base type value, it should be possibile to add that type in the listing view.

[remidej]

Does the text type refer to the database type?

@magick93 in this context, type refers to the Strapi type. They're pretty close to database types but a bit higher level. You can find the list there.

I know a lot of requestors, myself included, are wanting to surface additional database types

We're aware of this, and it's definitely something we'll want to add to Strapi. It's not the scope of this current feature however. We think of custom fields as a first step that already brings value, and that will later work hand in hand with custom types.

[remidej]

Waiting for this feature in order to adopt Strapi as headless cms, but we plan in many cases to use 'json' as base type.

@actarian that's interesting thanks for the insight. In think many others will be in that situtation, especially until we add custom database types.

Regarding your suggested solution:

• To render the custom field in the list view, that's why we allow users to pass a <View /> component in the RFC. You can do your own formatting logic in that component.
• To query based on a custom field, we'll rely on the underlying Strapi type. It's true that for JSON that means pretty much no search capabilities. But I'm not sure we want to introduce an API just for this one data type. Based on this forum thread, it seems that it's not so easy on the database layer. I'll ask the backend team what they think.

[actarian]

• To render the custom field in the list view, that's why we allow users to pass a component in the RFC.

@remidej as per the current capabilities is not possible to add a field in the listing of type JSON, only few types are allowed. So the View component should not appear if referred to a base type JSON.

Based on this forum thread, it seems that it's not so easy on the database layer. I'll ask the backend team what they think.

I'm aware of this issue, and is for this reason that I would allow at least the decision to add other non supported types in the listing to the developer, that should provide a custom implementation maybe of the query?.

But I understand that the best solution would be to resolve that issue on the database layer.

[derrickmehaffy]

Does the text type refer to the database type?

@magick93 in this context, type refers to the Strapi type. They're pretty close to database types but a bit higher level. You can find the list there.

I know a lot of requestors, myself included, are wanting to surface additional database types

We're aware of this, and it's definitely something we'll want to add to Strapi. It's not the scope of this current feature however. We think of custom fields as a first step that already brings value, and that will later work hand in hand with custom types.

As a sub-comment to this, while it's not directly supported and largely still extremely unstable. You could potentially bypass this requirement here: https://docs.strapi.io/developer-docs/latest/development/backend-customization/models.html#database-validations-and-settings

[Convly]

Hi and thank you for this very detailed RFC, this looks promising.

I'm sharing some thoughts I have regarding the server implementation:

I would like to better understand the reasoning behind exposing a "field" notion on the server logic, whereas the only additional logic done is handled by the admin panel. Moreover -still talking about the server side-, as I see it customFields are basically aliases between a Strapi type and a custom name with other options defined by the pluginOptions and nothing more. I know that in the future we would like to introduce real custom type which would be way more than this, but I can't help but think that maybe we don't need to leak this "field" logic in the server and only deal with what we would call "aliases" or smth like that. I see several benefits from doing so:

• Less boilerplate as we only have to use { type: "color-picker" } instead of { type: "customField", customField: "color-picker" }.
• Possibility to override Strapi type displays & add other options through the plugins (eg: define a custom string field resolving to Strapi string and adds additional options to it + other UI configurations)
• Less code to refactor when we'll add the real custom types + no breaking changes
• Avoid leaking the admin "field" notion in the server and only deal with server-side logic

And a potential drawback would be the implementation:

• The actual handling of the type wouldn't be more complicated as instead of handling the customField type everywhere, we would only have to resolve the alias before evey type-handling.
• However, it would be harder to find a place to bind/handle the custom options attached to the type.

I'm really looking for counter-arguments here because I feel like I might be missing something from the reasoning behind the server implementation.

Note: If we continue with this "customField" notion in the server, maybe we could at least put the registry in the admin services as it would be an admin-related feature, what do you think? (smth like strapi.admin.services.customFields)

[remidej]

Hey @Convly, sorry for not responding earlier. So far, it's true that custom fields are very admin-oriented, so I understand your concern. But there are 2 reasons why we thought we'd register custom fields on the server too.

Backend validation

First, though it won't be part of the MVP, we'll later want to enable custom fields to add their validation rules on the server. For example, if your custom field uses the text Strapi type, you may want to ensure that the content matches a regex as well. You can do that validation on the frontend for now, but for more safety, we'd want to apply it on the database layer too. I believe we'd need to have on entry point on the server for this.

Type swapping

The second reason is about the schema.json syntax. We chose to have customField as the type because it's easier for the backend to only add a single new possible type, instead of dynamic types. It was also because it looks familiar, given how the component and relation types already work.

But when it comes to the frontend, type: customField makes things a lot harder. It requires many changes in the CTB frontend, which is a delicate part of the codebase. To avoid this, we're considering modifying the attribute schema before it's sent to the admin via API calls.

So to follow the example mentioned in the RFC, when this is stored in your schema.json:

{
  "attributes": {
    "attributeName": {
      "type": "customField",
      "customField": "plugin::plugin-name.fieldname"
    }
  }
}

The admin on the other hand would receive this:

{
  "attributes": {
    "attributeName": {
      "type": "string",
      "customField": "plugin::plugin-name.fieldname"
    }
  }
}

The exact format after transformation is not determined yet, but the idea is that the admin would be able to infer that it's a custom type even without the explicit type.

To do this transformation, we need to map the original attribute to the type it's using, and it needs to happen on the server. That requires having some sort of custom fields store on the backend, which is why we think we need the server registration.

---

Regarding your suggestion to use something like strapi.admin.services.customFields, I definitely see your point. Personally, I think of custom fields as a Strapi feature more than a Strapi Admin feature, so I would rather surface their API more. But I'd love to hear more opinions on that point.

[derrickmehaffy]

Sharing some feedback from @napserious on Discord:

Here is the specific images he shared:

[dzcpy]

Will it be available in v4.2?

[derrickmehaffy]

Will it be available in v4.2?

No, release date TBD

[Landstein]

Any updates on the progress here? Would be great to have an estimate on the release

[remidej]

Thanks for all your feedback! We're merging the RFC because we're committing to that API. Development will now happen on this branch in the strapi repo.

We expect to ship a beta release for custom fields in September (ping @Landstein)

[strapi-bot]

This pull request has been mentioned on Strapi Community Forum. There might be relevant details there:

https://forum.strapi.io/t/discussion-regarding-the-complex-response-structure-for-rest-graphql-developer-experience/13400/76