diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5410688..4794425 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,8 +13,8 @@ jobs: name: mkdocs build --strict runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: '3.x' - run: pip install -r requirements.txt diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index ccd59b7..79a0877 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -18,8 +18,8 @@ jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: '3.x' - run: pip install -r requirements.txt diff --git a/README.md b/README.md index 8b4d3ac..e64ba55 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,21 @@ -# Spreadsheet Importer — Documentation +# Spreadsheet Importer documentation -Combined documentation for the **Spreadsheet Importer** family: +This repository publishes the [Spreadsheet Importer documentation](https://docs.spreadsheet-importer.com/). -- the **[UI5 Spreadsheet Importer](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter)** — - the frontend UI5 custom control, and -- the **server-side ABAP RAP Spreadsheet Importer** — the backend component. +- The [UI5 guide](https://docs.spreadsheet-importer.com/ui5/pages/GettingStarted/) covers version 2.5.0 of the [UI5 Spreadsheet Importer](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter), including installation, configuration and the OData V2 and V4 examples. The Community Edition uses the Apache License 2.0. +- The [ABAP guide](https://docs.spreadsheet-importer.com/abap/) covers the separate server-side RAP importer. -Built with [MkDocs](https://www.mkdocs.org/) + [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), -the same stack as the existing UI5 docs at [docs.spreadsheet-importer.com](https://docs.spreadsheet-importer.com/). +## Build locally -## Structure +From the root of this repository, use Python 3.11 or later. +```sh +python3 -m venv .venv +. .venv/bin/activate +python -m pip install -r requirements.txt +mkdocs serve ``` -docs/ -├── index.md # combined landing — the two-part ecosystem + "which one do I need?" -├── ui5/ # UI5 frontend component -│ └── index.md # overview + map to the live UI5 docs (full integration in progress) -└── abap/ # ABAP backend importer - ├── index.md # overview, requirements, install, quick start - ├── integration-guide.md - ├── public-api-contract.md - └── usage-cookbook.md -``` - -## Status - -- **ABAP backend docs** — added (overview, integration guide, public API contract, usage cookbook), - sanitized for a public site (no links into private/maintainer sources). -- **UI5 frontend docs** — a placeholder + map to the live site for now; full incorporation - (snapshot vs. multi-repo build) is a follow-up. -- **Deploy** — not wired yet. CI runs `mkdocs build --strict` on every push/PR; publishing to a domain - is a follow-up once the domain (vs. the live UI5 docs domain) is decided. -## Local development - -```bash -pip install -r requirements.txt -mkdocs serve # http://localhost:8000 - -# or, matching the UI5 repo's Docker workflow: -docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material -``` +Open to preview changes. Edit UI5 pages in `docs/ui5/pages/`, ABAP pages in `docs/abap/` and navigation in `mkdocs.yml`. -`mkdocs build --strict` must pass (CI enforces it) — it fails on broken internal links and pages -missing from the nav. +Run `mkdocs build --strict` to reproduce the pull request check. Merging to `main` builds the site and publishes it through GitHub Pages. diff --git a/docs/index.md b/docs/index.md index 4c1d862..3adeacf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,12 +19,13 @@ A quick integration tutorial for this component is available on YouTube [here](h !!! tip "Also available: a server-side ABAP importer" Need to import in the **backend** — large files, or straight into a RAP business object? The **[ABAP Spreadsheet Importer](abap/index.md)** parses xlsx/CSV in your S/4HANA / BTP ABAP system and - creates the rows through your own RAP BO via EML. Find it under **Integration → ABAP** in the navigation. + creates the rows through your own RAP BO via EML. Find it under **ABAP (Backend Importer)** in the navigation. ## Feature Overview - Supports upload from List Report/Object Page in Fiori Elements with or without draft - Usable across all Fiori scenarios (Fiori Elements, Freestyle, OpenUI5, V2/V4) +- [Export related records](ui5/pages/spreadsheetdownload.md) and [update existing rows](ui5/pages/Update.md) with OData V2 or V4 - Includes several frontend checks - Capability to download a pre-generated Spreadsheet template - Extension Points for uploading to App or sending to the backend diff --git a/docs/llms.txt b/docs/llms.txt index ff61ee6..6a9dcac 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,34 +2,36 @@ > UI5 component to import spreadsheet data into Fiori/UI5 apps, supporting bulk Excel uploads and optional CAP backend processing. **Notes** -- Works with Fiori Elements and freestyle UI5 apps; backend-agnostic; see repo for license. +- Works with Fiori Elements and freestyle UI5 apps; backend-agnostic. UI5 Spreadsheet Importer 2.5.0 uses Apache 2.0, including for production. - For large workbooks, prefer server-side processing with the CAP CDS Plugin. - Keep `manifest.json` version namespaces aligned with the deployed component. - Issues & updates: https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues ## Quick Start -- [Getting Started](https://docs.spreadsheet-importer.com/pages/GettingStarted/): Install via npm/CDN, set `resourceRoots` and `componentUsages`. -- [Configuration](https://docs.spreadsheet-importer.com/pages/Configuration/): Reference of options with examples and defaults. -- [API Reference](https://docs.spreadsheet-importer.com/pages/APIReference/): Component methods, events, and constructor options. +- [Getting Started](https://docs.spreadsheet-importer.com/ui5/pages/GettingStarted/): Install via npm/CDN, set `resourceRoots` and `componentUsages`. +- [Configuration](https://docs.spreadsheet-importer.com/ui5/pages/Configuration/): Reference of options with examples and defaults. +- [API Reference](https://docs.spreadsheet-importer.com/ui5/pages/APIReference/): Component methods, events, and constructor options. ## Core Features -- [Button Control](https://docs.spreadsheet-importer.com/pages/Button/): Add the importer button and preload configuration. -- [Events](https://docs.spreadsheet-importer.com/pages/Events/): Extension points for validation and data manipulation. -- [Wizard](https://docs.spreadsheet-importer.com/pages/Wizard/): Guided step-by-step import process (v2.2.0+). +- [Button Control](https://docs.spreadsheet-importer.com/ui5/pages/Button/): Add the importer button and preload configuration. +- [Events](https://docs.spreadsheet-importer.com/ui5/pages/Events/): Extension points for validation and data manipulation. +- [Wizard](https://docs.spreadsheet-importer.com/ui5/pages/Wizard/): Guided step-by-step import process (v2.2.0+). ## Deployment & Operations -- [Central Deployment](https://docs.spreadsheet-importer.com/pages/CentralDeployment/): Recommended central deployment to ABAP/BTP systems. -- [Update Operations](https://docs.spreadsheet-importer.com/pages/Update/): Update existing entities instead of creating new ones. -- [Supported Versions](https://docs.spreadsheet-importer.com/pages/SupportVersions/): Compatible UI5 versions and tested scenarios. +- [Central Deployment](https://docs.spreadsheet-importer.com/ui5/pages/CentralDeployment/): Recommended central deployment to ABAP/BTP systems. +- [Update Operations](https://docs.spreadsheet-importer.com/ui5/pages/Update/): Update existing entities instead of creating new ones. +- [Supported Versions](https://docs.spreadsheet-importer.com/ui5/pages/SupportVersions/): Compatible UI5 versions and tested scenarios. ## Backend & Advanced -- [CAP CDS Plugin](https://docs.spreadsheet-importer.com/pages/CdsPlugin/): Upload directly to CAP backend for scalability. -- [Troubleshooting](https://docs.spreadsheet-importer.com/pages/Troubleshooting/): Common errors, diagnostics, debug flags. +- [ABAP RAP importer](https://docs.spreadsheet-importer.com/abap/): Separate server-side component for ABAP systems. +- [OData V2 export and update](https://docs.spreadsheet-importer.com/ui5/pages/Development/ODataV2-ExportAndUpdate/): Implementation and draft handling in 2.5.0. +- [CAP CDS Plugin](https://docs.spreadsheet-importer.com/ui5/pages/CdsPlugin/): Upload directly to CAP backend for scalability. +- [Troubleshooting](https://docs.spreadsheet-importer.com/ui5/pages/Troubleshooting/): Common errors, diagnostics, debug flags. - [GitHub Repository](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter): Source, releases, issues. ## Optional -- [Checks & Validation](https://docs.spreadsheet-importer.com/pages/Checks/): Built-in data validation and error types. -- [Table Selector](https://docs.spreadsheet-importer.com/pages/TableSelector/): Multi-table selection dialog for complex views. -- [Spreadsheet Download](https://docs.spreadsheet-importer.com/pages/spreadsheetdownload/): Export backend data to spreadsheets. -- [Development Guide](https://docs.spreadsheet-importer.com/pages/Development/GettingStarted/): Local dev setup and sample apps. +- [Checks & Validation](https://docs.spreadsheet-importer.com/ui5/pages/Checks/): Built-in data validation and error types. +- [Table Selector](https://docs.spreadsheet-importer.com/ui5/pages/TableSelector/): Multi-table selection dialog for complex views. +- [Spreadsheet Download](https://docs.spreadsheet-importer.com/ui5/pages/spreadsheetdownload/): Export backend data to spreadsheets. +- [Development Guide](https://docs.spreadsheet-importer.com/ui5/pages/Development/GettingStarted/): Local dev setup and sample apps. - [Package on jsDelivr](https://www.jsdelivr.com/package/npm/ui5-cc-spreadsheetimporter): Public package and latest version. diff --git a/docs/ui5/pages/CHANGELOGSPREADSHEETIMPORTER.md b/docs/ui5/pages/CHANGELOGSPREADSHEETIMPORTER.md index 24533ca..17e6738 100644 --- a/docs/ui5/pages/CHANGELOGSPREADSHEETIMPORTER.md +++ b/docs/ui5/pages/CHANGELOGSPREADSHEETIMPORTER.md @@ -1,43 +1,41 @@ ## [2.5.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.4.0...ui5-cc-spreadsheetimporter-v2.5.0) (2026-11-20) - ### License UI5 Spreadsheet Importer 2.5.0 is available under the Apache License 2.0, including for production use. The package includes the license and third-party notices. The UI5 namespace is `cc.spreadsheetimporter.v2_5_0`. ### Features -* export with v2 ([#780](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/780)) ([4962c0f](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/4962c0fca6f86fccbddd483b6bd9d9c720a0621f)) - +- export with v2 ([#780](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/780)) ([4962c0f](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/4962c0fca6f86fccbddd483b6bd9d9c720a0621f)) ### Bug Fixes -* isolate V2 importer writes in a dedicated request group ([#231](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/231)) ([#811](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/811)) ([c59cc03](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/c59cc038ebc11f522473da8095905d76a071cb45)) -* match labelTypeBrackets columns case-insensitively ([#802](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/802)) ([2e15c2f](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/2e15c2ff877f06e18bb9134227cd6dad5298562d)) -* reset only importer-created entities, preserve user's pending changes ([#808](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/808)) ([b73de07](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/b73de070aaca2e478ad405eea498ed250b90ed57)) -* review follow-ups for OData V2 export & update ([#812](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/812)) ([9a30aec](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/9a30aec3b7ba07bf957b3c2bf61d3fe18acd2cd2)) +- isolate V2 importer writes in a dedicated request group ([#231](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/231)) ([#811](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/811)) ([c59cc03](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/c59cc038ebc11f522473da8095905d76a071cb45)) +- match labelTypeBrackets columns case-insensitively ([#802](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/802)) ([2e15c2f](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/2e15c2ff877f06e18bb9134227cd6dad5298562d)) +- reset only importer-created entities, preserve user's pending changes ([#808](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/808)) ([b73de07](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/b73de070aaca2e478ad405eea498ed250b90ed57)) +- review follow-ups for OData V2 export & update ([#812](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/812)) ([9a30aec](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/9a30aec3b7ba07bf957b3c2bf61d3fe18acd2cd2)) -## [2.3.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.2.0...ui5-cc-spreadsheetimporter-v2.3.0) (2025-07-04) +## [2.4.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.3.0...ui5-cc-spreadsheetimporter-v2.4.0) (2025-11-18) ### Features -- introduce pasting data or files to upload dialog ([#778](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/778)) ([10413df](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/10413df13889684b702b508f8d307bbc20496de9)) +- add markers for null and empty values ([#791](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/791)) ([1854fa8](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/1854fa854395465ee2f77676c727bbf42e9a9962)) ### Bug Fixes -- add dragdrop to wizard ([#777](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/777)) ([d2e2244](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/d2e22443f776bbc5d3e28d9ed928f421783fc12a)) -- add template download button to wizard ([#775](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/775)) ([4f1277a](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/4f1277aafd948cf9541c57d075e4cc470e4b694d)) +- handle floatingpoints errors coming from excel ([#789](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/789)) ([0ceb925](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/0ceb9252b8693886f0de75f5502fc5fdfe8d74f6)) +- reset OData model pending changes after backend errors ([#792](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/792)) ([672ea86](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/672ea86ca86e62f0df58c267f9d3323991920dab)) -## [2.4.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.3.0...ui5-cc-spreadsheetimporter-v2.4.0) (2025-11-18) +## [2.3.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.2.0...ui5-cc-spreadsheetimporter-v2.3.0) (2025-07-04) ### Features -- add markers for null and empty values ([#791](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/791)) ([1854fa8](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/1854fa854395465ee2f77676c727bbf42e9a9962)) +- introduce pasting data or files to upload dialog ([#778](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/778)) ([10413df](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/10413df13889684b702b508f8d307bbc20496de9)) ### Bug Fixes -- handle floatingpoints errors coming from excel ([#789](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/789)) ([0ceb925](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/0ceb9252b8693886f0de75f5502fc5fdfe8d74f6)) -- reset OData model pending changes after backend errors ([#792](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/792)) ([672ea86](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/672ea86ca86e62f0df58c267f9d3323991920dab)) +- add dragdrop to wizard ([#777](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/777)) ([d2e2244](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/d2e22443f776bbc5d3e28d9ed928f421783fc12a)) +- add template download button to wizard ([#775](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/775)) ([4f1277a](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/4f1277aafd948cf9541c57d075e4cc470e4b694d)) ## [2.2.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/ui5-cc-spreadsheetimporter-v2.1.0...ui5-cc-spreadsheetimporter-v2.2.0) (2025-07-02) @@ -698,9 +696,9 @@ The package was renamed from `ui5-cc-excelupload` to `ui5-cc-spreadsheetimporter - add Support for OpenUI5 ([#97](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/97)) ([9f1ed6c](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/9f1ed6c471c9d42e70fa265340df7c2dcaaa1ab3)) - including [Sample App for OpenUI5](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/examples/packages/ordersv2freestylenondraftopenui5) and wdi5 Tests - improve checks for all Edm Types ([#105](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/105)) ([dc91ee2](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/dc91ee252e1b9c2d204a1486ff8cf1f13ec3109e)) - - Documentation for the improved Error Handling can be found [here](https://docs.spreadsheet-importer.com/pages/Checks/) + - Documentation for the improved Error Handling can be found [here](https://docs.spreadsheet-importer.com/ui5/pages/Checks/) - improved checks on the data formats and error handling ([#103](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/103)) ([801cfcb](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/801cfcb9b5ed24807144707d03d1db5b0247178e)) - - Improvements for custom error handling. Documentation can be found [here](https://docs.spreadsheet-importer.com/pages/Events/#check-data-before-upload-to-app) + - Improvements for custom error handling. Documentation can be found [here](https://docs.spreadsheet-importer.com/ui5/pages/Events/#event-checkbeforeread) - new automatically translated languages added ([#107](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/107)) ([477e899](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/477e899d0dbd91149b2bad608bc12579e5ef6ac4)) - the english language was automatic translated to following languages: `Chinese`, `French`, `Spanish`, `Italien`, `Hindi`, `Japanese` @@ -775,7 +773,7 @@ The package was renamed from `ui5-cc-excelupload` to `ui5-cc-spreadsheetimporter **Breaking Changes** Changes involving in the manifest and custom code implementation. -See [Documenation](https://docs.spreadsheet-importer.com/pages/GettingStarted/#general-setup) +See [Documenation](https://docs.spreadsheet-importer.com/ui5/pages/GettingStarted/#setup) ### Bug Fixes @@ -796,7 +794,7 @@ See [Documenation](https://docs.spreadsheet-importer.com/pages/GettingStarted/#g ### Features Created compatibility and wdi5 tests for List Report and Object Page in Draft Mode for OData V2 (Versions 108,96,84,71) and OData V4 (Versions 108,96,84) -More info see [Supported Versions](https://docs.spreadsheet-importer.com/pages/SupportVersions/) +More info see [Supported Versions](https://docs.spreadsheet-importer.com/ui5/pages/SupportVersions/) - compatibility/wdi5 tests with v2 FE 96/84/71 ([3f010d9](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/3f010d9a1a360702972552b647f8f20368d72640)) - support for v4 96/84 ([#16](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues/16)) ([109813f](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/109813f8e20acc16d351da04c80b0208b90008c7)) @@ -817,7 +815,7 @@ More info see [Supported Versions](https://docs.spreadsheet-importer.com/pages/S **Breaking Changes** Changes involving in the manifest and custom code implementation. -See [Documenation](https://docs.spreadsheet-importer.com/pages/GettingStarted/#general-setup) +See [Documenation](https://docs.spreadsheet-importer.com/ui5/pages/GettingStarted/#setup) ### Features @@ -874,15 +872,15 @@ See [Documenation](https://docs.spreadsheet-importer.com/pages/GettingStarted/#g - remove wrong apostrophes from string ([b1d31dc](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/commit/b1d31dc52c2f055b3c1b9a74fa7e4a9816de2832)) -## [0.2.0](/compare/v0.1.2...v0.2.0) (2022-11-30) +## [0.2.0](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/v0.1.2...v0.2.0) (2022-11-30) ### Features - check for mandatory fields 0520ada - try get file name from v4 model fa9a349 -## [0.1.2](/compare/v0.1.1...v0.1.2) (2022-11-29) +## [0.1.2](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/v0.1.1...v0.1.2) (2022-11-29) -## [0.1.1](/compare/v0.1.0...v0.1.1) (2022-11-29) +## [0.1.1](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/compare/v0.1.0...v0.1.1) (2022-11-29) # 0.1.0 (2022-11-29) diff --git a/docs/ui5/pages/Development/Docs.md b/docs/ui5/pages/Development/Docs.md index 87efe9b..6e82288 100644 --- a/docs/ui5/pages/Development/Docs.md +++ b/docs/ui5/pages/Development/Docs.md @@ -1,38 +1,7 @@ -## Static Site Generator +# Contributing to the documentation -The documentation is set up with [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). +The [documentation repository](https://github.com/spreadsheetimporter/docs) hosts the public UI5 and ABAP guides. Edit UI5 guides in `docs/ui5/pages/`. Add new pages to the navigation in `mkdocs.yml`. -## Usage +To preview a change, use the [local setup instructions](https://github.com/spreadsheetimporter/docs#build-locally) and run `mkdocs serve`. Run `mkdocs build --strict` before opening a pull request. -### Configuration - -The configuration is in the [`mkdocs.yml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/mkdocs.yml) file. -The pages and images are stored in the [`docs`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/docs) folder. - -### Local Setup - -To run the docs locally, you can use Docker. -To build the Docker image, run: - -```sh -docker build . -t mkdocs -``` - -To run the container: - -```sh -docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material -``` - -or - -```sh -npm run runDocs -``` - -and then open http://localhost:8000. - -### Prod Build - -The Documentation is hosted on GitHub Pages and is rebuilt on every push to the `main` branch using the GitHub Action [`pushDocs.yml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/.github/workflows/pushDocs.yml) and forcefully pushed to the `gh-deploy` branch. -The current URL is: https://docs.spreadsheet-importer.com/ +The [deployment workflow](https://github.com/spreadsheetimporter/docs/blob/main/.github/workflows/deploy.yml) builds the site on pushes to `main` and publishes it from `gh-pages`. diff --git a/docs/ui5/pages/Development/GettingStarted.md b/docs/ui5/pages/Development/GettingStarted.md index 1a6b1f5..7e6a606 100644 --- a/docs/ui5/pages/Development/GettingStarted.md +++ b/docs/ui5/pages/Development/GettingStarted.md @@ -5,43 +5,9 @@ This will take a few minutes. [![Open Stable in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=569313224&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestEurope) -## Local Setup +## Local setup -### Requirements - -- Node.js Versions 16.18.0, 18.12.0, or later - -### Install required NPM Packages - -```sh -# npm is already available by default - -# Install @sap/cds-dk if needed -npm i -g @sap/cds-dk -``` - -### Quick start - -To quickly start the test environment, see here. See detailed information below. - -```sh -git clone https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter -npm install --legacy-peer-deps -# will run `build` and start CAP Server and FE Apps V4 1.108 -npm start -``` - -### Setup `ui5-cc-spreadsheetimporter` - -This is the basic setting-up to continue with the next steps. - -```sh -# Clone GitHub Repo -git clone https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter - -# Install all packages including for test environment -npm install --legacy-peer-deps -``` +Follow [Project setup](ProjectSetup.md#run-a-sample) for the Node.js version, installation command and a working sample. ## Start Developing @@ -70,8 +36,8 @@ This will copy the apps according to this [json file](https://github.com/spreads ```sh # Start Test Apps -npm run start:v4fe:108 -npm run start:v2fe:108 +npm run start:v4fe +npm run start:v2fe # Alternative with npm workspaces npm run start --workspace=ordersv2fe108 @@ -91,7 +57,7 @@ To run the wdi5 tests, the CAP server and the corresponding app must already be You can run the test for the OData V4 UI5 Version 108 with this command: ```sh -npm run test:v4fe:108 +npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv4fe 108 ``` More Info on the [wdi5 Tests](./wdi5.md) site. diff --git a/docs/ui5/pages/Development/GitHubActions.md b/docs/ui5/pages/Development/GitHubActions.md index cf94228..d704db6 100644 --- a/docs/ui5/pages/Development/GitHubActions.md +++ b/docs/ui5/pages/Development/GitHubActions.md @@ -1,10 +1,6 @@ -## Docs +## Documentation -The GitHub Actions `docs` is defined in the [`pushDocs.yml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/.github/workflows/pushDocs.yml) file. -The content of the docs is in the [`docs`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/docs) folder and the config file is [`mkdocs.yml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/mkdocs.yml). - -In an Ubuntu environment, the workflow will set up Python and install `mkdocs-material` and `mkdocs-minify-plugin`. -With `mkdocs gh-deploy --force`, the docs site will be pushed to the `gh-docs` branch and then published with GitHub Pages to https://docs.spreadsheet-importer.com/. +The [documentation repository](https://github.com/spreadsheetimporter/docs) runs a strict MkDocs build on pull requests and publishes the site on pushes to `main`. See [Contributing to the documentation](Docs.md) for local setup and the deployment workflow. ## wdi5 diff --git a/docs/ui5/pages/Development/ODataV2-ExportAndUpdate.md b/docs/ui5/pages/Development/ODataV2-ExportAndUpdate.md new file mode 100644 index 0000000..517e321 --- /dev/null +++ b/docs/ui5/pages/Development/ODataV2-ExportAndUpdate.md @@ -0,0 +1,17 @@ +# OData V2 export and update + +UI5 Spreadsheet Importer 2.5.0 can export related OData V2 records and update them from an edited workbook. For application configuration, see [Deep Download](../spreadsheetdownload.md) and [Update existing records](../Update.md). The [Fiori Elements V2 Object Page example](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/ui5-cc-spreadsheetimporter-v2.5.0/examples/packages/ordersv2fe/webapp/ext/controller/ObjectPageExt.controller.js) shows both operations. + +## Export related records + +1. `MetadataHandlerV2` reads the V2 metamodel for entity keys, labels and navigation properties. `deepDownloadConfig.deepLevel` limits how far the export traverses related entities. +2. `ODataV2` turns the navigation tree into V2 `$expand` paths and reads from the bound entity set. For large results it can request additional pages using `$skip` and `$top`. +3. `DataAssigner` maps the results to worksheets, and `SpreadsheetGenerator` builds the workbook. Set `deepDownloadConfig.addKeysToExport` to `true` if users will upload edits. + +## Update existing rows + +Set `action` to `UPDATE`. The importer uses metadata keys from each row to match it to the backend record. For a draft-enabled Object Page, open the object in edit mode before downloading and uploading. If only the active record exists, the importer reports **Edit mode required** for that row. + +`ODataV2RequestObjects` fetches the matching records and checks their draft state. `ODataV2.updateAsync` uses `ODataModel.createKey` to build the entity path and queues the write in the importer's dedicated request group. In the default partial-update mode, matching values are skipped and `updateConfig.columns` can restrict the fields sent. Setting `fullUpdate` to `true` changes which values are sent. The model's `defaultUpdateMethod` determines the HTTP method. + +The [V2 model handler](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/ui5-cc-spreadsheetimporter-v2.5.0/packages/ui5-cc-spreadsheetimporter/src/controller/odata/ODataV2.ts) contains the read and write paths. The [wdi5 V2 update tests](wdi5.md#v2-update-tests) cover the download, edit, upload and save sequence. diff --git a/docs/ui5/pages/Development/ProjectSetup.md b/docs/ui5/pages/Development/ProjectSetup.md new file mode 100644 index 0000000..1d63513 --- /dev/null +++ b/docs/ui5/pages/Development/ProjectSetup.md @@ -0,0 +1,25 @@ +# UI5 importer project setup + +The [UI5 Spreadsheet Importer repository](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter) contains the maintained Community Edition. The paths below refer to the [2.5.0 release tree](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/ui5-cc-spreadsheetimporter-v2.5.0). + +| Path | What you can change or run | +| --- | --- | +| `packages/ui5-cc-spreadsheetimporter/src/` | The UI5 component, controls, dialogs, translations and OData handlers. Start with `Component.ts` for public settings and events. | +| `packages/ui5-cc-spreadsheetimporter/test/unit/` | Jest tests for parsing, metadata, OData requests and validation. | +| `examples/packages/` | Fiori Elements and freestyle sample applications for OData V2 and V4. | +| `examples/packages/server/` | The CAP service used by the sample applications. | +| `examples/test/` | wdi5 browser tests and shared test workbooks. | +| `dev/testapps.json` | App variants, UI5 versions and ports used for testing. | + +## Run a sample + +Use Node.js 22 and npm. From a fresh checkout, install the workspaces and start the CAP server and the default Fiori Elements V4 app. + +```sh +git clone https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter +cd ui5-cc-spreadsheetimporter +npm ci --legacy-peer-deps +npm start +``` + +To try the V2 app instead, run `npm run start:server` in one terminal and `npm run start:v2fe` in another. Run `npm run test:unit --workspace=ui5-cc-spreadsheetimporter` for the component unit tests. See [wdi5 tests](wdi5.md) for browser testing and [Contributing to the documentation](Docs.md) to update the public guides. diff --git a/docs/ui5/pages/Development/SpreadsheetDownload.md b/docs/ui5/pages/Development/SpreadsheetDownload.md index fe1ae92..b39f391 100644 --- a/docs/ui5/pages/Development/SpreadsheetDownload.md +++ b/docs/ui5/pages/Development/SpreadsheetDownload.md @@ -1,6 +1,6 @@ # Deep Download Feature -This feature is experimental and only available with an OData V4 backend. It allows downloading data from OData V4 backends with support for nested entities and relationships, handling complex data structures efficiently. +Deep download exports related entities into a workbook. This page describes the OData V4 implementation. For the OData V2 implementation introduced in 2.5.0, see [OData V2 export and update](ODataV2-ExportAndUpdate.md). ## Triggering the Download diff --git a/docs/ui5/pages/Development/Update.md b/docs/ui5/pages/Development/Update.md index 10b9fa9..0281fdc 100644 --- a/docs/ui5/pages/Development/Update.md +++ b/docs/ui5/pages/Development/Update.md @@ -1,4 +1,4 @@ -Only V4 is supported for now. +This page describes OData V4 draft handling. For V2 support in 2.5.0, see [OData V2 export and update](ODataV2-ExportAndUpdate.md). ## OData V4 diff --git a/docs/ui5/pages/Development/wdi5.md b/docs/ui5/pages/Development/wdi5.md index f8bf87d..849fa24 100644 --- a/docs/ui5/pages/Development/wdi5.md +++ b/docs/ui5/pages/Development/wdi5.md @@ -4,26 +4,73 @@ The overview of which scenarios are covered by wdi5 tests can be found here: [wd ## Setup -wdi5 is used in the test setup in the [`examples`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/examples) folder in the [`test`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/examples/test) folder. +wdi5 is used in the test setup in the [`examples`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/examples) folder in the [`test`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/tree/main/examples/test) folder. As npm workspaces is used, with `npm install --legacy-peer-deps`, all the packages, including `wdio-ui5-service`, are installed. ### Configuration -The basic config file is the `wdio-base.conf.js` file. -To avoid having to create a separate configuration file for each scenario, logic is integrated into the file so that the appropriate variables are automatically drawn, for example the port or the appropriate spec files. +The basic config file is the `wdio-base.conf.js` file. +To avoid having to create a separate configuration file for each scenario, logic is integrated into the file so that the appropriate variables are automatically drawn, for example the port or the appropriate spec files. The data for this is stored in the [`testapps.json`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/dev/testapps.json) file. +#### How `wdio-base.conf.js` works + +The config file receives the scenario name and UI5 version as command-line arguments (e.g., `ordersv2fe 136`). It then: + +1. Looks up the scenario in `testapps.json` via `util.getTestappObject(scenario, version)` +2. Extracts the **port** and **spec file patterns** from the mapping +3. Constructs the `baseUrl` as `http://localhost:{port}/index.html?sap-language=EN` +4. Configures Chrome with appropriate window size and download directory + +#### How `testapps.json` works + +Each entry in `testapps.json` defines: + +- `rootAppName` — scenario identifier (e.g., `ordersv2fe`, `ordersv4fe`) +- `port` — the port the UI5 app runs on for the default version +- `testMapping.specs` — array of glob patterns pointing to test spec files +- `copyVersions` — array of alternative UI5 versions, each with their own port and optional spec overrides + +Example: `ordersv2fe` at version 136 maps to port 8081 and runs specs from `../test/specs/all/**.test.js` and `../test/specs/updatev2/**.test.js`. + +### Test Object Helpers + +Located in `examples/test/specs/Objects/`: + +| File | Purpose | +| --------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `Base.js` | Browser control utilities: `getControlById()`, `pressById()`, `dummyWait()` | +| `BaseUpload.js` | Reusable file upload helper — opens dialog, removes block layer, makes file input visible, sets file path, clicks upload | +| `FEV2.js` | OData V2 Fiori Elements control selectors and IDs (list report, object page, tables) | +| `FEV4.js` | OData V4 Fiori Elements control selectors and IDs | +| `FEV2ND.js` | Non-draft V2 variant selectors | +| `types.js` | Shared test option constants | + +### Test Data Files + +Located in `examples/test/testFiles/`: + +- Various `.xlsx` and `.csv` files for different test scenarios +- Files with errors, no errors, format variations, decimal separators +- Separate CSV subdirectories for comma/dot decimal formats + ## Run tests -You can run the tests for OData V2 and V4 UI5 Version 108 in the root folder with: +You can run the tests for OData V2 and V4 with the default UI5 version (136) from the root folder: + +```sh +npm run test:v4fe +npm run test:v2fe +``` + +Or with a specific UI5 version: ```sh -npm run test:v4fe:108 -npm run test:v2fe:108 +npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv4fe 108 +npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv2fe 108 ``` -which will run `npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv4fe 108`. -So, you can run all the other apps like +Use the same workspace command with another app name and UI5 minor version, for example ```sh npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv4fe 84 @@ -31,7 +78,7 @@ npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- ordersv4fe 84 ### Run single spec -You can also run single test specs. You need to go to the `examples` folder for this. +You can also run single test specs. You need to go to the `examples` folder for this. For example, you can run the test spec `OpenSpreadsheetUploadDialog` with OData V2 FE UI5 Version 96 with: ```sh @@ -46,8 +93,62 @@ The wdi5 tests in GitHub Actions must run headless, which is also possible to ca npm run test --workspace=ui5-cc-spreadsheetimporter-sample -- -- --headless ordersv4fe 84 ``` +### Watch mode + +Watch mode reruns tests automatically when source or test files change: + +```sh +cd examples +npm run test -- ordersv4fe 136 --watch +``` + +In watch mode: + +- Only 1 browser instance runs (vs 5 in normal mode) for stability +- File changes in `test/specs/` and `packages/ui5-cc-spreadsheetimporter/src/` are monitored +- Each test result is printed with pass/fail indicators + +### Debug mode + +Debug mode opens Chrome DevTools automatically and extends timeouts: + +```sh +cd examples +npm run test -- ordersv4fe 136 --debug +``` + +Connection timeout is extended to 20 minutes in debug mode to allow stepping through breakpoints. + +## V2 Update Tests + +The `updatev2/` test directory contains tests for the OData V2 deep download and mass update feature: + +**Flow:** + +1. Set entity to draft state via V4 API (CAP's cov2ap adapter translates) +2. Navigate to V2 draft object page +3. Trigger deep download → verify XLSX file created +4. Modify spreadsheet data (update quantities) +5. Upload modified file via mass update dialog +6. Save/activate draft +7. Verify updated data via API + +**Prerequisites:** CAP server must be running on port 4004, and the V2 FE app on its mapped port. + +## Unit Tests (Jest) + +In addition to wdi5 E2E tests, there are unit tests for the core library logic using Jest. + +```sh +npm run test:unit --workspace=ui5-cc-spreadsheetimporter +``` + +Unit tests are located in `packages/ui5-cc-spreadsheetimporter/test/unit/` and test pure logic like entity matching, draft validation, and error handling without requiring a running server. + +See the [Jest config](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/packages/ui5-cc-spreadsheetimporter/jest.config.js) for module mapping details. SAP UI5 modules are mocked in `test/unit/__mocks__/sap/`. + ## GitHub Actions As specified in the [`testapps.json`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/dev/testapps.json) file, the GitHub Action Workflow will run on every Pull Request push, testing scenarios with all current UI5 Maintenance Versions and is written in [`wdi5-test.yml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/.github/workflows/wdi5-test.yml). -More info at [GitHub Actions](./../Development/GitHubActions.md) +More info at [GitHub Actions](GitHubActions.md) diff --git a/docs/ui5/pages/GettingStarted.md b/docs/ui5/pages/GettingStarted.md index 81b93e4..0be2532 100644 --- a/docs/ui5/pages/GettingStarted.md +++ b/docs/ui5/pages/GettingStarted.md @@ -12,7 +12,7 @@ We recommend different deployment approaches depending on your platform: - **For ABAP systems**: Only **centralized deployment** is possible. Decentralized deployment is not supported for ABAP systems. - **For SAP Business Technology Platform (BTP)**: **Decentralized deployment** is recommended, though centralized deployment is also possible. -For decentralized deployment in ABAP, refer to [ABAP Component Deployment](#component-deployment). For BTP deployment, special considerations are necessary, which are detailed in [BTP Deployment](#btp-deployment). A full BTP deployment example is available in this [sample project](https://github.com/spreadsheetimporter/sample-full-btp). +For decentralized deployment in ABAP, refer to [ABAP Component Deployment](#component-deployment). For BTP deployment, special considerations are necessary, which are detailed in [BTP Deployment](#btp-environment). A full BTP deployment example is available in this [sample project](https://github.com/spreadsheetimporter/sample-full-btp). ### Decentralized Deployment @@ -26,7 +26,7 @@ For decentralized deployment in ABAP, refer to [ABAP Component Deployment](#comp For BTP applications, decentralized deployment is the recommended approach. -In decentralized deployment, the component is included directly in each app and deployed with it. For ABAP-specific instructions, refer to [ABAP Component Deployment](#component-deployment). For BTP-specific considerations, refer to [BTP Deployment](#btp-deployment). +In decentralized deployment, the component is included directly in each app and deployed with it. For ABAP-specific instructions, refer to [ABAP Component Deployment](#component-deployment). For BTP-specific considerations, refer to [BTP Deployment](#btp-environment). ### Central Deployment @@ -323,7 +323,7 @@ openSpreadsheetUploadDialog: async function (event) { These instructions apply generally to UI5 Reuse Components, not just the Spreadsheet Importer (see [UI5 Reuse Components](https://sapui5.hana.ondemand.com/sdk/#/topic/6314fcd2510648fbaad3cee8a421030d.html)). -When deploying the component decentrally to an ABAP system, its namespace is registered in the app index, just as it is with central deployment. After deploying decentrally for the first time, you can use the component centrally (see [Setup Central Deployment](#setup-central-deployment)). However, you can only deploy the component decentrally once because the namespace can only exist once in the app index. +When deploying the component decentrally to an ABAP system, its namespace is registered in the app index, just as it is with central deployment. After deploying decentrally for the first time, you can use the component centrally (see [Setup Central Deployment](#setup-for-central-deployment)). However, you can only deploy the component decentrally once because the namespace can only exist once in the app index. This is why we recommend starting with central deployment. @@ -475,7 +475,7 @@ builder: configuration: archiveName: uimodule includeDependencies: - - ui5-cc-spreadsheetimporter-v2-4-0 + - ui5-cc-spreadsheetimporter-v2-5-0 ``` The metadata name is defined in the [`ui5.yaml`](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/9b61a778e5b0a5b66c15f5889334a6d684ae88de/packages/ui5-cc-spreadsheetimporter/ui5.yaml#L4) file of the component. diff --git a/docs/ui5/pages/Pro/deepcreate.md b/docs/ui5/pages/Pro/deepcreate.md index 5e441f7..90e64d6 100644 --- a/docs/ui5/pages/Pro/deepcreate.md +++ b/docs/ui5/pages/Pro/deepcreate.md @@ -1,3 +1,7 @@ +# Legacy Pro deep create + +This page describes the historical Pro package. For operations supported in the current Community Edition, see the [API reference](../APIReference.md). + With this feature, you are able to upload a spreadsheet to create multiple entities and their relations. ## Configuration diff --git a/docs/ui5/pages/Pro/install.md b/docs/ui5/pages/Pro/install.md index b001d6b..de2442c 100644 --- a/docs/ui5/pages/Pro/install.md +++ b/docs/ui5/pages/Pro/install.md @@ -1,70 +1,9 @@ -# Installing npm Package from GitHub +# Installing the Community Edition -To install the `@spreadsheetimporter/ui5-cc-spreadsheetimporter-pro` package directly from a GitHub repository, you'll need a personal access token from GitHub and configure npm to use it. Below are the steps: +The maintained UI5 Spreadsheet Importer is available from the public npm registry. Version 2.5.0 includes production use under the Apache License 2.0. -## 1. Be a member of the GitHub organization [``](https://github.com/) - -1. After purchasing the Spreadsheet Importer package, you'll receive an invitation to join the GitHub organization. -2. If you did not receive an invitation, please contact us at [marian@marianzeis.de](mailto:marian@marianzeis.de). - -## 2. Generating a Personal Access Token on GitHub - -1. Navigate to **GitHub** and log in. -2. Click on your profile picture (top right) and choose **Settings**. -3. In the left sidebar, click on **Developer settings**. -4. Choose **Personal access tokens** from the left sidebar. -5. Click **Generate new token**. -6. Provide a descriptive name for the token in the **Note** field. -7. Under **scopes**, select the `repo` and `read:packages` checkboxes to allow access to private repositories and packages. -8. Click **Generate token**. -9. Copy the generated token. **Note**: This is your only chance to copy the token. If lost, you'll have to create a new one. - -## 3. Configuring npm with `.npmrc` - -More Information: [Configuring npm for use with GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) - -You can either set up a project-specific `.npmrc` file or edit the global `~/.npmrc`. - -### For Project-specific Configuration - -1. Go to your project directory. -2. Create or open the `.npmrc` file. - -``` -@spreadsheetimporter:registry=https://npm.pkg.github.com -//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN -``` - -Replace YOUR_PERSONAL_ACCESS_TOKEN with the token you generated in step 2. - -Now you can install the package: - -```bash -npm install @spreadsheetimporter/ui5-cc-spreadsheetimporter-pro +```sh +npm install --save-exact ui5-cc-spreadsheetimporter@2.5.0 ``` -### For Global Configuration - -1. Open the `~/.npmrc` file. -2. Add the following line: - -``` -@spreadsheetimporter:registry=https://npm.pkg.github.com -``` - -3. Save the file. - -Now you can install the package: - -```bash -npm install @spreadsheetimporter/ui5-cc-spreadsheetimporter-pro -``` - -## 4. Using the Package - -Now you can start using the package in your project. -For more information, please refer to the [Getting Started Page](./../GettingStarted.md). - -The documentation for pro features is here: - -- [Spreadsheet Download](../spreadsheetdownload.md) +Continue with the [installation and namespace setup](../GettingStarted.md#setup-for-decentralized-deployment). For previously published versions, see the [license history](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/main/LICENSE.md). diff --git a/docs/ui5/pages/SupportVersions.md b/docs/ui5/pages/SupportVersions.md index 5f874e5..9ffb48c 100644 --- a/docs/ui5/pages/SupportVersions.md +++ b/docs/ui5/pages/SupportVersions.md @@ -33,6 +33,11 @@ Here is an overview of the apps that were created and used for the tests. ## wdi5 Tests + +!!! info "Automated CI version set" + To keep CI fast and stable, the wdi5 suite runs against a representative version set — **1.136** (newest default), **1.120** (the Fiori Elements metadata divergence) and **1.71** (lowest supported) — across the Fiori Elements apps and the freestyle harness apps (`ordersv2freestylenondraft`, `ordersv4freestyle`). The intermediate versions in the tables below are bracketed by 1.120/1.71 and remain supported; the checkmarks reflect the versions that have passed wdi5. + + ### CAP V2 | UI5 Version | List Report Draft | List Report Non Draft | Object Page Draft | Object Page Non Draft | Freestyle | OpenUI5 Freestyle | diff --git a/docs/ui5/pages/Update.md b/docs/ui5/pages/Update.md index 24fd0ea..9adc593 100644 --- a/docs/ui5/pages/Update.md +++ b/docs/ui5/pages/Update.md @@ -1,11 +1,7 @@ - - -!!! warning - This feature is available since version 1.7.0 and currently experimental and may not work as expected. - Also only available for OData V4. - Please provide feedback: https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/issues +# Update existing records - +!!! note "Availability" + UPDATE is experimental. It became available for OData V4 in 1.7.0. Version 2.5.0 adds OData V2, including draft-enabled entities. ## Usage @@ -51,11 +47,14 @@ By default, only the changed properties are updated (partial update). You can ch ## How it works When you upload the file to the App, it will do the usual checks if the columns are in the data model and the data is valid (see [Checks](./Checks.md)). -When the user presses the upload button, it will fetch all the data in the batch. To make sure all the data is fetched, it will fetch the data for active and draft separately. So for every batch a ListBinding is created and two requests are made with filters for the keys and for `IsActiveEntity = true` and `IsActiveEntity = false`. This is needed because of the separation of active and draft (see [why requests fail in CAP with OData draft enabled](https://cap.cloud.sap/docs/get-started/troubleshooting#why-do-some-requests-fail-if-i-set-odata-draft-enabled-on-my-entity)). +The importer reads the matching backend records by key before it writes changes. For draft-enabled entities it checks active and draft records separately. It uses these results to report missing rows, select the correct draft and skip unchanged values in a partial update. -This data is used to determine if the object is in draft or active mode, if the object exists at all, and for partial updates whether a field is changed. +OData V4 uses a context binding for each change. OData V2 builds the entity path from its metadata keys and sends updates through a dedicated request group. For a working Fiori Elements V2 example, see the [Object Page controller](https://github.com/spreadsheetimporter/ui5-cc-spreadsheetimporter/blob/ui5-cc-spreadsheetimporter-v2.5.0/examples/packages/ordersv2fe/webapp/ext/controller/ObjectPageExt.controller.js). -For every change, an `ODataContextBinding` is created and the data is updated. + +!!! note "Draft-enabled entities on OData V2: edit mode required" + A draft-enabled entity can only be changed through its draft. If a row matches an **active** record that has **no draft in progress** (the object is in display mode), the importer cannot modify it directly — it reports an *"Edit mode required"* message for that row and skips it. Open the object in edit mode first (which creates the draft), then download, edit and upload the data from that edit-mode state. You can also bind a custom action's `enabled` to the edit state (e.g. `"enabled": "{ui>/isEditable}"`) to disable Mass Update outside edit mode — see [Getting Started](./GettingStarted.md). + ### Setting Values to NULL or Empty String @@ -74,8 +73,8 @@ When updating data, you may need to explicitly clear a field or set it to an emp | ID | Name | Email | Phone | Notes | | --- | ------------ | --------- | -------- | --------- | | 123 | | | 555-1234 | | -| 456 | John Updated | **NULL** | | **EMPTY** | -| 789 | | **EMPTY** | | Follow up | +| 456 | John Updated | `__NULL__` | | `__EMPTY__` | +| 789 | | `__EMPTY__` | | Follow up | - Record 123: Only phone is updated, all other fields unchanged - Record 456: Name updated, email set to NULL, notes set to empty string "", phone unchanged diff --git a/docs/ui5/pages/spreadsheetdownload.md b/docs/ui5/pages/spreadsheetdownload.md index fccc0c3..54c4b9d 100644 --- a/docs/ui5/pages/spreadsheetdownload.md +++ b/docs/ui5/pages/spreadsheetdownload.md @@ -1,10 +1,7 @@ # Spreadsheet Deep Download - -!!! warning - This new feature is available since version 1.5.0 and experimental and may change in the future and currently only available for OData V4. - If you deep download data, the OData Service need to support `expand`. - +!!! note "Availability" + Deep download is experimental. It became available for OData V4 in 1.5.0. Version 2.5.0 adds OData V2. To export related entities, the service must support `$expand`. This feature downloads data from the backend and converts it to a Spreadsheet file. @@ -28,7 +25,7 @@ This means that you can download all Orders, including the OrderItems, ShippingI | `filename` | Defines the filename for the export file | Entity Name | string | | `deepExport` | Turn on to export of sibling entities | `false` | boolean | | `deepLevel` | Defines the level of sibling entities to export | `0` | number | -| `showOptions` | Shows options dialog for users | `false` | boolean | +| `showOptions` | Shows options dialog for users | `true` | boolean | | `columns` | Defines the columns to export | `{}` | object or array | ### Sample Usage diff --git a/mkdocs.yml b/mkdocs.yml index 0d9458e..689a7a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: UI5 Custom Control Spreadsheet Upload +site_name: Spreadsheet Importer site_url: https://docs.spreadsheet-importer.com/ site_description: >- Documentation for the Spreadsheet Importer — the UI5 frontend custom control @@ -48,6 +48,8 @@ nav: - Use Cases: ui5/pages/UseCases.md - Development: - Getting Started: ui5/pages/Development/GettingStarted.md + - Project setup: ui5/pages/Development/ProjectSetup.md + - OData V2 export and update: ui5/pages/Development/ODataV2-ExportAndUpdate.md - Testing: - wdi5 Tests: ui5/pages/Development/wdi5.md - OPA5 Tests: ui5/pages/Development/opa5.md @@ -96,6 +98,41 @@ extra_javascript: plugins: - search + - redirects: + redirect_maps: + pages/APIReference.md: ui5/pages/APIReference.md + pages/Button.md: ui5/pages/Button.md + pages/CHANGELOGSPREADSHEETIMPORTER.md: ui5/pages/CHANGELOGSPREADSHEETIMPORTER.md + pages/CdsPlugin.md: ui5/pages/CdsPlugin.md + pages/CentralDeployment.md: ui5/pages/CentralDeployment.md + pages/Checks.md: ui5/pages/Checks.md + pages/Configuration.md: ui5/pages/Configuration.md + pages/Development/Docs.md: ui5/pages/Development/Docs.md + pages/Development/GettingStarted.md: ui5/pages/Development/GettingStarted.md + pages/Development/GitHubActions.md: ui5/pages/Development/GitHubActions.md + pages/Development/ODataV2-ExportAndUpdate.md: ui5/pages/Development/ODataV2-ExportAndUpdate.md + pages/Development/PrettierAndCommitlint.md: ui5/pages/Development/PrettierAndCommitlint.md + pages/Development/ProjectSetup.md: ui5/pages/Development/ProjectSetup.md + pages/Development/SampleApps.md: ui5/pages/Development/SampleApps.md + pages/Development/SpreadsheetDownload.md: ui5/pages/Development/SpreadsheetDownload.md + pages/Development/Update.md: ui5/pages/Development/Update.md + pages/Development/opa5.md: ui5/pages/Development/opa5.md + pages/Development/wdi5.md: ui5/pages/Development/wdi5.md + pages/Events.md: ui5/pages/Events.md + pages/GettingStarted.md: ui5/pages/GettingStarted.md + pages/HowItWorks.md: ui5/pages/HowItWorks.md + pages/NullHandling.md: ui5/pages/NullHandling.md + pages/Pro/deepcreate.md: ui5/pages/Pro/deepcreate.md + pages/Pro/install.md: ui5/pages/Pro/install.md + pages/SupportVersions.md: ui5/pages/SupportVersions.md + pages/TableSelector.md: ui5/pages/TableSelector.md + pages/Troubleshooting.md: ui5/pages/Troubleshooting.md + pages/Typescript.md: ui5/pages/Typescript.md + pages/Update.md: ui5/pages/Update.md + pages/UseCases.md: ui5/pages/UseCases.md + pages/UserDocumentation.md: ui5/pages/UserDocumentation.md + pages/Wizard.md: ui5/pages/Wizard.md + pages/spreadsheetdownload.md: ui5/pages/spreadsheetdownload.md - minify: minify_html: true diff --git a/requirements.txt b/requirements.txt index b194c65..5c740a7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,4 @@ -mkdocs-material>=9.5 -mkdocs-minify-plugin>=0.8 +mkdocs==1.6.1 +mkdocs-material==9.8.2 +mkdocs-minify-plugin==0.8.0 +mkdocs-redirects==1.2.3