Skip to main content

Custom record field rendering

Customizing how AdminForth renders the cells with record values​

Let's change how AdminForth renders the number of rooms in the 'list' and 'show' views. We will render '🟨' for each room and then we will print square_meter at the same cells.

Create directory custom. Create a file RoomsCell.vue in it:

./custom/RoomsCell.vue
<template>
  <div class="flex items-center">
    <span v-for="room in record.number_of_rooms">
      🟨
    </span>
      
    {{ record.square_meter }} m²
  </div>
</template>

<script setup>
defineProps({
  record: Object,
  resource: Object,
  adminUser: Object,
  meta: Object,
  columns: Object
});
</script>

Now you can use this component in the configuration of the resource:

./resources/apartments.ts
{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      ...
      name: 'number_of_rooms',
     components: {
       show: '@@/RoomsCell.vue',
       list: '@@/RoomsCell.vue',
     }
    },
    ...
  ],
  ...
}

Here is how it looks: alt text

In very similar way you can render how cell is rendered in 'edit' and 'create' view. You can use it for creating custom editors for the fields. Check component specs to understand which props are passed to the component

Parametrizing the custom components​

Sometimes you need to render same component with different parameters. You can use full component declaration

./resources/apartments.ts

{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      ...
      name: 'number_of_rooms',
      components: {
       show: '@@/RoomsCell.vue',
       show: {
         file: '@@/RoomsCell.vue',
         meta: {
           filler: '🟨',
         },
       },
       list: '@@/RoomsCell.vue',
       list: {
         file: '@@/RoomsCell.vue',
         meta: {
           filler: '🟦',
          },
        }
      }
    },
    ...
  ],
  ...
}

Now our component can read filler from meta prop:

./custom/RoomsCell.vue
<template>
  <div class="flex items-center">
    <span v-for="room in record.number_of_rooms">
     🟨
    {{ meta.filler }}
    </span>
    {{ room.square_meter }} m²
  </div>
</template>

<script setup>
defineProps({
  record: Object,
  resource: Object,
  adminUser: Object,
  meta: Object
  columns: Object
});
</script>

Using 3rd-party npm packages in the components​

To install 3rd-party npm packages you should create npm package in the custom directory:

cd custom
npm init -y

And simply do npm install for the package you need:

npm install <some package> --save-dev

Pre-made renderers​

Though creating custom renderers is super-easy, we have couple of pre-made renderers for you to use.

CompactUUID​

If you have a UUID column which you want display in table in more compact manner, you can use CompactUUID renderer.

./resources/apartments.ts
import { randomUUID } from 'crypto';

  ...
  columns: [
    { 
      name: 'id', 
      primaryKey: true,
      showIn: ['filter', 'show'],
      showIn: ['list', 'filter', 'show'],
      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),
      fillOnCreate: ({initialRecord}: any) => randomUUID(),
      components: {
        list: '@/renderers/CompactUUID.vue'
      }
    }
  ...

alt text

Country Flag​

Renders string fields containing ISO-3166-1 alpha-2 country codes as flags (e.g. 'US', 'DE', 'FR', etc.)

./resources/apartments.ts
  columns: [
    ...
    {
      name: 'country',
      components: {
        list: '@/renderers/CountryFlag.vue'
      },
    ...

alt text

You can also show country name after the flag:

./resources/apartments.ts
  columns: [
    ...
    {
      name: 'country',
      components: {
        list: {
          file: '@/renderers/CountryFlag.vue',
          meta: {
            showCountryName: true
          }
        }
      },
      ...
    }

alt text

Human Number​

It formats large numbers into a human-readable format (e.g., 10k, 1.5M) and supports localization for different number formats.

./resources/apartments.ts
  columns: [
    ...
    { 
          name: 'square_meter', 
          label: 'Square', 
          minValue: 1,  // you can set min /max value for number fields
          maxValue: 100000000,
          components: {
            list: {
              file: '@/renderers/HumanNumber.vue',
              meta: {
                showCountryName: true,
              }
            }
          }
        },
    {
    ...

alt text

URL​

If your field has absolute URLs as text strings you can use URLs renderer to render them as clickable links.

./resources/anyResource.ts
  columns: [
    ...
    {
      name: 'url',
      components: {
        list: '@/renderers/URL.vue'
      },
    ...

Relative Time​

To format your date fields to display the elapsed time, you can utilize the RelativeTime renderer.

./resources/anyResource.ts
  columns: [
    ...
    {
      name: 'created_at',
      components: {
        list: '@/renderers/RelativeTime.vue'
      },
    ...