Make useAsTitle formatable

[GeorgeHulpoi]

Currently useAsTitle property from CollectionConfig searches for the field in the collection. It would be useful to be able to format.
For example, a person has firstname and lastname properties, but for the title would be nice to have {{firstname}} {{lastname}}. So, there are a few solutions:

1. useAsTitle to accept a string or a function which returns a string
2. useAsTitle will parse the variables, search for fields, and replace them.

What do you think?

[matthijs166]

What we always do is add an hidden field and handle the logic in the beforeChange hook. This way you can also use it in your frondend.

        {
            name: "title",
            type: "text",
            required: true,
            admin: {
                hidden: true,
            },
            hooks: {
                beforeChange: [
                    async ({ data }) => {
                        // fallback?
                        return `$(data.firstname) - $(data.lastname)`
                    }
                ]
            }
        },

[GeorgeHulpoi]

@matthijs166 the solution I expect is to change that part of this code: https://github.com/payloadcms/payload/blob/master/src/admin/hooks/useTitle.tsx

@JarrodMFlesch if I can come up with a solution, I need to fork the master, be sure that the tests are passing and create a merge request on the main git?

[tyteen4a03]

This is the virtual fields paradigm: https://payloadcms.com/blog/learn-how-virtual-fields-can-help-solve-common-cms-challenges

[matthijs166]

@GeorgeHulpoi Do you have a code snippet of how your proposed solution will look? To me, it looks like almost the same pattern, only now there is an extra field.

Or is the case that you're making, to make it more intuitive for developers to add logic to the title the cleanest way possible?
It is an extra step to make it do what you want. Something not everybody gets when using Payload for the first time.

Maybe adding an beforeShowingTitle hook here can tackle this: (would be admin focused, so it's not triggered in the API)
https://payloadcms.com/docs/configuration/collections#admin-hooks

Also, would be an idea to add some documentation for making dynamic titles in the admin UI.

[tyteen4a03]

I would also like to see the team make virtual fields like this have less boilerplate, especially if we don't intend to query them from GQL.

[matthijs166]

You can follow the article you referenced, right? https://payloadcms.com/blog/learn-how-virtual-fields-can-help-solve-common-cms-challenges

Does it work if you set the access control read to false? This will hide it from the rest API (don't know if it will hide from GQL)

[GeorgeHulpoi]

@matthijs166 A very simple example would be to add a condition to the formatUseAsTitle to check if the given value is a function.

export const formatUseAsTitle = (args: {
  field?: FormField
  doc?: Record<string, any>
  collection: SanitizedCollectionConfig
  i18n: typeof i18next
  config: SanitizedConfig
}): string => {
  const {
    field: fieldFromProps,
    doc,
    collection,
    collection: {
      admin: { useAsTitle },
    },
    i18n,
    config: {
      admin: {
        dateFormat: dateFormatFromConfig,
      },
    },
  } = args;

  if (!fieldFromProps && !doc) {
    return '';
  }

  if (typeof collection.admin.useAsTitle === 'function') {
    collection.admin.useAsTitle.call({ doc })
  }

  const field = fieldFromProps || getObjectDotNotation<FormField>(doc, collection.admin.useAsTitle);

  let title = typeof field === 'string' ? field : field?.value as string;

  const fieldConfig = collection?.fields?.find((f) => 'name' in f && f?.name === useAsTitle);
  const isDate = fieldConfig?.type === 'date';

  if (title && isDate) {
    const dateFormat = fieldConfig?.admin?.date?.displayFormat || dateFormatFromConfig;
    title = formatDate(title, dateFormat, i18n?.language);
  }

  return title;
};

And use as you wish:

admin: {
    useAsTitle: ({doc}) => `${doc.firstname} ${doc.lastname}`
}

But now I think I understand that I was terribly wrong. The formatUseAsTitle is a front-end function, whereas the useAsTitle seems like a virtual field. Therefore there is no way to pass a function to formatUseAsTitle, right?

[matthijs166]

This looks clean and is going to work, just functions like a hook!

What are your thoughts on adding it to the admin hooks?
https://payloadcms.com/docs/configuration/collections#admin-hooks

Don't understand what you mean with the virtual field. It is indeed called in the front-end and the way you sketched it will work.

Also the docs can include this and payload users can easier find the way to add a composed dynamic titles.

Btw you can directly return the value of the useAsTitle hook if the return type of the hook is forced to a string.

  if (typeof collection.admin.useAsTitle === 'function') {
    return collection.admin.useAsTitle.call({ doc })
  }

Are you creating an PR for this? Otherwise, I have some time over in the weekend.
Would be cool to make this happen and see what others think of it.

[GeorgeHulpoi]

@matthijs166 based on https://github.com/payloadcms/payload/blob/master/CONTRIBUTING.md#before-starting I still wait for somebody from team to give us an answer.

[tyteen4a03]

If you use the virtual fields guide, the data does not make its way into the database.

However, I think this is an important enough use case that it should be built-in.

[GeorgeHulpoi]

@tyteen4a03 Yes, it makes its way into the database. The admin.hidden just will hide it, but if you check the database, you will see that field there.

[tyteen4a03]

@GeorgeHulpoi did you follow the guide in https://payloadcms.com/blog/learn-how-virtual-fields-can-help-solve-common-cms-challenges?

This hook explicitly stops it from entering the database:

    beforeChange: [({ siblingData }) => {
      delete siblingData.staff;
    }],

[GeorgeHulpoi]

@tyteen4a03 Oh, didn't see that part (honestly I didn't go to the bottom). I see, this may be an approach. But still, I maintain my opinion about it. It's cleaner for me to use a one-line function instead of creating a new field, passing a hook to it, and a few properties. It's more clean in my opinion.

[tyteen4a03]

I agree!

[CherryDT]

The virtual field solution is kinda OK but then the rendered title in the admin won't auto-update when typing into the fields the title depends on. Is there any way to make that work?

[CherryDT]

I found a solution now.

I created a file such as this:

import React, { useEffect } from 'react' // eslint-disable-line no-unused-vars
import { useFormFields } from 'payload/components/forms'

const buildDependentFieldUpdater = (path, dependencies, fn) => {
  // Returns an empty do-nothing component which does however take care of the updating
  return () => {
    const [object, dispatch] = useFormFields(([fields, dispatch]) => [Object.fromEntries([...dependencies, path].map(k => [k, fields[k]?.value])), dispatch])

    useEffect(() => {
      if (object && fn) {
        const newValue = fn(object, dispatch)
        if (newValue !== object[path]) dispatch({ type: 'UPDATE', path, value: newValue })
      }
    }, [object])

    return (<></>)
  }
}

export default buildDependentFieldUpdater

And then I configured my fields as follows:

const getFullName = doc => `${doc.firstName} ${doc.lastName}`

const fields = [
  {
    name: 'fullName',
    type: 'text',
    label: 'Full Name',
    admin: {
      hidden: true,
      disableBulkEdit: true
    },
    hooks: {
      beforeChange: [({ data }) => getFullName(data)],
      afterRead: [({ data }) => getFullName(data)]
    }
  },
  {
    type: 'ui',
    admin: {
      components: {
        Field: buildDependentFieldUpdater('fullName', ['firstName', 'lastName'], getFullName)
      }
    }
  },
  {
    name: 'firstName',
    type: 'text',
    label: 'First Name',
    required: true,
    defaultValue: ''
  },
  {
    name: 'lastName',
    type: 'text',
    label: 'Last Name',
    required: true,
    defaultValue: ''
  }
]

...and of course useAsTitle is set to fullName.

Note that I do not remove it from the DB, I intentionally leave it there, because this is necessary to make filtering work properly! While for the main list we could set additional search fields, in relationship fields that would not work to filter the dropdown!

[lsdebianchi]

I agree that this could be a nice feature.
It's a very common operation when building cms UI for editors. A concise syntax would remove a lot of boilerplate and it could also enable the update-as-you-type out of the box.

It could be a formatting syntax "{{firstname}} {{lastname}}" or even a function ( {data} ) => return `${data?.firstname} ${data?.lastname}`