Repository

The data handling of the SDK allows you to fetch and write nearly everything in the database. The behavior matches the data handling in the main administration. The only difference is the implementation details because the data handling don't request the server directly. It communicates with the admin which handles the requests, changesets, saving and more.

The data handling implements the repository pattern. You can create a repository for an entity simply like this:

import { data } from '@shopware-ag/meteor-admin-sdk';

const productRepository = data.repository('product');

With this repository you can search for data, save it, delete it, create it or check for changes.

Permissions

For every action on the repository, your app will need the matching permissions. Permissions are set in the app manifest file and are grouped by action. For actions you can choose between create, read, update and delete. Remember everytime you adjust the permissions in your manifest you need to increase the app version and update it.

<?xml version="1.0" encoding="UTF-8"?>
<manifest
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">

    <!-- ... -->

    <permissions>
        <create>product</create>
        <read>product</read>
        <update>product</update>
        <delete>product</delete>
    </permissions>
</manifest>

Criteria

For requesting data you need to create a Criteria class which contains all information for the request:

import { data } from '@shopware-ag/meteor-admin-sdk';

const { Criteria } = data.Classes;
const criteria = new Criteria();

criteria.setPage(1);
criteria.setLimit(10);
criteria.setTerm('foo');
criteria.setIds(['some-id', 'some-id']); // Allows to provide a list of ids which are used as a filter

/**
    * Configures the total value of a search result.
    * 0 - no total count will be selected. Should be used if no pagination required (fastest)
    * 1 - exact total count will be selected. Should be used if an exact pagination is required (slow)
    * 2 - fetches limit * 5 + 1. Should be used if pagination can work with "next page exists" (fast)
*/
criteria.setTotalCountMode(2);

criteria.addFilter(
    Criteria.equals('product.active', true)
);

criteria.addSorting(
    Criteria.sort('product.name', 'DESC')
);

criteria.addAggregation(
    Criteria.avg('average_price', 'product.price')
);

criteria.getAssociation('categories')
    .addSorting(Criteria.sort('category.name', 'ASC'));

repository.search()

Sends a search request for the repository entity.

Usage

const exampleRepository = data.repository('your_entity');

const yourEntities = await exampleRepository.search(yourCriteria);

Parameters

Name	Required	Default	Description
criteria	true		Your criteria object
context	false	{}	Change the request context

Return value

The return value is a EntityCollection which contains all entities matching the criteria.

repository.get()

Short hand to fetch a single entity from the server

Usage

const exampleRepository = data.repository('your_entity');

const yourEntity = await exampleRepository.get('theEntityId');

Parameters

Name	Required	Default	Description
id	true		The id of the entity
context	false	{}	Change the request context
criteria	true		Your criteria object

Return value

The return value is the entity result when a matching entity was found.

repository.save()

Detects all entity changes and send the changes to the server. If the entity is marked as new, the repository will send a POST create. Updates will be send as PATCH request. Deleted associations will be send as additional request

Usage

const exampleRepository = data.repository('your_entity');

await exampleRepository.save(yourEntityObject);

Parameters

Name	Required	Default	Description
entity	true		The entity object
context	false	{}	Change the request context

Return value

This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully.

repository.clone()

Clones an existing entity

Usage

const exampleRepository = data.repository('your_entity');

const clonedEntityId = await exampleRepository.clone(
    'theEntityIdToClone',
    yourApiContext
);

Parameters

Name	Required	Default	Description
entityId	true		The entity id which should be cloned
context	true		Change the request context
behavior	false		Configure the clone behavior

Return value

This method returns the id of the cloned entity.

repository.hasChanges()

Detects if the entity or the relations has remaining changes which are not synchronized with the server

Usage

const exampleRepository = data.repository('your_entity');

const hasChanges = await exampleRepository.hasChanges(yourEntityObject);

Parameters

Name	Required	Default	Description
entity	true		The entity object

Return value

This method returns a boolean value. If the entity has changes then it returns true. Otherwise it returns false.

repository.saveAll()

Detects changes of all provided entities and send the changes to the server

Usage

const exampleRepository = data.repository('your_entity');

await exampleRepository.saveAll(yourEntityCollection);

Parameters

Name	Required	Default	Description
entities	true		Your entity collection which should be saved
context	false	{}	Change the request context

Return value

This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully.

repository.delete()

Sends a delete request for the provided id.

Usage

const exampleRepository = data.repository('your_entity');

await exampleRepository.delete('yourEntityId');

Parameters

Name	Required	Default	Description
entityId	true		The id of the entity which should be deleted
context	false	{}	Change the request context

Return value

This method does not have a return value. It just returns a Promise which is resolved when it was deleted successfully.

repository.create()

Creates a new entity for the local schema. To Many association are initialed with a collection with the corresponding remote api route. This entity is not saved to the database yet.

Usage

const exampleRepository = data.repository('your_entity');

const yourNewEntity = await exampleRepository.create();

Parameters

Name	Required	Default	Description
context	false	{}	Change the request context
id	false		You can provide a id of the new entity if wanted

Return value

This method returns the newly created entity.

Request Context

You can optionally change the context of the request. It will be merged together with the base API context.

const exampleContext = {
    // Load also inherited data (example from parent product in variant)
    inheritance: true,
    // Change the language context of the entity to change data in different languages
    languageId: 'theLanguageId',
    // If you are working with versioned entities you can change the current live version id
    liveVersionId: 'yourLiveVersionId'
}

Clone Behavior

You can optionally change the clone behavior of the request. The clone behavior controls how the entity is duplicated on the server.

Use overwrites to replace values in the cloned entity before it is written, for example to set a different name or other field values on the copy.

Use cloneChildren to control whether child entities are cloned as well. This value defaults to true.

const exampleCloneBehavior = {
    // Replace values in the cloned entity before it is saved
    overwrites: {
        name: 'Copy of the original entity',
        active: false
    },
    // Set to false if child entities should not be cloned
    cloneChildren: true
}