Installatie- en configuratiehandleiding voor de module Kowal_ExportImportCategories
Dit document beschrijft de installatie, configuratie en het gebruik van de module Kowal_ExportImportCategories voor Magento 2. De handleiding bevat informatie uit het bestand README.md en de functies die in de module zijn geïmplementeerd.
Vereisten
- Magento 2.
- PHP compatibel met de Magento-installatie, aanbevolen PHP
8.1 of nieuwer. - Toegang tot Magento CLI.
- Toegang tot Composer.
- Magento-beheerdersrechten.
- Toegang tot de modulerepository.
- Voor het importeren van afbeeldingen: mogelijkheid om bestanden te plaatsen in de map
pub/media/import/categories.
Installatie via Composer
De module is beschikbaar via een Composer-repository.
1. Voeg de Composer-repository toe
composer config repositories.export.import.categories vcs https://github.com/kowalco/export-import-categories
2. Voeg een toegangstoken toe voor de private GitHub-repository
Als de repository privé is, configureer dan de GitHub-token:
composer config --global --auth github-oauth.github.com
Vervang door uw eigen toegangstoken.
3. Installeer de module
composer require kowal/module-export-import-categories
4. Schakel de module in Magento in
bin/magento module:enable Kowal_ExportImportCategories
5. Voer de Magento-update uit
bin/magento setup:upgrade
6. Leeg de cache
bin/magento cache:flush
7. Voer optioneel DI-compilatie uit
Op productieomgevingen of in production mode:
bin/magento setup:di:compile
8. Implementeer optioneel statische assets
Als de omgeving dit vereist:
bin/magento setup:static-content:deploybin/magento cache:flush
Handmatige installatie in app/code
Als alternatief kunt u de module handmatig in de volgende map plaatsen:
app/code/Kowal/ExportImportCategories
Voer na het kopiëren van de bestanden uit:
bin/magento module:enable Kowal_ExportImportCategoriesbin/magento setup:upgradebin/magento cache:flush
Voer in production mode ook uit:
bin/magento setup:di:compile
Installatie controleren
Controleer na de installatie of de module actief is:
bin/magento module:status Kowal_ExportImportCategories
De module moet in de lijst met actieve modules staan.
Ga in het beheerpaneel naar:
System > Data Transfer > Export/Import Categories
Er moeten drie items zichtbaar zijn:
Export Categories,Import Categories,Import History.
ACL-rechten
De module voegt afzonderlijke beheerdersrechten toe:
- toegang tot de hoofdsectie
Export/Import Categories, - categorieën exporteren,
- categorieën importeren,
- importgeschiedenis.
Als een admin-gebruiker het modulemenu niet ziet, controleer dan de gebruikersrol in:
System > Permissions > User Roles
Ken vervolgens de juiste rechten toe voor de modulebronnen.
Locatie van de module in het paneel
De module is beschikbaar onder:
System > Data Transfer > Export/Import Categories
Weergaven:
Export Categories - export van categorieën naar CSV.Import Categories - import van categorieën uit CSV.Import History - importgeschiedenis en rapporten.
Export configureren
Met de exportweergave kunt u een CSV-bestand met categorieën genereren.
Exportvelden
Store View
Selecteert de store view waaruit de waarden van categorieattributen worden gelezen.
Als u een taal-store view selecteert, kan de export waarden bevatten die specifiek zijn voor die store view of waarden die zijn geërfd uit de default scope, afhankelijk van de waardemodus.
Start Category ID
Optioneel veld waarmee u de export kunt beperken tot een geselecteerde categorie en de onderliggende boomstructuur.
Als het veld leeg blijft, exporteert de module categorieën vanaf de root category van de geselecteerde store view.
Store View Value Mode
Bepaalt hoe store view-afhankelijke waarden worden geëxporteerd.
Beschikbare varianten:
resolved_value,store_override_only.
resolved_value exporteert de waarde die zichtbaar is in de geselecteerde store view, met inachtneming van de Magento-fallback.
store_override_only exporteert alleen de waarde die voor de geselecteerde store view is overschreven. Als de waarde wordt geërfd uit de default scope, blijft de CSV-cel leeg.
CSV Delimiter
CSV-scheidingsteken. Standaard:
,
U kunt een ander scheidingsteken gebruiken als het bestand wordt bewerkt in een tool die bijvoorbeeld een puntkomma vereist.
Attributes
Lijst met categorieattributen die beschikbaar zijn in Magento.
De module haalt attributen dynamisch op uit EAV, waardoor ook eigen categorieattributen die in het project zijn toegevoegd in de lijst kunnen verschijnen.
Systeemkolommen worden automatisch toegevoegd en hoeven niet te worden geselecteerd.
Systeemkolommen in de export
De export moet altijd systeemkolommen bevatten:
store_view_code,entity_id,parent_entity_id,category_path,parent_path,level,position,attribute_set_id.
Deze kolommen dienen voor categorie-identificatie, validatie van de store view en ondersteuning van de boomstructuur.
Import configureren
Met de importweergave kunt u een CSV inlezen en categoriegegevens opslaan.
Importvelden
Store View
Selecteert de store view waarnaar de waarden worden opgeslagen.
Dit veld bepaalt de numerieke store_id die wordt gebruikt bij het opslaan in Magento-tabellen.
De kolom store_view_code uit de CSV wordt niet rechtstreeks omgezet naar store_id. Deze wordt gebruikt om te valideren of het bestand overeenkomt met de geselecteerde store view.
Voorbeeld:
- in het formulier selecteert u een store view met
store_id = 1, - in de CSV moet
store_view_code staan die overeenkomt met deze store view, - de module slaat gegevens op met gebruik van
store_id = 1.
Import Mode
Beschikbare modi:
update werkt bestaande categorieën bij.
insert maakt nieuwe categorieën aan.
CSV File
CSV-bestand met koppen in de eerste rij.
Het bestand moet in UTF-8 zijn gecodeerd.
CSV Delimiter
CSV-scheidingsteken. Dit moet overeenkomen met het scheidingsteken dat in het bestand is gebruikt.
Unknown Columns Policy
Bepaalt het gedrag voor kolommen die geen systeemkolommen en geen bekende categorieattributen zijn.
Beschikbare varianten:
error - de import meldt een fout voor onbekende kolommen.ignore - onbekende kolommen worden genegeerd.
Aanbevolen variant:
error
Empty Values Policy
Bepaalt hoe de module lege CSV-cellen interpreteert.
Beschikbare varianten:
skip_empty,clear_value,use_default.
skip_empty betekent dat een lege cel de huidige waarde niet wijzigt.
clear_value betekent dat een lege cel de attribuutwaarde wist.
use_default betekent dat een lege cel de store view-overschrijving verwijdert en Magento de standaardwaarde laat gebruiken.
Aanbevolen variant voor update-import:
skip_empty
URL Key Strategy
Bepaalt hoe het attribuut url_key wordt verwerkt.
Beschikbare varianten:
use_csv_value,generate_from_name,keep_existing,magento_default.
use_csv_value slaat url_key uit de CSV op.
generate_from_name genereert url_key op basis van de waarde name.
keep_existing behoudt de bestaande url_key in de modus update.
magento_default laat de URL-afhandeling over aan het standaardmechanisme van Magento.
Create permanent redirect for URL key changes
Deze optie bepaalt of Magento een permanent redirect moet aanmaken bij wijziging van url_key.
Het is aan te raden deze in te schakelen wanneer een wijziging van de categorie-URL SEO-redirects vanaf oude adressen moet behouden.
Images Base Directory
Basismap voor het importeren van categorieafbeeldingen ten opzichte van pub/media.
Standaard:
import/categories
Volledig pad in Magento:
pub/media/import/categories
Als u in de CSV opgeeft:
gear/bags.jpg
zoekt de module naar het bestand:
pub/media/import/categories/gear/bags.jpg
Error Policy
Bepaalt het gedrag van de import bij fouten.
Beschikbare varianten:
skip_invalid_rows,stop_on_first_error,all_or_nothing.
skip_invalid_rows slaat foutieve rijen over en gaat door met de import.
stop_on_first_error stopt de import na de eerste fout.
all_or_nothing vereist dat het volledige bestand correct is; als er een fout optreedt, mag de import geen gegevens opslaan.
Aanbevolen variant voor grote bestanden:
skip_invalid_rows
Batch Size
Aantal rijen dat in één batch wordt verwerkt.
Standaard:
100
Een lagere waarde beperkt het geheugengebruik. Een hogere waarde kan de import versnellen op krachtigere omgevingen.
Attributes to Import
Lijst met attributen die moeten worden geïmporteerd.
De import werkt alleen geselecteerde attributen bij. Als een kolom in de CSV bestaat, maar het attribuut niet in het formulier is aangevinkt, mag de module dit niet opslaan.
Dry Run
Validatiemodus zonder gegevens op te slaan.
Het wordt aanbevolen om dry-run uit te voeren vóór de daadwerkelijke import, vooral bij grote bestanden of SEO-wijzigingen.
Modus import/update
De modus update wordt gebruikt om bestaande categorieën bij te werken.
Vereiste gegevens
De CSV moet bevatten:
store_view_code,entity_id of category_path,- minstens één kolom van een geselecteerd attribuut.
Hoe categorie-identificatie werkt
De module probeert de categorie te vinden op basis van:
entity_id,category_path, als entity_id leeg is.
entity_id is de beste identificatie wanneer de import op dezelfde Magento-omgeving plaatsvindt.
category_path is beter overdraagbaar tussen omgevingen, maar moet eenduidig zijn.
Voorbeeld van het bijwerken van vertalingen
store_view_code,entity_id,category_path,name,url_key,meta_title,meta_descriptionpl,13,Default Category/Gear/Bags,Torby,torby,Torby,Torby i akcesoriapl,14,Default Category/Gear/Gloves,Rekawiczki,rekawiczki,Rekawiczki,Rekawiczki sportowe
Importinstellingen:
Store View: Poolse store view,Import Mode: update,Attributes to Import: name, url_key, meta_title, meta_description,URL Key Strategy: use_csv_value,Empty Values Policy: skip_empty,- eerst
Dry Run, daarna de daadwerkelijke import.
Modus import/insert
De modus insert wordt gebruikt om nieuwe categorieën aan te maken.
Vereiste gegevens
De CSV moet bevatten:
store_view_code,category_path,parent_entity_id of parent_path,name,- minstens één kolom van een geselecteerd attribuut.
entity_id is niet vereist, omdat Magento dit automatisch toekent.
Voorbeeld van het aanmaken van categorieën
store_view_code,parent_entity_id,parent_path,category_path,name,url_key,is_active,include_in_menudefault,12,Default Category/Gear,Default Category/Gear/Helmets,Helmets,helmets,1,1default,12,Default Category/Gear,Default Category/Gear/Gloves,Gloves,gloves,1,1
Importinstellingen:
Store View: default store view,Import Mode: insert,Attributes to Import: name, url_key, is_active, include_in_menu,URL Key Strategy: use_csv_value of generate_from_name,Error Policy: skip_invalid_rows,- eerst
Dry Run.
Werken met select en multiselect
De module ondersteunt select en multiselect op basis van optielabels.
Technische optie-ID's hoeven niet te worden opgegeven.
Voorbeeld:
store_view_code,entity_id,category_path,display_mode,available_sort_by,default_sort_bydefault,13,Default Category/Gear/Bags,Products only,Position|Product Name|Price,Position
Voor multiselect worden meerdere waarden gescheiden met het scheidingsteken:
|
Als het label niet bestaat of niet eenduidig is, meldt de import een fout.
Categorieafbeeldingen importeren
Plaats vóór het importeren van afbeeldingen de bestanden in de map:
pub/media/import/categories
CSV-voorbeeld:
store_view_code,entity_id,category_path,image,thumbnaildefault,13,Default Category/Gear/Bags,gear/bags.jpg,gear/bags-thumb.jpg
Importinstellingen:
Images Base Directory: import/categories,- geselecteerde attributen:
image, thumbnail.
De module controleert of de bestanden bestaan en ondersteunde extensies hebben.
Importrapport
Na de import genereert de module een CSV-rapport.
Het rapport bevat:
- rijnummer,
- categorie-ID,
- status,
- bericht,
- gewijzigde attributen.
Statussen kunnen onder andere zijn:
success,error,skipped_no_change,skipped_existing.
Importgeschiedenis
De importgeschiedenis is beschikbaar via:
System > Data Transfer > Export/Import Categories > Import History
De geschiedenis bevat:
- importdatum,
- admin-gebruiker,
- store view,
- importmodus,
- bestandsnaam,
- aantal rijen,
- aantal successen,
- aantal fouten,
- informatie over
dry-run, - downloadlink voor het rapport.
Aanbevolen werkwijze
Veilige update-import
- Exporteer de huidige categorieën.
- Bewaar het originele bestand als backup.
- Bereid de wijzigingen voor in een kopie van de CSV.
- Controleer of
store_view_code overeenkomt met de doel-store view. - Selecteer import
update. - Selecteer alleen de attributen die u wilt wijzigen.
- Zet
Empty Values Policy op skip_empty. - Voer
Dry Run uit. - Controleer het rapport.
- Voer de daadwerkelijke import uit.
- Leeg de cache als de wijzigingen niet direct zichtbaar zijn.
Veilige import van nieuwe categorieën
- Bereid een CSV voor met
category_path, parent_path of parent_entity_id. - Controleer of de oudercategorieën bestaan of eerder in het bestand voorkomen.
- Selecteer import
insert. - Selecteer minimaal
name en andere vereiste attributen. - Voer
Dry Run uit. - Corrigeer de fouten uit het rapport.
- Voer de daadwerkelijke import uit.
Cache en indexen
Na het importeren van categoriewijzigingen is het verstandig de Magento-cache te verversen:
bin/magento cache:clean
Als de winkel na grotere cataloguswijzigingen handmatige herindexering vereist:
bin/magento indexer:reindex
In standaard Magento-installaties zou het opslaan van categorieën via de standaardmechanismen van Magento de juiste processen moeten starten die aan het categoriemodel zijn gekoppeld, maar na grote imports wordt controle van cache en indexen aanbevolen.
Veelvoorkomende problemen
De import meldt een niet-overeenkomende store_view_code
Controleer of de code in de kolom store_view_code overeenkomt met de store view die in het importformulier is geselecteerd.
De import wijzigt geen waarden
Controleer:
- of het attribuut is geselecteerd in
Attributes to Import, - of de CSV-cel niet leeg is,
- of
Empty Values Policy niet is ingesteld op skip_empty, - of de import niet als
Dry Run is uitgevoerd.
Select of multiselect meldt een fout
Controleer of het optielabel in de CSV exact overeenkomt met het optielabel in Magento voor de geselecteerde store view.
De afbeelding wordt niet geïmporteerd
Controleer:
- of het bestand bestaat in
pub/media/import/categories, - of het pad in de CSV correct is,
- of de bestandsextensie wordt ondersteund,
- of het afbeeldingsattribuut voor import is geselecteerd.
Insert meldt dat de oudercategorie ontbreekt
Controleer parent_entity_id of parent_path. De oudercategorie moet in Magento bestaan of eerder in het importbestand staan.
Module verwijderen
Als de module via Composer is geïnstalleerd:
composer remove kowal/module-export-import-categoriesbin/magento setup:upgradebin/magento cache:flush
Controleer vóór het verwijderen of de importgeschiedenis mag worden verwijderd. De module maakt de tabel:
kowal_export_import_categories_history