Skip to main content

Developer Resources

Installation​

Minimum Requirements​

  • Frontend: 0.9.55 Dec 08, 2022
  • Backend: 0.9.84 Dec 08, 2022
  1. Installing dependencies
composer require qore/excel-import

For frontend you need to install the xlsx package

yarn add xlsx
  1. Publishing files
php artisan vendor:publish --tag=qore.excel-import.frontend

Understanding how it works​

In the case that you may want to extend the functionality, or override some parts, you should first understand how the flow of the importer works:

In this process you can override the resolveImportMappings function for each field, see more here.

Usage​

Disabling imports specific resources​

You can disable the import for a resource by overriding the following function:

Inside your resource:

public function importEnabled(): bool
{
    return false;
}

Disabling imports for fields​

You can disable specific fields from being shown inside the importer field selectors by doing the following:

For a field file​

You can override the isImportDisabled function inside the field:

public function isImportDisabled(): bool
{
    return false;
}

Inline in resource​

Or you can override just one field from your resource by doing the following:

public function fields(): FieldCollection
{
    return new FieldCollection(
        Id::make(),
        Text::make('Title', 'title')
            ->disableImporting(),
        ...
        CreatedAt::make(),
        UpdatedAt::make(),
    );
}

Overriding import functions​

You can override the default behaviour that a field will have when it is imported.

For that we need to understand how the importer works, in the flow described here we can see the Fill & Save process.

That process will call for each field that is mapped, a function that has to return an array that will later be used to fill the model.

danger

Be aware that relational fields behave differently and they are To be documented

For example, the following 2 fields on a resource:

Text::make('Title', 'title'),
Text::make('Description', 'description')

Will in their local mapping functions return this array:

// Title Field
return [
    'title' => $cellValue
];

// Description Field
return [
    'description' => $cellValue
];
tip

Here $cellValue is $getKeyForRow($mapping->mappings->first()), see example below.

For a field file​

class Text extends Field {
    // This is the default importMapper used by all fields beside relational ones
    public function importMapper(
        QoreResource $resource,
        HeaderMapping $mapping,
        array $row,
        callable $getKeyForRow
    ): array {
        $object = [];
        /** @var Header $header */
        foreach ($mapping->mappings as $header) {
            $object[$this->column] = $row[$getKeyForRow($header)];
        }
        return $object;
    }
}

Inline in resource​

Text::make('Title', 'title')
    ->disableImporting(),
    ->setImportMapper(function (
        QoreResource $resource,
        HeaderMapping $mapping,
        array $row,
        callable $getKeyForRow
    ) {
        /** @var Header $header */
        $header = $mapping->mappings->first();

        return [
            'first_name' => $row[$getKeyForRow($header)]
        ];
    }),