From 6aa59263867daddd6e5b12df1d342207beb3f067 Mon Sep 17 00:00:00 2001 From: Muhammad Muqarrab Date: Wed, 7 May 2025 17:35:48 +0500 Subject: [PATCH] Update Merger and Annotation tutorials --- .github/workflows/annotation-production.yml | 69 +++ .github/workflows/annotation-staging.yml | 69 +++ .github/workflows/merger-production.yml | 69 +++ .github/workflows/merger-staging.yml | 69 +++ config/annotation/_default/config.toml | 150 +++++ config/annotation/production/config.toml | 9 + config/annotation/staging/config.toml | 8 + config/merger/_default/config.toml | 150 +++++ config/merger/production/config.toml | 9 + config/merger/staging/config.toml | 8 + content/annotation/english/_index.md | 136 ++++ .../advanced-data-structures/_index.md | 40 ++ .../annotateoptions/_index.md | 174 ++++++ .../annotationapilink/_index.md | 168 +++++ .../annotationinfo/_index.md | 172 +++++ .../fileinfo/_index.md | 142 +++++ .../previewoptions/_index.md | 184 ++++++ .../removeoptions/_index.md | 167 +++++ .../english/advanced-features/_index.md | 58 ++ .../area-annotation/_index.md | 322 ++++++++++ .../arrow-annotation/_index.md | 339 ++++++++++ .../delete-annotations/_index.md | 318 ++++++++++ .../delete-document-pages/_index.md | 263 ++++++++ .../distance-annotation/_index.md | 341 ++++++++++ .../ellipse-annotation/_index.md | 352 +++++++++++ .../extract-annotations/_index.md | 368 +++++++++++ .../get-document-pages/_index.md | 426 +++++++++++++ .../image-annotation/_index.md | 338 ++++++++++ .../multiple-annotations/_index.md | 425 +++++++++++++ .../text-redaction/_index.md | 324 ++++++++++ .../english/getting-started/_index.md | 57 ++ .../getting-started/add-annotations/_index.md | 343 ++++++++++ .../convert-documents/_index.md | 367 +++++++++++ .../delete-annotations/_index.md | 344 ++++++++++ .../extract-annotations/_index.md | 410 ++++++++++++ .../get-document-information/_index.md | 230 +++++++ .../get-supported-file-formats/_index.md | 178 ++++++ .../preview-documents/_index.md | 380 ++++++++++++ content/home/english/_index.md | 4 +- content/merger/english/_index.md | 106 ++++ .../english/document-management/_index.md | 74 +++ .../generate-document-pages-preview/_index.md | 395 ++++++++++++ .../import-attachment/_index.md | 286 +++++++++ .../join-document-cross-format/_index.md | 305 +++++++++ .../document-management/join-images/_index.md | 378 +++++++++++ .../join-multiple-documents/_index.md | 288 +++++++++ .../join-word-continuous/_index.md | 322 ++++++++++ .../split-document/_index.md | 403 ++++++++++++ .../merger/english/getting_started/_index.md | 72 +++ .../get_document_information/_index.md | 299 +++++++++ .../get_supported_file_formats/_index.md | 338 ++++++++++ .../working_with_files/_index.md | 585 ++++++++++++++++++ .../working_with_folder/_index.md | 584 +++++++++++++++++ .../merger/english/page-processes/_index.md | 58 ++ .../change-page-orientation/_index.md | 264 ++++++++ .../page-processes/extract-pages/_index.md | 246 ++++++++ .../page-processes/move-pages/_index.md | 244 ++++++++ .../page-processes/remove-pages/_index.md | 248 ++++++++ .../page-processes/rotate-pages/_index.md | 265 ++++++++ .../page-processes/swap-pages/_index.md | 215 +++++++ 60 files changed, 13953 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/annotation-production.yml create mode 100644 .github/workflows/annotation-staging.yml create mode 100644 .github/workflows/merger-production.yml create mode 100644 .github/workflows/merger-staging.yml create mode 100644 config/annotation/_default/config.toml create mode 100644 config/annotation/production/config.toml create mode 100644 config/annotation/staging/config.toml create mode 100644 config/merger/_default/config.toml create mode 100644 config/merger/production/config.toml create mode 100644 config/merger/staging/config.toml create mode 100644 content/annotation/english/_index.md create mode 100644 content/annotation/english/advanced-data-structures/_index.md create mode 100644 content/annotation/english/advanced-data-structures/annotateoptions/_index.md create mode 100644 content/annotation/english/advanced-data-structures/annotationapilink/_index.md create mode 100644 content/annotation/english/advanced-data-structures/annotationinfo/_index.md create mode 100644 content/annotation/english/advanced-data-structures/fileinfo/_index.md create mode 100644 content/annotation/english/advanced-data-structures/previewoptions/_index.md create mode 100644 content/annotation/english/advanced-data-structures/removeoptions/_index.md create mode 100644 content/annotation/english/advanced-features/_index.md create mode 100644 content/annotation/english/advanced-features/area-annotation/_index.md create mode 100644 content/annotation/english/advanced-features/arrow-annotation/_index.md create mode 100644 content/annotation/english/advanced-features/delete-annotations/_index.md create mode 100644 content/annotation/english/advanced-features/delete-document-pages/_index.md create mode 100644 content/annotation/english/advanced-features/distance-annotation/_index.md create mode 100644 content/annotation/english/advanced-features/ellipse-annotation/_index.md create mode 100644 content/annotation/english/advanced-features/extract-annotations/_index.md create mode 100644 content/annotation/english/advanced-features/get-document-pages/_index.md create mode 100644 content/annotation/english/advanced-features/image-annotation/_index.md create mode 100644 content/annotation/english/advanced-features/multiple-annotations/_index.md create mode 100644 content/annotation/english/advanced-features/text-redaction/_index.md create mode 100644 content/annotation/english/getting-started/_index.md create mode 100644 content/annotation/english/getting-started/add-annotations/_index.md create mode 100644 content/annotation/english/getting-started/convert-documents/_index.md create mode 100644 content/annotation/english/getting-started/delete-annotations/_index.md create mode 100644 content/annotation/english/getting-started/extract-annotations/_index.md create mode 100644 content/annotation/english/getting-started/get-document-information/_index.md create mode 100644 content/annotation/english/getting-started/get-supported-file-formats/_index.md create mode 100644 content/annotation/english/getting-started/preview-documents/_index.md create mode 100644 content/merger/english/_index.md create mode 100644 content/merger/english/document-management/_index.md create mode 100644 content/merger/english/document-management/generate-document-pages-preview/_index.md create mode 100644 content/merger/english/document-management/import-attachment/_index.md create mode 100644 content/merger/english/document-management/join-document-cross-format/_index.md create mode 100644 content/merger/english/document-management/join-images/_index.md create mode 100644 content/merger/english/document-management/join-multiple-documents/_index.md create mode 100644 content/merger/english/document-management/join-word-continuous/_index.md create mode 100644 content/merger/english/document-management/split-document/_index.md create mode 100644 content/merger/english/getting_started/_index.md create mode 100644 content/merger/english/getting_started/get_document_information/_index.md create mode 100644 content/merger/english/getting_started/get_supported_file_formats/_index.md create mode 100644 content/merger/english/getting_started/working_with_files/_index.md create mode 100644 content/merger/english/getting_started/working_with_folder/_index.md create mode 100644 content/merger/english/page-processes/_index.md create mode 100644 content/merger/english/page-processes/change-page-orientation/_index.md create mode 100644 content/merger/english/page-processes/extract-pages/_index.md create mode 100644 content/merger/english/page-processes/move-pages/_index.md create mode 100644 content/merger/english/page-processes/remove-pages/_index.md create mode 100644 content/merger/english/page-processes/rotate-pages/_index.md create mode 100644 content/merger/english/page-processes/swap-pages/_index.md diff --git a/.github/workflows/annotation-production.yml b/.github/workflows/annotation-production.yml new file mode 100644 index 0000000..70b664d --- /dev/null +++ b/.github/workflows/annotation-production.yml @@ -0,0 +1,69 @@ +# This is a basic workflow to help you get started with Actions + +name: tutorials.groupdocs.cloud(annotation)(family)(Production) + +# Controls when the action will run. +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ master ] + paths: + - 'content/annotation/**' + pull_request: + branches: [ master ] + paths: + - 'content/annotation/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of annotation that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Checkout theme repo + uses: actions/checkout@main + with: + repository: groupdocs-cloud/tutorials-theme + token: ${{ secrets.REPO_TOKEN }} + fetch-depth: 0 + path: themes/tutorials-theme + # Step 2 - Sets up the latest version of Hugo + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.135.0' + extended: true + - name: Install Dependicies1 + run: npm install -D --save autoprefixer + - name: Install Dependicies2 + run: npm install -D --save postcss-cli + # Also specifies the theme we want to use + - name: Build + run: hugo --configDir config/annotation --environment production --minify + + - name: Deploy tutorials.groupdocs.cloud(annotation)(family)(Production) to S3 + run: hugo --configDir config/annotation --environment production deploy --target "Production" --maxDeletes 0 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} + # Invalidate Cloudfront + - name: invalidate + uses: chetan/invalidate-cloudfront-action@v2 + env: + DISTRIBUTION: ${{ secrets.AWS_DISTRIBUTION_PROD }} + PATHS: /annotation/* + AWS_REGION: 'us-west-2' + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} diff --git a/.github/workflows/annotation-staging.yml b/.github/workflows/annotation-staging.yml new file mode 100644 index 0000000..1ea7ea3 --- /dev/null +++ b/.github/workflows/annotation-staging.yml @@ -0,0 +1,69 @@ +# This is a basic workflow to help you get started with Actions + +name: qa-tutorials.groupdocs.cloud(annotation)(family)(Stage) + +# Controls when the action will run. +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ staging ] + paths: + - 'content/annotation/**' + pull_request: + branches: [ staging ] + paths: + - 'content/annotation/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of annotation that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Checkout theme repo + uses: actions/checkout@main + with: + repository: groupdocs-cloud/tutorials-theme + token: ${{ secrets.REPO_TOKEN }} + fetch-depth: 0 + path: themes/tutorials-theme + # Step 2 - Sets up the latest version of Hugo + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.135.0' + extended: true + - name: Install Dependicies1 + run: npm install -D --save autoprefixer + - name: Install Dependicies2 + run: npm install -D --save postcss-cli + # Also specifies the theme we want to use + - name: Build + run: hugo --configDir config/annotation --environment staging --minify + + - name: Deploy qa-tutorials.groupdocs.cloud(annotation)(family)(Stage) to S3 + run: hugo --configDir config/annotation --environment staging deploy --target "Stage" --maxDeletes 0 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} + # Invalidate Cloudfront + - name: invalidate + uses: chetan/invalidate-cloudfront-action@v2 + env: + DISTRIBUTION: ${{ secrets.AWS_DISTRIBUTION }} + PATHS: /annotation/* + AWS_REGION: 'us-west-2' + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} diff --git a/.github/workflows/merger-production.yml b/.github/workflows/merger-production.yml new file mode 100644 index 0000000..7130255 --- /dev/null +++ b/.github/workflows/merger-production.yml @@ -0,0 +1,69 @@ +# This is a basic workflow to help you get started with Actions + +name: tutorials.groupdocs.cloud(merger)(family)(Production) + +# Controls when the action will run. +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ master ] + paths: + - 'content/merger/**' + pull_request: + branches: [ master ] + paths: + - 'content/merger/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of merger that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Checkout theme repo + uses: actions/checkout@main + with: + repository: groupdocs-cloud/tutorials-theme + token: ${{ secrets.REPO_TOKEN }} + fetch-depth: 0 + path: themes/tutorials-theme + # Step 2 - Sets up the latest version of Hugo + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.135.0' + extended: true + - name: Install Dependicies1 + run: npm install -D --save autoprefixer + - name: Install Dependicies2 + run: npm install -D --save postcss-cli + # Also specifies the theme we want to use + - name: Build + run: hugo --configDir config/merger --environment production --minify + + - name: Deploy tutorials.groupdocs.cloud(merger)(family)(Production) to S3 + run: hugo --configDir config/merger --environment production deploy --target "Production" --maxDeletes 0 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} + # Invalidate Cloudfront + - name: invalidate + uses: chetan/invalidate-cloudfront-action@v2 + env: + DISTRIBUTION: ${{ secrets.AWS_DISTRIBUTION_PROD }} + PATHS: /merger/* + AWS_REGION: 'us-west-2' + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} diff --git a/.github/workflows/merger-staging.yml b/.github/workflows/merger-staging.yml new file mode 100644 index 0000000..14a1613 --- /dev/null +++ b/.github/workflows/merger-staging.yml @@ -0,0 +1,69 @@ +# This is a basic workflow to help you get started with Actions + +name: qa-tutorials.groupdocs.cloud(merger)(family)(Stage) + +# Controls when the action will run. +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ staging ] + paths: + - 'content/merger/**' + pull_request: + branches: [ staging ] + paths: + - 'content/merger/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of merger that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Checkout theme repo + uses: actions/checkout@main + with: + repository: groupdocs-cloud/tutorials-theme + token: ${{ secrets.REPO_TOKEN }} + fetch-depth: 0 + path: themes/tutorials-theme + # Step 2 - Sets up the latest version of Hugo + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.135.0' + extended: true + - name: Install Dependicies1 + run: npm install -D --save autoprefixer + - name: Install Dependicies2 + run: npm install -D --save postcss-cli + # Also specifies the theme we want to use + - name: Build + run: hugo --configDir config/merger --environment staging --minify + + - name: Deploy qa-tutorials.groupdocs.cloud(merger)(family)(Stage) to S3 + run: hugo --configDir config/merger --environment staging deploy --target "Stage" --maxDeletes 0 + env: + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} + # Invalidate Cloudfront + - name: invalidate + uses: chetan/invalidate-cloudfront-action@v2 + env: + DISTRIBUTION: ${{ secrets.AWS_DISTRIBUTION }} + PATHS: /merger/* + AWS_REGION: 'us-west-2' + AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }} diff --git a/config/annotation/_default/config.toml b/config/annotation/_default/config.toml new file mode 100644 index 0000000..7a435c3 --- /dev/null +++ b/config/annotation/_default/config.toml @@ -0,0 +1,150 @@ +baseURL = "/annotation" +title = "GroupDocs Cloud Tutorials" +staticdir = 'content/static' +enableRobotsTXT = true +enableGitInfo = true +disableKinds = ["taxonomy", "taxonomyTerm", "page", "RSS"] + +# Hugo allows theme composition (and inheritance). The precedence is from left to right. +theme = ["tutorials-theme"] + +[params.menu] +zh = "groupdocscloud-zh" +ru = "groupdocscloud-ru" +ar = "groupdocscloud-ar" +cs = "groupdocscloud-cs" +de = "groupdocscloud-de" +el = "groupdocscloud-el" +es = "groupdocscloud-es" +fr = "groupdocscloud-fr" +hi = "groupdocscloud-hi" +hu = "groupdocscloud-hu" +id = "groupdocscloud-id" +it = "groupdocscloud-it" +ja = "groupdocscloud-ja" +ko = "groupdocscloud-ko" +nl = "groupdocscloud-nl" +pl = "groupdocscloud-pl" +pt = "groupdocscloud-pt" +sv = "groupdocscloud-sv" +th = "groupdocscloud-th" +tr = "groupdocscloud-tr" +vi = "groupdocscloud-vi" +zh-hant = "groupdocscloud-zht" + +defaultContentLang = 'en' +[languages] + [languages.en] + contentDir = 'content/annotation/english' + languageName = 'English' + languageCode = "en" + flag = "flag-us" + weight = 10 + +ignoreFiles = ["(?i:readme.md)", '\.spin$'] + +# Image processing configuration. +[imaging] +resampleFilter = "CatmullRom" +quality = 75 +anchor = "smart" + +[services] +[services.googleAnalytics] +# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback]. +# id = "UA-00000000-0" + +[markup] + [markup.tableOfContents] + endLevel = 2 + ordered = true + startLevel = 2 + [markup.goldmark] + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + anchorLineNos = false + codeFences = true + guessSyntax = false + hl_Lines = "" + lineAnchors = "" + lineNoStart = 1 + lineNos = false + lineNumbersInTable = true + noClasses = false + tabWidth = 4 + +# Everything below this are Site Params + +[params] +copyright = "The GroupDocs Cloud Authors" +privacy_policy = "https://policies.google.com/privacy" +topbar_search_active = false +logo_rel_link = "" + +# Containerize Menu +[params.containerize] +menu = "groupdocscloud-en" + +[params.meta] +msapplication_TileColor = "#2b5797" +msapplication_config = "https://cms.admin.containerize.com/templates/groupdocscloud/images/browserconfig.xml" +theme_color = "#ffffff" +author = "GroupDocs Cloud" + +# Title of 404 page +title_404_page = "404 - Page Not Found | GroupDocs Cloud Tutorials" + +# Open Grapgh settings +title = "GroupDocs Cloud Tutorials" +images = ["images/aspose-cloud-image-for-open-graph.jpg"] +description = "REST APIs along with open-source SDKs that allow developers to enhance applications with the capability to display, annotate, convert, e-sign, merge, classify, compare & translate documents in the Cloud" + + +# Set to true to disable breadcrumb navigation. +breadcrumb_disable = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = true +# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar +navbar_logo = false +# Set to true to disable the About link in the site footer +footer_about_disable = false + + +[minify] + disableCSS = false + disableHTML = false + disableJS = false + disableJSON = false + disableSVG = false + disableXML = false + minifyOutput = true + [minify.tdewolff] + [minify.tdewolff.css] + decimals = -1 + keepCSS2 = true + [minify.tdewolff.html] + keepConditionalComments = true + keepDefaultAttrVals = true + keepDocumentTags = true + keepEndTags = true + keepQuotes = false + keepWhitespace = false + [minify.tdewolff.js] + [minify.tdewolff.json] + [minify.tdewolff.svg] + decimals = -1 + [minify.tdewolff.xml] + keepWhitespace = false + +[Taxonomies] + +[deployment] +[[deployment.matchers]] +# Set custom content type for /sitemap.xml +#pattern = "^sitemap\\.xml$" +#pattern = "^[a-z]\\.xml$" +pattern = "^.+\\.(xml)$" +contentType = "application/xml" +gzip = true +force = true diff --git a/config/annotation/production/config.toml b/config/annotation/production/config.toml new file mode 100644 index 0000000..4a345d3 --- /dev/null +++ b/config/annotation/production/config.toml @@ -0,0 +1,9 @@ +baseURL = "https://tutorials.groupdocs.cloud/annotation" + +# Google Tag Manager settings +[params.gtm] +gtm_id = "GTM-T42TVBC" + +[[deployment.targets]] +name = "Production" +URL = "s3://tutorials.groupdocs.cloud/?prefix=annotation/®ion=us-west-2" diff --git a/config/annotation/staging/config.toml b/config/annotation/staging/config.toml new file mode 100644 index 0000000..e12da7a --- /dev/null +++ b/config/annotation/staging/config.toml @@ -0,0 +1,8 @@ +baseURL = "https://qa-tutorials.groupdocs.cloud/annotation" + +[[deployment.targets]] +name = "Stage" +URL = "s3://qa-tutorials.groupdocs.cloud/?prefix=annotation /®ion=us-west-2" + + + diff --git a/config/merger/_default/config.toml b/config/merger/_default/config.toml new file mode 100644 index 0000000..edeb8d2 --- /dev/null +++ b/config/merger/_default/config.toml @@ -0,0 +1,150 @@ +baseURL = "/merger" +title = "GroupDocs Cloud Tutorials" +staticdir = 'content/static' +enableRobotsTXT = true +enableGitInfo = true +disableKinds = ["taxonomy", "taxonomyTerm", "page", "RSS"] + +# Hugo allows theme composition (and inheritance). The precedence is from left to right. +theme = ["tutorials-theme"] + +[params.menu] +zh = "groupdocscloud-zh" +ru = "groupdocscloud-ru" +ar = "groupdocscloud-ar" +cs = "groupdocscloud-cs" +de = "groupdocscloud-de" +el = "groupdocscloud-el" +es = "groupdocscloud-es" +fr = "groupdocscloud-fr" +hi = "groupdocscloud-hi" +hu = "groupdocscloud-hu" +id = "groupdocscloud-id" +it = "groupdocscloud-it" +ja = "groupdocscloud-ja" +ko = "groupdocscloud-ko" +nl = "groupdocscloud-nl" +pl = "groupdocscloud-pl" +pt = "groupdocscloud-pt" +sv = "groupdocscloud-sv" +th = "groupdocscloud-th" +tr = "groupdocscloud-tr" +vi = "groupdocscloud-vi" +zh-hant = "groupdocscloud-zht" + +defaultContentLang = 'en' +[languages] + [languages.en] + contentDir = 'content/merger/english' + languageName = 'English' + languageCode = "en" + flag = "flag-us" + weight = 10 + +ignoreFiles = ["(?i:readme.md)", '\.spin$'] + +# Image processing configuration. +[imaging] +resampleFilter = "CatmullRom" +quality = 75 +anchor = "smart" + +[services] +[services.googleAnalytics] +# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback]. +# id = "UA-00000000-0" + +[markup] + [markup.tableOfContents] + endLevel = 2 + ordered = true + startLevel = 2 + [markup.goldmark] + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + anchorLineNos = false + codeFences = true + guessSyntax = false + hl_Lines = "" + lineAnchors = "" + lineNoStart = 1 + lineNos = false + lineNumbersInTable = true + noClasses = false + tabWidth = 4 + +# Everything below this are Site Params + +[params] +copyright = "The GroupDocs Cloud Authors" +privacy_policy = "https://policies.google.com/privacy" +topbar_search_active = false +logo_rel_link = "" + +# Containerize Menu +[params.containerize] +menu = "groupdocscloud-en" + +[params.meta] +msapplication_TileColor = "#2b5797" +msapplication_config = "https://cms.admin.containerize.com/templates/groupdocscloud/images/browserconfig.xml" +theme_color = "#ffffff" +author = "GroupDocs Cloud" + +# Title of 404 page +title_404_page = "404 - Page Not Found | GroupDocs Cloud Tutorials" + +# Open Grapgh settings +title = "GroupDocs Cloud Tutorials" +images = ["images/aspose-cloud-image-for-open-graph.jpg"] +description = "REST APIs along with open-source SDKs that allow developers to enhance applications with the capability to display, annotate, convert, e-sign, merge, classify, compare & translate documents in the Cloud" + + +# Set to true to disable breadcrumb navigation. +breadcrumb_disable = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = true +# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar +navbar_logo = false +# Set to true to disable the About link in the site footer +footer_about_disable = false + + +[minify] + disableCSS = false + disableHTML = false + disableJS = false + disableJSON = false + disableSVG = false + disableXML = false + minifyOutput = true + [minify.tdewolff] + [minify.tdewolff.css] + decimals = -1 + keepCSS2 = true + [minify.tdewolff.html] + keepConditionalComments = true + keepDefaultAttrVals = true + keepDocumentTags = true + keepEndTags = true + keepQuotes = false + keepWhitespace = false + [minify.tdewolff.js] + [minify.tdewolff.json] + [minify.tdewolff.svg] + decimals = -1 + [minify.tdewolff.xml] + keepWhitespace = false + +[Taxonomies] + +[deployment] +[[deployment.matchers]] +# Set custom content type for /sitemap.xml +#pattern = "^sitemap\\.xml$" +#pattern = "^[a-z]\\.xml$" +pattern = "^.+\\.(xml)$" +contentType = "application/xml" +gzip = true +force = true diff --git a/config/merger/production/config.toml b/config/merger/production/config.toml new file mode 100644 index 0000000..27ea607 --- /dev/null +++ b/config/merger/production/config.toml @@ -0,0 +1,9 @@ +baseURL = "https://tutorials.groupdocs.cloud/merger" + +# Google Tag Manager settings +[params.gtm] +gtm_id = "GTM-T42TVBC" + +[[deployment.targets]] +name = "Production" +URL = "s3://tutorials.groupdocs.cloud/?prefix=merger/®ion=us-west-2" diff --git a/config/merger/staging/config.toml b/config/merger/staging/config.toml new file mode 100644 index 0000000..db9ea54 --- /dev/null +++ b/config/merger/staging/config.toml @@ -0,0 +1,8 @@ +baseURL = "https://qa-tutorials.groupdocs.cloud/merger" + +[[deployment.targets]] +name = "Stage" +URL = "s3://qa-tutorials.groupdocs.cloud/?prefix=merger /®ion=us-west-2" + + + diff --git a/content/annotation/english/_index.md b/content/annotation/english/_index.md new file mode 100644 index 0000000..d773ca3 --- /dev/null +++ b/content/annotation/english/_index.md @@ -0,0 +1,136 @@ +--- + +title: GroupDocs.Annotation Cloud Implementation & Best Practices +weight: 2 +url: /annotation/ +description: Comprehensive resource for integrating GroupDocs.Annotation Cloud API, covering authentication, document workflows, annotation types, and practical integration tips. +--- + +# GroupDocs.Annotation Cloud Tutorials + +Welcome to the GroupDocs.Annotation Cloud tutorials. This comprehensive resource provides all the information you need to integrate powerful document annotation capabilities into your applications. + +## Overview + +GroupDocs.Annotation Cloud is a versatile REST API that enables you to add, edit, and manage annotations across various document formats including PDF, Microsoft Office documents, images, CAD drawings, and more. This guide will walk you through the implementation process step by step. + +## Getting Started + +### [Getting Started Tutorials](/annotation/getting-started/) + +Step-by-step tutorials to help developers get started with GroupDocs.Annotation Cloud API + +### [Advanced Features Tutorials](/annotation/advanced-features/) + +Step-by-step tutorials for advanced document annotation features using GroupDocs.Annotation Cloud API - learn how to add, customize, and manage annotations in your documents. + +### [Document Advanced Data Structures Tutorials](/annotation/advanced-data-structures/) + +Learn how to effectively work with advanced data structures in GroupDocs.Annotation Cloud API through our hands-on tutorials. + +### Requirements + +- A GroupDocs.Annotation Cloud account +- API credentials (Client ID and Client Secret) +- Basic understanding of REST API concepts +- Familiarity with your preferred programming language + +### Authentication + +Before using GroupDocs.Annotation Cloud API, you need to authenticate your requests: + +``` +// Example authentication code +string clientId = "YOUR_CLIENT_ID"; +string clientSecret = "YOUR_CLIENT_SECRET"; +var configuration = new Configuration(clientId, clientSecret); +var apiInstance = new AnnotateApi(configuration); +``` + +## Core Concepts + +### Document Handling + +The API allows you to: +- Upload documents for annotation +- Convert between formats when necessary +- Manage document versions +- Control document permissions + +## Implementation Guide + +### Basic Workflow + +1. Authenticate to the API +2. Upload or access an existing document +3. Add or modify annotations +4. Save changes +5. Generate annotated output + +### Code Examples + +#### Adding a Text Annotation + +```csharp +// Example code for adding a text annotation +var options = new AnnotationInfo +{ + Box = new Rectangle(100, 100, 200, 30), + PageNumber = 0, + Type = AnnotationType.Text, + Text = "This is a text annotation" +}; + +var request = new AddAnnotationsRequest(filename, options); +var response = apiInstance.AddAnnotations(request); +``` + +## Best Practices + +- Cache authentication tokens to reduce API calls +- Process large documents in chunks +- Implement proper error handling +- Use webhooks for asynchronous processing +- Optimize annotation rendering for mobile devices + +## Troubleshooting + +Common issues and solutions: + +- Authentication failures +- Format compatibility problems +- Performance optimizations +- Error response interpretation + +## API Reference + +For a complete list of endpoints and parameters, refer to the [API Reference](annotation/api-reference) section. + +## SDK Integration + +GroupDocs.Annotation Cloud offers SDKs for popular programming languages: + +- .NET +- Java +- PHP +- Node.js +- Python +- Ruby + +## Advanced Topics + +- Custom annotation styles +- Annotation permissions and user roles +- Batch processing +- Event-driven architecture +- Integration with document management systems + +## Support Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-data-structures/_index.md b/content/annotation/english/advanced-data-structures/_index.md new file mode 100644 index 0000000..644cd2d --- /dev/null +++ b/content/annotation/english/advanced-data-structures/_index.md @@ -0,0 +1,40 @@ +--- +title: GroupDocs.Annotation Cloud API Document Advanced Data Structures Tutorials +weight: 4 +url: /advanced-data-structures/ +description: Learn how to effectively work with advanced data structures in GroupDocs.Annotation Cloud API through our hands-on tutorials. +--- + +# GroupDocs.Annotation Cloud API Document Advanced Data Structures Tutorials + +Welcome to our hands-on tutorial series for developers working with GroupDocs.Annotation Cloud API's advanced data structures. This comprehensive learning path will guide you from basic concepts to advanced implementations, helping you master document annotation capabilities in your applications. + +## Learning Path + +Our tutorials are organized to build your knowledge progressively, from fundamental data structures to complex implementations: + +- [Tutorial: Learn to Work with FileInfo Structure](/advanced-data-structures/fileinfo/) - Master the essential structure for specifying input files with this beginner-friendly guide + +- [Tutorial: How to Implement AnnotationInfo in Your Applications](/advanced-data-structures/annotationinfo/) - Discover the powerful annotation properties structure with step-by-step instructions + +- [Tutorial: Working with AnnotateOptions for Document Processing](/advanced-data-structures/annotateoptions/) - Learn to define comprehensive options for annotating documents + +- [Tutorial: Implementing RemoveOptions in Your Annotation Workflow](/advanced-data-structures/removeoptions/) - Master the process of configuring annotation removal with practical examples + +- [Tutorial: Creating Document Previews with PreviewOptions](/advanced-data-structures/previewoptions/) - Step-by-step guide to generating document previews with customizable settings + +- [Tutorial: Working with AnnotationApiLink for Output File Management](/advanced-data-structures/annotationapilink/) - Learn to effectively handle output file links in your annotation projects + +## Helpful Resources + +To support your learning journey, we recommend the following resources: + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about these tutorials? Feel free to post them on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/). diff --git a/content/annotation/english/advanced-data-structures/annotateoptions/_index.md b/content/annotation/english/advanced-data-structures/annotateoptions/_index.md new file mode 100644 index 0000000..bfca2dd --- /dev/null +++ b/content/annotation/english/advanced-data-structures/annotateoptions/_index.md @@ -0,0 +1,174 @@ +--- +title: Working with AnnotateOptions for Document Processing Tutorial +weight: 3 +url: /advanced-data-structures/annotateoptions/ +description: This hands-on tutorial teaches developers how to effectively implement AnnotateOptions to control document annotation behavior in GroupDocs.Annotation Cloud +--- + +# Tutorial: Working with AnnotateOptions for Document Processing + +## Learning Objectives + +In this tutorial, you'll learn: +- The purpose and structure of the AnnotateOptions object +- How to configure document annotation settings +- Controlling page selection for annotation processing +- Managing output file paths and storage locations +- Best practices for real-world implementation + +## Prerequisites + +Before starting this tutorial, ensure you have: +- Completed our [FileInfo Structure Tutorial](/advanced-data-structures/fileinfo/) +- Familiarity with [AnnotationInfo Structure](/advanced-data-structures/annotationinfo/) +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is AnnotateOptions? + +AnnotateOptions is a crucial structure in GroupDocs.Annotation Cloud that defines how document annotation operations should be performed. It allows you to specify: + +- Input file information +- Annotations to be added +- Page range selection +- Output file configuration +- Processing optimization settings + +## Step 1: Understanding the AnnotateOptions Structure + +The AnnotateOptions structure contains these important fields: + +| Field | Description | Required | +|---|---|---| +| FileInfo | Input file path and password | Yes | +| Annotations | Array of annotations to add to the document | Yes (for annotation operations) | +| FirstPage | First page to annotate | No | +| LastPage | Last page to annotate | No | +| OnlyAnnotatedPages | Whether to save only annotated pages | No (default: false) | +| OutputPath | Path of output document | Yes | + +Let's examine a basic AnnotateOptions JSON example: + +```json +{ + "FileInfo": { + "FilePath": "documents/sample.pdf", + "Password": "p@ssw0rd" + }, + "Annotations": [], + "FirstPage": 1, + "LastPage": 5, + "OnlyAnnotatedPages": true, + "OutputPath": "documents/annotated/output.pdf" +} +``` + +## Step 2: Creating a Basic AnnotateOptions Instance + +Let's implement a simple AnnotateOptions configuration: + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Working with Page Selection + +AnnotateOptions allows fine-grained control over which pages are processed: + +### Processing Specific Page Ranges + + + +### Try it yourself + +1. Create an AnnotateOptions instance that processes only pages 5-10 of a document +2. Add text annotations to pages 6 and 8 +3. Configure the output to include only the annotated pages + +## Step 4: Managing Output Configuration + +Proper output configuration ensures your annotated documents are stored correctly: + +### Custom Output Path Configuration + + + +## Step 5: Optimizing Document Processing + +For large documents, performance optimization is crucial: + +### Optimizing for Large Documents + + + +### Learning Checkpoint + +Test your understanding of AnnotateOptions optimization: + +1. When should you use the OnlyAnnotatedPages option? +2. How can you optimize performance when annotating specific sections of a large document? +3. What considerations should you make when setting output paths for batch processing? + +## Troubleshooting Common Issues + +When working with AnnotateOptions, you might encounter these common issues: + +1. Invalid Page Range + - Ensure FirstPage and LastPage values are within document boundaries + - Check that FirstPage is less than or equal to LastPage + +2. Output Path Problems + - Verify the output directory exists and is writable + - Ensure the output filename has a valid extension + - Check storage permissions for the output location + +3. Annotation Array Issues + - Confirm the Annotations array is properly formatted + - Verify all AnnotationInfo objects are valid + - Check for potential JSON formatting errors in large annotation collections + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the AnnotateOptions object +- How to create and configure AnnotateOptions instances +- Working with page selection for targeted processing +- Managing output file paths and storage locations +- Optimizing document processing for better performance +- Troubleshooting common implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a batch annotation process that handles multiple documents with different page ranges +2. Implement a function that validates AnnotateOptions parameters before submission +3. Build a system that dynamically determines optimal page selection based on document size + +## Next Steps + +Now that you've mastered the AnnotateOptions structure, continue your learning journey with our [Tutorial: Implementing RemoveOptions in Your Annotation Workflow](/advanced-data-structures/removeoptions/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Post them on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/). diff --git a/content/annotation/english/advanced-data-structures/annotationapilink/_index.md b/content/annotation/english/advanced-data-structures/annotationapilink/_index.md new file mode 100644 index 0000000..aee4512 --- /dev/null +++ b/content/annotation/english/advanced-data-structures/annotationapilink/_index.md @@ -0,0 +1,168 @@ +--- +title: Working with AnnotationApiLink for Output File Management Tutorial +weight: 6 +url: /advanced-data-structures/annotationapilink/ +description: Learn how to effectively utilize the AnnotationApiLink structure to manage output files in GroupDocs.Annotation Cloud API +--- + +# Tutorial: Working with AnnotationApiLink for Output File Management + +## Learning Objectives + +In this tutorial, you'll learn: +- The purpose and structure of the AnnotationApiLink object +- How to interpret and utilize file download URLs +- Working with file naming and types +- Best practices for implementing file management with AnnotationApiLink +- Common use cases for AnnotationApiLink in applications + +## Prerequisites + +Before starting this tutorial, ensure you have: +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is AnnotationApiLink? + +AnnotationApiLink is a simple yet important data structure in GroupDocs.Annotation Cloud that describes output file links. When you perform operations like adding annotations or generating previews, the API returns information about the resulting files using the AnnotationApiLink structure. + +This structure allows you to: +- Access download URLs for processed files +- Identify file types and names +- Manage file relationships in complex workflows + +## Step 1: Understanding the AnnotationApiLink Structure + +The AnnotationApiLink structure contains these important fields: + +| Field | Description | Purpose | +|---|---|---| +| Href | File download URL | Provides direct access to the output file | +| Rel | Reserved field | For future use | +| Type | Reserved field | For future use | +| Title | File name | Identifies the output file | + +Let's examine a typical AnnotationApiLink JSON response: + +```json +{ + "Href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/output.pdf", + "Rel": "self", + "Type": "application/pdf", + "Title": "output.pdf" +} +``` + +## Step 2: Retrieving AnnotationApiLink Responses + +Let's see how AnnotationApiLink objects are returned in API responses: + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Working with File Download URLs + +The most important field in AnnotationApiLink is the Href, which provides the download URL: + +### Downloading Files Using AnnotationApiLink + + + +### Try it yourself + +1. Implement a function that takes an AnnotationApiLink object and downloads the file to a local directory +2. Add error handling for network and file system operations +3. Test your function with different file types (PDF, DOCX, images) + +## Step 4: Implementing File Management Workflows + +AnnotationApiLink can be integrated into complete file management workflows: + +### File Management Workflow + + + +## Step 5: Real-World Use Cases + +Let's explore practical applications of AnnotationApiLink in real-world scenarios: + +### Document Collaboration System + + + +### Learning Checkpoint + +Test your understanding of AnnotationApiLink implementation: + +1. How would you use AnnotationApiLink to implement a document version control system? +2. What security considerations should you keep in mind when working with download URLs? +3. How would you handle file naming conflicts in a multi-user environment? + +## Troubleshooting Common Issues + +When working with AnnotationApiLink, you might encounter these common issues: + +1. URL Expiration + - Download URLs may have limited validity periods + - Implement retry logic for expired URLs + - Consider immediately downloading and caching important files + +2. Network Issues + - Handle network timeouts and interruptions gracefully + - Implement progressive or resumable downloads for large files + - Add appropriate error messaging for network-related failures + +3. File Processing Errors + - Verify file integrity after download + - Implement appropriate error handling for malformed files + - Consider implementing file format validation + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the AnnotationApiLink object +- How to interpret and utilize file download URLs +- Working with file naming and types +- Implementing complete file management workflows +- Real-world applications of AnnotationApiLink +- Troubleshooting common implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a file caching system that stores downloaded files locally +2. Implement a file verification system that checks file integrity after download +3. Build a document management UI that displays files retrieved via AnnotationApiLink + +## Next Steps + +Congratulations! You've completed our tutorial series on GroupDocs.Annotation Cloud API Advanced Data Structures. You now have a comprehensive understanding of the key data structures used in the API. + +To continue your learning journey, explore these additional resources: +- [API Reference Documentation](https://reference.groupdocs.cloud/annotation/) +- [GroupDocs.Annotation Cloud Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Post them on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/). diff --git a/content/annotation/english/advanced-data-structures/annotationinfo/_index.md b/content/annotation/english/advanced-data-structures/annotationinfo/_index.md new file mode 100644 index 0000000..91952e4 --- /dev/null +++ b/content/annotation/english/advanced-data-structures/annotationinfo/_index.md @@ -0,0 +1,172 @@ +--- +title: How to Implement AnnotationInfo in Your Applications Tutorial +weight: 2 +url: /advanced-data-structures/annotationinfo/ +description: Learn to master the AnnotationInfo structure to create powerful document annotations in GroupDocs.Annotation Cloud API +--- + +# Tutorial: How to Implement AnnotationInfo in Your Applications + +## Learning Objectives + +In this tutorial, you'll learn: +- The purpose and structure of the AnnotationInfo object +- How to configure different types of annotations +- Working with annotation positioning, styling, and metadata +- Managing annotation replies +- Best practices for implementing AnnotationInfo in real-world scenarios + +## Prerequisites + +Before starting this tutorial, ensure you have: +- Completed our [FileInfo Structure Tutorial](/advanced-data-structures/fileinfo/) +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is AnnotationInfo? + +AnnotationInfo is a comprehensive data structure in GroupDocs.Annotation Cloud that describes all properties of an annotation. It allows you to define: + +- Annotation type and content +- Positioning information +- Visual styling properties +- Creator metadata +- Threaded replies +- Creation timestamp + +## Step 1: Understanding the AnnotationInfo Structure + +The AnnotationInfo structure contains numerous fields to accommodate various annotation types and properties: + +| Category | Key Fields | Description | +|---|---|---| +| Identification | Id, Type | Core identification information | +| Content | Text, TextToReplace | The annotation's text content | +| Creator | CreatorId, CreatorName, CreatorEmail | Information about who created the annotation | +| Positioning | Box, Points, PageNumber, AnnotationPosition, SvgPath | Where and how the annotation is positioned | +| Styling | FontColor, PenColor, PenWidth, BackgroundColor, FontFamily, FontSize, Opacity, Angle | Visual appearance properties | +| Interaction | Replies, Url, ImagePath | Additional interactive elements | +| Metadata | CreatedOn | When the annotation was created | + +## Step 2: Creating a Basic Text Annotation + +Let's start with implementing a simple text annotation using AnnotationInfo: + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Working with Different Annotation Types + +GroupDocs.Annotation Cloud supports various annotation types, each requiring specific configuration: + +### Area Annotation + +Area annotations highlight rectangular regions of a document: + + + +### Point Annotation + +Point annotations mark specific points in a document: + + + +### Polyline Annotation + +Polyline annotations create custom shapes with connected lines: + + + +### Try it yourself + +1. Create an AnnotationInfo instance for a text highlight annotation +2. Configure it with a yellow background color at 50% opacity +3. Position it on page 2 of a document + +## Step 4: Managing Annotation Replies + +AnnotationInfo supports threaded replies, enabling collaborative document review: + + + +### Learning Checkpoint + +Test your understanding of the AnnotationReplyInfo structure: + +1. What fields are required when creating a new reply? +2. How would you create a reply to an existing reply (nested reply)? +3. How can you retrieve all replies for a specific annotation? + +## Step 5: Advanced Styling and Positioning + +Fine-tuning the visual presentation of annotations enhances document clarity: + +### Styling Text Annotations + + + +### Precise Annotation Positioning + + + +## Troubleshooting Common Issues + +When working with AnnotationInfo, you might encounter these common issues: + +1. Invalid Annotation Type + - Ensure the annotation Type field contains a valid value + - Verify required fields for the specific annotation type are provided + +2. Positioning Problems + - Check that coordinates are within document boundaries + - For point-based annotations, ensure all required points are specified + +3. Reply Linking Issues + - Verify that ParentReplyId references an existing reply + - Ensure reply IDs are unique within the annotation + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the AnnotationInfo object +- How to create different types of annotations +- Configuring annotation appearance and positioning +- Working with threaded replies +- Troubleshooting common AnnotationInfo implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a multi-page document with different annotation types on each page +2. Implement a collaborative annotation system with threaded replies +3. Create a function that generates consistent styling across multiple annotations + +## Next Steps + +Now that you've mastered the AnnotationInfo structure, continue your learning journey with our [Tutorial: Working with AnnotateOptions for Document Processing](/advanced-data-structures/annotateoptions/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Post them on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/). diff --git a/content/annotation/english/advanced-data-structures/fileinfo/_index.md b/content/annotation/english/advanced-data-structures/fileinfo/_index.md new file mode 100644 index 0000000..40ad757 --- /dev/null +++ b/content/annotation/english/advanced-data-structures/fileinfo/_index.md @@ -0,0 +1,142 @@ +--- +title: Learn to Work with FileInfo Structure in GroupDocs.Annotation Cloud Tutorial +weight: 1 +url: /advanced-data-structures/fileinfo/ +description: This tutorial teaches developers how to effectively implement the FileInfo structure to manage document inputs in GroupDocs.Annotation Cloud API +--- + +# Tutorial: Learn to Work with FileInfo Structure in GroupDocs.Annotation Cloud + +## Learning Objectives + +In this tutorial, you'll learn: +- What the FileInfo structure is and why it's essential +- How to properly configure the FileInfo parameters +- Implementing FileInfo in different annotation scenarios +- Best practices for handling password-protected documents + +## Prerequisites + +Before starting this tutorial, ensure you have: +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is FileInfo? + +FileInfo is a fundamental data structure in GroupDocs.Annotation Cloud that describes input files for annotation operations. It serves as the foundation for almost all operations, allowing you to specify: + +- The location of your document +- Storage information +- Version details +- Password protection parameters + +## Step 1: Understanding the FileInfo Structure + +The FileInfo structure contains the following key fields: + +| Field | Description | Required | +|---|---|---| +| FilePath | The path to your file in storage | Yes | +| StorageName | Name of the storage where the file is located | No (uses default if not specified) | +| VersionId | Version identifier for the document | No | +| Password | Password for protected documents | No (required only for protected files) | + +Let's examine a basic FileInfo JSON example: + +```json +{ + "FilePath": "documents/sample.pdf", + "StorageName": "MyStorage", + "VersionId": "1.0", + "Password": "p@ssw0rd" +} +``` + +## Step 2: Creating a Basic FileInfo Instance + +Let's start implementing the FileInfo structure in different programming languages. + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Working with Password-Protected Documents + +When dealing with password-protected documents, proper configuration of the FileInfo structure is crucial. + +### Try it yourself + +1. Create a FileInfo instance for a password-protected PDF document +2. Implement error handling for incorrect passwords +3. Test your implementation with both correct and incorrect passwords + + + +## Step 4: Advanced FileInfo Usage Scenarios + +### Using FileInfo with Different Storage Providers + +GroupDocs.Annotation Cloud supports various storage options. Here's how to configure FileInfo for different storage providers: + + + +### Troubleshooting Common Issues + +When working with FileInfo, you might encounter these common issues: + +1. File Not Found Errors + - Ensure the FilePath is correct and the file exists in the specified location + - Check storage permissions and accessibility + +2. Password Issues + - Verify the password is correct for protected documents + - Ensure special characters are properly encoded + +3. Storage Configuration Problems + - Confirm your storage configuration is properly set up + - Verify the StorageName parameter matches your configured storage + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the FileInfo object +- How to create and configure FileInfo instances +- Working with different storage providers +- Handling password-protected documents +- Troubleshooting common FileInfo implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a FileInfo structure for a document in Amazon S3 storage +2. Implement a function that validates FileInfo parameters before submission +3. Build a FileInfo generator that handles multiple file types with appropriate configurations + +## Next Steps + +Now that you've mastered the FileInfo structure, continue your learning journey with our [Tutorial: How to Implement AnnotationInfo in Your Applications](/advanced-data-structures/annotationinfo/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Post them on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/). diff --git a/content/annotation/english/advanced-data-structures/previewoptions/_index.md b/content/annotation/english/advanced-data-structures/previewoptions/_index.md new file mode 100644 index 0000000..5877911 --- /dev/null +++ b/content/annotation/english/advanced-data-structures/previewoptions/_index.md @@ -0,0 +1,184 @@ +--- +title: Creating Document Previews with PreviewOptions Tutorial +weight: 5 +url: /advanced-data-structures/previewoptions/ +description: Learn how to generate high-quality document previews using the PreviewOptions structure in GroupDocs.Annotation Cloud API +--- + +# Tutorial: Creating Document Previews with PreviewOptions + +## Learning Objectives + +In this tutorial, you'll learn: +- The purpose and structure of the PreviewOptions object +- How to configure preview generation settings +- Controlling image format, size, and quality +- Selectively previewing specific pages +- Configuring comment visibility in previews +- Best practices for implementing document previews + +## Prerequisites + +Before starting this tutorial, ensure you have: +- Completed our [FileInfo Structure Tutorial](/advanced-data-structures/fileinfo/) +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is PreviewOptions? + +PreviewOptions is a powerful data structure in GroupDocs.Annotation Cloud that defines parameters for generating document previews. It allows you to specify: + +- Input file information +- Preview image format (PNG, JPEG, BMP) +- Dimensional properties (width, height) +- Specific pages to preview +- Comment visibility settings + +Document previews are essential for creating responsive document viewing interfaces, thumbnail galleries, and preview-before-download functionality in your applications. + +## Step 1: Understanding the PreviewOptions Structure + +The PreviewOptions structure contains these important fields: + +| Field | Description | Required | +|---|---|---| +| FileInfo | Input file path and password | Yes | +| Format | Preview format (PNG, JPEG, BMP) | No (default: PNG) | +| PageNumbers | Page numbers to create preview for | No (default: all pages) | +| Width | Preview image width | No | +| Height | Preview image height | No | +| RenderComments | Whether to show comments in preview | No (default: false) | + +Let's examine a basic PreviewOptions JSON example: + +```json +{ + "FileInfo": { + "FilePath": "documents/sample.pdf", + "Password": "p@ssw0rd" + }, + "Format": "PNG", + "PageNumbers": [1, 2, 5], + "Width": 800, + "Height": 600, + "RenderComments": true +} +``` + +## Step 2: Creating a Basic PreviewOptions Instance + +Let's implement a simple PreviewOptions configuration: + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Configuring Preview Format and Quality + +PreviewOptions allows fine-grained control over the format and quality of generated previews: + +### Format and Quality Settings + + + +### Try it yourself + +1. Create a PreviewOptions instance that generates JPEG previews at 75% quality +2. Configure the dimensions to 1024x768 +3. Test the preview generation and note the file size differences compared to PNG + +## Step 4: Selectively Previewing Pages + +For large documents, you may want to preview only specific pages: + +### Selective Page Preview + + + +## Step 5: Working with Annotations in Previews + +PreviewOptions allows you to control whether annotations are visible in the preview: + +### Annotation Visibility in Previews + + + +### Learning Checkpoint + +Test your understanding of PreviewOptions configuration: + +1. How would you implement a thumbnail gallery showing the first page of each document? +2. What's the best format for previews that need to maintain transparency? +3. How would you configure previews for a responsive web interface that needs to display documents at different sizes? + +## Step 6: Implementing a Complete Preview Workflow + +Let's build a complete workflow for document preview generation: + +### Complete Preview Generation Workflow + + + +## Troubleshooting Common Issues + +When working with PreviewOptions, you might encounter these common issues: + +1. Image Dimension Problems + - Ensure width and height values are reasonable for the document type + - Consider aspect ratio to avoid distorted previews + - For large documents, test performance with different dimensions + +2. Format Compatibility Issues + - Some document elements may display differently across formats + - Test transparency support in your chosen format + - Consider file size implications for different formats + +3. Page Selection Errors + - Verify page numbers are within document boundaries + - Check for potential array formatting issues in PageNumbers + - Ensure proper handling of zero-based vs. one-based page numbering + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the PreviewOptions object +- How to create and configure PreviewOptions instances +- Working with different preview formats and quality settings +- Selectively generating previews for specific pages +- Controlling annotation visibility in previews +- Implementing a complete document preview workflow +- Troubleshooting common implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a thumbnail generator that creates previews of multiple documents +2. Implement a responsive preview system that generates images at different resolutions +3. Build a document viewer that uses previews with configurable annotation visibility + +## Next Steps + +Now that you've mastered the PreviewOptions structure, continue your learning journey with our [Tutorial: Working with AnnotationApiLink for Output File Management](/advanced-data-structures/annotationapilink/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-data-structures/removeoptions/_index.md b/content/annotation/english/advanced-data-structures/removeoptions/_index.md new file mode 100644 index 0000000..275d90e --- /dev/null +++ b/content/annotation/english/advanced-data-structures/removeoptions/_index.md @@ -0,0 +1,167 @@ +--- +title: Implementing RemoveOptions in Your Annotation Workflow Tutorial +weight: 4 +url: /advanced-data-structures/removeoptions/ +description: Learn how to effectively remove annotations from documents using the RemoveOptions structure in GroupDocs.Annotation Cloud API +--- + +# Tutorial: Implementing RemoveOptions in Your Annotation Workflow + +## Learning Objectives + +In this tutorial, you'll learn: +- The purpose and structure of the RemoveOptions object +- How to configure annotation removal settings +- Selectively removing annotations by ID +- Managing output file paths after annotation removal +- Best practices for implementing removal operations + +## Prerequisites + +Before starting this tutorial, ensure you have: +- Completed our [FileInfo Structure Tutorial](/advanced-data-structures/fileinfo/) +- Familiarity with [AnnotationInfo Structure](/advanced-data-structures/annotationinfo/) +- A GroupDocs.Annotation Cloud account ([get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs and your preferred programming language +- Development environment set up for the SDK of your choice (Python, Java, or C#) + +## What is RemoveOptions? + +RemoveOptions is a specialized structure in GroupDocs.Annotation Cloud that defines parameters for removing annotations from documents. It allows you to specify: + +- Input file information +- Specific annotation IDs to remove +- Output file configuration +- Page processing settings + +## Step 1: Understanding the RemoveOptions Structure + +The RemoveOptions structure contains these important fields: + +| Field | Description | Required | +|---|---|---| +| FileInfo | Input file path and password | Yes | +| AnnotationIds | Array of IDs of annotations to remove | Yes | +| OutputPath | Path of output document | Yes | + +Let's examine a basic RemoveOptions JSON example: + +```json +{ + "FileInfo": { + "FilePath": "documents/annotated.pdf", + "Password": "p@ssw0rd" + }, + "AnnotationIds": [1, 2, 5], + "OutputPath": "documents/cleaned/output.pdf" +} +``` + +## Step 2: Creating a Basic RemoveOptions Instance + +Let's implement a simple RemoveOptions configuration: + +### Using cURL + + + +### Using Python SDK + + + +### Using Java SDK + + + +### Using C# SDK + + + +## Step 3: Selectively Removing Annotations + +RemoveOptions allows precise control over which annotations are removed: + +### Removing Specific Annotation Types + + + +### Try it yourself + +1. Create a document with multiple types of annotations (text, area, point) +2. Retrieve the annotation IDs for all annotations +3. Create a RemoveOptions instance that removes only the text annotations +4. Verify that only the intended annotations were removed + +## Step 4: Managing Document Output + +Proper output configuration ensures your documents without annotations are stored correctly: + +### Output Path Configuration + + + +## Step 5: Implementing a Complete Annotation Removal Workflow + +Let's build a complete workflow for annotation management: + +### Complete Annotation Removal Workflow + + + +### Learning Checkpoint + +Test your understanding of RemoveOptions implementation: + +1. How would you implement a feature that allows users to selectively remove annotations? +2. What's the best approach for storing the original document alongside the version with removed annotations? +3. How can you track which annotations have been removed for auditing purposes? + +## Troubleshooting Common Issues + +When working with RemoveOptions, you might encounter these common issues: + +1. Invalid Annotation IDs + - Ensure all IDs in the AnnotationIds array exist in the document + - Check for potential data type issues (strings vs. integers) + +2. Output Path Problems + - Verify the output directory exists and is writable + - Ensure the output filename has a valid extension + - Check storage permissions for the output location + +3. Document Access Issues + - Confirm the document isn't locked by another process + - Verify password is correct for protected documents + - Check file permissions on the input document + +## What You've Learned + +In this tutorial, you've learned: +- The structure and purpose of the RemoveOptions object +- How to create and configure RemoveOptions instances +- Selectively removing annotations by ID +- Managing output file paths after annotation removal +- Implementing a complete annotation management workflow +- Troubleshooting common implementation issues + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a system that allows batch removal of annotations across multiple documents +2. Implement a function that validates RemoveOptions parameters before submission +3. Build a user interface that allows visual selection of annotations for removal + +## Next Steps + +Now that you've mastered the RemoveOptions structure, continue your learning journey with our [Tutorial: Creating Document Previews with PreviewOptions](/advanced-data-structures/previewoptions/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + diff --git a/content/annotation/english/advanced-features/_index.md b/content/annotation/english/advanced-features/_index.md new file mode 100644 index 0000000..b449e63 --- /dev/null +++ b/content/annotation/english/advanced-features/_index.md @@ -0,0 +1,58 @@ +--- +title: GroupDocs.Annotation Cloud API Document Advanced Features Tutorials +weight: 2 +url: /advanced-features/ +description: Step-by-step tutorials for advanced document annotation features using GroupDocs.Annotation Cloud API - learn how to add, customize, and manage annotations in your documents. +--- + +# GroupDocs.Annotation Cloud Advanced Features Tutorials + +Welcome to our comprehensive tutorial series on GroupDocs.Annotation Cloud API's advanced features. These hands-on tutorials are designed to help developers progress from basic to advanced annotation capabilities, providing practical guidance for implementing powerful document annotation functionality in your applications. + +## Learning Path + +Our tutorials follow a structured learning path to help you master advanced annotation features: + +1. Adding Annotations - Learn to add various types of annotations to your documents +2. Annotation Customization - Discover how to customize annotation appearance and properties +3. Document Preview - Explore techniques for generating document previews with annotations +4. Annotation Management - Master the processes for managing existing annotations + +## Available Tutorials + +### Adding Annotations + +- [Tutorial: How to Add Area Annotations](/advanced-features/area-annotation/) - Learn to mark specific rectangular areas within documents +- [Tutorial: How to Add Arrow Annotations](/advanced-features/arrow-annotation/) - Master the process of adding directional arrow indicators to documents +- [Tutorial: How to Add Distance Annotations](/advanced-features/distance-annotation/) - Learn to measure and annotate distances between document elements +- [Tutorial: How to Add Ellipse Annotations](/advanced-features/ellipse-annotation/) - Discover techniques for adding elliptical highlight annotations +- [Tutorial: How to Add Image Annotations](/advanced-features/image-annotation/) - Learn to embed image annotations within your documents +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations/) - Discover efficient methods for adding several annotations at once +- [Tutorial: How to Add Text Redaction Annotations](/advanced-features/text-redaction/) - Learn to securely redact text content + + +### Managing Annotations + +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations/) - Master retrieving annotation data from documents. + +### Document Preview + +- [Tutorial: How to Generate Document Page Previews](/advanced-features/get-document-pages/) - Learn to create visual previews of document pages +- [Tutorial: How to Delete Document Pages](/advanced-features/delete-document-pages/) - Master cleaning up preview resources. +### Annotation Management + +- [Tutorial: How to Delete Annotations](/advanced-features/delete-annotations/) - Master the process of removing annotations from documents + +## Helpful Resources + +To support your learning journey with GroupDocs.Annotation Cloud API, we've compiled these additional resources: + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about these tutorials? Feel free to reach out on our support forum for assistance! diff --git a/content/annotation/english/advanced-features/area-annotation/_index.md b/content/annotation/english/advanced-features/area-annotation/_index.md new file mode 100644 index 0000000..c7d0ef8 --- /dev/null +++ b/content/annotation/english/advanced-features/area-annotation/_index.md @@ -0,0 +1,322 @@ +--- + +title: How to Add Area Annotations Tutorial +weight: 1 +url: /advanced-features/area-annotation/ +description: Learn how to add area annotations to documents with GroupDocs.Annotation Cloud API in this step-by-step tutorial for developers +--- + +# Tutorial: How to Add Area Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to add area annotations to documents using the GroupDocs.Annotation Cloud API. Area annotations allow you to mark rectangular regions within a document, which is useful for highlighting specific sections that require attention or additional information. + +## Prerequisites + +Before beginning this tutorial, you should have: + +1. Basic knowledge of REST APIs and your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +2. A [GroupDocs.Cloud](https://dashboard.groupdocs.cloud) account and an app created with access to the Annotation API +3. Your Client ID and Client Secret from the dashboard +4. A sample document uploaded to your storage (we'll use a DOCX file in this tutorial) + +## What is an Area Annotation? + +Area annotation allows you to mark up a specific rectangular region within a document page. This type of annotation is useful when you need to highlight a particular section of text, an image, or any other content within your document that requires attention or additional information. + +## Tutorial Steps + +### Step 1: Authenticate with the API + +Before adding annotations, you need to authenticate with the GroupDocs.Annotation Cloud API to get an access token. + +Try it yourself: + +Use the following cURL command to authenticate and obtain your access token: + +```bash +// First get JSON Web Token +// Please get your Client Id and Client Secret from https://dashboard.groupdocs.cloud/applications +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the access token from the response for use in the next steps. + +### Step 2: Prepare Your Annotation Request + +Now, let's create a request to add an area annotation to your document. The request should include: + +1. File information (path to your document) +2. Output path (where to save the annotated document) +3. Annotation details (type, text, position, size, etc.) + +Here is a sample cURL request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d " +{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'Output/output.docx', + 'Annotations': [ + { + 'Type': 'Area', + 'Text': 'This is area annotation', + 'CreatorName': 'Anonym A.', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 100, + 'Height': 100 + }, + 'PageNumber': 0, + 'AnnotationPosition': { + 'X': 1, + 'Y': 1 + }, + 'Replies': [ + { + 'Comment': 'First comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + }, + { + 'Comment': 'Second comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + } + ], + 'CreatedOn': '2023-01-15T06:52:01.376Z', + 'PenStyle': 'Solid', + 'PenColor': 65535, + 'PenWidth': 3, + 'BackgroundColor': 65535, + 'Opacity': 0.7 + } +] +} +" +``` + +### Step 3: Execute the Request + +Execute the prepared request to add the area annotation to your document. The API will return a response with a link to your annotated document. + +### Step 4: Analyze the Response + +After executing the request, you'll receive a response similar to the following: + +```json +{ + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/Output/output.docx", + "rel": "self", + "type": "file", + "title": "output.docx" +} +``` + +This response provides a link to your annotated document stored in your cloud storage. + +### Step 5: Download the Annotated Document + +You can download the annotated document using the link provided in the response. + +## SDK Examples + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo {FilePath = "one-page.docx"}; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + AnnotationPosition = new Point { X = 1, Y = 1 }, + Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 }, + PageNumber = 0, + BackgroundColor = 65535, + PenColor = 65535, + PenStyle = AnnotationInfo.PenStyleEnum.Solid, + PenWidth = 3, + Type = AnnotationInfo.TypeEnum.Area, + Text = "This is area annotation", + CreatorName = "Anonym A.", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "First comment", + RepliedOn = DateTime.Now + }, + new AnnotationReplyInfo + { + Comment = "Second comment", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "Output/output.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("AddAreaAnnotation: Area Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +String MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyAppSid, MyAppKey); + +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation/s. +AnnotationInfo[] annotations = new AnnotationInfo[1]; +annotations[0] = new AnnotationInfo(); + +Point pt = new Point(); +pt.setX(1.0); +pt.setY(1.0); +annotations[0].setAnnotationPosition(pt); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(200.0); +r.setHeight(100.0); + +annotations[0].setBox(r); + +annotations[0].setPageNumber(0); +annotations[0].setPenColor(1201033); +annotations[0].setPenStyle(PenStyleEnum.SOLID); +annotations[0].setPenWidth(1); +annotations[0].setBackgroundColor(65535); +annotations[0].setOpacity(0.7); +annotations[0].setType(TypeEnum.AREA); +annotations[0].setText("This is area annotation"); +annotations[0].setCreatorName("Anonym A."); + +// Create request object. +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Annotationdocs\\one-page.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("Output/one-page-annotated.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Executing api method. +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("AddAreaAnnotation: Area Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +a1 = groupdocs_annotation_cloud.AnnotationInfo() +a1.annotation_position = groupdocs_annotation_cloud.Point() +a1.annotation_position.x = 1 +a1.annotation_position.y = 1 +a1.box = groupdocs_annotation_cloud.Rectangle() +a1.box.x = 100 +a1.box.y = 100 +a1.box.width = 200 +a1.box.height = 100 +a1.page_number = 0 +a1.pen_color = 1201033 +a1.pen_style = "Solid" +a1.pen_width = 1 +a1.opacity = 0.7 +a1.type = "Area" +a1.text = "This is area annotation" +a1.creator_name = "Anonym A." + +file_info = FileInfo() +file_info.file_path = "annotationdocs\\one-page.docx" +options = AnnotateOptions() +options.file_info = file_info +options.annotations = [a1] +options.output_path = "Output\\output.docx" + +request = AnnotateRequest(options) +result = api.annotate(request) + +print("AddAreaAnnotation: Area Annotation added: " + result['href']) +``` + +## Troubleshooting Tips + +1. Authentication Errors: If you encounter authentication issues, verify your Client ID and Client Secret and make sure they're correctly input in your request. +2. File Not Found Errors: Ensure the file path is correct and the file exists in your storage. +3. Annotation Position Issues: If the annotation doesn't appear where expected, verify the coordinates and dimensions in your request. + +## What You've Learned + +In this tutorial, you've learned: +- How to create a request to add an area annotation to a document +- How to implement this functionality in various programming languages +- How to analyze and use the API response +- Common troubleshooting tips for annotation implementation + +## Further Practice + +To reinforce your learning, try these exercises: +1. Modify the example to change the color and opacity of the area annotation +2. Try adding multiple area annotations in a single request +3. Experiment with different sizes and positions for your area annotations + +## Next Tutorial + +Ready to learn about more annotation types? Proceed to our next tutorial on [How to Add Arrow Annotations](/advanced-features/arrow-annotation/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback and questions in our support forum! diff --git a/content/annotation/english/advanced-features/arrow-annotation/_index.md b/content/annotation/english/advanced-features/arrow-annotation/_index.md new file mode 100644 index 0000000..ea28c17 --- /dev/null +++ b/content/annotation/english/advanced-features/arrow-annotation/_index.md @@ -0,0 +1,339 @@ +--- +title: How to Add Arrow Annotations Tutorial +weight: 2 +url: /advanced-features/arrow-annotation/ +description: Master the process of adding arrow annotations to documents with this step-by-step tutorial for GroupDocs.Annotation Cloud API +--- + +# Tutorial: How to Add Arrow Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to add arrow annotations to documents using the GroupDocs.Annotation Cloud API. Arrow annotations are useful for pointing to specific elements in a document and can be customized with different colors, styles, and properties. + +## Prerequisites + +Before beginning this tutorial, you should have: + +1. Basic knowledge of REST APIs and your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +2. A [GroupDocs.Cloud](https://dashboard.groupdocs.cloud) account and an app created with access to the Annotation API +3. Your Client ID and Client Secret from the dashboard +4. A sample document uploaded to your storage (we'll use a DOCX file in this tutorial) + +## What is an Arrow Annotation? + +An arrow annotation draws a directional indicator on a document page, allowing you to point to specific content that requires attention. It's commonly used for: + +- Highlighting important sections +- Indicating relationships between document elements +- Providing visual guidance for document reviews +- Drawing attention to specific details within the document + +## Tutorial Steps + +### Step 1: Authenticate with the API + +Before adding any annotations, you need to authenticate with the GroupDocs.Annotation Cloud API to obtain an access token. + +Try it yourself: + +Use the following cURL command to authenticate and obtain your access token: + +```bash +// First get JSON Web Token +// Please get your Client Id and Client Secret from https://dashboard.groupdocs.cloud/applications +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the access token from the response for use in the next steps. + +### Step 2: Prepare Your Arrow Annotation Request + +Now, let's create a request to add an arrow annotation to your document. The following parameters are important for arrow annotations: + +- Type: Must be set to "Arrow" +- Box: Defines the position and dimensions of the arrow +- PageNumber: Specifies which page to annotate +- PenColor: Sets the color of the arrow +- PenWidth: Controls the thickness of the arrow +- PenStyle: Defines the line style (solid, dashed, etc.) +- Text: Optional comment associated with the annotation + +Here's a sample cURL request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d " +{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'Output/output.docx', + 'Annotations': [ + { + 'Type': 'Arrow', + 'Text': 'This is arrow annotation', + 'CreatorName': 'Anonym A.', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 100, + 'Height': 100 + }, + 'PageNumber': 0, + 'AnnotationPosition': { + 'X': 1, + 'Y': 1 + }, + 'Replies': [ + { + 'Comment': 'First comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + }, + { + 'Comment': 'Second comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + } + ], + 'CreatedOn': '2023-01-15T06:52:01.376Z', + 'PenStyle': 'Solid', + 'PenColor': 65535, + 'PenWidth': 3, + 'BackgroundColor': 65535, + 'Opacity': 0.7 + } +] +} +" +``` + +### Step 3: Execute the Request + +Execute the prepared request to add the arrow annotation to your document. The API will return a response with a link to your annotated document. + +### Step 4: Analyze the Response + +After executing the request, you'll receive a response similar to the following: + +```json +{ + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/Output/output.docx", + "rel": "self", + "type": "file", + "title": "output.docx" +} +``` + +This response provides a link to your annotated document stored in your cloud storage. + +### Step 5: Download and Verify the Annotated Document + +You can download the annotated document using the link provided in the response. Open the document to verify that your arrow annotation appears correctly. + +## Arrow Annotation Customization Options + +You can customize your arrow annotations in various ways: + +- Color: Change the `PenColor` value to use different colors +- Transparency: Adjust the `Opacity` value between 0.0 (transparent) and 1.0 (opaque) +- Thickness: Modify the `PenWidth` value to make thinner or thicker arrows +- Style: Set `PenStyle` to different values like "Solid", "Dash", or "Dot" + +## SDK Examples + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo {FilePath = "one-page.docx"}; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + AnnotationPosition = new Point { X = 1, Y = 1 }, + Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 }, + PageNumber = 0, + BackgroundColor = 65535, + PenColor = 65535, + PenStyle = AnnotationInfo.PenStyleEnum.Solid, + PenWidth = 3, + Opacity = 0.7, + Type = AnnotationInfo.TypeEnum.Arrow, + Text = "This is arrow annotation", + CreatorName = "Anonym A.", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "First comment", + RepliedOn = DateTime.Now + }, + new AnnotationReplyInfo + { + Comment = "Second comment", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "Output/output.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("AddArrowAnnotation: Arrow Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +String MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyAppSid, MyAppKey); + +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation/s. +AnnotationInfo[] annotations = new AnnotationInfo[1]; +annotations[0] = new AnnotationInfo(); + +Point pt = new Point(); +pt.setX(1.0); +pt.setY(1.0); +annotations[0].setAnnotationPosition(pt); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(200.0); +r.setHeight(100.0); + +annotations[0].setBox(r); +annotations[0].setPageNumber(0); +annotations[0].setPenColor(1201033); +annotations[0].setPenStyle(PenStyleEnum.SOLID); +annotations[0].setPenWidth(1); +annotations[0].setBackgroundColor(65535); +annotations[0].setOpacity(0.7); +annotations[0].setType(TypeEnum.ARROW); +annotations[0].setText("This is arrow annotation"); +annotations[0].setCreatorName("Anonym A."); + +// Create request object. +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Annotationdocs\\one-page.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("Output/one-page-annotated.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Executing api method. +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("AddArrowAnnotation: Arrow Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +a1 = groupdocs_annotation_cloud.AnnotationInfo() +a1.annotation_position = groupdocs_annotation_cloud.Point() +a1.annotation_position.x = 1 +a1.annotation_position.y = 1 +a1.box = groupdocs_annotation_cloud.Rectangle() +a1.box.x = 100 +a1.box.y = 100 +a1.box.width = 200 +a1.box.height = 100 +a1.page_number = 0 +a1.pen_color = 1201033 +a1.pen_style = "Solid" +a1.pen_width = 1 +a1.opacity = 0.7 +a1.type = "Arrow" +a1.text = "This is arrow annotation" +a1.creator_name = "Anonym A." + +file_info = FileInfo() +file_info.file_path = "annotationdocs\\one-page.docx" +options = AnnotateOptions() +options.file_info = file_info +options.annotations = [a1] +options.output_path = "Output\\output.docx" + +request = AnnotateRequest(options) +result = api.annotate(request) + +print("AddArrowAnnotation: Arrow Annotation added: " + result['href']) +``` + +## Troubleshooting Tips + +1. Invisible Arrows: If your arrow isn't visible, check that the pen color offers enough contrast with the document background. +2. Size Issues: If the arrow is too small, try increasing the Width and Height values in the Box parameter. +3. Direction Problems: Remember that the arrow direction is determined by the Box coordinates. The arrow points from the top-left to the bottom-right corner of the Box. +4. Color Display Issues: If colors don't display correctly, ensure you're using valid RGB color values. + +## What You've Learned + +In this tutorial, you've learned: +- How to create and add arrow annotations to documents +- The essential parameters for configuring arrow annotations +- How to customize the appearance of arrow annotations +- How to implement arrow annotations in different programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create an arrow annotation with a different color +2. Add multiple arrow annotations to a document in a single request +3. Experiment with different pen styles (Solid, Dash, Dot) +4. Create arrows of different sizes and thicknesses + +## Next Tutorial + +Ready to learn about more annotation types? Proceed to our next tutorial on [How to Add Distance Annotations](/advanced-features/distance-annotation/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/delete-annotations/_index.md b/content/annotation/english/advanced-features/delete-annotations/_index.md new file mode 100644 index 0000000..5b6e03f --- /dev/null +++ b/content/annotation/english/advanced-features/delete-annotations/_index.md @@ -0,0 +1,318 @@ +--- +title: How to Delete Annotations from Documents in GroupDocs.Annotation Cloud Tutorial +description: Learn how to delete specific annotations from documents using the GroupDocs.Annotation Cloud API in this step-by-step tutorial +weight: 210 +url: /advanced-features/delete-annotations/ +--- + +# Tutorial: How to Delete Annotations from Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Remove specific annotations from documents by their IDs +- Create a workflow for annotation management +- Implement annotation deletion in different programming languages +- Handle annotation deletion responses and error scenarios + +## What is Annotation Deletion? + +Annotation deletion allows you to remove one or more specific annotations from a document while preserving others. This is useful for cleaning up documents, implementing approval workflows, or removing outdated feedback. + +## Prerequisites + +Before starting this tutorial, ensure you have: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. An annotated document uploaded to your GroupDocs.Annotation Cloud storage +5. Knowledge of annotation IDs you want to delete (using the Extract Annotations API) + +## Implementation Steps + +Let's walk through the process of deleting specific annotations from a document: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Identify Annotation IDs to Delete + +Before deleting annotations, you need to know their IDs. You can get these by using the Extract Annotations endpoint: + +```javascript +// Get annotation IDs +curl -v "https://api.groupdocs.cloud/v2.0/annotation/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ \"FilePath\": \"annotated-document.docx\"}" +``` + +From the response, note the IDs of the annotations you want to delete. + +### 3. Delete Specific Annotations + +Use the `POST /annotation/remove` endpoint to delete the annotations: + +```javascript +// Delete annotations +curl -v "https://api.groupdocs.cloud/v2.0/annotation/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + \"FileInfo\": { + \"FilePath\": \"annotated-document.docx\" + }, + \"AnnotationIds\": [1, 2, 3], + \"OutputPath\": \"output/cleaned-document.docx\" +}" +``` + +### 4. Download the Updated Document + +After successful deletion, download your updated document using the File API. + +## Try It Yourself + +Now, let's implement annotation deletion in different programming languages. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "annotated-document.docx" }; + +// First, extract annotations to get their IDs +var extractedAnnotations = apiInstance.Extract(new ExtractRequest(fileInfo)); +Console.WriteLine("Found annotations: " + extractedAnnotations.Count); + +// For this example, let's delete the first 2 annotations +var annotationIdsToDelete = extractedAnnotations + .Take(2) + .Select(a => a.Id) + .ToList(); + +Console.WriteLine("Deleting annotation IDs: " + string.Join(", ", annotationIdsToDelete)); + +// Create delete options +var options = new RemoveOptions +{ + FileInfo = fileInfo, + AnnotationIds = annotationIdsToDelete, + OutputPath = "output/cleaned-document.docx" +}; + +// Delete the annotations +var link = apiInstance.RemoveAnnotations(new RemoveAnnotationsRequest(options)); +Console.WriteLine("Annotations deleted, updated document saved at: " + link.Title); +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create file info object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("annotated-document.docx"); + +// First, extract annotations to get their IDs +List extractedAnnotations = apiInstance.extract(new ExtractRequest(fileInfo)); +System.out.println("Found annotations: " + extractedAnnotations.size()); + +// For this example, let's delete the first 2 annotations +List annotationIdsToDelete = new ArrayList<>(); +for (int i = 0; i < Math.min(2, extractedAnnotations.size()); i++) { + annotationIdsToDelete.add(extractedAnnotations.get(i).getId()); +} + +System.out.println("Deleting annotation IDs: " + String.join(", ", + annotationIdsToDelete.stream().map(String::valueOf).collect(Collectors.toList()))); + +// Create delete options +RemoveOptions options = new RemoveOptions(); +options.setFileInfo(fileInfo); +options.setAnnotationIds(annotationIdsToDelete); +options.setOutputPath("output/cleaned-document.docx"); + +// Delete the annotations +AnnotationApiLink link = apiInstance.removeAnnotations(new RemoveAnnotationsRequest(options)); +System.out.println("Annotations deleted, updated document saved at: " + link.getTitle()); +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Set up file info for the annotated document +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotated-document.docx" + +# First, extract annotations to get their IDs +extracted_annotations = api.extract(groupdocs_annotation_cloud.ExtractRequest(file_info)) +print(f"Found annotations: {len(extracted_annotations)}") + +# For this example, let's delete the first 2 annotations +annotation_ids_to_delete = [ann.id for ann in extracted_annotations[:2]] +print(f"Deleting annotation IDs: {', '.join(map(str, annotation_ids_to_delete))}") + +# Create delete options +options = groupdocs_annotation_cloud.RemoveOptions() +options.file_info = file_info +options.annotation_ids = annotation_ids_to_delete +options.output_path = "output/cleaned-document.docx" + +# Delete the annotations +request = groupdocs_annotation_cloud.RemoveAnnotationsRequest(options) +result = api.remove_annotations(request) + +print(f"Annotations deleted, updated document saved at: {result.title}") +``` + +## Advanced Annotation Deletion Workflows + +Here are some common workflow patterns for annotation deletion: + +### 1. Approval-Based Cleanup + +Delete annotations after they've been processed in an approval workflow: + +```python +# Pseudocode for approval workflow +for annotation in extracted_annotations: + if annotation.text.startswith("[APPROVED]"): + # Process approval logic here + + # Delete the approval annotation after processing + annotation_ids_to_delete.append(annotation.id) + +# Delete processed annotations +delete_annotations(annotation_ids_to_delete) +``` + +### 2. Batched Deletion + +For documents with many annotations, you may want to delete them in batches: + +```csharp +// Pseudocode for batch deletion +List allAnnotationIds = extractedAnnotations.Select(a => a.Id).ToList(); +int batchSize = 10; + +for (int i = 0; i < allAnnotationIds.Count; i += batchSize) +{ + List batch = allAnnotationIds + .Skip(i) + .Take(batchSize) + .ToList(); + + // Delete the current batch + DeleteAnnotations(batch); +} +``` + +### 3. Selective Deletion by User + +Delete annotations from specific users: + +```java +// Pseudocode for user-specific deletion +String userToRemove = "John Doe"; +List userAnnotationIds = new ArrayList<>(); + +for (AnnotationInfo annotation : extractedAnnotations) { + if (userToRemove.equals(annotation.getCreatorName())) { + userAnnotationIds.add(annotation.getId()); + } +} + +// Delete all annotations from this user +DeleteAnnotations(userAnnotationIds); +``` + +### 4. Deletion by Annotation Type + +Delete annotations of a specific type: + +```python +# Pseudocode for type-specific deletion +annotation_type_to_remove = "TextHighlight" +type_annotation_ids = [] + +for annotation in extracted_annotations: + if annotation.type == annotation_type_to_remove: + type_annotation_ids.append(annotation.id) + +# Delete all annotations of this type +delete_annotations(type_annotation_ids) +``` + +## Troubleshooting Tips + +1. Invalid Annotation IDs: Make sure the annotation IDs you're trying to delete actually exist in the document +2. Document Not Found: Verify that the input file path is correct +3. Permission Issues: Ensure you have write permissions for the output file path +4. No Changes: If the document isn't changed, ensure that the annotation IDs are correct and that the document contains those annotations + +## What You've Learned + +In this tutorial, you've learned how to: +- Extract annotation IDs from documents +- Delete specific annotations based on their IDs +- Create efficient annotation deletion workflows +- Handle annotation deletion in different programming languages + +## Further Practice + +To enhance your understanding of annotation deletion, try these exercises: +1. Create a UI that displays annotations and allows selective deletion +2. Implement a time-based cleanup system that removes annotations older than a specific date +3. Build a workflow that automatically cleans up resolved comment threads +4. Develop a system that archives annotations before deleting them from documents + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations/) +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/delete-document-pages/_index.md b/content/annotation/english/advanced-features/delete-document-pages/_index.md new file mode 100644 index 0000000..58424f0 --- /dev/null +++ b/content/annotation/english/advanced-features/delete-document-pages/_index.md @@ -0,0 +1,263 @@ +--- +title: How to Delete Document Pages in GroupDocs.Annotation Cloud Tutorial +description: Learn how to clean up document page preview resources using the GroupDocs.Annotation Cloud API in this step-by-step tutorial +weight: 230 +url: /advanced-features/delete-document-pages/ +--- + +# Tutorial: How to Delete Document Pages + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Delete document page preview resources from cloud storage +- Implement efficient resource management for previews +- Handle cleanup operations in different programming languages +- Create a complete preview workflow with cleanup + +## What is Page Preview Cleanup? + +When you generate document page previews using the Get Pages method, the API creates image files in your cloud storage. The Delete Pages method allows you to remove these preview images when they're no longer needed, helping you manage storage space efficiently. + +## Prerequisites + +Before starting this tutorial, ensure you have: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. Document preview images already generated in your cloud storage + +## Implementation Steps + +Let's walk through the process of deleting document page preview resources: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Delete Page Preview Resources + +Use the `POST /annotation/preview/remove` endpoint to delete the preview images: + +```javascript +// cURL example to delete document preview images +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ \"FilePath\": \"sample-document.docx\"}" +``` + +### 3. Process the Response + +If the operation is successful, the API returns a `200 OK` status code. There's no specific response body for this operation. + +## Try It Yourself + +Let's implement document page preview deletion in different programming languages. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +// Create file info object +var fileInfo = new FileInfo { FilePath = "sample-document.docx" }; + +// Delete page preview resources +var request = new DeletePagesRequest(fileInfo); +apiInstance.DeletePages(request); + +Console.WriteLine("Page preview resources have been successfully deleted."); +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create file info object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("sample-document.docx"); + +// Delete page preview resources +DeletePagesRequest request = new DeletePagesRequest(fileInfo); +apiInstance.deletePages(request); + +System.out.println("Page preview resources have been successfully deleted."); +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Set up file info for the document +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "sample-document.docx" + +# Delete page preview resources +request = groupdocs_annotation_cloud.DeletePagesRequest(file_info) +api.delete_pages(request) + +print("Page preview resources have been successfully deleted.") +``` + +## Complete Preview Workflow with Cleanup + +Here's a complete workflow that generates previews, processes them, and cleans up afterward: + +```python +# Pseudocode for complete preview workflow +def document_preview_workflow(document_path): + try: + # Step 1: Generate page previews + preview_options = create_preview_options(document_path) + page_images = generate_previews(preview_options) + + # Step 2: Process the previews (e.g., display, analyze, etc.) + for page in page_images: + process_page(page) + + # Step 3: Clean up resources when done + delete_preview_resources(document_path) + + return "Document preview workflow completed successfully" + except Exception as e: + return f"Error in document preview workflow: {str(e)}" +``` + +## Best Practices for Resource Management + +1. Always Clean Up: Always delete preview resources when they're no longer needed to avoid accumulating unused files in your storage. + +2. Implement Try-Finally Blocks: Use try-finally blocks to ensure cleanup happens even if errors occur: + +```csharp +try +{ + // Generate and process previews + var pages = apiInstance.GetPages(new GetPagesRequest(options)); + ProcessPages(pages); +} +finally +{ + // Clean up resources regardless of success or failure + apiInstance.DeletePages(new DeletePagesRequest(fileInfo)); +} +``` + +3. Batch Processing: For batch processing of multiple documents, consider using a queue system: + +```python +# Pseudocode for batch processing +documents_to_process = ["doc1.pdf", "doc2.docx", "doc3.pptx"] + +for document in documents_to_process: + try: + # Generate previews + previews = generate_previews(document) + + # Process previews + process_previews(previews) + finally: + # Clean up + delete_preview_resources(document) +``` + +4. Temporary Preview Retention: If you need previews for a limited time, consider implementing a retention policy: + +```java +// Pseudocode for preview retention +class PreviewManager { + private Map previewExpirations = new HashMap<>(); + private final long RETENTION_PERIOD = 30 * 60 * 1000; // 30 minutes + + public void generatePreview(String documentPath) { + // Generate previews + generatePreviews(documentPath); + + // Set expiration time + previewExpirations.put(documentPath, System.currentTimeMillis() + RETENTION_PERIOD); + } + + public void cleanupExpiredPreviews() { + long currentTime = System.currentTimeMillis(); + + for (Iterator> it = previewExpirations.entrySet().iterator(); it.hasNext();) { + Map.Entry entry = it.next(); + + if (entry.getValue() < currentTime) { + // Preview has expired, clean it up + deletePreviewResources(entry.getKey()); + it.remove(); + } + } + } +} +``` + +## Troubleshooting Tips + +1. File Not Found: If you get a file not found error, ensure the document path is correct +2. Authentication Issues: Verify your JWT token is valid and not expired +3. No Effect: If deletion appears to have no effect, verify that the preview images were actually generated first +4. Permission Issues: Ensure your API credentials have proper permissions for file deletion + +## What You've Learned + +In this tutorial, you've learned how to: +- Delete document page preview resources from your cloud storage +- Implement resource cleanup in different programming languages +- Create a complete preview workflow with proper resource management +- Apply best practices for efficient storage management + +## Further Practice + +To enhance your understanding of preview resource management, try these exercises: +1. Create a scheduled task that automatically cleans up preview files older than a certain time +2. Build a preview cache system that efficiently manages resources +3. Implement a user interface for previewing and managing document resources +4. Create an audit system that tracks preview generation and cleanup operations + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations/) +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/distance-annotation/_index.md b/content/annotation/english/advanced-features/distance-annotation/_index.md new file mode 100644 index 0000000..138596f --- /dev/null +++ b/content/annotation/english/advanced-features/distance-annotation/_index.md @@ -0,0 +1,341 @@ +--- +title: How to Add Distance Annotations Tutorial +weight: 3 +url: /advanced-features/distance-annotation/ +description: Learn how to measure and annotate distances between elements in documents with this tutorial for GroupDocs.Annotation Cloud API +--- + +# Tutorial: How to Add Distance Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to add distance annotations to documents using the GroupDocs.Annotation Cloud API. Distance annotations are useful for measuring and marking spaces between elements in your documents, providing valuable visual measurements for technical documents, diagrams, and plans. + +## Prerequisites + +Before beginning this tutorial, you should have: + +1. Basic knowledge of REST APIs and your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +2. A [GroupDocs.Cloud](https://dashboard.groupdocs.cloud) account and an app created with access to the Annotation API +3. Your Client ID and Client Secret from the dashboard +4. A sample document uploaded to your storage (we'll use a DOCX file in this tutorial) + +## What is a Distance Annotation? + +A distance annotation creates a line with measurement indicators between two points in a document. This type of annotation is particularly useful for: + +- Measuring dimensions in technical drawings +- Indicating spatial relationships between document elements +- Adding measurement information to architectural plans +- Highlighting the distance between objects in diagrams or images + +## Tutorial Steps + +### Step 1: Authenticate with the API + +Before adding annotations, you need to authenticate with the GroupDocs.Annotation Cloud API to get an access token. + +Try it yourself: + +Use the following cURL command to authenticate and obtain your access token: + +```bash +// First get JSON Web Token +// Please get your Client Id and Client Secret from https://dashboard.groupdocs.cloud/applications +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the access token from the response for use in the next steps. + +### Step 2: Prepare Your Distance Annotation Request + +Now, let's create a request to add a distance annotation to your document. The following parameters are important for distance annotations: + +- Type: Must be set to "Distance" +- Box: Defines the position and dimensions of the distance line +- AnnotationPosition: Specifies the position of the annotation +- PageNumber: Indicates which page to annotate +- PenColor: Sets the color of the distance line +- PenWidth: Controls the thickness of the line +- PenStyle: Defines the line style (solid, dashed, etc.) +- Text: Optional comment associated with the annotation + +Here's a sample cURL request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d " +{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'Output/output.docx', + 'Annotations': [ + { + 'Type': 'Distance', + 'Text': 'This is distance annotation', + 'CreatorName': 'Anonym A.', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 100, + 'Height': 100 + }, + 'PageNumber': 0, + 'AnnotationPosition': { + 'X': 1, + 'Y': 1 + }, + 'Replies': [ + { + 'Comment': 'First comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + }, + { + 'Comment': 'Second comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + } + ], + 'CreatedOn': '2023-01-15T06:52:01.376Z', + 'PenStyle': 'Solid', + 'PenColor': 65535, + 'PenWidth': 3, + 'BackgroundColor': 65535, + 'Opacity': 0.7 + } +] +} +" +``` + +### Step 3: Execute the Request + +Execute the prepared request to add the distance annotation to your document. The API will return a response with a link to your annotated document. + +### Step 4: Analyze the Response + +After executing the request, you'll receive a response similar to the following: + +```json +{ + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/Output/output.docx", + "rel": "self", + "type": "file", + "title": "output.docx" +} +``` + +This response provides a link to your annotated document stored in your cloud storage. + +### Step 5: Download and Verify the Annotated Document + +You can download the annotated document using the link provided in the response. Open the document to verify that your distance annotation appears correctly with measurement indicators. + +## Understanding Distance Annotation Properties + +For distance annotations, it's important to understand how various properties affect the annotation: + +- Box: The starting point (X, Y) and the ending point (X+Width, Y+Height) of the distance measurement +- PenColor: The color of the distance line and measurement indicators +- PenWidth: The thickness of the distance line +- Opacity: The transparency level of the annotation +- Text: Optional comment or measurement information + +## SDK Examples + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "one-page.docx" }; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + AnnotationPosition = new Point { X = 1, Y = 1 }, + Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 }, + PageNumber = 0, + BackgroundColor = 65535, + PenColor = 65535, + PenStyle = AnnotationInfo.PenStyleEnum.Solid, + PenWidth = 3, + Opacity = 0.7, + Type = AnnotationInfo.TypeEnum.Distance, + Text = "This is distance annotation", + CreatorName = "Anonym A.", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "First comment", + RepliedOn = DateTime.Now + }, + new AnnotationReplyInfo + { + Comment = "Second comment", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "Output/output.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("AddDistanceAnnotation: Distance Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +String MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyAppSid, MyAppKey); + +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation/s. +AnnotationInfo[] annotations = new AnnotationInfo[1]; +annotations[0] = new AnnotationInfo(); + +Point pt = new Point(); +pt.setX(1.0); +pt.setY(1.0); +annotations[0].setAnnotationPosition(pt); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(200.0); +r.setHeight(100.0); + +annotations[0].setBox(r); +annotations[0].setPageNumber(0); +annotations[0].setPenColor(1201033); +annotations[0].setPenStyle(PenStyleEnum.SOLID); +annotations[0].setPenWidth(1); +annotations[0].setBackgroundColor(65535); +annotations[0].setOpacity(0.7); +annotations[0].setType(TypeEnum.DISTANCE); +annotations[0].setText("This is distance annotation"); +annotations[0].setCreatorName("Anonym A."); + +// Create request object. +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Annotationdocs\\one-page.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("Output/one-page-annotated.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Executing api method. +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("AddDistanceAnnotation: Distance Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +a1 = groupdocs_annotation_cloud.AnnotationInfo() +a1.annotation_position = groupdocs_annotation_cloud.Point() +a1.annotation_position.x = 1 +a1.annotation_position.y = 1 +a1.box = groupdocs_annotation_cloud.Rectangle() +a1.box.x = 100 +a1.box.y = 100 +a1.box.width = 200 +a1.box.height = 100 +a1.page_number = 0 +a1.pen_color = 1201033 +a1.pen_style = "Solid" +a1.pen_width = 1 +a1.opacity = 0.7 +a1.type = "Distance" +a1.text = "This is Distance annotation" +a1.creator_name = "Anonym A." + +file_info = FileInfo() +file_info.file_path = "annotationdocs\\one-page.docx" +options = AnnotateOptions() +options.file_info = file_info +options.annotations = [a1] +options.output_path = "Output\\output.docx" + +request = AnnotateRequest(options) +result = api.annotate(request) + +print("AddDistanceAnnotation: Distance Annotation added: " + result['href']) +``` + +## Troubleshooting Tips + +1. Missing Measurement Indicators: If measurement indicators don't appear, check that the `PenWidth` is sufficient to make them visible. +2. Unclear Distance Line: If the distance line is difficult to see, try increasing the contrast by changing the `PenColor` or `PenWidth`. +3. Incorrect Measurement Direction: The direction of measurement is determined by the `Box` parameters. Adjust the X, Y, Width, and Height values to change the direction. +4. Visibility Issues: If the annotation is not clearly visible, check the `Opacity` value and increase it if necessary. + +## What You've Learned + +In this tutorial, you've learned: +- How to create and add distance annotations to documents +- The essential parameters for configuring distance measurements +- How to customize the appearance of distance annotations +- How to implement distance annotations in different programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create distance annotations with different measurement directions (horizontal, vertical, diagonal) +2. Add multiple distance annotations to a single document +3. Customize the appearance of the distance annotation with different colors and styles +4. Add explanatory text to the distance annotation + +## Next Tutorial + +Ready to learn about more annotation types? Proceed to our next tutorial on [How to Add Ellipse Annotations](/advanced-features/ellipse-annotation/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/ellipse-annotation/_index.md b/content/annotation/english/advanced-features/ellipse-annotation/_index.md new file mode 100644 index 0000000..93e7cb3 --- /dev/null +++ b/content/annotation/english/advanced-features/ellipse-annotation/_index.md @@ -0,0 +1,352 @@ +--- +title: How to Add Ellipse Annotations Tutorial +weight: 4 +url: /advanced-features/ellipse-annotation/ +description: Learn how to add elliptical highlight annotations to documents with this step-by-step tutorial for GroupDocs.Annotation Cloud API +--- + +# Tutorial: How to Add Ellipse Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to add ellipse annotations to documents using the GroupDocs.Annotation Cloud API. Ellipse annotations allow you to draw oval or circular shapes to highlight specific areas of your document, creating visual emphasis on important content. + +## Prerequisites + +Before beginning this tutorial, you should have: + +1. Basic knowledge of REST APIs and your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +2. A [GroupDocs.Cloud](https://dashboard.groupdocs.cloud) account and an app created with access to the Annotation API +3. Your Client ID and Client Secret from the dashboard +4. A sample document uploaded to your storage (we'll use a DOCX file in this tutorial) + +## What is an Ellipse Annotation? + +An ellipse annotation draws an oval or circular shape on a document page. This type of annotation is particularly useful for: + +- Highlighting areas of interest in images or diagrams +- Drawing attention to specific content without obscuring it +- Creating emphasis on important information +- Marking circular or oval-shaped content in technical documents + +## Tutorial Steps + +### Step 1: Authenticate with the API + +Before adding annotations, you need to authenticate with the GroupDocs.Annotation Cloud API to get an access token. + +Try it yourself: + +Use the following cURL command to authenticate and obtain your access token: + +```bash +// First get JSON Web Token +// Please get your Client Id and Client Secret from https://dashboard.groupdocs.cloud/applications +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the access token from the response for use in the next steps. + +### Step 2: Prepare Your Ellipse Annotation Request + +Now, let's create a request to add an ellipse annotation to your document. The following parameters are important for ellipse annotations: + +- Type: Must be set to "Ellipse" +- Box: Defines the position and dimensions of the ellipse +- PageNumber: Indicates which page to annotate +- PenColor: Sets the color of the ellipse outline +- PenWidth: Controls the thickness of the ellipse outline +- PenStyle: Defines the line style (solid, dashed, etc.) +- BackgroundColor: Sets the fill color of the ellipse +- Opacity: Controls the transparency of the annotation + +Here's a sample cURL request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d " +{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'Output/output.docx', + 'Annotations': [ + { + 'Type': 'Ellipse', + 'Text': 'This is ellipse annotation', + 'CreatorName': 'Anonym A.', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 100, + 'Height': 100 + }, + 'PageNumber': 0, + 'Replies': [ + { + 'Comment': 'First comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + }, + { + 'Comment': 'Second comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + } + ], + 'CreatedOn': '2023-01-15T06:52:01.376Z', + 'PenStyle': 'Solid', + 'PenColor': 65535, + 'PenWidth': 3, + 'BackgroundColor': 65535, + 'Opacity': 0.7 + } +] +} +" +``` + +### Step 3: Execute the Request + +Execute the prepared request to add the ellipse annotation to your document. The API will return a response with a link to your annotated document. + +### Step 4: Analyze the Response + +After executing the request, you'll receive a response similar to the following: + +```json +{ + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/Output/output.docx", + "rel": "self", + "type": "file", + "title": "output.docx" +} +``` + +This response provides a link to your annotated document stored in your cloud storage. + +### Step 5: Download and Verify the Annotated Document + +You can download the annotated document using the link provided in the response. Open the document to verify that your ellipse annotation appears correctly. + +## Customizing Ellipse Annotations + +Ellipse annotations can be customized in various ways to suit your specific needs: + +1. Size and Shape: Adjust the Width and Height values in the Box parameter to create ellipses of different shapes and sizes. +2. Outline Appearance: Modify the PenColor, PenWidth, and PenStyle to change how the ellipse outline appears. +3. Fill Appearance: Change the BackgroundColor and Opacity to alter the fill appearance of the ellipse. +4. Position: Adjust the X and Y coordinates in the Box parameter to place the ellipse at different locations on the page. + +## SDK Examples + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "one-page.docx" }; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + AnnotationPosition = new Point { X = 1, Y = 1 }, + Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 }, + PageNumber = 0, + BackgroundColor = 65535, + PenColor = 65535, + PenStyle = AnnotationInfo.PenStyleEnum.Solid, + PenWidth = 3, + Opacity = 0.7, + Type = AnnotationInfo.TypeEnum.Ellipse, + Text = "This is ellipse annotation", + CreatorName = "Anonym A.", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "First comment", + RepliedOn = DateTime.Now + }, + new AnnotationReplyInfo + { + Comment = "Second comment", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "Output/output.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("AddEllipseeAnnotation: Ellipse Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +String MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyAppSid, MyAppKey); + +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation/s. +AnnotationInfo[] annotations = new AnnotationInfo[1]; +annotations[0] = new AnnotationInfo(); + +Point pt = new Point(); +pt.setX(1.0); +pt.setY(1.0); +annotations[0].setAnnotationPosition(pt); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(200.0); +r.setHeight(100.0); + +annotations[0].setBox(r); +annotations[0].setPageNumber(0); +annotations[0].setPenColor(1201033); +annotations[0].setPenStyle(PenStyleEnum.SOLID); +annotations[0].setPenWidth(1); +annotations[0].setBackgroundColor(65535); +annotations[0].setOpacity(0.7); +annotations[0].setType(TypeEnum.ELLIPSE); +annotations[0].setText("This is ellipse annotation"); +annotations[0].setCreatorName("Anonym A."); + +// Create request object. +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Annotationdocs\\one-page.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("Output/one-page-annotated.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Executing api method. +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("AddEllipseAnnotation: Ellipse Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +a1 = groupdocs_annotation_cloud.AnnotationInfo() +a1.annotation_position = groupdocs_annotation_cloud.Point() +a1.annotation_position.x = 1 +a1.annotation_position.y = 1 +a1.box = groupdocs_annotation_cloud.Rectangle() +a1.box.x = 100 +a1.box.y = 100 +a1.box.width = 200 +a1.box.height = 100 +a1.page_number = 0 +a1.pen_color = 1201033 +a1.pen_style = "Solid" +a1.pen_width = 1 +a1.opacity = 0.7 +a1.type = "Ellipse" +a1.text = "This is Ellipse annotation" +a1.creator_name = "Anonym A." + +file_info = FileInfo() +file_info.file_path = "annotationdocs\\one-page.docx" +options = AnnotateOptions() +options.file_info = file_info +options.annotations = [a1] +options.output_path = "Output\\output.docx" + +request = AnnotateRequest(options) +result = api.annotate(request) + +print("AddEllipseAnnotation: Ellipse Annotation added: " + result['href']) +``` + +## Creating Perfect Circles vs. Ellipses + +When working with ellipse annotations, you might want to create perfect circles rather than ellipses. To create a perfect circle, ensure that the Width and Height values in the Box parameter are equal. For example: + +```json +"Box": { + "X": 100, + "Y": 100, + "Width": 100, + "Height": 100 +} +``` + +This will create a perfect circle with a radius of 50 units. If you want an ellipse, simply use different values for Width and Height. + +## Troubleshooting Tips + +1. Invisible Ellipse: If your ellipse isn't visible, check that both the pen color and background color offer sufficient contrast with the document background. +2. Misshapen Ellipse: If your ellipse appears distorted, verify that your Width and Height values are appropriate for the content you're highlighting. +3. Transparency Issues: If your ellipse is too transparent or too opaque, adjust the Opacity value (between 0.0 and 1.0). +4. Position Problems: If the ellipse isn't positioned correctly, make sure the X and Y coordinates in the Box parameter are appropriate for your document page. + +## What You've Learned + +In this tutorial, you've learned: +- How to create and add ellipse annotations to documents +- The essential parameters for configuring elliptical highlights +- How to customize the appearance of ellipse annotations +- How to implement ellipse annotations in different programming languages +- How to create perfect circles vs. ellipses + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create ellipse annotations with different colors and opacity levels +2. Add multiple ellipse annotations to highlight different areas of a document +3. Experiment with different pen styles for the ellipse outline +4. Create a perfect circle annotation and compare it with an elliptical annotation + +## Next Tutorial + +Ready to learn about more annotation types? Proceed to our next tutorial on [How to Add Image Annotations](/advanced-features/image-annotation/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/extract-annotations/_index.md b/content/annotation/english/advanced-features/extract-annotations/_index.md new file mode 100644 index 0000000..5da018e --- /dev/null +++ b/content/annotation/english/advanced-features/extract-annotations/_index.md @@ -0,0 +1,368 @@ +--- +title: How to Extract Annotations from Documents in GroupDocs.Annotation Cloud Tutorial +description: Learn how to extract annotations from documents using the GroupDocs.Annotation Cloud API in this step-by-step tutorial +weight: 200 +url: /advanced-features/extract-annotations/ +--- + +# Tutorial: How to Extract Annotations from Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Extract all annotations from an annotated document +- Parse and process annotation data +- Access annotation properties and metadata +- Implement annotation extraction in different programming languages + +## What is Annotation Extraction? + +Annotation extraction allows you to retrieve all annotations from a document as structured data. This is useful for analyzing annotations, generating reports, implementing approval workflows, or building collaborative review systems. + +## Prerequisites + +Before starting this tutorial, ensure you have: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. An annotated document uploaded to your GroupDocs.Annotation Cloud storage + +## Implementation Steps + +Let's walk through the process of extracting annotations from a document: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Extract Annotations + +Use the `POST /annotation/extract` endpoint to retrieve all annotations: + +```javascript +// cURL example to extract annotations +curl -v "https://api.groupdocs.cloud/v2.0/annotation/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ \"FilePath\": \"annotated-document.docx\"}" +``` + +### 3. Process the Response + +The API returns an array of annotation objects with all properties. Here's a sample response: + +```javascript +[ + { + "id": 0, + "text": "This is ellipse annotation", + "textToReplace": null, + "horizontalAlignment": 0, + "verticalAlignment": 0, + "creatorId": 0, + "creatorName": "John Doe", + "creatorEmail": null, + "box": { + "x": 100, + "y": 100, + "width": 100, + "height": 100 + }, + "points": null, + "pageNumber": 0, + "annotationPosition": null, + "svgPath": null, + "type": 4, + "replies": [ + { + "id": 0, + "userId": 0, + "userName": null, + "userEmail": null, + "comment": "First comment", + "repliedOn": "2023-04-25T06:52:01.376Z", + "parentReplyId": 0 + }, + { + "id": 0, + "userId": 0, + "userName": null, + "userEmail": null, + "comment": "Second comment", + "repliedOn": "2023-04-25T06:52:01.376Z", + "parentReplyId": 0 + } + ], + "createdOn": "2023-04-25T06:52:01.376Z", + "fontColor": null, + "penColor": null, + "penWidth": null, + "penStyle": null, + "backgroundColor": null, + "fontFamily": null, + "fontSize": null, + "opacity": null, + "angle": null, + "url": null, + "imagePath": null + } +] +``` + +The response contains detailed information about each annotation, including: +- Annotation ID and type +- Text content +- Position information (box, points) +- Page number +- Creator information +- Creation date +- Replies/comments +- Style properties (colors, opacity, etc.) + +## Try It Yourself + +Now, let's implement annotation extraction in different programming languages. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "annotated-document.docx" }; + +// Extract annotations +var response = apiInstance.Extract(new ExtractRequest(fileInfo)); + +Console.WriteLine("Extracted annotations count: " + response.Count); + +// Process the annotations +foreach (var annotation in response) +{ + Console.WriteLine($"Annotation ID: {annotation.Id}"); + Console.WriteLine($"Type: {annotation.Type}"); + Console.WriteLine($"Text: {annotation.Text}"); + Console.WriteLine($"Page Number: {annotation.PageNumber}"); + Console.WriteLine($"Creator: {annotation.CreatorName}"); + Console.WriteLine($"Created On: {annotation.CreatedOn}"); + + // Process replies if present + if (annotation.Replies != null && annotation.Replies.Count > 0) + { + Console.WriteLine("Replies:"); + foreach (var reply in annotation.Replies) + { + Console.WriteLine($" - {reply.Comment} (by: {reply.UserName ?? "Anonymous"}, on: {reply.RepliedOn})"); + } + } + + Console.WriteLine("-------------------"); +} +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create request object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("annotated-document.docx"); + +ExtractRequest request = new ExtractRequest(); +request.setfileInfo(fileInfo); + +// Execute API method +List response = apiInstance.extract(request); + +System.out.println("Extracted annotations count: " + response.size()); + +// Process the annotations +for (AnnotationInfo annotation : response) { + System.out.println("Annotation ID: " + annotation.getId()); + System.out.println("Type: " + annotation.getType()); + System.out.println("Text: " + annotation.getText()); + System.out.println("Page Number: " + annotation.getPageNumber()); + System.out.println("Creator: " + annotation.getCreatorName()); + System.out.println("Created On: " + annotation.getCreatedOn()); + + // Process replies if present + if (annotation.getReplies() != null && !annotation.getReplies().isEmpty()) { + System.out.println("Replies:"); + for (AnnotationReplyInfo reply : annotation.getReplies()) { + System.out.println(" - " + reply.getComment() + + " (by: " + (reply.getUserName() != null ? reply.getUserName() : "Anonymous") + + ", on: " + reply.getRepliedOn() + ")"); + } + } + + System.out.println("-------------------"); +} +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Set up file info for the annotated document +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotated-document.docx" + +# Create extract request +request = groupdocs_annotation_cloud.ExtractRequest(file_info) +result = api.extract(request) + +print(f"Extracted annotations count: {len(result)}") + +# Process the annotations +for annotation in result: + print(f"Annotation ID: {annotation.id}") + print(f"Type: {annotation.type}") + print(f"Text: {annotation.text}") + print(f"Page Number: {annotation.page_number}") + print(f"Creator: {annotation.creator_name}") + print(f"Created On: {annotation.created_on}") + + # Process replies if present + if annotation.replies and len(annotation.replies) > 0: + print("Replies:") + for reply in annotation.replies: + print(f" - {reply.comment} (by: {reply.user_name or 'Anonymous'}, on: {reply.replied_on})") + + print("-------------------") +``` + +## Working with Extracted Annotations + +Here are some common use cases for extracted annotation data: + +### 1. Building Approval Workflows + +Extract annotations to identify approvals, rejections, or requests for changes in a review process: + +```python +# Pseudocode for approval workflow +approval_status = "Pending" + +for annotation in extracted_annotations: + if "APPROVED" in annotation.text.upper(): + approval_status = "Approved" + approver = annotation.creator_name + approval_date = annotation.created_on + elif "REJECTED" in annotation.text.upper(): + approval_status = "Rejected" + rejection_reason = annotation.text + rejector = annotation.creator_name +``` + +### 2. Generating Annotation Reports + +Create summary reports of all annotations in a document: + +```csharp +// Pseudocode for generating report +StringBuilder report = new StringBuilder(); +report.AppendLine("Annotation Report - " + DateTime.Now); +report.AppendLine("Document: " + filePath); +report.AppendLine("Total Annotations: " + annotations.Count); +report.AppendLine(); + +var annotationsByPage = annotations.GroupBy(a => a.PageNumber); +foreach (var pageGroup in annotationsByPage) +{ + report.AppendLine($"Page {pageGroup.Key + 1}:"); + foreach (var annotation in pageGroup) + { + report.AppendLine($" - {annotation.Type}: {annotation.Text} (by {annotation.CreatorName})"); + } +} +``` + +### 3. Collaborative Review Analysis + +Analyze collaboration patterns based on annotation data: + +```java +// Pseudocode for collaboration analysis +Map contributorCounts = new HashMap<>(); +Map> annotationsByPage = new HashMap<>(); + +for (AnnotationInfo annotation : annotations) { + // Count contributions by user + String creator = annotation.getCreatorName(); + contributorCounts.put(creator, contributorCounts.getOrDefault(creator, 0) + 1); + + // Group annotations by page + int page = annotation.getPageNumber(); + if (!annotationsByPage.containsKey(page)) { + annotationsByPage.put(page, new ArrayList<>()); + } + annotationsByPage.get(page).add(annotation); +} +``` + +## Troubleshooting Tips + +1. Empty Result: Ensure the document actually contains annotations; some file formats may not support all annotation types +2. Authentication Issues: Verify your JWT token is valid and not expired +3. File Not Found: Check that the file path is correct and the document exists in your cloud storage +4. Type Interpretation: The `type` property is returned as a numeric value; refer to the API documentation for a mapping of type values to annotation types + +## What You've Learned + +In this tutorial, you've learned how to: +- Extract annotations from documents using the GroupDocs.Annotation Cloud API +- Process and interpret annotation data +- Implement annotation extraction in different programming languages +- Work with extracted annotation data for various business use cases + +## Further Practice + +To enhance your understanding of annotation extraction, try these exercises: +1. Create a system that extracts annotations and saves them to a database +2. Build a dashboard that visualizes annotation activity across multiple documents +3. Implement a notification system that alerts users when their annotations receive replies +4. Create a document comparison tool that identifies differences in annotations between document versions + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Delete Annotations](/advanced-features/delete-annotations/) +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/get-document-pages/_index.md b/content/annotation/english/advanced-features/get-document-pages/_index.md new file mode 100644 index 0000000..36e0370 --- /dev/null +++ b/content/annotation/english/advanced-features/get-document-pages/_index.md @@ -0,0 +1,426 @@ +--- +title: How to Get Document Pages in GroupDocs.Annotation Cloud Tutorial +description: Learn how to create image previews of document pages using the GroupDocs.Annotation Cloud API in this step-by-step tutorial +weight: 220 +url: /advanced-features/get-document-pages/ +--- + +# Tutorial: How to Get Document Pages + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Generate image representations of document pages +- Access and process document page images +- Implement document preview functionality in different programming languages +- Clean up preview resources when they're no longer needed + +## What is Document Page Preview? + +The Document Page Preview feature allows you to create image representations (PNG format) of each page in a document. This is useful for building document viewers, implementing annotation UI's, or creating document thumbnails without requiring users to have the original document software installed. + +## Prerequisites + +Before starting this tutorial, ensure you have: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. A document uploaded to your GroupDocs.Annotation Cloud storage + +## Implementation Steps + +Let's walk through the process of generating document page previews: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Generate Page Previews + +Use the `POST /annotation/preview/create` endpoint to generate page images: + +```javascript +// cURL example to create document preview images +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview/create" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ \"FileInfo\": { \"FilePath\": \"sample-document.docx\" }}" +``` + +### 3. Process the Response + +The API returns information about the generated page images: + +```javascript +{ + "totalCount": 3, + "entries": [ + { + "number": 0, + "link": { + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/sample-document_docx/page_0.png", + "rel": "self", + "type": "file", + "title": "page_0.png" + } + }, + { + "number": 1, + "link": { + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/sample-document_docx/page_1.png", + "rel": "self", + "type": "file", + "title": "page_1.png" + } + }, + { + "number": 2, + "link": { + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/sample-document_docx/page_2.png", + "rel": "self", + "type": "file", + "title": "page_2.png" + } + } + ] +} +``` + +### 4. Access the Page Images + +Each entry in the response contains a link to the generated PNG image file. You can download these images using the provided URLs. + +### 5. Clean Up Resources (Optional) + +When you're done with the preview images, you can remove them using the `POST /annotation/preview/remove` endpoint: + +```javascript +// cURL example to delete document preview images +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ \"FilePath\": \"sample-document.docx\"}" +``` + +## Try It Yourself + +Let's implement document page preview generation in different programming languages. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +// Create file info object +var fileInfo = new FileInfo { FilePath = "sample-document.docx" }; +var options = new PreviewOptions { FileInfo = fileInfo }; + +// Generate page previews +var request = new GetPagesRequest(options); +var response = apiInstance.GetPages(request); + +Console.WriteLine($"Generated previews for {response.TotalCount} pages:"); + +// Process the page images +foreach (var entry in response.Entries) +{ + Console.WriteLine($"Page {entry.Number}: {entry.Link.Title} - {entry.Link.Href}"); + + // Here you could download each image or process it further + // For example: + // DownloadImage(entry.Link.Href, $"page_{entry.Number}.png"); +} + +// Optional: Clean up the preview resources when done +var cleanupRequest = new DeletePagesRequest(fileInfo); +apiInstance.DeletePages(cleanupRequest); +Console.WriteLine("Preview resources cleaned up"); + +// Example download method (not implemented) +void DownloadImage(string url, string savePath) +{ + // Code to download image from url and save to disk + Console.WriteLine($"Downloaded {url} to {savePath}"); +} +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create file info object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("sample-document.docx"); + +PreviewOptions options = new PreviewOptions(); +options.setFileInfo(fileInfo); + +// Generate page previews +GetPagesRequest request = new GetPagesRequest(options); +PageImages response = apiInstance.getPages(request); + +System.out.println("Generated previews for " + response.getTotalCount() + " pages:"); + +// Process the page images +for (PageImage entry : response.getEntries()) { + System.out.println("Page " + entry.getNumber() + ": " + + entry.getLink().getTitle() + " - " + entry.getLink().getHref()); + + // Here you could download each image or process it further + // For example: + // downloadImage(entry.getLink().getHref(), "page_" + entry.getNumber() + ".png"); +} + +// Optional: Clean up the preview resources when done +DeletePagesRequest cleanupRequest = new DeletePagesRequest(fileInfo); +apiInstance.deletePages(cleanupRequest); +System.out.println("Preview resources cleaned up"); + +// Example download method (not implemented) +void downloadImage(String url, String savePath) { + // Code to download image from url and save to disk + System.out.println("Downloaded " + url + " to " + savePath); +} +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud +import requests # For downloading images + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Set up file info for the document +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "sample-document.docx" + +options = groupdocs_annotation_cloud.PreviewOptions() +options.file_info = file_info + +# Generate page previews +request = groupdocs_annotation_cloud.GetPagesRequest(options) +response = api.get_pages(request) + +print(f"Generated previews for {response.total_count} pages:") + +# Process the page images +for entry in response.entries: + print(f"Page {entry.number}: {entry.link.title} - {entry.link.href}") + + # Here you could download each image or process it further + # For example: + # download_image(entry.link.href, f"page_{entry.number}.png") + +# Optional: Clean up the preview resources when done +cleanup_request = groupdocs_annotation_cloud.DeletePagesRequest(file_info) +api.delete_pages(cleanup_request) +print("Preview resources cleaned up") + +# Example download method +def download_image(url, save_path): + response = requests.get(url) + if response.status_code == 200: + with open(save_path, 'wb') as f: + f.write(response.content) + print(f"Downloaded {url} to {save_path}") + else: + print(f"Failed to download {url}, status code: {response.status_code}") +``` + +## Building Document Viewers with Page Previews + +Document page previews enable you to build custom document viewers for your applications. Here are some common implementation patterns: + +### 1. Basic Document Viewer + +A simple document viewer implementation: + +```javascript +// Pseudocode for a basic document viewer +function loadDocumentViewer(documentPath) { + // Generate page previews + const pages = generatePagePreviews(documentPath); + + // Display pages in a container + const viewerContainer = document.getElementById('viewer-container'); + + pages.forEach(page => { + const pageElement = document.createElement('div'); + pageElement.className = 'document-page'; + + const pageImage = document.createElement('img'); + pageImage.src = page.link.href; + pageImage.alt = `Page ${page.number + 1}`; + + pageElement.appendChild(pageImage); + viewerContainer.appendChild(pageElement); + }); +} +``` + +### 2. Lazy-Loading Document Viewer + +For documents with many pages, implement lazy loading for better performance: + +```javascript +// Pseudocode for a lazy-loading document viewer +function lazyLoadDocumentViewer(documentPath, totalPages) { + const viewerContainer = document.getElementById('viewer-container'); + let loadedPages = 0; + const pageHeight = 1000; // Estimated page height in pixels + + // Setup container with placeholder pages + for (let i = 0; i < totalPages; i++) { + const pageElement = document.createElement('div'); + pageElement.className = 'document-page'; + pageElement.id = `page-${i}`; + pageElement.style.height = `${pageHeight}px`; + viewerContainer.appendChild(pageElement); + } + + // Function to load visible pages + function loadVisiblePages() { + const viewportTop = window.scrollY; + const viewportBottom = viewportTop + window.innerHeight; + + for (let i = 0; i < totalPages; i++) { + const pageElement = document.getElementById(`page-${i}`); + const pageRect = pageElement.getBoundingClientRect(); + + // If page is visible and not already loaded + if (pageRect.top < viewportBottom && + pageRect.bottom > viewportTop && + !pageElement.dataset.loaded) { + + // Mark as loaded + pageElement.dataset.loaded = true; + + // Load page image + const pageImage = document.createElement('img'); + pageImage.src = getPageImageUrl(documentPath, i); + pageImage.alt = `Page ${i + 1}`; + pageElement.innerHTML = ''; + pageElement.appendChild(pageImage); + + console.log(`Loaded page ${i + 1}`); + } + } + } + + // Initial load of visible pages + loadVisiblePages(); + + // Load pages when scrolling + window.addEventListener('scroll', loadVisiblePages); +} +``` + +### 3. Document Viewer with Annotation Interface + +Combine page previews with annotation capability: + +```javascript +// Pseudocode for viewer with annotation interface +function annotationEnabledViewer(documentPath) { + // Generate page previews + const pages = generatePagePreviews(documentPath); + + // Display pages in a container + const viewerContainer = document.getElementById('viewer-container'); + + pages.forEach(page => { + const pageElement = document.createElement('div'); + pageElement.className = 'document-page'; + pageElement.dataset.pageNumber = page.number; + + const pageImage = document.createElement('img'); + pageImage.src = page.link.href; + pageImage.alt = `Page ${page.number + 1}`; + + pageElement.appendChild(pageImage); + viewerContainer.appendChild(pageElement); + + // Add annotation layer on top of the page + const annotationLayer = document.createElement('div'); + annotationLayer.className = 'annotation-layer'; + pageElement.appendChild(annotationLayer); + + // Setup annotation events + annotationLayer.addEventListener('mousedown', startAnnotation); + annotationLayer.addEventListener('mousemove', updateAnnotation); + annotationLayer.addEventListener('mouseup', finalizeAnnotation); + }); +} + +// Annotation event handlers would be implemented here +``` + +## Troubleshooting Tips + +1. No Pages Generated: Verify that the document format is supported and the file exists +2. Image Quality Issues: The default image format is PNG; consider requesting different formats if needed +3. Large Documents: For documents with many pages, implement pagination or lazy loading +4. Resource Cleanup: Always clean up preview resources when no longer needed to save storage space + +## What You've Learned + +In this tutorial, you've learned how to: +- Generate image representations of document pages +- Access and process the generated page images +- Implement document preview functionality in different programming languages +- Clean up preview resources when they're no longer needed +- Build different types of document viewers using page previews + +## Further Practice + +To enhance your understanding of document page previews, try these exercises: +1. Create a complete document viewer that supports navigation, zooming, and rotation +2. Implement a document thumbnail gallery for quick navigation +3. Build a document comparison tool that shows two documents side by side +4. Create a document preview system with caching for improved performance + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Delete Document Pages](/advanced-features/delete-document-pages) +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations) +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/image-annotation/_index.md b/content/annotation/english/advanced-features/image-annotation/_index.md new file mode 100644 index 0000000..52729b5 --- /dev/null +++ b/content/annotation/english/advanced-features/image-annotation/_index.md @@ -0,0 +1,338 @@ +--- +url: /advanced-features/image-annotation/ +title: How to Add Image Annotations Tutorial +weight: 5 +description: Learn how to embed image annotations within your documents using this step-by-step tutorial for GroupDocs.Annotation Cloud API +--- + +# Tutorial: How to Add Image Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to add image annotations to documents using the GroupDocs.Annotation Cloud API. Image annotations allow you to embed pictures, logos, or other visual elements directly into your documents as annotations, enhancing the visual communication of your content. + +## Prerequisites + +Before beginning this tutorial, you should have: + +1. Basic knowledge of REST APIs and your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +2. A [GroupDocs.Cloud](https://dashboard.groupdocs.cloud) account and an app created with access to the Annotation API +3. Your Client ID and Client Secret from the dashboard +4. A sample document uploaded to your storage (we'll use a DOCX file in this tutorial) +5. An image file uploaded to your storage (we'll use a PNG file in this tutorial) + +## What is an Image Annotation? + +An image annotation allows you to add images within a document page. This type of annotation is particularly useful for: + +- Adding logos or company branding to documents +- Including visual examples or references +- Embedding screenshots or diagrams +- Enhancing document content with relevant imagery +- Adding signatures or stamps to documents + +## Tutorial Steps + +### Step 1: Authenticate with the API + +Before adding annotations, you need to authenticate with the GroupDocs.Annotation Cloud API to get an access token. + +Try it yourself: + +Use the following cURL command to authenticate and obtain your access token: + +```bash +// First get JSON Web Token +// Please get your Client Id and Client Secret from https://dashboard.groupdocs.cloud/applications +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the access token from the response for use in the next steps. + +### Step 2: Upload Your Image File (If Not Already Uploaded) + +Before you can add an image annotation, you need to ensure that the image file is available in your cloud storage. If you haven't already uploaded your image, you can do so using the following cURL command: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/storage/file/JohnSmith.png" \ +-X PUT \ +-H "Content-Type: multipart/form-data" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-F file=@"path/to/your/local/JohnSmith.png" +``` + +Make sure to replace `path/to/your/local/JohnSmith.png` with the actual path to your local image file. + +### Step 3: Prepare Your Image Annotation Request + +Now, let's create a request to add an image annotation to your document. The following parameters are important for image annotations: + +- Type: Must be set to "Image" +- ImagePath: Path to the image file in your cloud storage +- Box: Defines the position and dimensions where the image will be placed +- PageNumber: Indicates which page to annotate +- Opacity: Controls the transparency of the image + +Here's a sample cURL request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d " +{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'Output/output.docx', + 'Annotations': [ + { + 'Type': 'Image', + 'Text': 'This is image annotation', + 'ImagePath': 'JohnSmith.png', + 'CreatorName': 'Anonym A.', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 200, + 'Height': 100 + }, + 'PageNumber': 0, + 'Replies': [ + { + 'Comment': 'First comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + }, + { + 'Comment': 'Second comment', + 'RepliedOn': '2023-01-15T06:52:01.376Z' + } + ], + 'CreatedOn': '2023-01-15T06:52:01.376Z', + 'Opacity': 0.7 + } +] +} +" +``` + +### Step 4: Execute the Request + +Execute the prepared request to add the image annotation to your document. The API will return a response with a link to your annotated document. + +### Step 5: Analyze the Response + +After executing the request, you'll receive a response similar to the following: + +```json +{ + "href": "https://api.groupdocs.cloud/v2.0/annotation/storage/file/Output/output.docx", + "rel": "self", + "type": "file", + "title": "output.docx" +} +``` + +This response provides a link to your annotated document stored in your cloud storage. + +### Step 6: Download and Verify the Annotated Document + +You can download the annotated document using the link provided in the response. Open the document to verify that your image annotation appears correctly. + +## Important Parameters for Image Annotations + +When working with image annotations, it's important to understand the key parameters: + +1. ImagePath: The path to the image file in your cloud storage. This must be accurately specified, or the annotation will fail. +2. Box: Defines the position (X, Y) and size (Width, Height) of the image annotation. Make sure to set appropriate values for your document. +3. Opacity: Controls the transparency of the image. Values range from 0.0 (completely transparent) to 1.0 (completely opaque). +4. PageNumber: Specifies the page on which the image annotation will appear. Page numbering starts from 0. + +## SDK Examples + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "one-page.docx" }; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + Box = new Rectangle { X = 100, Y = 100, Width = 200, Height = 100 }, + PageNumber = 0, + Type = AnnotationInfo.TypeEnum.Image, + ImagePath = "JohnSmith.png", + Text = "This is image annotation", + CreatorName = "Anonym A.", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "First comment", + RepliedOn = DateTime.Now + }, + new AnnotationReplyInfo + { + Comment = "Second comment", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "Output/output.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("AddImageAnnotation: Image Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +String MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyAppSid, MyAppKey); + +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation/s. +AnnotationInfo[] annotations = new AnnotationInfo[1]; +annotations[0] = new AnnotationInfo(); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(200.0); +r.setHeight(100.0); + +annotations[0].setBox(r); +annotations[0].setImagePath("Annotationdocs\\JohnSmith.png"); +annotations[0].setPageNumber(0); +annotations[0].setType(TypeEnum.IMAGE); +annotations[0].setText("This is image annotation"); +annotations[0].setCreatorName("Anonym A."); + +// Create request object. +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Annotationdocs\\one-page.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("Output/one-page-annotated.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Executing api method. +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("AddImageAnnotation: image Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +a1 = groupdocs_annotation_cloud.AnnotationInfo() +a1.box = groupdocs_annotation_cloud.Rectangle() +a1.box.x = 100 +a1.box.y = 100 +a1.box.width = 200 +a1.box.height = 100 +a1.page_number = 0 +a1.opacity = 0.7 +a1.type = "Image" +a1.text = "This is Image annotation" +a1.creator_name = "Anonym A." +a1.image_path = "annotationdocs\\JohnSmith.png" + +file_info = FileInfo() +file_info.file_path = "annotationdocs\\one-page.docx" +options = AnnotateOptions() +options.file_info = file_info +options.annotations = [a1] +options.output_path = "Output\\output.docx" + +request = AnnotateRequest(options) +result = api.annotate(request) + +print("AddImageAnnotation: Image Annotation added: " + result['href']) +``` + +## Image Formatting and Size Considerations + +When working with image annotations, keep these important considerations in mind: + +1. Image Formats: The GroupDocs.Annotation Cloud API supports common image formats like PNG, JPG, JPEG, BMP, and GIF. +2. Image Size: Large images may be scaled to fit within the specified box dimensions. Choose appropriate box dimensions to maintain image clarity. +3. Resolution: Higher resolution images will appear clearer in the document, but may increase the document size. +4. Aspect Ratio: The image will be scaled to fit within the box dimensions, which may distort the image if the box's aspect ratio differs from the image's aspect ratio. + +## Troubleshooting Tips + +1. Missing Image: If your image annotation doesn't appear, check that the ImagePath is correct and the image file exists in your cloud storage. +2. Image Size Issues: If the image appears too small or too large, adjust the Width and Height values in the Box parameter. +3. Image Quality: If the image appears distorted or blurry, try uploading a higher-resolution image or adjusting the box dimensions to match the image's aspect ratio. +4. File Format Problems: If the image doesn't display correctly, ensure you're using a supported image format. + +## What You've Learned + +In this tutorial, you've learned: +- How to upload image files to your cloud storage +- How to create and add image annotations to documents +- The essential parameters for configuring image annotations +- How to customize the appearance and position of image annotations +- How to implement image annotations in different programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Add multiple image annotations to a single document +2. Experiment with different image formats to compare quality and file size +3. Try overlapping image annotations with different opacity levels +4. Create image annotations of different sizes and positions + +## Next Tutorial + +Ready to learn about more annotation types? Proceed to our next tutorial on [How to Add Image Annotations](/advanced-features/image-annotation/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/multiple-annotations/_index.md b/content/annotation/english/advanced-features/multiple-annotations/_index.md new file mode 100644 index 0000000..41f45a1 --- /dev/null +++ b/content/annotation/english/advanced-features/multiple-annotations/_index.md @@ -0,0 +1,425 @@ +--- +title: How to Add Multiple Annotations in GroupDocs.Annotation Cloud Tutorial +description: Learn how to add multiple annotations to documents in a single API call using the GroupDocs.Annotation Cloud API in this comprehensive tutorial +weight: 170 +url: /advanced-features/multiple-annotations/ +--- + +# Tutorial: How to Add Multiple Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Add multiple annotation types to a document in a single API call +- Configure different properties for each annotation type +- Optimize annotation processes for multi-user scenarios +- Implement advanced annotation patterns in various programming languages + +## What are Multiple Annotations? + +Multiple annotations allow you to add different types of annotations (arrows, areas, text highlights, etc.) to a document in a single API request. This improves performance and creates a more efficient workflow when annotating documents collaboratively. + +## Prerequisites + +Before starting this tutorial, ensure you have: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. A sample multi-page document uploaded to your GroupDocs.Annotation Cloud storage + +## Implementation Steps + +Let's walk through the process of adding multiple annotations to a document: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Define Multiple Annotation Properties + +For multiple annotations, you'll need to: +- Create an array of annotation objects +- Define properties for each annotation type +- Specify page numbers for each annotation (can be different pages) + +### 3. Add Multiple Annotations + +Use the `POST /annotation/add` endpoint to add multiple annotations: + +```javascript +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'multi-page-document.docx' + }, + 'OutputPath': 'output/annotated-document.docx', + 'Annotations': [ + { + 'Type': 'Area', + 'Text': 'This is area annotation', + 'CreatorName': 'John Doe', + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 100, + 'Height': 100 + }, + 'PageNumber': 0, + 'PenColor': 65535, + 'PenWidth': 3 + }, + { + 'Type': 'Point', + 'CreatorName': 'John Doe', + 'Box': { + 'X': 375, + 'Y': 59, + 'Width': 88, + 'Height': 37 + }, + 'PageNumber': 2, + 'AnnotationPosition': { + 'X': 852, + 'Y': 59 + } + }, + { + 'Type': 'TextHighlight', + 'Text': 'Text to highlight', + 'CreatorName': 'John Doe', + 'Points': [ + { + 'X': 80, + 'Y': 730 + }, + { + 'X': 240, + 'Y': 730 + }, + { + 'X': 80, + 'Y': 650 + }, + { + 'X': 240, + 'Y': 650 + } + ], + 'PageNumber': 1, + 'BackgroundColor': 16711680 + } + ] +}" +``` + +### 4. Download the Annotated Document + +After successful annotation, download your annotated document using the File API. + +## Try It Yourself + +Now, try implementing multiple annotations in your preferred programming language. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "multi-page-document.docx" }; + +// Create multiple annotation objects +AnnotationInfo[] annotations = +{ + // Area annotation on page 0 + new AnnotationInfo + { + AnnotationPosition = new Point { X = 1, Y = 1 }, + Box = new Rectangle { X = 100, Y = 100, Width = 100, Height = 100 }, + PageNumber = 0, + BackgroundColor = 65535, + PenColor = 65535, + PenStyle = AnnotationInfo.PenStyleEnum.Solid, + PenWidth = 3, + Type = AnnotationInfo.TypeEnum.Area, + Text = "This is area annotation", + CreatorName = "John Doe", + CreatedOn = DateTime.Now + }, + + // Point annotation on page 2 + new AnnotationInfo + { + AnnotationPosition = new Point { X = 852, Y = 59.388262910798119 }, + Box = new Rectangle { X = 375.89276123046875, Y = 59.388263702392578, Width = 88.7330551147461, Height = 37.7290153503418 }, + PageNumber = 2, + Type = AnnotationInfo.TypeEnum.Point, + CreatorName = "John Doe", + CreatedOn = DateTime.Now + }, + + // Text highlight annotation on page 1 + new AnnotationInfo + { + Points = new List + { + new Point {X = 80, Y = 730}, new Point {X=240, Y=730}, new Point {X=80, Y=650}, new Point {X=240, Y=650} + }, + BackgroundColor = 16711680, // Yellow + PageNumber = 1, + Type = AnnotationInfo.TypeEnum.TextHighlight, + Text = "Text to highlight", + CreatorName = "John Doe", + CreatedOn = DateTime.Now + } +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "output/multi-annotated-document.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("Multiple Annotations added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation objects +AnnotationInfo[] annotations = new AnnotationInfo[3]; + +// Area annotation on page 0 +annotations[0] = new AnnotationInfo(); +Point pt = new Point(); +pt.setX(1.0); +pt.setY(1.0); +annotations[0].setAnnotationPosition(pt); + +Rectangle r = new Rectangle(); +r.setX(100.0); +r.setY(100.0); +r.setWidth(100.0); +r.setHeight(100.0); + +annotations[0].setBox(r); +annotations[0].setPageNumber(0); +annotations[0].setPenColor(65535); +annotations[0].setPenStyle(PenStyleEnum.SOLID); +annotations[0].setPenWidth(3); +annotations[0].setType(TypeEnum.AREA); +annotations[0].setText("This is area annotation"); +annotations[0].setCreatorName("John Doe"); + +// Point annotation on page 2 +annotations[1] = new AnnotationInfo(); +Point pt2 = new Point(); +pt2.setX(852.0); +pt2.setY(59.388262910798119); +annotations[1].setAnnotationPosition(pt2); + +Rectangle r2 = new Rectangle(); +r2.setX(375.89276123046875); +r2.setY(59.388263702392578); +r2.setWidth(88.7330551147461); +r2.setHeight(37.7290153503418); +annotations[1].setBox(r2); +annotations[1].setPageNumber(2); +annotations[1].setType(TypeEnum.POINT); +annotations[1].setCreatorName("John Doe"); + +// Text highlight annotation on page 1 +annotations[2] = new AnnotationInfo(); +Point[] points = new Point[4]; +points[0] = new Point(); +points[0].setX(80.0); +points[0].setY(730.0); +points[1] = new Point(); +points[1].setX(240.0); +points[1].setY(730.0); +points[2] = new Point(); +points[2].setX(80.0); +points[2].setY(650.0); +points[3] = new Point(); +points[3].setX(240.0); +points[3].setY(650.0); +annotations[2].setPoints(Arrays.asList(points)); +annotations[2].setPageNumber(1); +annotations[2].setBackgroundColor(16711680); // Yellow +annotations[2].setType(TypeEnum.TEXTHIGHLIGHT); +annotations[2].setText("Text to highlight"); +annotations[2].setCreatorName("John Doe"); + +// Create request object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("multi-page-document.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Arrays.asList(annotations)); +options.setOutputPath("output/multi-annotated-document.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Execute API method +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("Multiple Annotations added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Create area annotation for page 0 +area_annotation = groupdocs_annotation_cloud.AnnotationInfo() +area_annotation.annotation_position = groupdocs_annotation_cloud.Point() +area_annotation.annotation_position.x = 1 +area_annotation.annotation_position.y = 1 +area_annotation.box = groupdocs_annotation_cloud.Rectangle() +area_annotation.box.x = 100 +area_annotation.box.y = 100 +area_annotation.box.width = 100 +area_annotation.box.height = 100 +area_annotation.page_number = 0 +area_annotation.pen_color = 65535 +area_annotation.pen_style = "Solid" +area_annotation.pen_width = 3 +area_annotation.type = "Area" +area_annotation.text = "This is area annotation" +area_annotation.creator_name = "John Doe" + +# Create point annotation for page 2 +point_annotation = groupdocs_annotation_cloud.AnnotationInfo() +point_annotation.annotation_position = groupdocs_annotation_cloud.Point() +point_annotation.annotation_position.x = 852 +point_annotation.annotation_position.y = 59 +point_annotation.box = groupdocs_annotation_cloud.Rectangle() +point_annotation.box.x = 375 +point_annotation.box.y = 59 +point_annotation.box.width = 88 +point_annotation.box.height = 37 +point_annotation.page_number = 2 +point_annotation.type = "Point" +point_annotation.creator_name = "John Doe" + +# Create text highlight annotation for page 1 +highlight_annotation = groupdocs_annotation_cloud.AnnotationInfo() +p1 = groupdocs_annotation_cloud.Point() +p1.x = 80 +p1.y = 730 +p2 = groupdocs_annotation_cloud.Point() +p2.x = 240 +p2.y = 730 +p3 = groupdocs_annotation_cloud.Point() +p3.x = 80 +p3.y = 650 +p4 = groupdocs_annotation_cloud.Point() +p4.x = 240 +p4.y = 650 +highlight_annotation.points = [p1, p2, p3, p4] +highlight_annotation.page_number = 1 +highlight_annotation.background_color = 16711680 # Yellow +highlight_annotation.type = "TextHighlight" +highlight_annotation.text = "Text to highlight" +highlight_annotation.creator_name = "John Doe" + +# Set up options +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "multi-page-document.docx" + +options = groupdocs_annotation_cloud.AnnotateOptions() +options.file_info = file_info +options.annotations = [area_annotation, point_annotation, highlight_annotation] +options.output_path = "output/multi-annotated-document.docx" + +request = groupdocs_annotation_cloud.AnnotateRequest(options) +result = api.annotate(request) + +print("Multiple Annotations added: " + result.title) +``` + +## Best Practices for Multiple Annotations + +1. Batch Processing: Group related annotations together in a single API call to reduce network overhead. + +2. Page Organization: Organize annotations by page number to make document review easier. + +3. Performance Considerations: While you can add many annotations in a single call, very large batches (hundreds of annotations) may impact performance. Consider splitting very large annotation sets into multiple reasonable-sized batches. + +4. Error Handling: When adding multiple annotations, implement robust error handling to identify which specific annotations failed, if any. + +5. Annotation IDs: Keep track of annotation IDs returned by the API to allow for later updates or deletions of specific annotations. + +## Troubleshooting Tips + +1. Mixed Annotation Types: Ensure each annotation object has the correct Type property set to avoid rendering issues +2. Page Numbers: Verify all page numbers are within the document's page range (remember, page numbers are zero-based) +3. Coordinate Systems: Different annotation types may use coordinates differently - check documentation for each type +4. Output Path: Ensure the output path directory exists in your cloud storage + +## What You've Learned + +In this tutorial, you've learned how to: +- Add multiple different types of annotations to a document in a single API call +- Configure properties specific to each annotation type +- Optimize annotation processes for better performance +- Implement multiple annotation patterns in different programming languages + +## Further Practice + +To enhance your understanding of multiple annotations, try these exercises: +1. Create a workflow that adds different annotation types based on document content +2. Implement a solution that allows multiple users to add annotations to the same document +3. Add annotations to all pages of a large document efficiently +4. Create a pattern for programmatically generating annotations based on document analysis + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations/) +- [Tutorial: How to Delete Annotations](/advanced-features/delete-annotations/) +- [Tutorial: How to Get Document Pages](/advanced-features/get-document-pages/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/advanced-features/text-redaction/_index.md b/content/annotation/english/advanced-features/text-redaction/_index.md new file mode 100644 index 0000000..b12fe6e --- /dev/null +++ b/content/annotation/english/advanced-features/text-redaction/_index.md @@ -0,0 +1,324 @@ +--- +title: How to Add Text Redaction Annotations in GroupDocs.Annotation Cloud Tutorial +description: Learn how to securely redact sensitive text in documents using the GroupDocs.Annotation Cloud API in this step-by-step tutorial +weight: 110 +url: /advanced-features/text-redaction/ +--- + +# Tutorial: How to Add Text Redaction Annotations + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Add text redaction annotations to securely hide sensitive text in documents +- Configure redaction properties and appearance +- Implement text redaction in different programming languages +- Create a secure workflow for handling sensitive information + +## What is a Text Redaction Annotation? + +Text redaction annotations allow you to permanently hide sensitive text in documents by replacing it with black rectangles. Unlike other annotation types that can be removed, redaction permanently removes the underlying text, making it ideal for securing sensitive information in documents before sharing them. + +## Prerequisites + +Before you begin: +1. A GroupDocs.Annotation Cloud account (or [get a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret credentials +3. A development environment for your preferred language +4. A sample document uploaded to your GroupDocs.Annotation Cloud storage + +## Implementation Steps + +Let's walk through the process of adding text redaction annotations to a document: + +### 1. Authentication + +First, authenticate with the GroupDocs.Annotation Cloud API: + +```javascript +// Get JWT token +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Save the received JWT token for subsequent API calls. + +### 2. Define Text Redaction Properties + +Text redaction annotations require the following properties: +- Coordinates of the text area to redact (Points array) +- Page number +- Creator information +- Optional comments (replies) + +### 3. Add the Text Redaction Annotation + +Use the `POST /annotation/add` endpoint to add the text redaction: + +```javascript +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'your-document.docx' + }, + 'OutputPath': 'output/redacted-document.docx', + 'Annotations': [ + { + 'Type': 'TextRedaction', + 'Text': 'This text will be redacted', + 'CreatorName': 'Security Officer', + 'Points': [ + { + 'X': 80, + 'Y': 730 + }, + { + 'X': 240, + 'Y': 730 + }, + { + 'X': 80, + 'Y': 650 + }, + { + 'X': 240, + 'Y': 650 + } + ], + 'PageNumber': 0, + 'Replies': [ + { + 'Comment': 'Sensitive information redacted', + 'RepliedOn': '2023-04-25T12:00:00.000Z' + } + ] + } + ] +}" +``` + +### 4. Download the Redacted Document + +After successful redaction, download your redacted document using the File API. + +## Try It Yourself + +Now, try implementing text redaction annotations in your preferred programming language. + +### C# Example + +```csharp +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = "YOUR_APP_KEY"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = "YOUR_APP_SID"; + +var configuration = new Configuration(MyAppSid, MyAppKey); +var apiInstance = new AnnotateApi(configuration); + +var fileInfo = new FileInfo { FilePath = "input/document-with-sensitive-info.docx" }; + +AnnotationInfo[] annotations = +{ + new AnnotationInfo + { + Points = new List + { + new Point {X = 80, Y = 730}, + new Point {X = 240, Y = 730}, + new Point {X = 80, Y = 650}, + new Point {X = 240, Y = 650} + }, + PageNumber = 0, + Type = AnnotationInfo.TypeEnum.TextRedaction, + Text = "This text will be redacted", + CreatorName = "Security Officer", + CreatedOn = DateTime.Now, + Replies = new List + { + new AnnotationReplyInfo + { + Comment = "Sensitive information redacted", + RepliedOn = DateTime.Now + } + } + }, +}; + +var options = new AnnotateOptions +{ + FileInfo = fileInfo, + Annotations = annotations.ToList(), + OutputPath = "output/redacted-document.docx" +}; + +var link = apiInstance.Annotate(new AnnotateRequest(options)); +Console.WriteLine("Text Redaction Annotation added: " + link.Title); +``` + +### Java Example + +```java +// For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-java-samples +String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String clientSecret = "YOUR_CLIENT_SECRET"; + +Configuration configuration = new Configuration(clientId, clientSecret); +AnnotateApi apiInstance = new AnnotateApi(configuration); + +// Create annotation +AnnotationInfo annotation = new AnnotationInfo(); + +Point[] points = new Point[4]; +points[0] = new Point(); +points[0].setX(80.0); +points[0].setY(730.0); +points[1] = new Point(); +points[1].setX(240.0); +points[1].setY(730.0); +points[2] = new Point(); +points[2].setX(80.0); +points[2].setY(650.0); +points[3] = new Point(); +points[3].setX(240.0); +points[3].setY(650.0); + +annotation.setPoints(Arrays.asList(points)); +annotation.setPageNumber(0); +annotation.setType(TypeEnum.TEXTREDACTION); +annotation.setText("This text will be redacted"); +annotation.setCreatorName("Security Officer"); + +// Create reply/comment +AnnotationReplyInfo reply = new AnnotationReplyInfo(); +reply.setComment("Sensitive information redacted"); +reply.setRepliedOn(OffsetDateTime.now()); +annotation.setReplies(Collections.singletonList(reply)); + +// Create request object +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("input/document-with-sensitive-info.docx"); + +AnnotateOptions options = new AnnotateOptions(); +options.setFileInfo(fileInfo); +options.setAnnotations(Collections.singletonList(annotation)); +options.setOutputPath("output/redacted-document.docx"); + +AnnotateRequest request = new AnnotateRequest(options); + +// Execute API method +AnnotationApiLink result = apiInstance.annotate(request); + +System.out.println("Text Redaction Annotation added: " + result.getTitle()); +``` + +### Python Example + +```python +# For complete examples, visit: https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud +from datetime import datetime + +app_sid = "YOUR_APP_SID" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "YOUR_APP_KEY" + +api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Create annotation +annotation = groupdocs_annotation_cloud.AnnotationInfo() + +# Define points for text redaction +p1 = groupdocs_annotation_cloud.Point() +p1.x = 80 +p1.y = 730 +p2 = groupdocs_annotation_cloud.Point() +p2.x = 240 +p2.y = 730 +p3 = groupdocs_annotation_cloud.Point() +p3.x = 80 +p3.y = 650 +p4 = groupdocs_annotation_cloud.Point() +p4.x = 240 +p4.y = 650 +annotation.points = [p1, p2, p3, p4] + +annotation.page_number = 0 +annotation.type = "TextRedaction" +annotation.text = "This text will be redacted" +annotation.creator_name = "Security Officer" + +# Create reply/comment +reply = groupdocs_annotation_cloud.AnnotationReplyInfo() +reply.comment = "Sensitive information redacted" +reply.replied_on = datetime.now().isoformat() +annotation.replies = [reply] + +# Set up options +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "input/document-with-sensitive-info.docx" + +options = groupdocs_annotation_cloud.AnnotateOptions() +options.file_info = file_info +options.annotations = [annotation] +options.output_path = "output/redacted-document.docx" + +request = groupdocs_annotation_cloud.AnnotateRequest(options) +result = api.annotate(request) + +print("Text Redaction Annotation added: " + result.title) +``` + +## Security Considerations for Text Redaction + +When implementing text redaction, keep these security best practices in mind: + +1. Permanent Redaction: Text redaction in GroupDocs.Annotation Cloud is permanent - the original text cannot be recovered after redaction. + +2. Review Before Sharing: Always review redacted documents before sharing them to ensure all sensitive content has been properly redacted. + +3. Metadata Check: Remember that document metadata might contain sensitive information. Consider using additional tools to remove metadata. + +4. Access Control: Implement proper access controls to ensure only authorized personnel can perform redactions. + +5. Audit Trail: Maintain an audit trail of all redaction activities for compliance purposes. + +## Troubleshooting Tips + +1. Text Not Fully Redacted: Ensure the Points array completely covers the text to be redacted +2. Redaction Not Visible: Check that the page number is correct (zero-based) +3. Redaction Box Size: If the redaction box is too small, adjust the Points coordinates + +## What You've Learned + +In this tutorial, you've learned: +- How to implement text redaction annotations to permanently hide sensitive information +- Best practices for secure document redaction +- How to implement the redaction process in different programming languages +- Security considerations for document redaction workflows + +## Further Practice + +To enhance your understanding of text redaction, try these exercises: +1. Redact multiple sections of text in a single document +2. Create a workflow that identifies personally identifiable information (PII) and applies redactions automatically +3. Combine text redaction with resource redaction to create fully sanitized documents + +## Next Steps + +Continue your learning journey with these related tutorials: +- [Tutorial: How to Add Multiple Annotations](/advanced-features/multiple-annotations/) +- [Tutorial: How to Extract Annotations](/advanced-features/extract-annotations/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/_index.md b/content/annotation/english/getting-started/_index.md new file mode 100644 index 0000000..cf82dc2 --- /dev/null +++ b/content/annotation/english/getting-started/_index.md @@ -0,0 +1,57 @@ +--- +title: GroupDocs.Annotation Cloud API Getting Started Tutorials +weight: 1 +url: /getting-started/ +description: Step-by-step tutorials to help developers get started with GroupDocs.Annotation Cloud API +--- + +# GroupDocs.Annotation Cloud API Getting Started Tutorials + +Welcome to our comprehensive tutorial series for GroupDocs.Annotation Cloud API! These hands-on tutorials are designed to help developers quickly learn how to implement document annotation features in their applications using our powerful cloud-based API. + +## Learning Path + +Our tutorials follow a structured learning path, taking you from the basics to more advanced implementations: + +1. Beginner Level - Learn fundamental API concepts and basic operations +2. Intermediate Level - Explore annotation types and document manipulation +3. Advanced Level - Implement complex annotation scenarios and integrations + +## Available Tutorials + +### Basic Usage Tutorials + +- [Tutorial: How to Get Supported File Formats](/getting-started/get-supported-file-formats/) - Learn to retrieve all file formats supported by GroupDocs.Annotation Cloud API. + +- [Tutorial: How to Get Document Information](/getting-started/get-document-information/) - Master the process of extracting document metadata and page information using the API. + +### Working with Annotations + +- [Tutorial: How to Add Annotations to a Document](/getting-started/add-annotations/) - Learn to add various types of annotations to your documents programmatically. + +### Document Operations + +- [Tutorial: How to Convert Annotated Documents](/getting-started/convert-documents/) - Learn to convert documents with annotations to different formats. + +- [Tutorial: How to Delete Annotations](/getting-started/delete-annotations/) - Master the process of removing specific annotations from documents. + +- [Tutorial: How to Preview Documents](/getting-started/preview-documents/) - Discover how to generate document previews and thumbnails. + +## Prerequisites + +To follow these tutorials, you'll need: + +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Basic knowledge of REST APIs +3. Familiarity with at least one programming language (C#, Java, Python, PHP, Ruby, or Node.js) +4. Your preferred IDE or code editor + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.annotation-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/add-annotations/_index.md b/content/annotation/english/getting-started/add-annotations/_index.md new file mode 100644 index 0000000..a87c98d --- /dev/null +++ b/content/annotation/english/getting-started/add-annotations/_index.md @@ -0,0 +1,343 @@ +--- +title: How to Add Annotations to Documents with GroupDocs.Annotation Cloud API Tutorial +weight: 1 +url: /getting-started/add-annotations/ +description: Learn how to add different types of annotations to documents using GroupDocs.Annotation Cloud API in this step-by-step developer tutorial +--- + +# Tutorial: How to Add Annotations to Documents with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Add various types of annotations to documents using the GroupDocs.Annotation Cloud API +- Configure annotation properties such as position, color, and opacity +- Understand the different annotation types and their specific properties +- Implement annotation functionality in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your storage (or you can use the sample documents provided by the API) +4. Completed the [Get Document Information tutorial](/getting-started/get-document-information/) (recommended) +5. Basic knowledge of REST APIs +6. A development environment set up with your preferred language + +## Practical Scenario + +Imagine you're developing a document review system where multiple team members need to provide feedback on documents. Your application needs to support different annotation types like highlighting text, adding comments, marking areas, and drawing arrows to point out specific elements. This tutorial will show you how to implement these annotation capabilities. + +## Understanding Annotation Types + +GroupDocs.Annotation Cloud API supports several annotation types: + +1. Area Annotation: Highlights a rectangular area on the page +2. Point Annotation: Places a point marker at a specific location +3. Text Annotation: Adds text notes with optional comments +4. Text Highlight Annotation: Highlights text within the document +5. Text Strikeout Annotation: Strikes through text +6. Text Underline Annotation: Underlines text +7. Polyline Annotation: Creates lines and shapes with multiple points +8. Arrow Annotation: Draws an arrow pointing to specific content +9. Watermark Annotation: Adds text watermarks to pages +10. Distance Annotation: Measures distance between two points + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides an endpoint to add annotations to a document: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/add +``` + +This endpoint requires you to specify the document path and annotation objects in the request body. + +### 2. Preparing the Annotation Request + +To add annotations, you'll need to: +1. Specify the input document path +2. Provide annotation objects with their properties +3. Optionally specify output options (like the output file path) + +### 3. Creating an Area Annotation + +Let's start with a simple example - adding an area annotation to highlight a rectangular region on a page: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'output/annotated-with-area.docx', + 'Annotations': [ + { + 'Type': 'Area', + 'PageNumber': 1, + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 200, + 'Height': 100 + }, + 'BackgroundColor': 16761035, + 'Opacity': 0.7 + } + ] +}" +``` + +This request will: +- Take the document at `annotationdocs/one-page.docx` +- Add a pink semi-transparent area annotation on page 1 +- Save the result to `output/annotated-with-area.docx` + +### 4. Understanding Annotation Properties + +Each annotation type has specific properties. Here are some common ones: + +- Type: Specifies the annotation type (Area, Point, Text, etc.) +- PageNumber: The page where the annotation should appear (1-based) +- Box: Position and size of the annotation (X, Y, Width, Height) +- BackgroundColor: Color of the annotation (RGB integer value) +- Opacity: Transparency level (0.0 to 1.0) +- Text: Text content for text-based annotations +- FontColor: Color of the text +- FontSize: Size of the text +- Points: Array of points for polyline annotations + +### 5. Adding Multiple Annotation Types + +Let's see how to add multiple annotation types in a single request: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/add" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/one-page.docx' + }, + 'OutputPath': 'output/multi-annotated.docx', + 'Annotations': [ + { + 'Type': 'Area', + 'PageNumber': 1, + 'Box': { + 'X': 100, + 'Y': 100, + 'Width': 200, + 'Height': 100 + }, + 'BackgroundColor': 16761035, + 'Opacity': 0.7 + }, + { + 'Type': 'Point', + 'PageNumber': 1, + 'Box': { + 'X': 50, + 'Y': 50, + 'Width': 0, + 'Height': 0 + } + }, + { + 'Type': 'Text', + 'PageNumber': 1, + 'Box': { + 'X': 300, + 'Y': 200, + 'Width': 200, + 'Height': 30 + }, + 'Text': 'This is a text annotation', + 'FontColor': 255, + 'FontSize': 12 + } + ] +}" +``` + +This request adds an area annotation, a point annotation, and a text annotation to the document. + +### 6. Implementing in C# + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create AnnotateApi instance +var apiInstance = new AnnotateApi(configuration); + +// Create file info object +var fileInfo = new FileInfo +{ + FilePath = "annotationdocs/one-page.docx" +}; + +// Create a collection of annotations +var annotations = new List +{ + // Area annotation + new AnnotationInfo + { + Type = AnnotationInfo.TypeEnum.Area, + PageNumber = 1, + Box = new Rectangle + { + X = 100, + Y = 100, + Width = 200, + Height = 100 + }, + BackgroundColor = 16761035, // RGB color (Pink) + Opacity = 0.7 + }, + + // Text annotation + new AnnotationInfo + { + Type = AnnotationInfo.TypeEnum.Text, + PageNumber = 1, + Box = new Rectangle + { + X = 300, + Y = 200, + Width = 200, + Height = 30 + }, + Text = "This is a text annotation", + FontColor = 255, // RGB color (Blue) + FontSize = 12 + } +}; + +// Create request object +var request = new AnnotateRequest(fileInfo, annotations) +{ + OutputPath = "output/annotated-document.docx" +}; + +// Call API method +var result = apiInstance.Annotate(request); + +// Process the result +Console.WriteLine($"Document saved to {result.Path}"); +``` + +### 7. Implementing in Python + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +annotate_api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Create file info object +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotationdocs/one-page.docx" + +# Create annotations +annotations = [] + +# Area annotation +area_annotation = groupdocs_annotation_cloud.AnnotationInfo() +area_annotation.type = "Area" +area_annotation.page_number = 1 +area_annotation.box = groupdocs_annotation_cloud.Rectangle() +area_annotation.box.x = 100 +area_annotation.box.y = 100 +area_annotation.box.width = 200 +area_annotation.box.height = 100 +area_annotation.background_color = 16761035 # RGB color (Pink) +area_annotation.opacity = 0.7 +annotations.append(area_annotation) + +# Arrow annotation +arrow_annotation = groupdocs_annotation_cloud.AnnotationInfo() +arrow_annotation.type = "Arrow" +arrow_annotation.page_number = 1 +arrow_annotation.box = groupdocs_annotation_cloud.Rectangle() +arrow_annotation.box.x = 400 +arrow_annotation.box.y = 400 +arrow_annotation.box.width = 100 +arrow_annotation.box.height = 100 +annotations.append(arrow_annotation) + +# Create request +request = groupdocs_annotation_cloud.AnnotateRequest(file_info, annotations) +request.output_path = "output/annotated-document.docx" + +# Call API method +result = annotate_api.annotate(request) + +# Process the result +print(f"Document saved to {result.path}") +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing annotations in your own application: + +1. Get your API credentials from the dashboard +2. Upload a document to your storage or use a sample document +3. Choose your preferred programming language +4. Decide which annotation types you want to add +5. Configure the annotation properties (position, colors, etc.) +6. Run the code and observe the results + +## Troubleshooting Tips + +- Annotation Position Issues: If annotations don't appear where expected, make sure you've retrieved the document information first to understand page dimensions. +- Color Formatting: Colors are represented as RGB integer values. Use online color pickers to find the right values for your annotations. +- Annotation Type Errors: Double-check that you're using the correct properties for each annotation type. Some properties are specific to certain annotation types. +- Authentication Errors: Verify your AppSID and AppKey are correctly set up. +- File Not Found Errors: Make sure the document path is correct and the file exists in your storage. + +## What You've Learned + +In this tutorial, you have learned: +- How to add different types of annotations to documents using the GroupDocs.Annotation Cloud API +- How to configure annotation properties like position, color, and opacity +- How to use different annotation types for specific scenarios +- How to implement annotation functionality in C# and Python + +## Further Practice + +To solidify your understanding: +1. Try adding other annotation types not covered in this tutorial +2. Create a function that adds annotations based on user input (e.g., from a form) +3. Implement a feature to annotate multiple pages in a single request +4. Add annotations with different colors, opacity levels, and text formatting + +## Next Steps + +Ready to learn more? Check out our next tutorial on extracting annotations from documents. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + diff --git a/content/annotation/english/getting-started/convert-documents/_index.md b/content/annotation/english/getting-started/convert-documents/_index.md new file mode 100644 index 0000000..579f958 --- /dev/null +++ b/content/annotation/english/getting-started/convert-documents/_index.md @@ -0,0 +1,367 @@ +--- +title: How to Convert Annotated Documents with GroupDocs.Annotation Cloud API Tutorial +weight: 1 +url: /getting-started/convert-documents/ +description: Learn how to convert annotated documents to different formats using GroupDocs.Annotation Cloud API in this comprehensive developer tutorial +--- + +# Tutorial: How to Convert Annotated Documents with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Convert annotated documents to different formats using the GroupDocs.Annotation Cloud API +- Control how annotations appear in the output document +- Specify conversion options for different target formats +- Implement document conversion in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document with annotations uploaded to your storage (ideally, follow the [Add Annotations tutorial](/getting-started/add-annotations/) first to create one) +4. Basic knowledge of REST APIs +5. A development environment set up with your preferred language + +## Practical Scenario + +When working with annotated documents, you often need to convert them to different formats for various purposes. For example, you might want to: +- Convert a Word document with annotations to PDF for easier sharing +- Convert an annotated PDF to an image format for presentation +- Export documents with or without annotations for different audiences +- Preserve annotations when converting between formats + +This tutorial shows you how to implement these document conversion scenarios. + +## Understanding Supported Conversion Formats + +GroupDocs.Annotation Cloud API supports converting documents with annotations to various formats, including: +- PDF +- Word documents (DOCX, DOC) +- Excel spreadsheets (XLSX, XLS) +- PowerPoint presentations (PPTX, PPT) +- Images (PNG, JPG) +- HTML +- And more + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides an endpoint to convert documents: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/convert +``` + +This endpoint requires you to specify the document path and conversion options in the request body. + +### 2. Basic Document Conversion + +Let's start with a basic example - converting a Word document with annotations to PDF: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/convert" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/annotated-sample.docx' + }, + 'Format': 'pdf', + 'OutputPath': 'output/converted-document.pdf' +}" +``` + +This request will: +- Take the document at `annotationdocs/annotated-sample.docx` +- Convert it to PDF format while preserving the annotations +- Save the result to `output/converted-document.pdf` + +### 3. Converting with Specific Options + +You can customize the conversion process using various options. For example, when converting to PDF, you can set password protection: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/convert" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/annotated-sample.docx' + }, + 'Format': 'pdf', + 'OutputPath': 'output/password-protected.pdf', + 'ConvertOptions': { + 'PdfOptions': { + 'Password': 'p@s$w0rd', + 'PdfFormat': 'PDF' + } + } +}" +``` + +### 4. Controlling Annotation Appearance + +When converting documents, you can control how annotations appear in the output document. For example, you can: +- Choose to include or exclude annotations +- Control annotation visibility +- Set annotation properties like color, opacity, etc. + +These settings are typically specified in the API implementation rather than through the REST API directly. + +### 5. Implementing in C# + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create AnnotateApi instance +var apiInstance = new AnnotateApi(configuration); + +// Create file info object +var fileInfo = new FileInfo +{ + FilePath = "annotationdocs/annotated-sample.docx" +}; + +// Basic conversion to PDF +Console.WriteLine("Converting document to PDF..."); +var convertRequest = new ConvertRequest(fileInfo, "pdf") +{ + OutputPath = "output/converted-document.pdf" +}; + +var convertResult = apiInstance.Convert(convertRequest); +Console.WriteLine($"Document converted successfully to PDF. Saved to {convertResult.Path}"); + +// Conversion to PDF with password protection +Console.WriteLine("\nConverting document to password-protected PDF..."); +var pdfOptions = new PdfConvertOptions +{ + Password = "p@s$w0rd", + PdfFormat = PdfConvertOptions.PdfFormatEnum.PDF +}; + +var convertWithOptionsRequest = new ConvertRequest(fileInfo, "pdf") +{ + OutputPath = "output/password-protected.pdf", + ConvertOptions = new ConvertOptions { PdfOptions = pdfOptions } +}; + +var convertWithOptionsResult = apiInstance.Convert(convertWithOptionsRequest); +Console.WriteLine($"Document converted successfully to password-protected PDF. Saved to {convertWithOptionsResult.Path}"); + +// Conversion to image format (PNG) +Console.WriteLine("\nConverting document to PNG..."); +var convertToImageRequest = new ConvertRequest(fileInfo, "png") +{ + OutputPath = "output/converted-document.png" +}; + +var convertToImageResult = apiInstance.Convert(convertToImageRequest); +Console.WriteLine($"Document converted successfully to PNG. Saved to {convertToImageResult.Path}"); +``` + +### 6. Implementing in Python + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +annotate_api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Create file info object +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotationdocs/annotated-sample.docx" + +# Basic conversion to PDF +print("Converting document to PDF...") +convert_request = groupdocs_annotation_cloud.ConvertRequest(file_info, "pdf") +convert_request.output_path = "output/converted-document.pdf" + +convert_result = annotate_api.convert(convert_request) +print(f"Document converted successfully to PDF. Saved to {convert_result.path}") + +# Conversion to PDF with password protection +print("\nConverting document to password-protected PDF...") +pdf_options = groupdocs_annotation_cloud.PdfConvertOptions() +pdf_options.password = "p@s$w0rd" +pdf_options.pdf_format = "PDF" + +convert_options = groupdocs_annotation_cloud.ConvertOptions() +convert_options.pdf_options = pdf_options + +convert_with_options_request = groupdocs_annotation_cloud.ConvertRequest(file_info, "pdf") +convert_with_options_request.output_path = "output/password-protected.pdf" +convert_with_options_request.convert_options = convert_options + +convert_with_options_result = annotate_api.convert(convert_with_options_request) +print(f"Document converted successfully to password-protected PDF. Saved to {convert_with_options_result.path}") + +# Conversion to image format (PNG) +print("\nConverting document to PNG...") +convert_to_image_request = groupdocs_annotation_cloud.ConvertRequest(file_info, "png") +convert_to_image_request.output_path = "output/converted-document.png" + +convert_to_image_result = annotate_api.convert(convert_to_image_request) +print(f"Document converted successfully to PNG. Saved to {convert_to_image_result.path}") +``` + +### 7. Implementing in Node.js + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +const { AnnotateApi, FileInfo, ConvertOptions, PdfConvertOptions } = require("groupdocs-annotation-cloud"); + +// Set up authentication credentials +const appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +const appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +// Initialize API instance +const annotateApi = new AnnotateApi.fromKeys(appSid, appKey); + +// Create file info object +const fileInfo = new FileInfo(); +fileInfo.filePath = "annotationdocs/annotated-sample.docx"; + +// Basic conversion to PDF +console.log("Converting document to PDF..."); +const convertRequest = { + fileInfo: fileInfo, + format: "pdf", + outputPath: "output/converted-document.pdf" +}; + +annotateApi.convert(convertRequest) + .then((convertResult) => { + console.log(`Document converted successfully to PDF. Saved to ${convertResult.path}`); + + // Conversion to PDF with password protection + console.log("\nConverting document to password-protected PDF..."); + + const pdfOptions = new PdfConvertOptions(); + pdfOptions.password = "p@s$w0rd"; + pdfOptions.pdfFormat = "PDF"; + + const convertOptions = new ConvertOptions(); + convertOptions.pdfOptions = pdfOptions; + + const convertWithOptionsRequest = { + fileInfo: fileInfo, + format: "pdf", + outputPath: "output/password-protected.pdf", + convertOptions: convertOptions + }; + + return annotateApi.convert(convertWithOptionsRequest); + }) + .then((convertWithOptionsResult) => { + console.log(`Document converted successfully to password-protected PDF. Saved to ${convertWithOptionsResult.path}`); + + // Conversion to image format (PNG) + console.log("\nConverting document to PNG..."); + + const convertToImageRequest = { + fileInfo: fileInfo, + format: "png", + outputPath: "output/converted-document.png" + }; + + return annotateApi.convert(convertToImageRequest); + }) + .then((convertToImageResult) => { + console.log(`Document converted successfully to PNG. Saved to ${convertToImageResult.path}`); + }) + .catch((error) => { + console.error("Error:", error.message); + }); +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing document conversion in your own application: + +1. Get your API credentials from the dashboard +2. Upload an annotated document to your storage or use a sample document +3. Choose your preferred programming language +4. Decide which format you want to convert to +5. Copy the appropriate code example above +6. Modify it with your credentials, document path, and conversion options +7. Run the code and verify the converted document + +## Format-Specific Conversion Options + +Depending on the target format, you can specify different conversion options: + +### PDF Options +- Password protection +- PDF/A compliance +- Compression settings +- Page layout options + +### Image Options +- Resolution (DPI) +- Image quality +- Color mode (RGB, grayscale, etc.) +- Image format (PNG, JPG, etc.) + +### Word Options +- Document protection +- Page setup +- Compatibility mode + +### HTML Options +- Embedded resources +- CSS styling +- JavaScript options + +## Troubleshooting Tips + +- Unsupported Format: Make sure both the source and target formats are supported by the API. +- Authentication Errors: Verify your AppSID and AppKey are correctly set up. +- File Not Found Errors: Ensure the document path is correct and the file exists in your storage. +- Output Path Issues: Make sure the output folder exists in your storage or use a different path. +- Annotation Rendering Issues: If annotations don't appear correctly in the output document, check the annotation properties and compatibility with the target format. +- File Size Limitations: Be aware of file size limitations, especially when converting large documents. + +## What You've Learned + +In this tutorial, you have learned: +- How to convert annotated documents to different formats using the GroupDocs.Annotation Cloud API +- How to specify conversion options for different target formats +- How to implement document conversion in C#, Python, and Node.js +- How to handle format-specific options like password protection + +## Further Practice + +To solidify your understanding: +1. Try converting documents to different formats not covered in this tutorial +2. Experiment with different conversion options for each format +3. Create a batch conversion function to process multiple documents +4. Build a simple UI that lets users select conversion options + +## Next Steps + +Ready to learn more? Check out our other tutorials on document operations with GroupDocs.Annotation Cloud API. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/delete-annotations/_index.md b/content/annotation/english/getting-started/delete-annotations/_index.md new file mode 100644 index 0000000..f9eab63 --- /dev/null +++ b/content/annotation/english/getting-started/delete-annotations/_index.md @@ -0,0 +1,344 @@ +--- +title: How to Delete Annotations from Documents with GroupDocs.Annotation Cloud API Tutorial +url: /getting-started/delete-annotations/ +weight: 3 +description: Learn how to selectively remove annotations from documents using GroupDocs.Annotation Cloud API in this step-by-step developer tutorial +--- + +# Tutorial: How to Delete Annotations from Documents with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Remove specific annotations from documents using the GroupDocs.Annotation Cloud API +- Delete all annotations from a document +- Selectively remove annotations by ID +- Implement annotation deletion in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document with annotations uploaded to your storage (ideally, follow the [Add Annotations tutorial](/getting-started/add-annotations/) first to create one) +4. Basic knowledge of REST APIs +5. A development environment set up with your preferred language + +## Practical Scenario + +In a document management system, you often need to clean up or selectively remove annotations. For example, you might want to remove outdated comments, delete annotations from specific reviewers, or create a clean version of a document without any annotations. This tutorial shows you how to implement these common annotation management scenarios. + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides an endpoint to delete annotations from a document: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/remove +``` + +This endpoint requires you to specify the document path and annotation IDs in the request body. + +### 2. First Step: Extract Annotation IDs + +Before deleting annotations, you typically need to extract them first to get their IDs. Let's revisit the extraction process briefly: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FilePath': 'annotationdocs/annotated-sample.docx' +}" +``` + +From the response, note the IDs of the annotations you want to delete. + +### 3. Deleting Specific Annotations + +Now, let's delete specific annotations using their IDs: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/annotated-sample.docx' + }, + 'AnnotationIds': [1, 3], + 'OutputPath': 'output/annotations-removed.docx' +}" +``` + +This request will: +- Take the document at `annotationdocs/annotated-sample.docx` +- Remove annotations with IDs 1 and 3 +- Save the result to `output/annotations-removed.docx` + +### 4. Deleting All Annotations + +To delete all annotations from a document, you can first extract all annotation IDs and then use them in the remove request. Alternatively, some implementations of the SDK provide a convenience method to remove all annotations: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/annotated-sample.docx' + }, + 'AnnotationIds': [], + 'OutputPath': 'output/all-annotations-removed.docx' +}" +``` + +By providing an empty array for `AnnotationIds`, the API will remove all annotations. + +### 5. Implementing in C# + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create AnnotateApi instance +var apiInstance = new AnnotateApi(configuration); + +// Step 1: Extract annotations to get their IDs +var extractRequest = new ExtractRequest( + new FileInfo { FilePath = "annotationdocs/annotated-sample.docx" } +); + +var extractResult = apiInstance.Extract(extractRequest); +Console.WriteLine($"Found {extractResult.Annotations.Count} annotations in the document."); + +// Step 2: Select which annotations to delete (in this example, we'll delete the first two) +var annotationIdsToDelete = new List(); +if (extractResult.Annotations.Count > 0) +{ + annotationIdsToDelete.Add(extractResult.Annotations[0].Id); + + if (extractResult.Annotations.Count > 1) + { + annotationIdsToDelete.Add(extractResult.Annotations[1].Id); + } + + Console.WriteLine($"Deleting annotations with IDs: {string.Join(", ", annotationIdsToDelete)}"); + + // Step 3: Create request to remove specific annotations + var removeRequest = new RemoveAnnotationsRequest( + new FileInfo { FilePath = "annotationdocs/annotated-sample.docx" }, + annotationIdsToDelete + ) + { + OutputPath = "output/annotations-removed.docx" + }; + + // Call API to remove annotations + var removeResult = apiInstance.RemoveAnnotations(removeRequest); + + Console.WriteLine($"Annotations removed successfully. Document saved to {removeResult.Path}"); +} +else +{ + Console.WriteLine("No annotations found to delete."); +} + +// Example of removing all annotations from a document +Console.WriteLine("\nRemoving all annotations from the document..."); + +var removeAllRequest = new RemoveAnnotationsRequest( + new FileInfo { FilePath = "annotationdocs/annotated-sample.docx" }, + new List() // Empty list means remove all annotations +) +{ + OutputPath = "output/all-annotations-removed.docx" +}; + +var removeAllResult = apiInstance.RemoveAnnotations(removeAllRequest); + +Console.WriteLine($"All annotations removed successfully. Document saved to {removeAllResult.Path}"); +``` + +### 6. Implementing in Python + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +annotate_api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Step 1: Create file info object +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotationdocs/annotated-sample.docx" + +# Step 2: Extract annotations to get their IDs +extract_request = groupdocs_annotation_cloud.ExtractRequest(file_info) +extract_result = annotate_api.extract(extract_request) + +print(f"Found {len(extract_result.annotations)} annotations in the document.") + +# Step 3: Select which annotations to delete (in this example, we'll delete the first two) +annotation_ids_to_delete = [] +if extract_result.annotations and len(extract_result.annotations) > 0: + annotation_ids_to_delete.append(extract_result.annotations[0].id) + + if len(extract_result.annotations) > 1: + annotation_ids_to_delete.append(extract_result.annotations[1].id) + + print(f"Deleting annotations with IDs: {', '.join(map(str, annotation_ids_to_delete))}") + + # Step 4: Create request to remove specific annotations + remove_request = groupdocs_annotation_cloud.RemoveAnnotationsRequest(file_info, annotation_ids_to_delete) + remove_request.output_path = "output/annotations-removed.docx" + + # Call API to remove annotations + remove_result = annotate_api.remove_annotations(remove_request) + + print(f"Annotations removed successfully. Document saved to {remove_result.path}") +else: + print("No annotations found to delete.") + +# Example of removing all annotations from a document +print("\nRemoving all annotations from the document...") + +remove_all_request = groupdocs_annotation_cloud.RemoveAnnotationsRequest(file_info, []) # Empty list means remove all +remove_all_request.output_path = "output/all-annotations-removed.docx" + +remove_all_result = annotate_api.remove_annotations(remove_all_request) + +print(f"All annotations removed successfully. Document saved to {remove_all_result.path}") +``` + +### 7. Implementing in Node.js + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +const { AnnotateApi, FileInfo } = require("groupdocs-annotation-cloud"); + +// Set up authentication credentials +const appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +const appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +// Initialize API instance +const annotateApi = new AnnotateApi.fromKeys(appSid, appKey); + +// Create file info object +const fileInfo = new FileInfo(); +fileInfo.filePath = "annotationdocs/annotated-sample.docx"; + +// Step 1: Extract annotations to get their IDs +const extractRequest = { + fileInfo: fileInfo +}; + +annotateApi.extract(extractRequest) + .then((extractResult) => { + console.log(`Found ${extractResult.annotations.length} annotations in the document.`); + + // Step 2: Select which annotations to delete (in this example, we'll delete the first two) + const annotationIdsToDelete = []; + if (extractResult.annotations && extractResult.annotations.length > 0) { + annotationIdsToDelete.push(extractResult.annotations[0].id); + + if (extractResult.annotations.length > 1) { + annotationIdsToDelete.push(extractResult.annotations[1].id); + } + + console.log(`Deleting annotations with IDs: ${annotationIdsToDelete.join(', ')}`); + + // Step 3: Create request to remove specific annotations + const removeRequest = { + fileInfo: fileInfo, + annotationIds: annotationIdsToDelete, + outputPath: "output/annotations-removed.docx" + }; + + // Call API to remove annotations + return annotateApi.removeAnnotations(removeRequest); + } else { + console.log("No annotations found to delete."); + return Promise.resolve(); + } + }) + .then((removeResult) => { + if (removeResult) { + console.log(`Annotations removed successfully. Document saved to ${removeResult.path}`); + } + + // Example of removing all annotations from a document + console.log("\nRemoving all annotations from the document..."); + + const removeAllRequest = { + fileInfo: fileInfo, + annotationIds: [], // Empty array means remove all annotations + outputPath: "output/all-annotations-removed.docx" + }; + + return annotateApi.removeAnnotations(removeAllRequest); + }) + .then((removeAllResult) => { + console.log(`All annotations removed successfully. Document saved to ${removeAllResult.path}`); + }) + .catch((error) => { + console.error("Error:", error.message); + }); +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing annotation deletion in your own application: + +1. Get your API credentials from the dashboard +2. Upload an annotated document to your storage or use a sample document +3. Choose your preferred programming language +4. Copy the appropriate code example above +5. Modify it with your credentials and document path +6. Run the code and verify that the annotations are removed + +## Troubleshooting Tips + +- Invalid Annotation IDs: Make sure you're using valid annotation IDs obtained from the extract operation. +- Authentication Errors: Verify your AppSID and AppKey are correctly set up. +- File Not Found Errors: Ensure the document path is correct and the file exists in your storage. +- Output Path Issues: Make sure the output folder exists in your storage or use a different path. +- Original Document Unchanged: If the original document remains unchanged, check that you're looking at the output document and not the original. + +## What You've Learned + +In this tutorial, you have learned: +- How to extract annotation IDs from a document +- How to remove specific annotations by ID +- How to delete all annotations from a document +- How to implement annotation deletion in C#, Python, and Node.js + +## Further Practice + +To solidify your understanding: +1. Create a function that removes annotations based on certain criteria (e.g., by page, type, or content) +2. Build a simple UI that allows users to select which annotations to delete +3. Implement a batch processing feature to remove annotations from multiple documents +4. Create a version control system that maintains both annotated and clean versions of documents + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/extract-annotations/_index.md b/content/annotation/english/getting-started/extract-annotations/_index.md new file mode 100644 index 0000000..97fcf81 --- /dev/null +++ b/content/annotation/english/getting-started/extract-annotations/_index.md @@ -0,0 +1,410 @@ + + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing annotation extraction in your own application: + +1. Get your API credentials from the dashboard +2. Upload an annotated document to your storage or use a sample document +3. Choose your preferred programming language +4. Copy the appropriate code example above +5. Modify it with your credentials and document path +6. Run the code and analyze the extracted annotations + +## Troubleshooting Tips + +- No Annotations Found: If the API returns an empty list, verify that the document actually contains annotations. +- Wrong Document Format: Make sure you're using a supported document format. +- Authentication Errors: Verify your AppSID and AppKey are correctly set up. +- File Not Found Errors: Ensure the document path is correct and the file exists in your storage. +- Date Parsing Issues: If you encounter problems with date parsing, make sure you're handling timezone information correctly. + +## What You've Learned + +In this tutorial, you have learned: +- How to extract annotations from documents using the GroupDocs.Annotation Cloud API +- How to process different annotation types and their properties +- How to filter and group annotations for analysis +- How to implement annotation extraction in C#, Python, and Node.js + +## Further Practice + +To solidify your understanding: +1. Create a function to export annotations to a CSV or JSON file +2. Build a simple UI that displays extracted annotations in a table +3. Implement annotation filtering by date range, user, or content +4. Create a report generator that summarizes annotations by type and page + +## Next Steps + +Ready to learn more? Check out our next tutorial on converting annotated documents to different formats. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to ask on our [support forum](https://forum.groupdocs.cloud/c/annotation/10/)!--- +id: "extract-annotations-tutorial" +url: /getting-started/extract-annotations" +title: "Tutorial: How to Extract Annotations from Documents with GroupDocs.Annotation Cloud API" + +weight: 2 +description: "Learn how to extract and process existing annotations from documents using GroupDocs.Annotation Cloud API in this step-by-step tutorial" +keywords: "extract annotations, get annotations, document annotation tutorial, cloud api, annotation retrieval, process annotations, groupdocs cloud" +toc: True +--- + +# Tutorial: How to Extract Annotations from Documents with GroupDocs.Annotation Cloud API + +Difficulty Level: Intermediate +Estimated Time: 25 minutes + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Extract existing annotations from documents using the GroupDocs.Annotation Cloud API +- Parse and process annotation data including position, type, and content +- Filter annotations by different criteria +- Implement annotation extraction in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document with annotations uploaded to your storage (ideally, follow the [Add Annotations tutorial](/getting-started/add-annotations) first to create one) +4. Basic knowledge of REST APIs +5. A development environment set up with your preferred language + +## Practical Scenario + +In a collaborative document review system, you not only need to add annotations but also retrieve and process them. For example, you might want to display all comments made by a specific reviewer, compile a summary of feedback, or generate a report of all annotations in a document. This tutorial shows you how to extract annotations from documents to enable these scenarios. + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides an endpoint to extract annotations from a document: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/extract +``` + +This endpoint requires you to specify the document path in the request body. + +### 2. Making the API Request with cURL + +Let's try calling the API using cURL to understand the request and response structure: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FilePath': 'annotationdocs/annotated-sample.docx' +}" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual JWT token obtained from your AppSID and AppKey. + +### 3. Understanding the Response + +The API returns a JSON response containing an array of annotations with their properties. Here's an example of what the response might look like: + +```json +{ + "annotations": [ + { + "type": "Area", + "pageNumber": 1, + "box": { + "x": 100, + "y": 100, + "width": 200, + "height": 100 + }, + "backgroundColor": 16761035, + "opacity": 0.7, + "createdOn": "2023-07-25T14:20:30.123Z", + "id": 1 + }, + { + "type": "Text", + "pageNumber": 1, + "box": { + "x": 300, + "y": 200, + "width": 150, + "height": 30 + }, + "text": "This is a text annotation", + "fontColor": 255, + "fontSize": 12, + "opacity": 1.0, + "createdOn": "2023-07-25T14:22:45.678Z", + "id": 2 + } + ] +} +``` + +### 4. Processing Annotation Data + +Once you've extracted annotations, you can process them to: +- Count total annotations by type +- Extract text content from text-based annotations +- Determine annotation positions and sizes +- Filter annotations by page, type, or other criteria +- Generate reports or summaries + +### 5. Implementing in C# + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create AnnotateApi instance +var apiInstance = new AnnotateApi(configuration); + +// Create file info object +var fileInfo = new FileInfo +{ + FilePath = "annotationdocs/annotated-sample.docx" +}; + +// Create request object +var request = new ExtractRequest(fileInfo); + +// Call API method +var result = apiInstance.Extract(request); + +// Process the extracted annotations +if (result.Annotations != null && result.Annotations.Count > 0) +{ + Console.WriteLine($"Found {result.Annotations.Count} annotations:"); + + // Group annotations by type for easy analysis + var annotationsByType = result.Annotations.GroupBy(a => a.Type); + + foreach (var group in annotationsByType) + { + Console.WriteLine($"\n{group.Key} annotations ({group.Count()}):"); + + foreach (var annotation in group) + { + Console.WriteLine($" - ID: {annotation.Id}"); + Console.WriteLine($" Page: {annotation.PageNumber}"); + Console.WriteLine($" Position: X={annotation.Box.X}, Y={annotation.Box.Y}"); + + // Handle specific annotation type properties + if (annotation.Type == AnnotationInfo.TypeEnum.Text || + annotation.Type == AnnotationInfo.TypeEnum.TextReplacement) + { + Console.WriteLine($" Text: {annotation.Text}"); + } + + if (annotation.CreatedOn.HasValue) + { + Console.WriteLine($" Created: {annotation.CreatedOn.Value:yyyy-MM-dd HH:mm:ss}"); + } + + Console.WriteLine(); + } + } +} +else +{ + Console.WriteLine("No annotations found in the document."); +} +``` + +### 6. Implementing in Python + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud +from collections import defaultdict +from datetime import datetime + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +annotate_api = groupdocs_annotation_cloud.AnnotateApi.from_keys(app_sid, app_key) + +# Create file info object +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotationdocs/annotated-sample.docx" + +# Create request object +request = groupdocs_annotation_cloud.ExtractRequest(file_info) + +# Call API method +result = annotate_api.extract(request) + +# Process the extracted annotations +if result.annotations and len(result.annotations) > 0: + print(f"Found {len(result.annotations)} annotations:") + + # Group annotations by type + annotations_by_type = defaultdict(list) + for annotation in result.annotations: + annotations_by_type[annotation.type].append(annotation) + + # Process each annotation type + for annotation_type, annotations in annotations_by_type.items(): + print(f"\n{annotation_type} annotations ({len(annotations)}):") + + for annotation in annotations: + print(f" - ID: {annotation.id}") + print(f" Page: {annotation.page_number}") + print(f" Position: X={annotation.box.x}, Y={annotation.box.y}") + + # Handle specific annotation type properties + if annotation_type in ["Text", "TextReplacement"]: + print(f" Text: {annotation.text}") + + if annotation.created_on: + created_time = datetime.fromisoformat(annotation.created_on.replace('Z', '+00:00')) + print(f" Created: {created_time.strftime('%Y-%m-%d %H:%M:%S')}") + + print() + + # Example of filtering annotations by page + page_1_annotations = [a for a in result.annotations if a.page_number == 1] + print(f"\nAnnotations on page 1: {len(page_1_annotations)}") + + # Example of extracting all text content from text annotations + text_contents = [a.text for a in result.annotations if hasattr(a, 'text') and a.text] + if text_contents: + print("\nText annotation contents:") + for i, text in enumerate(text_contents, 1): + print(f" {i}. {text}") +else: + print("No annotations found in the document.") +``` + +### 7. Implementing in Node.js + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +const { AnnotateApi, FileInfo } = require("groupdocs-annotation-cloud"); + +// Set up authentication credentials +const appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +const appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +// Initialize API instance +const annotateApi = new AnnotateApi.fromKeys(appSid, appKey); + +// Create file info object +const fileInfo = new FileInfo(); +fileInfo.filePath = "annotationdocs/annotated-sample.docx"; + +// Create request object +const request = { + fileInfo: fileInfo +}; + +// Call API method to extract annotations +annotateApi.extract(request) + .then((result) => { + if (result.annotations && result.annotations.length > 0) { + console.log(`Found ${result.annotations.length} annotations:`); + + // Group annotations by type + const annotationsByType = {}; + result.annotations.forEach(annotation => { + if (!annotationsByType[annotation.type]) { + annotationsByType[annotation.type] = []; + } + annotationsByType[annotation.type].push(annotation); + }); + + // Process each annotation type + Object.keys(annotationsByType).forEach(type => { + const annotations = annotationsByType[type]; + console.log(`\n${type} annotations (${annotations.length}):`); + + annotations.forEach(annotation => { + console.log(` - ID: ${annotation.id}`); + console.log(` Page: ${annotation.pageNumber}`); + console.log(` Position: X=${annotation.box.x}, Y=${annotation.box.y}`); + + // Handle specific annotation type properties + if (type === "Text" || type === "TextReplacement") { + console.log(` Text: ${annotation.text}`); + } + + if (annotation.createdOn) { + const createdDate = new Date(annotation.createdOn); + console.log(` Created: ${createdDate.toISOString().replace('T', ' ').substr(0, 19)}`); + } + + console.log(); + }); + }); + + // Example of filtering annotations by page + const page1Annotations = result.annotations.filter(a => a.pageNumber === 1); + console.log(`\nAnnotations on page 1: ${page1Annotations.length}`); + + // Example of extracting all text content from text annotations + const textContents = result.annotations + .filter(a => a.text && a.text.trim().length > 0) + .map(a => a.text); + + if (textContents.length > 0) { + console.log("\nText annotation contents:"); + textContents.forEach((text, index) => { + console.log(` ${index + 1}. ${text}`); + }); + } + } else { + console.log("No annotations found in the document."); + } + }) + .catch((error) => { + console.error("Error extracting annotations:", error.message); + }); + +// Expected output: +// Found 4 annotations: +// +// Area annotations (1): +// - ID: 1 +// Page: 1 +// Position: X=100, Y=100 +// Created: 2023-07-25 14:20:30 +// +// Text annotations (1): +// - ID: 2 +// Page: 1 +// Position: X=300, Y=200 +// Text: This is a text annotation +// Created: 2023-07-25 14:22:45 +// +// Arrow annotations (1): +// - ID: 3 +// Page: 1 +// Position: X=400, Y=400 +// +// TextHighlight annotations (1): +// - ID: 4 +// Page: 1 +// Position: X=50, Y=350 +// +// Annotations on page 1: 4 +// +// Text annotation contents: +// 1. This is a text annotation \ No newline at end of file diff --git a/content/annotation/english/getting-started/get-document-information/_index.md b/content/annotation/english/getting-started/get-document-information/_index.md new file mode 100644 index 0000000..30f36fd --- /dev/null +++ b/content/annotation/english/getting-started/get-document-information/_index.md @@ -0,0 +1,230 @@ +--- +title: How to Get Document Information with GroupDocs.Annotation Cloud API Tutorial +weight: 2 +url: /getting-started/get-document-information/ +description: Learn how to extract document metadata and page information using GroupDocs.Annotation Cloud API in this developer tutorial +--- + +# Tutorial: How to Get Document Information with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Retrieve detailed information about a document using the GroupDocs.Annotation Cloud API +- Extract metadata such as file format, size, and modification date +- Get page dimensions for accurate annotation placement +- Implement this functionality in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your storage (or you can use the sample documents provided by the API) +4. Basic knowledge of REST APIs +5. A development environment set up with your preferred language + +## Practical Scenario + +When building a document annotation application, you often need to know details about the documents before allowing users to add annotations. For example, you need to know the page dimensions to correctly position annotations, or you might want to show document metadata to users. This tutorial shows you how to retrieve this critical information. + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides a dedicated endpoint to retrieve document information: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/info +``` + +This endpoint requires you to specify the document path in the request body. + +### 2. Making the API Request with cURL + +Let's try calling the API using cURL to understand the request and response structure: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/info" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ 'FilePath': 'annotationdocs/one-page.docx'}" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual JWT token obtained from your AppSID and AppKey. + +### 3. Understanding the Response + +The API returns a JSON response containing comprehensive information about the document, including: +- Basic file properties (name, path, extension, format) +- File size and modification date +- Page information including dimensions (width and height) + +Here's what a typical response looks like: + +```json +{ + "name": "one-page.docx", + "path": "annotationdocs/one-page.docx", + "extension": ".docx", + "fileFormat": "Microsoft Word Open XML format", + "size": 16646, + "dateModified": "2021-02-05T05:17:10Z", + "pages": [ + { + "number": 1, + "width": 595, + "height": 841 + } + ] +} +``` + +### 4. Why Page Dimensions Matter + +The page dimensions (width and height) are particularly important for annotation. They allow you to: +- Calculate relative positions for annotations +- Ensure annotations appear in the correct location across different devices +- Scale annotations properly when the document is rendered at different sizes + +### 5. Implementing in Different Programming Languages + +Let's implement this API call in various programming languages: + +#### C# Implementation + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create API instance +var apiInstance = new InfoApi(configuration); + +// Create request object +var request = new GetInfoRequest +{ + FilePath = "annotationdocs/one-page.docx" +}; + +// Call API method +var response = apiInstance.GetInfo(request); + +// Process the document information +Console.WriteLine($"File: {response.Name}"); +Console.WriteLine($"Format: {response.FileFormat}"); +Console.WriteLine($"Size: {response.Size} bytes"); +Console.WriteLine($"Modified: {response.DateModified}"); + +// Process page information +foreach (var page in response.Pages) +{ + Console.WriteLine($"Page {page.Number}: Width={page.Width}, Height={page.Height}"); +} +``` + +#### Python Implementation + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +info_api = groupdocs_annotation_cloud.InfoApi.from_keys(app_sid, app_key) + +# Create request object +request = groupdocs_annotation_cloud.GetInfoRequest("annotationdocs/one-page.docx") + +# Call API method +result = info_api.get_info(request) + +# Process the document information +print(f"File: {result.name}") +print(f"Format: {result.file_format}") +print(f"Size: {result.size} bytes") +print(f"Modified: {result.date_modified}") + +# Process page information +for page in result.pages: + print(f"Page {page.number}: Width={page.width}, Height={page.height}") +``` + +#### Node.js Implementation + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +global.annotation_cloud = require("groupdocs-annotation-cloud"); + +global.appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +global.appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +// Create API instance +global.infoApi = annotation_cloud.InfoApi.fromKeys(appSid, appKey); + +// Prepare request object +let request = new annotation_cloud.GetInfoRequest(); +request.filePath = "annotationdocs/one-page.docx"; + +// Call API method +let result = await infoApi.getInfo(request); + +// Process the document information +console.log(`File: ${result.name}`); +console.log(`Format: ${result.fileFormat}`); +console.log(`Size: ${result.size} bytes`); +console.log(`Modified: ${result.dateModified}`); + +// Process page information +result.pages.forEach(page => { + console.log(`Page ${page.number}: Width=${page.width}, Height=${page.height}`); +}); +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing this in your own application: + +1. Get your API credentials from the dashboard +2. Upload a document to your storage or use a sample document +3. Choose your preferred programming language +4. Copy the appropriate code example above +5. Modify it with your credentials and document path +6. Run the code and observe the results + +## Troubleshooting Tips + +- File Not Found Error: Make sure the document path is correct and the file exists in your storage. +- Authentication Error: Verify your AppSID and AppKey are correctly set up. +- Unsupported Format: If you get an error related to format, check if the file format is supported by using the [Get Supported File Formats](/getting-started/get-supported-file-formats/) API. +- Large Files: If you're working with large files, you might need to increase timeout values in your API client. + +## What You've Learned + +In this tutorial, you have learned: +- How to retrieve document information using the GroupDocs.Annotation Cloud API +- The importance of page dimensions for annotation positioning +- How to extract metadata such as file size and format +- How to implement this functionality in C#, Python, and Node.js + +## Further Practice + +To solidify your understanding: +1. Try retrieving information for different file types (PDF, images, Excel files) +2. Create a function that validates if a document is suitable for annotation based on its properties +3. Build a simple UI that displays document metadata and previews page dimensions + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/get-supported-file-formats/_index.md b/content/annotation/english/getting-started/get-supported-file-formats/_index.md new file mode 100644 index 0000000..9a912a3 --- /dev/null +++ b/content/annotation/english/getting-started/get-supported-file-formats/_index.md @@ -0,0 +1,178 @@ +--- +title: How to Get Supported File Formats with GroupDocs.Annotation Cloud API Tutorial +url: /getting-started/get-supported-file-formats/ +weight: 1 +description: Learn how to retrieve all supported file formats in GroupDocs.Annotation Cloud API in this step-by-step tutorial for developers +--- + +# Tutorial: How to Get Supported File Formats with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Make API calls to retrieve the list of file formats supported by GroupDocs.Annotation Cloud +- Interpret the format information returned by the API +- Implement this functionality in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. Basic knowledge of REST APIs +4. A development environment set up with your preferred language + +## Practical Scenario + +Imagine you're developing a document management application that needs to validate file uploads. Before allowing users to upload files for annotation, you want to check if the file format is supported by the API. This tutorial shows you how to retrieve the list of supported file formats to implement this validation. + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides a dedicated endpoint to retrieve all supported file formats: + +``` +GET https://api.groupdocs.cloud/v2.0/annotation/formats +``` + +This REST API resource will return a comprehensive list of all file formats that can be annotated using the API. + +### 2. Making the API Request with cURL + +Let's try calling the API using cURL first to understand the request and response structure: + +```bash +curl -X GET "https://api.groupdocs.cloud/v2.0/annotation/formats" \ + -H "accept: application/json" \ + -H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual JWT token obtained from your AppSID and AppKey. + +### 3. Understanding the Response + +The API returns a JSON response containing an array of supported file formats. Each format includes: +- `extension`: The file extension (e.g., ".docx") +- `fileFormat`: A description of the format (e.g., "Microsoft Word") + +Here's a snippet of what the response looks like: + +```json +{ + "formats": [ + { + "extension": ".doc", + "fileFormat": "Microsoft Word" + }, + { + "extension": ".docx", + "fileFormat": "Microsoft Word" + }, + ... + ] +} +``` + +### 4. Implementing in Different Programming Languages + +Let's implement this API call in various programming languages: + +#### C# Implementation + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +var apiInstance = new InfoApi(configuration); +var response = apiInstance.GetSupportedFileFormats(); + +// Process the formats +foreach (var format in response.Formats) +{ + Console.WriteLine($"Extension: {format.Extension}, Format: {format.FileFormat}"); +} +``` + +#### Python Implementation + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +info_api = groupdocs_annotation_cloud.InfoApi.from_keys(app_sid, app_key) + +result = info_api.get_supported_file_formats() + +# Process the formats +for format_info in result.formats: + print(f"Extension: {format_info.extension}, Format: {format_info.file_format}") +``` + +#### Node.js Implementation + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +global.annotation_cloud = require("groupdocs-annotation-cloud"); + +global.appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +global.appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +global.infoApi = annotation_cloud.InfoApi.fromKeys(appSid, appKey); + +let response = await infoApi.getSupportedFileFormats(); + +// Process the formats +response.formats.forEach(format => { + console.log(`Extension: ${format.extension}, Format: ${format.fileFormat}`); +}); +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing this in your own application: + +1. Get your API credentials from the dashboard +2. Choose your preferred programming language +3. Copy the appropriate code example above +4. Modify it with your credentials +5. Run the code and observe the results + +## Troubleshooting Tips + +- Authentication Error: Make sure your AppSID and AppKey are correctly set up and that you're generating the JWT token properly. +- Empty Response: If you receive an empty list, check that your account has permissions to access the API. +- Network Errors: Ensure your firewall isn't blocking API requests to the GroupDocs.Annotation Cloud endpoint. + +## What You've Learned + +In this tutorial, you have learned: +- How to retrieve a list of supported file formats from the GroupDocs.Annotation Cloud API +- How to interpret the format data returned by the API +- How to implement this functionality in C#, Python, and Node.js + +## Further Practice + +To solidify your understanding: +1. Try filtering the response to only show specific categories (e.g., only Microsoft Word formats) +2. Create a validation function that checks if a given file extension is supported +3. Implement a user-friendly UI component that shows supported formats to end-users + +## Next Steps + +Ready to learn more? Check out our next tutorial: [How to Get Document Information with GroupDocs.Annotation Cloud API](/getting-started/get-document-information/). + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/annotation/english/getting-started/preview-documents/_index.md b/content/annotation/english/getting-started/preview-documents/_index.md new file mode 100644 index 0000000..47a63ac --- /dev/null +++ b/content/annotation/english/getting-started/preview-documents/_index.md @@ -0,0 +1,380 @@ +--- +title: How to Preview Documents with GroupDocs.Annotation Cloud API Tutorial +weight: 2 +url: /getting-started/preview-documents/ +description: Learn how to generate document previews and thumbnails using GroupDocs.Annotation Cloud API in this step-by-step developer tutorial +--- + +# Tutorial: How to Preview Documents with GroupDocs.Annotation Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Generate document previews using the GroupDocs.Annotation Cloud API +- Render specific pages or page ranges from documents +- Create thumbnails for document preview +- Configure preview options like image quality and format +- Implement document preview in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Annotation Cloud account (if you don't have one, [get a free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your API keys (AppSID and AppKey) from the [dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your storage +4. Basic knowledge of REST APIs +5. A development environment set up with your preferred language + +## Practical Scenario + +In a document management system, users typically want to preview documents before opening or annotating them. This preview functionality helps users quickly identify the document they're looking for and see any existing annotations without opening the full document. For example, you might want to: +- Display document thumbnails in a file browser +- Show a preview of the first page in a document list +- Allow users to navigate through document pages before opening +- Generate preview images for presentations or reports + +This tutorial shows you how to implement these preview features in your applications. + +## Step-by-Step Guide + +### 1. Understanding the API Endpoint + +GroupDocs.Annotation Cloud API provides an endpoint to generate document previews: + +``` +POST https://api.groupdocs.cloud/v2.0/annotation/preview +``` + +This endpoint requires you to specify the document path and preview options in the request body. + +### 2. Generating a Preview for a Specific Page + +Let's start with a basic example - generating a preview for a specific page of a document: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/sample.docx' + }, + 'PageNumber': 1, + 'Format': 'PNG', + 'OutputPath': 'output/preview-page-1.png' +}" +``` + +This request will: +- Take the document at `annotationdocs/sample.docx` +- Generate a PNG preview of page 1 +- Save the result to `output/preview-page-1.png` + +### 3. Generating Previews for Multiple Pages + +You can also generate previews for multiple pages at once: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/sample.docx' + }, + 'PageNumbers': [1, 2, 3], + 'Format': 'JPEG', + 'OutputPath': 'output/preview-page-{0}.jpg' +}" +``` + +This request will generate JPEG previews for pages 1, 2, and 3, saving them to separate files with the page number in the filename. + +### 4. Customizing Preview Options + +You can customize the preview by setting various options: + +```bash +curl -v "https://api.groupdocs.cloud/v2.0/annotation/preview" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'annotationdocs/sample.docx' + }, + 'PageNumber': 1, + 'Format': 'JPEG', + 'Width': 800, + 'Height': 1000, + 'Resolution': 96, + 'RenderComments': true, + 'OutputPath': 'output/custom-preview.jpg' +}" +``` + +This request adds options like width, height, resolution, and whether to render comments in the preview. + +### 5. Implementing in C# + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-dotnet-samples +string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyAppSid, MyAppKey); + +// Create PreviewApi instance +var apiInstance = new PreviewApi(configuration); + +// Create file info object +var fileInfo = new FileInfo +{ + FilePath = "annotationdocs/sample.docx" +}; + +// Generate preview for a specific page +Console.WriteLine("Generating preview for page 1..."); +var previewRequest = new PreviewRequest(fileInfo) +{ + PageNumber = 1, + Format = "PNG", + OutputPath = "output/preview-page-1.png" +}; + +var previewResult = apiInstance.Preview(previewRequest); +Console.WriteLine($"Preview generated successfully. Saved to {previewResult.Path}"); + +// Generate previews for multiple pages +Console.WriteLine("\nGenerating previews for pages 1, 2, and 3..."); +var multiPagePreviewRequest = new PreviewRequest(fileInfo) +{ + PageNumbers = new List { 1, 2, 3 }, + Format = "JPEG", + OutputPath = "output/preview-page-{0}.jpg" +}; + +var multiPagePreviewResult = apiInstance.Preview(multiPagePreviewRequest); +Console.WriteLine($"Multiple page previews generated successfully."); +foreach (var path in multiPagePreviewResult.Paths) +{ + Console.WriteLine($"Preview saved to: {path}"); +} + +// Generate a customized preview +Console.WriteLine("\nGenerating a customized preview..."); +var customPreviewRequest = new PreviewRequest(fileInfo) +{ + PageNumber = 1, + Format = "JPEG", + Width = 800, + Height = 1000, + Resolution = 96, + RenderComments = true, + OutputPath = "output/custom-preview.jpg" +}; + +var customPreviewResult = apiInstance.Preview(customPreviewRequest); +Console.WriteLine($"Customized preview generated successfully. Saved to {customPreviewResult.Path}"); +``` + +### 6. Implementing in Python + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-python-samples +import groupdocs_annotation_cloud + +app_sid = "XXXX-XXXX-XXXX-XXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud +app_key = "XXXXXXXXXXXXXXXX" # Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +# Create API instance +preview_api = groupdocs_annotation_cloud.PreviewApi.from_keys(app_sid, app_key) + +# Create file info object +file_info = groupdocs_annotation_cloud.FileInfo() +file_info.file_path = "annotationdocs/sample.docx" + +# Generate preview for a specific page +print("Generating preview for page 1...") +preview_request = groupdocs_annotation_cloud.PreviewRequest(file_info) +preview_request.page_number = 1 +preview_request.format = "PNG" +preview_request.output_path = "output/preview-page-1.png" + +preview_result = preview_api.preview(preview_request) +print(f"Preview generated successfully. Saved to {preview_result.path}") + +# Generate previews for multiple pages +print("\nGenerating previews for pages 1, 2, and 3...") +multi_page_preview_request = groupdocs_annotation_cloud.PreviewRequest(file_info) +multi_page_preview_request.page_numbers = [1, 2, 3] +multi_page_preview_request.format = "JPEG" +multi_page_preview_request.output_path = "output/preview-page-{0}.jpg" + +multi_page_preview_result = preview_api.preview(multi_page_preview_request) +print("Multiple page previews generated successfully.") +for path in multi_page_preview_result.paths: + print(f"Preview saved to: {path}") + +# Generate a customized preview +print("\nGenerating a customized preview...") +custom_preview_request = groupdocs_annotation_cloud.PreviewRequest(file_info) +custom_preview_request.page_number = 1 +custom_preview_request.format = "JPEG" +custom_preview_request.width = 800 +custom_preview_request.height = 1000 +custom_preview_request.resolution = 96 +custom_preview_request.render_comments = True +custom_preview_request.output_path = "output/custom-preview.jpg" + +custom_preview_result = preview_api.preview(custom_preview_request) +print(f"Customized preview generated successfully. Saved to {custom_preview_result.path}") +``` + +### 7. Implementing in Node.js + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-annotation-cloud/groupdocs-annotation-cloud-node-samples +const { PreviewApi, FileInfo } = require("groupdocs-annotation-cloud"); + +// Set up authentication credentials +const appSid = "XXXX-XXXX-XXXX-XXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud +const appKey = "XXXXXXXXXXXXXXXX"; // Get AppKey and AppSID from https://dashboard.groupdocs.cloud + +// Initialize API instance +const previewApi = new PreviewApi.fromKeys(appSid, appKey); + +// Create file info object +const fileInfo = new FileInfo(); +fileInfo.filePath = "annotationdocs/sample.docx"; + +// Generate preview for a specific page +console.log("Generating preview for page 1..."); +const previewRequest = { + fileInfo: fileInfo, + pageNumber: 1, + format: "PNG", + outputPath: "output/preview-page-1.png" +}; + +previewApi.preview(previewRequest) + .then((previewResult) => { + console.log(`Preview generated successfully. Saved to ${previewResult.path}`); + + // Generate previews for multiple pages + console.log("\nGenerating previews for pages 1, 2, and 3..."); + const multiPagePreviewRequest = { + fileInfo: fileInfo, + pageNumbers: [1, 2, 3], + format: "JPEG", + outputPath: "output/preview-page-{0}.jpg" + }; + + return previewApi.preview(multiPagePreviewRequest); + }) + .then((multiPagePreviewResult) => { + console.log("Multiple page previews generated successfully."); + multiPagePreviewResult.paths.forEach(path => { + console.log(`Preview saved to: ${path}`); + }); + + // Generate a customized preview + console.log("\nGenerating a customized preview..."); + const customPreviewRequest = { + fileInfo: fileInfo, + pageNumber: 1, + format: "JPEG", + width: 800, + height: 1000, + resolution: 96, + renderComments: true, + outputPath: "output/custom-preview.jpg" + }; + + return previewApi.preview(customPreviewRequest); + }) + .then((customPreviewResult) => { + console.log(`Customized preview generated successfully. Saved to ${customPreviewResult.path}`); + }) + .catch((error) => { + console.error("Error:", error.message); + }); +``` + +## Creating Thumbnails + +Thumbnails are smaller versions of document previews, typically used in document lists or galleries. You can generate thumbnails by setting smaller dimensions in the preview request: + +```csharp +// Generate thumbnails for all pages +var thumbnailRequest = new PreviewRequest(fileInfo) +{ + Format = "JPEG", + Width = 150, + Height = 200, + OutputPath = "output/thumbnail-{0}.jpg" +}; + +var thumbnailResult = apiInstance.Preview(thumbnailRequest); +Console.WriteLine($"Thumbnails generated successfully."); +foreach (var path in thumbnailResult.Paths) +{ + Console.WriteLine($"Thumbnail saved to: {path}"); +} +``` + +## Try It Yourself + +Now that you've seen the examples, it's time to try implementing document preview in your own application: + +1. Get your API credentials from the dashboard +2. Upload a document to your storage or use a sample document +3. Choose your preferred programming language +4. Decide which preview options you want to use +5. Copy the appropriate code example above +6. Modify it with your credentials, document path, and preview options +7. Run the code and verify the generated previews + +## Troubleshooting Tips + +- Unsupported Format: Make sure the preview format (PNG, JPEG, etc.) is supported by the API. +- Authentication Errors: Verify your AppSID and AppKey are correctly set up. +- File Not Found Errors: Ensure the document path is correct and the file exists in your storage. +- Output Path Issues: Make sure the output folder exists in your storage or use a different path. +- Page Number Issues: If you're getting errors about page numbers, make sure you're not requesting pages that don't exist in the document. +- Image Quality Issues: If the preview quality is too low, try increasing the resolution or quality settings. + +## What You've Learned + +In this tutorial, you have learned: +- How to generate document previews using the GroupDocs.Annotation Cloud API +- How to render specific pages or page ranges from documents +- How to create thumbnails for document preview +- How to configure preview options like image quality and format +- How to implement document preview in C#, Python, and Node.js + +## Further Practice + +To solidify your understanding: +1. Try generating previews for different document types (PDF, Word, Excel, etc.) +2. Experiment with different image formats and quality settings +3. Create a function that generates thumbnails for all pages in a document +4. Build a simple UI that displays document previews and allows navigation between pages + +## Next Steps + +Ready to learn more? Check out our other tutorials on document operations with GroupDocs.Annotation Cloud API. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/annotation/) +- [Documentation](https://docs.groupdocs.cloud/annotation/) +- [API Reference](https://reference.groupdocs.cloud/annotation/) +- [Live Demo](https://products.groupdocs.app/annotation/family) +- [Free Support](https://forum.groupdocs.cloud/c/annotation/10/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) diff --git a/content/home/english/_index.md b/content/home/english/_index.md index 0cff129..178a836 100644 --- a/content/home/english/_index.md +++ b/content/home/english/_index.md @@ -18,12 +18,12 @@ Learn how to render and display over 170 document and image file formats in your ### [GroupDocs.Conversion Cloud Tutorials](./conversion/) Master document conversion between multiple formats with our detailed guides. Learn to convert documents to and from PDF, Word, Excel, PowerPoint, images, and many other formats through simple API calls. -### [GroupDocs.Merger Cloud Tutorials](#) +### [GroupDocs.Merger Cloud Tutorials](./merger/) Discover how to join multiple documents into one, split documents into parts, manage pages, and organize documents efficiently through our cloud API integration. ## Document Processing Tutorials -### [GroupDocs.Annotation Cloud Tutorials](#) +### [GroupDocs.Annotation Cloud Tutorials](./annotation/) Explore our tutorials on adding, editing, and managing annotations in documents. Learn to implement comments, highlights, text markup, and various other annotation tools in your applications. ### [GroupDocs.Comparison Cloud Tutorials](#) diff --git a/content/merger/english/_index.md b/content/merger/english/_index.md new file mode 100644 index 0000000..9e5d82d --- /dev/null +++ b/content/merger/english/_index.md @@ -0,0 +1,106 @@ +--- +title: GroupDocs.Merger Cloud Comprehensive Document Manipulation API +weight: 2 +url: /merger/ +description: Learn how to seamlessly join, split, rearrange, rotate, remove, and extract pages from various document formats using the powerful GroupDocs.Merger Cloud API with step-by-step instructions and code examples. +--- + +# GroupDocs.Merger Cloud Tutorials + +## Introduction + +Welcome to the GroupDocs.Merger Cloud tutorials. This comprehensive guide provides detailed instructions for developers who want to integrate document merging, splitting, and manipulation capabilities into their applications using our REST API. + +## Getting Started + +### [Getting Started Tutorials](/merger/getting-started/) + +Step-by-step tutorials for developers to learn how to use GroupDocs.Merger Cloud API - from basic operations to advanced document manipulation. + +### [Document Management Tutorials](/merger/document-management/) + +Step-by-step tutorials for developers to learn how to manage documents with GroupDocs.Merger Cloud API + +### [Document Page Processes Tutorials](/merger/page-processes/) + +Learn document page manipulation with these step-by-step tutorials for GroupDocs.Merger Cloud API +## Authentication + +All API requests require authentication. GroupDocs.Merger Cloud uses OAuth 2.0 for secure API access. + +```csharp +// Example authentication code +string clientId = "YOUR_CLIENT_ID"; +string clientSecret = "YOUR_CLIENT_SECRET"; +string token = GetAuthToken(clientId, clientSecret); +``` + +## API Reference + +This guide provides detailed examples for each API endpoint. Each section includes: + +- Endpoint description +- Request parameters +- Response format +- Code samples in multiple languages (C#, Java, PHP, Python, Ruby, Node.js) +- Error handling + +## Error Handling + +The API uses standard HTTP status codes to indicate success or failure: + +- 200 - Success +- 400 - Bad request +- 401 - Authentication failure +- 404 - Resource not found +- 500 - Server error + +## SDK Usage Examples + +### Merge Documents Example + +```csharp +// Example code for merging PDF files +var mergeOptions = new MergeOptions +{ + JoinItems = new List + { + new JoinItem { FilePath = "document1.pdf" }, + new JoinItem { FilePath = "document2.pdf" } + }, + OutputPath = "merged-output.pdf" +}; + +var response = api.Merge(new MergeRequest(mergeOptions)); +``` + +### Split Document Example + +```csharp +// Example code for splitting a document +var splitOptions = new SplitOptions +{ + FilePath = "document.pdf", + Mode = SplitMode.Pages, + Pages = new List { 2, 4, 6 }, + OutputPath = "split-output" +}; + +var response = api.Split(new SplitRequest(splitOptions)); +``` + +## Best Practices + +- Cache authentication tokens to avoid repeated authentication requests +- Use appropriate file formats for your specific use case +- Implement error handling to manage API exceptions +- Optimize document size before uploading for better performance + + +## Additional Resources + +- [API Reference](https://apireference.groupdocs.cloud/merger/) +- [GitHub SDK Repositories](https://github.com/groupdocs-merger-cloud) +- [Code Examples](https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-examples) +- [Documentation Home](https://docs.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/category/merger/) diff --git a/content/merger/english/document-management/_index.md b/content/merger/english/document-management/_index.md new file mode 100644 index 0000000..04ec1b6 --- /dev/null +++ b/content/merger/english/document-management/_index.md @@ -0,0 +1,74 @@ +--- +url: /document-management/ +title: GroupDocs.Merger Cloud API Document Management Tutorials +weight: 10 +description: Step-by-step tutorials for developers to learn how to manage documents with GroupDocs.Merger Cloud API +--- + +# Document Management Tutorials for GroupDocs.Merger Cloud API + +Welcome to our comprehensive tutorial series on Document Management with GroupDocs.Merger Cloud API. These hands-on tutorials are designed to help developers quickly learn and implement document operations in their applications. + +## Learning Path + +This tutorial collection follows a structured learning path, guiding you from basic to advanced document management operations: + +1. Basic Document Operations - Learn fundamental operations like joining multiple documents and splitting documents +2. Advanced Document Operations - Master specialized operations like joining specific pages, cross-format joining, and working with password-protected documents +3. Special Document Operations - Implement advanced features like document attachments, continuous merging, and image joining + +## Prerequisites + +Before starting these tutorials, you should have: + +- A GroupDocs.Merger Cloud account (Free trial available [here](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST API concepts +- Familiarity with your preferred programming language (C#, Java, PHP, Python, Ruby, or Node.js) +- Development environment set up for your chosen SDK + +## Estimated Time + +Each tutorial is designed to take approximately 15-30 minutes to complete, depending on your prior experience. + +## Available Tutorials + +### Basic Document Operations + +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) - Learn to combine several documents into a single file with complete examples in multiple languages. + +- [Tutorial: How to Split a Document](/document-management/split-document/) - Master document splitting techniques including single-page extraction, page range splitting, and filtered splitting. + +### Advanced Document Operations + +- [Tutorial: How to Join Documents of Different Formats](/document-management/join-document-cross-format/) - Master cross-format document merging techniques to combine different file types. + +### Special Document Operations + +- [Tutorial: How to Import Attachments into PDF Documents](/document-management/import-attachment/) - Learn to add file attachments to PDF documents. + +- [Tutorial: How to Join Word Documents Continuously](/document-management/join-word-continous/) - Master continuous joining of Word documents without page breaks. + +- [Tutorial: How to Join Images](/document-management/join-images/) - Learn to combine multiple images vertically or horizontally. + +- [Tutorial: How to Generate Document Page Previews](/document-management/generate-document-pages-preview/) - Master creating image previews of document pages. + +## What You'll Gain + +By completing these tutorials, you will: + +- Develop practical skills in document management operations +- Learn best practices for implementing GroupDocs.Merger in your applications +- Understand how to use the SDK in different programming languages +- Be able to integrate advanced document processing features into your solutions + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +We encourage you to follow the tutorials in the suggested order to build your knowledge progressively. Have questions about a specific tutorial? Feel free to leave a comment or visit our support forum! diff --git a/content/merger/english/document-management/generate-document-pages-preview/_index.md b/content/merger/english/document-management/generate-document-pages-preview/_index.md new file mode 100644 index 0000000..7f18097 --- /dev/null +++ b/content/merger/english/document-management/generate-document-pages-preview/_index.md @@ -0,0 +1,395 @@ +--- +title: How to Generate Document Page Previews Tutorial +url: /document-management/generate-document-pages-preview/ +weight: 45 +description: Learn how to create image previews of document pages using GroupDocs.Merger Cloud API in this comprehensive developer tutorial. +--- + +# Tutorial: How to Generate Document Page Previews + +## Introduction + +In this tutorial, you'll learn how to generate image previews (thumbnails) of document pages using GroupDocs.Merger Cloud API. Page preview generation is a valuable feature for document management systems, allowing users to quickly visualize documents without opening them in their native applications. This functionality is particularly useful for creating document galleries, previewing search results, or implementing document viewers in web and mobile applications. + +GroupDocs.Merger Cloud provides a flexible API for generating high-quality image previews of various document formats, with control over page selection, image dimensions, and output format. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Generate image previews of document pages +- Select specific pages or page ranges for preview generation +- Configure preview image dimensions and format +- Implement preview generation in different programming languages +- Handle password-protected documents during preview operations + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample documents to generate previews for (PDF, DOCX, etc.) + +## Use Case Scenario + +Let's consider a practical scenario: You're developing a document management system that needs to display thumbnails of documents in its web interface. Users upload various document types (PDF, Word, Excel, etc.), and your application needs to generate preview images of these documents to display in the UI, allowing users to quickly identify and locate their files visually. + +## Understanding Preview Generation + +GroupDocs.Merger Cloud allows you to generate previews with several configuration options: + +1. Page Selection: Generate previews for specific pages or page ranges +2. Filtering: Apply filters to include only even or odd pages +3. Image Dimensions: Control the width and height of the generated preview images +4. Image Format: Choose from formats like JPG, PNG, or BMP for the output images + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Preview Generation Request + +To generate page previews, create a JSON request specifying: +- The document to generate previews from +- Pages to preview (specific pages or a range) +- Optional dimensions and format for the preview images +- Output path pattern for the generated images +- Password (if the document is protected) + +Here's a basic request structure for generating previews of specific pages: + +```json +{ + "FileInfo": { + "FilePath": "WordProcessing/four-pages.docx" + }, + "OutputPath": "/Output/preview-page", + "Pages": [1, 3], + "Format": "Png" +} +``` + +### Step 3: Generate Previews Using the API + +Now let's execute the preview generation operation using the API: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/preview" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': 'WordProcessing/four-pages.docx' }, + 'OutputPath': '/Output/preview-page', + 'Pages': [1, 3], + 'Format': 'Png' + }" +``` + +The API will respond with: + +```json +{ + "documents": [ + { + "path": "\\Output\\preview-page_1.png" + }, + { + "path": "\\Output\\preview-page_3.png" + } + ] +} +``` + +### Step 4: Retrieve and Use the Preview Images + +After successful preview generation, you can download or use the preview images from the output paths provided in the response. + +## Try It Yourself + +Let's implement preview generation in different programming languages. First, make sure your document is uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Configure preview options + var options = new PreviewOptions + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/four-pages.docx" + }, + OutputPath = "Output/preview-page", + Pages = new List { 1, 3 }, + Format = PreviewOptions.FormatEnum.Png, + Width = 800, // Optional: specify width in pixels + Height = 600 // Optional: specify height in pixels + }; + + // Execute preview operation + var request = new PreviewRequest(options); + var response = apiInstance.Preview(request); + + Console.WriteLine("Number of preview images: " + response.Documents.Count); + foreach (var doc in response.Documents) + { + Console.WriteLine("Preview image path: " + doc.Path); + } +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure file info + FileInfo fileInfo = new FileInfo(); + fileInfo.setFilePath("WordProcessing/four-pages.docx"); + + // Configure preview options + PreviewOptions options = new PreviewOptions(); + options.setFileInfo(fileInfo); + options.setPages(Arrays.asList(1, 3)); + options.setFormat(FormatEnum.PNG); + options.setWidth(800); // Optional: specify width in pixels + options.setHeight(600); // Optional: specify height in pixels + options.setOutputPath("Output/preview-page"); + + // Execute preview operation + PreviewRequest request = new PreviewRequest(options); + PreviewResult response = apiInstance.preview(request); + + System.out.println("Number of preview images: " + response.getDocuments().size()); + for(DocumentResult doc : response.getDocuments()) { + System.out.println("Preview image path: " + doc.getPath()); + } +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure file info +file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/four-pages.docx") + +# Configure preview options +options = groupdocs_merger_cloud.PreviewOptions() +options.file_info = file_info +options.pages = [1, 3] +options.format = "Png" # Use "Png", "Jpg", or "Bmp" +options.width = 800 # Optional: specify width in pixels +options.height = 600 # Optional: specify height in pixels +options.output_path = "Output/preview-page" + +# Execute preview operation +result = document_api.preview(groupdocs_merger_cloud.PreviewRequest(options)) + +print(f"Number of preview images: {len(result.documents)}") +for doc in result.documents: + print(f"Preview image path: {doc.path}") +``` + +## Advanced Preview Generation Options + +Let's explore some advanced options for generating document page previews: + +### Generating Previews of a Page Range + +Instead of specifying individual pages, you can generate previews for a range of pages using the `StartPageNumber` and `EndPageNumber` properties: + +```json +{ + "FileInfo": { + "FilePath": "WordProcessing/ten-pages.docx" + }, + "StartPageNumber": 2, + "EndPageNumber": 5, + "OutputPath": "/Output/preview-range" +} +``` + +This will generate previews for pages 2 through 5 of the document. + +### Filtering Pages with RangeMode + +You can filter pages within a range to include only even or odd pages using the `RangeMode` property: + +```json +{ + "FileInfo": { + "FilePath": "WordProcessing/ten-pages.docx" + }, + "StartPageNumber": 1, + "EndPageNumber": 10, + "RangeMode": "Odd", + "OutputPath": "/Output/preview-odd-pages" +} +``` + +This will generate previews for odd-numbered pages (1, 3, 5, 7, 9) within the specified range. + +### Customizing Image Dimensions + +You can control the dimensions of the generated preview images with the `Width` and `Height` properties: + +```json +{ + "FileInfo": { + "FilePath": "WordProcessing/four-pages.docx" + }, + "Pages": [1, 2], + "Width": 1024, + "Height": 768, + "OutputPath": "/Output/preview-custom-size" +} +``` + +The dimensions are specified in pixels. If you specify only one dimension (width or height), the API will maintain the aspect ratio of the document when generating the preview. + +### Choosing Different Output Formats + +You can generate preview images in different formats using the `Format` property: + +```json +{ + "FileInfo": { + "FilePath": "WordProcessing/four-pages.docx" + }, + "Pages": [1], + "Format": "Jpg", // Options: "Jpg", "Png", "Bmp" + "OutputPath": "/Output/preview-jpg" +} +``` + +The default format is JPG if not specified. + +## Supporting Password-Protected Documents + +For password-protected documents, include the password in the `FileInfo` object: + +```json +{ + "FileInfo": { + "FilePath": "Pdf/protected-document.pdf", + "Password": "your-password" + }, + "Pages": [1, 2, 3], + "OutputPath": "/Output/preview-protected" +} +``` + +## Supported Document Formats + +GroupDocs.Merger Cloud can generate previews for a wide range of document formats, including: +- PDF documents +- Word documents (DOCX, DOC, RTF, etc.) +- Excel spreadsheets (XLSX, XLS, etc.) +- PowerPoint presentations (PPTX, PPT, etc.) +- Images (JPG, PNG, TIFF, etc.) +- And many more + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file path is correct and that the document exists in your cloud storage. + +3. Password Protection: For protected documents, ensure you're providing the correct password in the request. + +4. Page Number Out of Range: If you specify page numbers that don't exist in the document, you'll receive an error. Always ensure that page numbers are within the valid range of your document. + +5. Output File Size: Very large preview images (high resolution) may take longer to generate and result in larger file sizes. Choose appropriate dimensions based on your use case. + +## Practical Applications + +Here are some common applications for document preview generation: + +1. Document Management Systems: Display thumbnails of documents in file browsers or document libraries +2. Content Preview: Show previews of documents in search results or file listings +3. Mobile Applications: Generate lightweight previews for mobile document viewers +4. Email Attachments: Create previews of email attachments without downloading the full documents +5. Document Comparison: Generate previews of different document versions for visual comparison + +## What You've Learned + +In this tutorial, you've learned how to: +- Generate image previews of document pages +- Select specific pages or page ranges for preview generation +- Apply filters to generate previews of only odd or even pages +- Customize the dimensions and format of preview images +- Implement preview generation in different programming languages +- Handle password-protected documents + +## Further Practice + +To reinforce your learning, try these exercises: +1. Generate previews of different document formats (PDF, DOCX, XLSX, etc.) +2. Create a thumbnail gallery by generating previews of all pages in a document +3. Implement a document viewer that displays preview images with navigation controls +4. Compare the quality and file size of previews in different formats (JPG, PNG, BMP) + +## Next Steps + +Ready to explore more document operations? Check out these related tutorials: +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) +- [Tutorial: How to Split a Document](/document-management/split-document/) +- [Tutorial: How to Import Attachments into PDF Documents](/document-management/import-attachment/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/). + " \ No newline at end of file diff --git a/content/merger/english/document-management/import-attachment/_index.md b/content/merger/english/document-management/import-attachment/_index.md new file mode 100644 index 0000000..4a2e051 --- /dev/null +++ b/content/merger/english/document-management/import-attachment/_index.md @@ -0,0 +1,286 @@ +--- +title: How to Import Attachments into PDF Documents Tutorial +url: /document-management/import-attachment/ +weight: 40 +description: Learn how to add file attachments to PDF documents using GroupDocs.Merger Cloud API in this step-by-step developer tutorial. +--- + +# Tutorial: How to Import Attachments into PDF Documents + +## Introduction + +In this tutorial, you'll learn how to import file attachments into PDF documents using GroupDocs.Merger Cloud API. PDF attachments are a powerful feature that allows you to embed and distribute supplementary files along with your PDF document. This capability is particularly useful for including reference materials, source data, or related documents that provide additional context to the main PDF content. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Understand the concept of PDF attachments and their benefits +- Import file attachments into PDF documents using GroupDocs.Merger Cloud +- Implement attachment import operations in different programming languages +- Handle password-protected PDF documents during attachment operations + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- A PDF document to add attachments to +- Files to attach (text, images, documents, etc.) + +## Use Case Scenario + +Let's consider a practical scenario: You're developing a contract management system that needs to include supporting documents along with the main contract PDF. For example, a sales contract might need to include specification sheets, terms and conditions, and other legal documents as attachments rather than merging them all into a single document. This way, users can easily access these supplementary materials while keeping the main contract clean and focused. + +## Understanding PDF Attachments + +PDF attachments are files embedded within a PDF document. They can be of any file type (documents, images, spreadsheets, etc.) and travel with the PDF document. Key benefits include: + +1. File Integrity: Attached files maintain their original format and can be extracted and opened in their native applications. +2. Document Consolidation: Multiple related files can be distributed as a single package. +3. Reduced File Size: Compared to merging all content into a single PDF, attachments can be more space-efficient. +4. Enhanced Referencing: Readers can easily access supplementary materials without breaking the flow of the main document. + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Upload Files to Cloud Storage + +Before importing attachments, ensure that both your PDF document and the files you want to attach are uploaded to your GroupDocs Cloud storage. + +### Step 3: Prepare Your Import Attachment Request + +To import attachments into a PDF document, create a JSON request specifying: +- The PDF document to add attachments to +- The file paths of the attachments to import +- Output path for the resultant PDF document +- Password (if the PDF is protected) + +Here's a basic request structure for importing attachments: + +```json +{ + "FileInfo": { + "FilePath": "Pdf/one-page-password.pdf", + "Password": "password" + }, + "Attachments": [ "Txt/document.txt" ], + "OutputPath": "Output/with-attachment.pdf" +} +``` + +### Step 4: Import Attachments Using the API + +Now let's execute the attachment import operation using the API: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/import" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': + { + 'FilePath': 'Pdf/one-page-password.pdf', + 'Password': 'password' + }, + 'Attachments': [ 'Txt/document.txt' ], + 'OutputPath': 'Output/with-attachment.pdf' +}" +``` + +The API will respond with: + +```json +{ + "path": "Output/with-attachment.pdf" +} +``` + +### Step 5: Retrieve and Verify the PDF with Attachments + +After successful importing, you can download the PDF with attachments from the output path provided in the response. Open the PDF in a compatible reader to verify that the attachments are present and accessible. + +## Try It Yourself + +Let's implement attachment importing in different programming languages. First, make sure your PDF document and attachment files are uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Configure import options + var options = new ImportOptions + { + FileInfo = new FileInfo + { + FilePath = "Pdf/one-page-password.pdf", + Password = "password" // If your PDF is password-protected + }, + Attachments = new List { "Txt/document.txt" }, + OutputPath = "Output/with-attachment.pdf" + }; + + // Execute import operation + var request = new ImportRequest(options); + var response = apiInstance.Import(request); + + Console.WriteLine("Output file path: " + response.Path); +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure import options + ImportOptions options = new ImportOptions(); + FileInfo fileInfo = new FileInfo(); + fileInfo.setFilePath("Pdf/one-page-password.pdf"); + fileInfo.setPassword("password"); // If your PDF is password-protected + options.setFileInfo(fileInfo); + options.addAttachmentsItem("Txt/document.txt"); + options.setOutputPath("output/with-attachment.pdf"); + + // Execute import operation + CallImportRequest request = new CallImportRequest(options); + DocumentResult response = apiInstance.callImport(request); + + System.out.println("Output file path: " + response.getPath()); +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure import options +options = groupdocs_merger_cloud.ImportOptions() +options.file_info = groupdocs_merger_cloud.FileInfo("Pdf/one-page-password.pdf", None, None, "password") +options.attachments = ["Txt/document.txt"] +options.output_path = "Output/with-attachment.pdf" + +# Execute import operation +result = document_api.call_import(groupdocs_merger_cloud.CallImportRequest(options)) + +print("Output file path = " + result.path) +``` + +## Adding Multiple Attachments + +You can add multiple attachments to a PDF document in a single operation by including additional file paths in the `Attachments` array: + +```json +"Attachments": [ + "Txt/document1.txt", + "Spreadsheets/data.xlsx", + "Images/diagram.png" +] +``` + +This allows you to attach different types of files to the same PDF document. + +## Supported Attachment File Types + +You can attach virtually any file type to a PDF document, including: +- Text documents (.txt, .doc, .docx, etc.) +- Spreadsheets (.xls, .xlsx, etc.) +- Presentations (.ppt, .pptx, etc.) +- Images (.jpg, .png, .gif, etc.) +- Archives (.zip, .rar, etc.) +- And many more + +The file type doesn't affect the attachment process, as files are embedded in their original format. + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file paths are correct and that both the PDF document and attachment files exist in your cloud storage. + +3. Password Protection: For protected PDF documents, ensure you're providing the correct password in the request. + +4. Large Attachments: Be mindful of the size of attachments. Very large attachments will increase the overall PDF file size significantly, which might impact sharing and downloading. + +5. PDF Version Compatibility: Some very old PDF readers might not properly support or display attachments. For best results, ensure your users have modern PDF readers. + +## What You've Learned + +In this tutorial, you've learned how to: +- Understand the concept and benefits of PDF attachments +- Add file attachments to PDF documents using GroupDocs.Merger Cloud +- Configure attachment import operations with various options +- Implement attachment importing in different programming languages +- Handle password-protected PDF documents + +## Further Practice + +To reinforce your learning, try these exercises: +1. Add multiple attachments of different file types to a PDF document +2. Create a workflow that combines document joining and attachment operations +3. Build a simple application that allows users to select files to attach to a PDF +4. Compare the file size difference between merging documents versus attaching them + +## Next Steps + +Ready to explore more document operations? Check out these related tutorials: +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) +- [Tutorial: How to Split a Document](/document-management/split-document/) +- [Tutorial: How to Generate Document Page Previews](/document-management/generate-document-pages-preview/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/document-management/join-document-cross-format/_index.md b/content/merger/english/document-management/join-document-cross-format/_index.md new file mode 100644 index 0000000..aa6e600 --- /dev/null +++ b/content/merger/english/document-management/join-document-cross-format/_index.md @@ -0,0 +1,305 @@ +--- +title: How to Join Documents of Different Formats Tutorial +url: /document-management/join-document-cross-format/ +weight: 20 +description: Learn to combine documents of different formats like PDF, DOCX, and more into a single file with this step-by-step tutorial for developers. +--- + +# Tutorial: How to Join Documents of Different Formats + +## Introduction + +In this tutorial, you'll learn how to join documents of different formats into a single PDF or Word document using GroupDocs.Merger Cloud API. Cross-format document merging is a powerful feature that allows you to combine various document types (like PDF and DOCX) into one unified document without manual conversion steps. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Join documents with different formats (PDF, DOCX, etc.) into a single document +- Handle password-protected documents during cross-format joining +- Implement cross-format joining in different programming languages +- Understand format compatibility and limitations + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample documents of different formats (PDF, DOCX, etc.) +- Completed the [basic document joining tutorial](/document-management/join-multiple-documents/) (recommended) + +## Use Case Scenario + +Let's consider a practical scenario: You're building a report generation system that needs to combine various document types. Your users have content in different formats (PDF reports, Word documents, etc.) that need to be merged into a single comprehensive document for distribution. + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Cross-Format Join Request + +To join documents of different formats, create a JSON request specifying: +- The files to be joined (with their different formats) +- Output path and format for the resultant document +- Any passwords for protected documents + +Here's a basic request structure for joining a PDF and a DOCX file: + +```json +{ + "JoinItems": [ + { + "FileInfo": { + "FilePath": "Pdf/document.pdf", + "Password": "password" + } + }, + { + "FileInfo": { + "FilePath": "WordProcessing/document.docx" + } + } + ], + "OutputPath": "output/joined.pdf" +} +``` + +### Step 3: Join Different Format Documents Using the API + +Now let's execute the cross-format document join operation: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/join" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'JoinItems': + [ + { + 'FileInfo': + { + 'FilePath': 'Pdf/one-page-password.pdf', + 'Password': 'password' + } + }, + { + 'FileInfo': + { + 'FilePath': 'WordProcessing/one-page.docx' + } + } + ], + 'OutputPath': 'Output/joined.pdf' +}" +``` + +The API will respond with: + +```json +{ + "path": "Output/joined.pdf" +} +``` + +### Step 4: Retrieve the Joined Document + +After successful joining, you can download or use the merged document from the output path provided in the response. + +## Try It Yourself + +Let's practice joining documents of different formats in various programming languages. First, ensure your documents are uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Create a join item for PDF document (password-protected) + var item1 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "Pdf/one-page-password.pdf", + Password = "password" + } + }; + + // Create a join item for DOCX document + var item2 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/one-page.docx" + } + }; + + // Configure join options with PDF output format + var options = new JoinOptions + { + JoinItems = new List { item1, item2 }, + OutputPath = "Output/joined.pdf" + }; + + // Execute join operation + var request = new JoinRequest(options); + var response = apiInstance.Join(request); + + Console.WriteLine("Output file path: " + response.Path); +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure first document (PDF with password) + FileInfo fileInfo1 = new FileInfo(); + fileInfo1.setFilePath("Pdf/one-page-password.pdf"); + fileInfo1.setPassword("password"); + JoinItem item1 = new JoinItem(); + item1.setFileInfo(fileInfo1); + + // Configure second document (DOCX) + FileInfo fileInfo2 = new FileInfo(); + fileInfo2.setFilePath("WordProcessing/one-page.docx"); + JoinItem item2 = new JoinItem(); + item2.setFileInfo(fileInfo2); + + // Configure join options with PDF output + JoinOptions options = new JoinOptions(); + options.setJoinItems(Arrays.asList(item1, item2)); + options.setOutputPath("output/joined.pdf"); + + // Execute join operation + JoinRequest request = new JoinRequest(options); + DocumentResult response = apiInstance.join(request); + + System.out.println("Output file path: " + response.getPath()); +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure first document (PDF with password) +item1 = groupdocs_merger_cloud.JoinItem() +item1.file_info = groupdocs_merger_cloud.FileInfo("Pdf/one-page-password.pdf", None, None, "password") + +# Configure second document (DOCX) +item2 = groupdocs_merger_cloud.JoinItem() +item2.file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/one-page.docx") + +# Configure join options with PDF output +options = groupdocs_merger_cloud.JoinOptions() +options.join_items = [item1, item2] +options.output_path = "Output/joined.pdf" + +# Execute join operation +result = document_api.join(groupdocs_merger_cloud.JoinRequest(options)) + +print("Output file path = " + result.path) +``` + +## Format Compatibility and Considerations + +When joining documents of different formats, keep in mind the following: + +1. Output Format: The output format should be either PDF or a word processing format (DOCX, DOC, etc.). + +2. Format Compatibility Matrix: + - PDF can be combined with: DOCX, DOC, XLS, XLSX, PPT, PPTX, HTML, TXT + - DOCX can be combined with: PDF, DOC, TXT, HTML, RTF + - For other combinations, consider converting documents to compatible formats first + +3. Content Rendering: Some formatting or advanced features might not translate perfectly across formats. Complex layouts in presentations or spreadsheets may be simplified when converted to PDF or DOCX. + +4. File Size: The resultant file may be larger than the sum of the original files due to format conversion overhead. + +## Common Issues and Troubleshooting + +1. Format Not Supported: If you receive an error about incompatible formats, check the format compatibility matrix above. Some combinations may not be directly supported. + +2. Layout Issues: If the layout in the joined document doesn't match the original, consider using format-specific settings or converting documents to the same format before joining. + +3. Password Protection: Ensure you're providing the correct password for protected documents. + +4. Large Documents: For large documents, the operation may take longer to complete. Consider implementing asynchronous processing for better user experience. + +## What You've Learned + +In this tutorial, you've learned how to: +- Join documents of different formats into a single PDF or Word document +- Create appropriate requests for cross-format joining operations +- Implement cross-format joining in various programming languages +- Handle password-protected documents in a cross-format scenario +- Consider format compatibility and limitations + +## Further Practice + +To reinforce your learning, try these exercises: +1. Join a PDF, a DOCX, and a TXT file into a single PDF +2. Join a presentation (PPT/PPTX) with a Word document +3. Compare the results of joining to PDF vs. joining to DOCX + +## Next Steps + +Ready to learn more document operations? Check out these related tutorials: +- [Tutorial: How to Join Word Documents Continuously](/document-management/join-word-continous/) +- [Tutorial: How to Split a Document](/document-management/split-document/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/document-management/join-images/_index.md b/content/merger/english/document-management/join-images/_index.md new file mode 100644 index 0000000..9fe1e67 --- /dev/null +++ b/content/merger/english/document-management/join-images/_index.md @@ -0,0 +1,378 @@ +--- +title: How to Join Images Tutorial +url: /document-management/join-images/ +weight: 35 +description: Learn how to combine multiple images horizontally or vertically using GroupDocs.Merger Cloud API in this comprehensive tutorial for developers. +--- + +# Tutorial: How to Join Images + +## Introduction + +In this tutorial, you'll learn how to join multiple images into a single composite image using GroupDocs.Merger Cloud API. Image joining is a powerful feature that allows you to combine separate image files either horizontally (side by side) or vertically (stacked). This capability is particularly useful for creating panoramas, comparison images, or consolidated visual reports. + +GroupDocs.Merger Cloud provides a simple yet flexible way to join images with control over the orientation of the combined result. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Join multiple images into a single composite image +- Control the joining orientation (horizontal or vertical) +- Implement image joining in different programming languages +- Handle various image formats during joining operations + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample image files to join (JPG, PNG, etc.) + +## Use Case Scenario + +Let's consider a practical scenario: You're developing a product comparison application that needs to generate side-by-side image comparisons of different products. Users upload individual product images, and your application needs to combine them horizontally into a single comparison image that can be shared or included in reports. + +## Understanding Image Joining Modes + +GroupDocs.Merger Cloud provides two modes for joining images: + +1. Horizontal Mode: Images are placed side by side, creating a wider composite image +2. Vertical Mode: Images are stacked on top of each other, creating a taller composite image + +The mode is specified using the `ImageJoinMode` parameter in the join request. + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Image Join Request + +To join images, create a JSON request specifying: +- The image files to be joined +- The joining mode (horizontal or vertical) +- Output path for the resultant image + +Here's a basic request structure for joining images: + +```json +{ + "JoinItems": [ + { + "FileInfo": { + "FilePath": "Img/task1.jpg" + } + }, + { + "FileInfo": { + "FilePath": "Img/task2.jpg" + }, + "ImageJoinMode": "Vertical" + } + ], + "OutputPath": "Output/joined.jpg" +} +``` + +Note that the `ImageJoinMode` parameter determines how the images will be combined. In this example, the images will be stacked vertically. + +### Step 3: Join Images Using the API + +Now let's execute the image join operation using the API: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/join" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'JoinItems': + [ + { + 'FileInfo': + { + 'FilePath': 'Img/task1.jpg' + } + }, + { + 'FileInfo': + { + 'FilePath': 'Img/task2.jpg' + }, + 'ImageJoinMode': 'Vertical' + } + ], + 'OutputPath': 'Output/joined.jpg' +}" +``` + +The API will respond with: + +```json +{ + "path": "Output/joined.jpg" +} +``` + +### Step 4: Retrieve the Joined Image + +After successful joining, you can download or use the merged image from the output path provided in the response. + +## Try It Yourself + +Let's implement image joining in different programming languages. First, make sure your image files are uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Create first image join item + var item1 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "Img/task1.jpg" + } + }; + + // Create second image join item with vertical mode + var item2 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "Img/task2.jpg" + }, + ImageJoinMode = JoinItem.ImageJoinModeEnum.Vertical + }; + + // Configure join options + var options = new JoinOptions + { + JoinItems = new List { item1, item2 }, + OutputPath = "Output/joined.jpg" + }; + + // Execute join operation + var request = new JoinRequest(options); + var response = apiInstance.Join(request); + + Console.WriteLine("Output file path: " + response.Path); +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure first image + FileInfo fileInfo1 = new FileInfo(); + fileInfo1.setFilePath("Img/task1.jpg"); + JoinItem item1 = new JoinItem(); + item1.setFileInfo(fileInfo1); + + // Configure second image with vertical mode + FileInfo fileInfo2 = new FileInfo(); + fileInfo2.setFilePath("Img/task2.jpg"); + JoinItem item2 = new JoinItem(); + item2.setFileInfo(fileInfo2); + item2.setImageJoinMode(ImageJoinModeEnum.VERTICAL); + + // Configure join options + JoinOptions options = new JoinOptions(); + options.setJoinItems(Arrays.asList(item1, item2)); + options.setOutputPath("Output/joined.jpg"); + + // Execute join operation + JoinRequest request = new JoinRequest(options); + DocumentResult response = apiInstance.join(request); + + System.out.println("Output file path: " + response.getPath()); +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure first image +item1 = groupdocs_merger_cloud.JoinItem() +item1.file_info = groupdocs_merger_cloud.FileInfo("Img/task1.jpg") + +# Configure second image with vertical mode +item2 = groupdocs_merger_cloud.JoinItem() +item2.file_info = groupdocs_merger_cloud.FileInfo("Img/task2.jpg") +item2.image_join_mode = "Vertical" # Use "Vertical" or "Horizontal" + +# Configure join options +options = groupdocs_merger_cloud.JoinOptions() +options.join_items = [item1, item2] +options.output_path = "Output/joined.jpg" + +# Execute join operation +result = document_api.join(groupdocs_merger_cloud.JoinRequest(options)) + +print("Output file path = " + result.path) +``` + +## Exploring Image Joining Modes + +Let's explore the two image joining modes in more detail: + +### Horizontal Mode + +When using the horizontal mode, images are placed side by side from left to right. This is useful for: +- Creating panoramic images +- Side-by-side comparisons +- Before/after presentations + +To use horizontal mode, set the `ImageJoinMode` parameter to "Horizontal" or use the enum value in your code: + +```json +"ImageJoinMode": "Horizontal" +``` + +### Vertical Mode + +When using the vertical mode, images are stacked on top of each other from top to bottom. This is useful for: +- Creating photo strips +- Timeline presentations +- Sequential visual narratives + +To use vertical mode, set the `ImageJoinMode` parameter to "Vertical" or use the enum value in your code: + +```json +"ImageJoinMode": "Vertical" +``` + +## Joining Multiple Images + +You can join more than two images in a single operation by adding additional items to the `JoinItems` array: + +```json +{ + "JoinItems": [ + { + "FileInfo": { + "FilePath": "Img/task1.jpg" + } + }, + { + "FileInfo": { + "FilePath": "Img/task2.jpg" + }, + "ImageJoinMode": "Vertical" + }, + { + "FileInfo": { + "FilePath": "Img/task3.jpg" + }, + "ImageJoinMode": "Vertical" + } + ], + "OutputPath": "Output/joined.jpg" +} +``` + +## Supported Image Formats + +GroupDocs.Merger Cloud supports joining various image formats, including: +- JPEG/JPG +- PNG +- BMP +- GIF (static) +- TIFF + +You can mix different formats in the same join operation, and the output will be in the format specified by the output file extension. + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file paths are correct and that the images exist in your cloud storage. + +3. Image Size Differences: When joining images of different dimensions: + - In horizontal mode, the height of the resultant image will match the tallest input image, and shorter images will be padded. + - In vertical mode, the width of the resultant image will match the widest input image, and narrower images will be padded. + +4. Large Images: Be mindful of memory constraints when joining large or high-resolution images. Consider resizing images before joining if necessary. + +5. Unsupported Formats: Ensure you're using supported image formats. Some formats like SVG are not supported for joining operations. + +## What You've Learned + +In this tutorial, you've learned how to: +- Join multiple images into a single composite image +- Control the orientation of joined images (horizontal or vertical) +- Implement image joining in different programming languages +- Handle various image formats and considerations + +## Further Practice + +To reinforce your learning, try these exercises: +1. Join three or more images in both horizontal and vertical modes +2. Create a grid-like composite by joining horizontal strips vertically +3. Join images of different formats and dimensions to observe how they are handled +4. Build a simple application that allows users to select images and joining mode + +## Next Steps + +Ready to explore more document operations? Check out these related tutorials: +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) +- [Tutorial: How to Generate Document Page Previews](/document-management/generate-document-pages-preview/) +- [Tutorial: How to Split a Document](/document-management/split-document/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/document-management/join-multiple-documents/_index.md b/content/merger/english/document-management/join-multiple-documents/_index.md new file mode 100644 index 0000000..d6f0e50 --- /dev/null +++ b/content/merger/english/document-management/join-multiple-documents/_index.md @@ -0,0 +1,288 @@ +--- +title: How to Join Multiple Documents Tutorial +weight: 10 +url: /document-management/join-multiple-documents/ +description: Learn how to combine multiple documents into a single file with GroupDocs.Merger Cloud API in this step-by-step tutorial for developers. +--- + +# Tutorial: How to Join Multiple Documents + +## Introduction + +In this tutorial, you'll learn how to join multiple documents into a single resultant file using GroupDocs.Merger Cloud API. Document merging is one of the most common operations in document management systems, and this tutorial will guide you through implementing this functionality in your applications. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Understand the GroupDocs.Merger Join API's capabilities +- Implement document joining functionality in different programming languages +- Handle password-protected documents during the joining process +- Combine different document formats (DOCX, PDF, etc.) + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample documents to merge (DOCX, PDF, etc.) + +## Use Case Scenario + +Let's consider a practical scenario: You're developing a document processing application that needs to combine multiple reports into a single document. Your users want to upload separate files and receive a unified document that contains all content in the correct order. + +## Implementation Steps + +### Step 1: Authenticate with the API + +Before performing any document operations, you need to authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Document Join Request + +To join documents, you need to create a JSON request specifying: +- The files to be joined (file paths in storage) +- Output path for the resultant document +- Any passwords for protected documents + +Here's a basic request structure: + +```json +{ + "JoinItems": [ + { + "FileInfo": { + "FilePath": "/WordProcessing/document1.docx" + } + }, + { + "FileInfo": { + "FilePath": "/WordProcessing/document2.docx" + } + } + ], + "OutputPath": "output/joined-document.docx" +} +``` + +### Step 3: Join Documents Using the API + +Now let's execute the document join operation using the API: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/join" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'JoinItems': + [ + { + 'FileInfo': + { + 'FilePath': '/WordProcessing/four-pages.docx', + 'Password': 'password' + } + }, + { + 'FileInfo': + { + 'FilePath': '/WordProcessing/one-page.docx' + } + } + ], + 'OutputPath': 'output/joined.docx' +}" +``` + +The API will respond with: + +```json +{ + "path": "output/joined.docx" +} +``` + +### Step 4: Retrieve the Joined Document + +After successful joining, you can download or use the merged document from the output path provided in the response. + +## Try It Yourself + +Let's practice joining documents in different programming languages. First, make sure your documents are uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Create a join item for the first document (password-protected) + var item1 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/four-pages.docx", + Password = "password" + } + }; + + // Create a join item for the second document + var item2 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/one-page.docx" + } + }; + + // Configure join options + var options = new JoinOptions + { + JoinItems = new List { item1, item2 }, + OutputPath = "Output/joined.docx" + }; + + // Execute join operation + var request = new JoinRequest(options); + var response = apiInstance.Join(request); + + Console.WriteLine("Output file path: " + response.Path); +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure first document (password-protected) + FileInfo fileInfo1 = new FileInfo(); + fileInfo1.setFilePath("WordProcessing/four-pages.docx"); + fileInfo1.setPassword("password"); + JoinItem item1 = new JoinItem(); + item1.setFileInfo(fileInfo1); + + // Configure second document + FileInfo fileInfo2 = new FileInfo(); + fileInfo2.setFilePath("WordProcessing/one-page.docx"); + JoinItem item2 = new JoinItem(); + item2.setFileInfo(fileInfo2); + + // Configure join options + JoinOptions options = new JoinOptions(); + options.setJoinItems(Arrays.asList(item1, item2)); + options.setOutputPath("output/joined.docx"); + + // Execute join operation + JoinRequest request = new JoinRequest(options); + DocumentResult response = apiInstance.join(request); + + System.out.println("Output file path: " + response.getPath()); +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure first document (password-protected) +item1 = groupdocs_merger_cloud.JoinItem() +item1.file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/four-pages.docx", None, None, "password") + +# Configure second document +item2 = groupdocs_merger_cloud.JoinItem() +item2.file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/one-page.docx") + +# Configure join options +options = groupdocs_merger_cloud.JoinOptions() +options.join_items = [item1, item2] +options.output_path = "Output/joined.docx" + +# Execute join operation +result = document_api.join(groupdocs_merger_cloud.JoinRequest(options)) + +print("Output file path = " + result.path) +``` + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file paths are correct and that the documents exist in your cloud storage. + +3. Password Protection: For protected documents, ensure you're providing the correct password in the request. + +4. Format Compatibility: When joining different document formats, make sure they are compatible for joining operations. For cross-format joining, refer to our [dedicated tutorial](/document-management/join-document-cross-format/). + +## What You've Learned + +In this tutorial, you've learned how to: +- Authenticate with the GroupDocs.Merger Cloud API +- Create a request to join multiple documents +- Handle password-protected documents +- Execute the join operation in various programming languages +- Process the API response to get the merged document + +## Further Practice + +To reinforce your learning, try these exercises: +1. Join three or more documents of the same format +2. Join documents from different storage locations +3. Join specific pages from documents instead of entire documents + +## Next Steps + +Ready to learn more advanced document operations? Check out these related tutorials: +- [Tutorial: How to Join Documents of Different Formats](/document-management/join-document-cross-format/) +- [Tutorial: How to Split a Document](/document-management/split-document/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/document-management/join-word-continuous/_index.md b/content/merger/english/document-management/join-word-continuous/_index.md new file mode 100644 index 0000000..628ac33 --- /dev/null +++ b/content/merger/english/document-management/join-word-continuous/_index.md @@ -0,0 +1,322 @@ +--- +title: How to Join Word Documents Continuously Tutorial +weight: 30 +url: /document-management/join-word-continous/ +description: Learn how to merge Word documents without page breaks in this step-by-step tutorial using GroupDocs.Merger Cloud API. +--- + +# Tutorial: How to Join Word Documents Continuously + +## Introduction + +In this tutorial, you'll learn how to join Word documents continuously, meaning without page breaks between documents, using GroupDocs.Merger Cloud API. This is a specialized joining option that allows you to merge documents seamlessly, as if they were parts of the same document from the beginning. + +When merging Word documents using the standard method, each source document typically starts on a new page in the resultant document. With continuous joining, the last page of one document flows directly into the first page of the next document, creating a seamless transition without empty space or page breaks between them. + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Understand the difference between standard and continuous document joining +- Implement continuous joining for Word documents +- Configure WordJoinMode parameter for seamless document merging +- Test and validate continuous joining in different programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample Word documents to merge +- Completed the [basic document joining tutorial](/document-management/join-multiple-documents/) (recommended) + +## Use Case Scenario + +Let's consider a practical scenario: You're building a contract generation system that needs to combine standard clauses with custom sections into a single, seamless document. Each section is stored as a separate Word document, but when combined, they should flow naturally as if they were written as one document, without unnecessary page breaks. + +## Understanding Continuous Joining + +### Standard vs. Continuous Joining + +Standard Joining: By default, when joining Word documents, each source document starts on a new page in the resultant document. This is appropriate for combining complete chapters or independent documents. + +Continuous Joining: With continuous joining, the last page of one document flows directly into the first page of the next document without a page break in between. This is ideal for joining partial sections that should be read as a single continuous document. + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Continuous Join Request + +To join Word documents continuously, create a JSON request specifying: +- The files to be joined +- The WordJoinMode parameter set to "Continuous" for the second and subsequent documents +- Output path for the resultant document + +Here's a basic request structure: + +```json +{ + "JoinItems": [ + { + "FileInfo": { + "FilePath": "WordProcessing/four-pages.docx", + "Password": "password" + } + }, + { + "FileInfo": { + "FilePath": "WordProcessing/one-page.docx" + }, + "WordJoinMode": "Continuous" + } + ], + "OutputPath": "output/joined_continuous.docx" +} +``` + +Note that the `WordJoinMode` parameter is set to "Continuous" only for the second document, as it will be appended to the first document without a page break. + +### Step 3: Join Word Documents Continuously Using the API + +Now let's execute the continuous document join operation using the API: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/join" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'JoinItems': + [ + { + 'FileInfo': + { + 'FilePath': 'WordProcessing/four-pages.docx', + 'Password': 'password' + } + }, + { + 'FileInfo': + { + 'FilePath': 'WordProcessing/one-page.docx' + }, + 'WordJoinMode': 'Continuous' + } + ], + 'OutputPath': 'output/joined_continuous.docx' +}" +``` + +The API will respond with: + +```json +{ + "path": "output/joined_continuous.docx" +} +``` + +### Step 4: Retrieve and Verify the Joined Document + +After successful joining, you can download the merged document from the output path provided in the response. Open the document to verify that there is no page break between the content of the first and second documents. + +## Try It Yourself + +Let's implement continuous document joining in different programming languages. First, make sure your Word documents are uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Create first join item (standard) + var item1 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/four-pages.docx" + } + }; + + // Create second join item with continuous mode + var item2 = new JoinItem + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/one-page.docx" + }, + WordJoinMode = JoinItem.WordJoinModeEnum.Continuous + }; + + // Configure join options + var options = new JoinOptions + { + JoinItems = new List { item1, item2 }, + OutputPath = "Output/joined_continuous.docx" + }; + + // Execute join operation + var request = new JoinRequest(options); + var response = apiInstance.Join(request); + + Console.WriteLine("Output file path: " + response.Path); +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure first document (standard joining) + FileInfo fileInfo1 = new FileInfo(); + fileInfo1.setFilePath("WordProcessing/four-pages.docx"); + JoinItem item1 = new JoinItem(); + item1.setFileInfo(fileInfo1); + + // Configure second document (continuous joining) + FileInfo fileInfo2 = new FileInfo(); + fileInfo2.setFilePath("WordProcessing/one-page.docx"); + JoinItem item2 = new JoinItem(); + item2.setFileInfo(fileInfo2); + item2.setWordJoinMode(WordJoinModeEnum.CONTINUOUS); + + // Configure join options + JoinOptions options = new JoinOptions(); + options.setJoinItems(Arrays.asList(item1, item2)); + options.setOutputPath("output/joined_continuous.docx"); + + // Execute join operation + JoinRequest request = new JoinRequest(options); + DocumentResult response = apiInstance.join(request); + + System.out.println("Output file path: " + response.getPath()); +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure first document (standard joining) +item1 = groupdocs_merger_cloud.JoinItem() +item1.file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/four-pages.docx") + +# Configure second document (continuous joining) +item2 = groupdocs_merger_cloud.JoinItem() +item2.file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/one-page.docx") +item2.word_join_mode = "Continuous" + +# Configure join options +options = groupdocs_merger_cloud.JoinOptions() +options.join_items = [item1, item2] +options.output_path = "Output/joined_continuous.docx" + +# Execute join operation +result = document_api.join(groupdocs_merger_cloud.JoinRequest(options)) + +print("Output file path = " + result.path) +``` + +## Important Considerations + +When using continuous joining, keep these points in mind: + +1. Compatible Documents Only: Continuous joining works only with Word documents (DOCX, DOC, etc.). It cannot be used with PDF, presentations, or other formats. + +2. Formatting Consistency: For the best results, ensure that the documents being joined have consistent formatting (font, styles, etc.) to create a truly seamless appearance. + +3. Headers and Footers: Be aware that headers and footers from individual documents may behave unexpectedly when using continuous joining. Test the results to ensure they meet your expectations. + +4. Section Breaks: If your source documents contain section breaks, they might affect how the continuous joining works. You may need to clean up the documents beforehand. + +5. Document Properties: The properties of the first document (such as author, title, etc.) will be preserved in the resultant document. + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file paths are correct and that the documents exist in your cloud storage. + +3. Password Protection: For protected documents, ensure you're providing the correct password in the request. + +4. Unsupported Format: If you attempt to use continuous joining with non-Word documents, you may receive an error. Ensure you're using compatible formats. + +5. Unexpected Formatting: If the joined document has unexpected formatting or layout issues, try opening and resaving the source documents to ensure they are properly formatted. + +## What You've Learned + +In this tutorial, you've learned how to: +- Understand the difference between standard and continuous document joining +- Create a request for continuous joining of Word documents +- Configure the WordJoinMode parameter for seamless document merging +- Implement continuous joining in various programming languages +- Handle potential issues and considerations for optimal results + +## Further Practice + +To reinforce your learning, try these exercises: +1. Join three or more Word documents with continuous joining between some of them +2. Compare the results of standard joining versus continuous joining with the same documents +3. Join documents with different formatting styles and observe how the formatting is handled in the resultant document +4. Create a document template system that combines standard clauses with custom sections seamlessly + +## Next Steps + +Ready to explore more document operations? Check out these related tutorials: +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) +- [Tutorial: How to Join Images](/document-management/join-images/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/document-management/split-document/_index.md b/content/merger/english/document-management/split-document/_index.md new file mode 100644 index 0000000..137c37b --- /dev/null +++ b/content/merger/english/document-management/split-document/_index.md @@ -0,0 +1,403 @@ +--- +title: How to Split a Document Tutorial +weight: 25 +url: /document-management/split-document/ +description: Learn how to split documents into multiple files with precision using GroupDocs.Merger Cloud API in this comprehensive developer tutorial. +--- + +# Tutorial: How to Split a Document + +## Introduction + +In this tutorial, you'll learn how to split documents into multiple smaller documents using GroupDocs.Merger Cloud API. Document splitting is a powerful feature that allows you to divide large documents into more manageable pieces, extract specific sections, or create separate documents for different chapters or sections. + +GroupDocs.Merger Cloud offers flexible document splitting capabilities with multiple approaches: +- Split into single-page documents by specifying exact page numbers +- Split into single-page documents using start/end page ranges +- Apply filters to split only even or odd pages +- Split into multi-page documents at specified breakpoints + +## Learning Objectives + +By the end of this tutorial, you will be able to: +- Split a document into multiple single-page documents +- Extract specific pages from a document +- Split documents using page ranges and filters +- Create multi-page documents from splitting operations +- Implement document splitting in different programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +- A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +- Your Client ID and Client Secret credentials +- Basic knowledge of RESTful APIs +- Sample multi-page documents to work with + +## Use Case Scenario + +Let's consider a practical scenario: You have a large annual report document (100+ pages) that needs to be divided into separate chapters for distribution to different departments. Each chapter starts on specific pages within the document (e.g., chapter 1 on page 1, chapter 2 on page 25, chapter 3 on page 42, etc.). + +## Implementation Steps + +### Step 1: Authenticate with the API + +First, authenticate with the GroupDocs.Merger Cloud API by obtaining a JWT token using your Client ID and Client Secret. + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +### Step 2: Prepare Your Document Splitting Request + +GroupDocs.Merger Cloud provides different approaches to document splitting. Let's explore each method: + +#### Method 1: Split to Single-Page Documents by Exact Page Numbers + +This method allows you to extract specific pages into separate single-page documents. + +```json +{ + "FileInfo": { "FilePath": "WordProcessing/sample-10-pages.docx" }, + "Pages": [ 3, 6, 8 ], + "Mode": "Pages", + "OutputPath": "output/split-to-specific-pages" +} +``` + +#### Method 2: Split to Single-Page Documents by Page Range + +This method creates separate single-page documents for each page within a specified range. + +```json +{ + "FileInfo": { "FilePath": "WordProcessing/sample-10-pages.docx" }, + "StartPageNumber": 3, + "EndPageNumber": 7, + "Mode": "Pages", + "OutputPath": "output/split-by-page-range" +} +``` + +#### Method 3: Split to Single-Page Documents with Filtering + +This method creates separate single-page documents for odd or even pages within a specified range. + +```json +{ + "FileInfo": { "FilePath": "WordProcessing/sample-10-pages.docx" }, + "StartPageNumber": 3, + "EndPageNumber": 7, + "RangeMode": "Odd", + "Mode": "Pages", + "OutputPath": "output/split-filtered-pages" +} +``` + +#### Method 4: Split to Multi-Page Documents + +This method creates multiple multi-page documents based on specified breakpoints. + +```json +{ + "FileInfo": { "FilePath": "WordProcessing/sample-10-pages.docx" }, + "Pages": [ 3, 6, 8 ], + "Mode": "Intervals", + "OutputPath": "output/split-to-multipage" +} +``` + +### Step 3: Execute Document Splitting Operation + +Let's execute the document splitting operation using the API. For this example, we'll use Method 1 to extract specific pages: + +#### cURL Example + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/split" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': 'WordProcessing/sample-10-pages.docx' }, + 'Pages': [ 3, 6, 8 ], + 'Mode': 'Pages', + 'OutputPath': 'output/split-to-specific-pages' +}" +``` + +The API will respond with: + +```json +{ + "documents": [ + { + "path": "output/split-to-specific-pages/sample-10-pages_0.docx" + }, + { + "path": "output/split-to-specific-pages/sample-10-pages_1.docx" + }, + { + "path": "output/split-to-specific-pages/sample-10-pages_2.docx" + } + ] +} +``` + +## Try It Yourself + +Let's implement document splitting in different programming languages. First, make sure your multi-page document is uploaded to your GroupDocs Cloud storage, then use the appropriate SDK for your language. + +### C# Example: Splitting to Single Pages by Exact Numbers + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Configure split options with specific pages + var options = new SplitOptions + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/sample-10-pages.docx" + }, + Pages = new List { 3, 6, 8 }, + Mode = SplitOptions.ModeEnum.Pages, + OutputPath = "Output/split-to-specific-pages" + }; + + // Execute split operation + var request = new SplitRequest(options); + var response = apiInstance.Split(request); + + Console.WriteLine("Number of created documents: " + response.Documents.Count); + foreach (var doc in response.Documents) + { + Console.WriteLine("Document path: " + doc.Path); + } +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +### Java Example: Splitting to Single Pages by Page Range + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +String MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +DocumentApi apiInstance = new DocumentApi(configuration); + +try { + // Configure file info + FileInfo fileInfo = new FileInfo(); + fileInfo.setFilePath("WordProcessing/sample-10-pages.docx"); + + // Configure split options with page range + SplitOptions options = new SplitOptions(); + options.setFileInfo(fileInfo); + options.setStartPageNumber(3); + options.setEndPageNumber(7); + options.setMode(ModeEnum.PAGES); + options.setOutputPath("output/split-by-page-range"); + + // Execute split operation + SplitRequest request = new SplitRequest(options); + SplitResult response = apiInstance.split(request); + + System.out.println("Number of created documents: " + response.getDocuments().size()); + for(DocumentResult doc : response.getDocuments()) { + System.out.println("Document path: " + doc.getPath()); + } +} catch (ApiException e) { + System.err.println("Exception while calling API:"); + e.printStackTrace(); +} +``` + +### Python Example: Splitting to Single Pages with Filtering (Odd Pages) + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger_cloud-cloud/groupdocs-merger_cloud-cloud-python-samples +from groupdocs_merger_cloud import * +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +# Create instance of the API +document_api = groupdocs_merger_cloud.DocumentApi.from_keys(client_id, client_secret) + +# Configure file info +file_info = groupdocs_merger_cloud.FileInfo("WordProcessing/sample-10-pages.docx") + +# Configure split options with page range and odd filter +options = groupdocs_merger_cloud.SplitOptions() +options.file_info = file_info +options.start_page_number = 3 +options.end_page_number = 7 +options.range_mode = "Odd" # Use "Odd" for odd pages, "Even" for even pages +options.mode = "Pages" +options.output_path = "Output/split-filtered-pages" + +# Execute split operation +result = document_api.split(groupdocs_merger_cloud.SplitRequest(options)) + +print(f"Number of created documents: {len(result.documents)}") +for doc in result.documents: + print(f"Document path: {doc.path}") +``` + +### C# Example: Splitting to Multi-Page Documents + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); +var apiInstance = new DocumentApi(configuration); + +try +{ + // Configure split options for multi-page documents + var options = new SplitOptions + { + FileInfo = new FileInfo + { + FilePath = "WordProcessing/sample-10-pages.docx" + }, + Pages = new List { 3, 6, 8 }, + Mode = SplitOptions.ModeEnum.Intervals, // Use Intervals mode for multi-page splitting + OutputPath = "Output/split-to-multipage" + }; + + // Execute split operation + var request = new SplitRequest(options); + var response = apiInstance.Split(request); + + Console.WriteLine("Number of created documents: " + response.Documents.Count); + foreach (var doc in response.Documents) + { + Console.WriteLine("Document path: " + doc.Path); + } +} +catch (Exception e) +{ + Console.WriteLine("Exception while calling API: " + e.Message); +} +``` + +## Understanding Document Splitting Options + +GroupDocs.Merger Cloud provides versatile splitting capabilities through several key parameters: + +### Pages Collection vs. Page Range + +You have two ways to specify which pages to extract: + +- Pages Collection: Provide an array of specific page numbers to extract. + ```json + "Pages": [3, 6, 8] + ``` + +- Page Range: Define a contiguous range with start and end page numbers. + ```json + "StartPageNumber": 3, + "EndPageNumber": 7 + ``` + +### Splitting Modes + +The `Mode` parameter determines how the document will be split: + +- Pages Mode: Creates separate single-page documents for each specified page. + ```json + "Mode": "Pages" + ``` + +- Intervals Mode: Creates multi-page documents using the specified pages as breakpoints. + ```json + "Mode": "Intervals" + ``` + +When using Intervals mode with Pages [3, 6, 8], you will get: +- Document 1: Pages 1-2 +- Document 2: Pages 3-5 +- Document 3: Pages 6-7 +- Document 4: Pages 8-10 + +### Range Filtering + +The `RangeMode` parameter allows you to filter pages when using page ranges: + +- All: Include all pages in the range (default) +- Odd: Include only odd-numbered pages in the range +- Even: Include only even-numbered pages in the range + +```json +"RangeMode": "Odd" +``` + +## Common Issues and Troubleshooting + +1. Authentication Error: If you receive a 401 Unauthorized error, make sure your Client ID and Client Secret are correct and that your JWT token hasn't expired. + +2. File Not Found: Verify that the file path is correct and that the document exists in your cloud storage. + +3. Invalid Page Numbers: If you specify page numbers that don't exist in the document, you'll receive an error. Always ensure that page numbers are within the valid range of your document. + +4. Output Path Issues: Make sure the output path is valid. The API will create any necessary directories. + +5. File Format Support: Verify that your document format is supported for splitting operations. Most common formats (PDF, DOCX, PPTX, etc.) are supported. + +## What You've Learned + +In this tutorial, you've learned how to: +- Split a document into multiple single-page documents +- Extract specific pages from a document +- Create page ranges with filtering options +- Split a document into multi-page documents at specified breakpoints +- Implement document splitting in different programming languages +- Handle the API response to access the extracted documents + +## Further Practice + +To reinforce your learning, try these exercises: +1. Split a PDF document with more than 20 pages into chapters at pages 5, 10, 15, and 20 +2. Extract only even pages from a specific range of a document +3. Create a custom workflow that first splits a document and then joins specific parts back together +4. Split a password-protected document + +## Next Steps + +Ready to learn more advanced document operations? Check out these related tutorials: +- [Tutorial: How to Join Multiple Documents](/document-management/join-multiple-documents/) +- [Tutorial: How to Generate Document Page Previews](/document-management/generate-document-pages-preview/) + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +Have questions about this tutorial? Feel free to share your feedback or ask questions on our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! \ No newline at end of file diff --git a/content/merger/english/getting_started/_index.md b/content/merger/english/getting_started/_index.md new file mode 100644 index 0000000..ea9e9c6 --- /dev/null +++ b/content/merger/english/getting_started/_index.md @@ -0,0 +1,72 @@ +--- +title: GroupDocs.Merger Cloud API Getting Started Tutorials +weight: 1 +url: /getting-started/ +description: Step-by-step tutorials for developers to learn how to use GroupDocs.Merger Cloud API - from basic operations to advanced document manipulation. +--- + +# GroupDocs.Merger Cloud API: Getting Started Tutorials + +Welcome to our hands-on tutorial series for the GroupDocs.Merger Cloud API! These step-by-step guides are designed to help developers quickly understand and implement document merging operations in their applications. + +## Learning Path: From Basics to Advanced + +This tutorial series follows a structured learning path, beginning with fundamental concepts and progressing to more advanced document manipulation techniques. Whether you're new to GroupDocs.Merger Cloud or looking to expand your knowledge, these tutorials provide practical, real-world examples to enhance your development skills. + +## Estimated Time: 2-3 hours for the complete series + +## Prerequisites + +Before starting these tutorials, you should have: +- A GroupDocs.Merger Cloud account (or [sign up for a free trial](https://dashboard.groupdocs.cloud/#/apps) +- Basic knowledge of REST APIs +- Familiarity with your preferred programming language (C#, Java, PHP, Node.js, Python, or Ruby) +- Development environment set up for your chosen language + +## Tutorial Guide + +### Beginner Level + +1. [Tutorial: Getting Document Information](/getting-started/get-document-information/) + - Learn to retrieve essential metadata and page properties from your documents + - Understand document structure before performing merge operations + +2. [Tutorial: Getting Supported File Formats](/getting-started/get-supported-file-formats/) + - Discover all document formats supported by the API + - Learn how to check compatibility before processing files + +3. [Tutorial: Working with Files](/getting-started/working-with-files/) + - Master uploading, downloading, and managing files in the cloud storage + - Learn essential file operations for document processing workflows + +### Intermediate Level + +4. [Tutorial: Working with Folders](/getting-started/working-with-folder/) + - Learn efficient folder management techniques + - Organize your documents for better project structure + +## What You'll Learn + +By completing these tutorials, you'll gain practical skills to: +- Integrate GroupDocs.Merger Cloud API into your applications +- Perform document operations efficiently and securely +- Implement best practices for document management +- Build robust document processing workflows + +## Further Practice + +Each tutorial includes "Try it yourself" sections with additional exercises to reinforce your learning. We encourage you to experiment with different parameter combinations and document types to deepen your understanding. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +## Feedback + +Have questions about these tutorials? We're here to help! Please share your feedback or ask questions in our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/getting_started/get_document_information/_index.md b/content/merger/english/getting_started/get_document_information/_index.md new file mode 100644 index 0000000..296ecdd --- /dev/null +++ b/content/merger/english/getting_started/get_document_information/_index.md @@ -0,0 +1,299 @@ +--- +title: How to Get Document Information with GroupDocs.Merger Cloud API Tutorial +weight: 1 +url: /getting-started/get-document-information/ +description: Learn how to retrieve document metadata and page properties with GroupDocs.Merger Cloud API in this step-by-step tutorial for developers. +--- + +# Tutorial: How to Get Document Information with GroupDocs.Merger Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to use the GroupDocs.Merger Cloud API to retrieve essential information about documents stored in your cloud storage. This foundational skill will help you understand document structure before performing more complex operations. + +## Prerequisites + +Before starting this tutorial, ensure you have: + +1. A GroupDocs.Merger Cloud account (or [sign up for a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret from the [GroupDocs Cloud Dashboard](https://dashboard.groupdocs.cloud/) +3. At least one document uploaded to your cloud storage +4. Basic understanding of REST API concepts +5. Development environment for your preferred language (optional for cURL examples) + +## Use Case Scenario + +Imagine you're building a document management system that needs to display document properties to users before they perform merge operations. You need to extract information such as: + +- Document file extension +- File size +- File format +- Page dimensions +- Page visibility status + +This tutorial will show you how to retrieve this information programmatically. + +## Step 1: Understanding the Document Information API + +The GroupDocs.Merger Cloud API provides an endpoint that returns basic information about a document and its pages. This REST API accepts the document storage path as an input payload. + +Here's what you can retrieve: +- Document properties: File extension, size in bytes, and file format +- Page properties: Width and height in pixels, page number, and visibility status + +The API endpoint for this operation is: + +``` +HTTP POST ~/info +``` + +## Step 2: Preparing Your Request + +To retrieve document information, you'll need to: + +1. Obtain an access token using your Client ID and Client Secret +2. Make a POST request to the info endpoint with your document path + +Let's break this down: + +### Step 2.1: Get Your Access Token + +First, you need to authenticate with the API to receive a JSON Web Token (JWT): + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual credentials. + +The response will contain an access token that you'll use in the next step. + +### Step 2.2: Formulate Your Document Information Request + +Now, construct a POST request to retrieve document information: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/info" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ +-d "{ \"FilePath\": \"/wordprocessing/four-pages.docx\" }" +``` + +Replace `YOUR_ACCESS_TOKEN` with the token you received in Step 2.1, and adjust the `FilePath` to match your document's location in cloud storage. + +## Step 3: Understanding the Response + +When you execute the request, you'll receive a JSON response like this: + +```json +{ + "extension": ".docx", + "pages": [ + { + "width": 612, + "height": 792, + "pageNumber": 1, + "visible": true + }, + { + "width": 612, + "height": 792, + "pageNumber": 2, + "visible": true + }, + { + "width": 612, + "height": 792, + "pageNumber": 3, + "visible": true + }, + { + "width": 612, + "height": 792, + "pageNumber": 4, + "visible": true + } + ], + "size": 8651, + "fileFormat": "Microsoft Word Open XML Document" +} +``` + +This response shows: +- The document is a `.docx` file (Microsoft Word Open XML Document) +- It has 4 pages, each 612×792 pixels when converted to an image +- All pages are visible (important for page manipulation operations) +- The file size is 8,651 bytes + +## Step 4: Implementing with SDK in Your Application + +While you can use direct REST API calls as shown above, GroupDocs provides SDKs for various programming languages to simplify integration. Let's see how to get document information using these SDKs. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new InfoApi(configuration); + +var fileInfo = new FileInfo +{ + FilePath = "wordprocessing/four-pages.docx" +}; + +var request = new GetInfoRequest(fileInfo); + +var response = apiInstance.GetInfo(request); + +// Document information +Console.WriteLine("Document properties:"); +Console.WriteLine($"File format: {response.FileFormat}"); +Console.WriteLine($"Extension: {response.Extension}"); +Console.WriteLine($"Size in bytes: {response.Size}"); + +// Page information +Console.WriteLine("\nPage information:"); +foreach (var page in response.Pages) +{ + Console.WriteLine($"\nPage #{page.PageNumber}"); + Console.WriteLine($"Width: {page.Width}px"); + Console.WriteLine($"Height: {page.Height}px"); + Console.WriteLine($"Visible: {page.Visible}"); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get your client ID and secret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get your client ID and secret from https://dashboard.groupdocs.cloud + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(client_id, client_secret) +api = groupdocs_merger_cloud.InfoApi(configuration) + +# Prepare request +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "wordprocessing/four-pages.docx" + +request = groupdocs_merger_cloud.GetInfoRequest(file_info) + +# Retrieve document information +result = api.get_info(request) + +# Document information +print("Document properties:") +print(f"File format: {result.file_format}") +print(f"Extension: {result.extension}") +print(f"Size in bytes: {result.size}") + +# Page information +print("\nPage information:") +for page in result.pages: + print(f"\nPage #{page.page_number}") + print(f"Width: {page.width}px") + print(f"Height: {page.height}px") + print(f"Visible: {page.visible}") +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +import com.groupdocs.cloud.merger.client.*; +import com.groupdocs.cloud.merger.model.*; +import com.groupdocs.cloud.merger.api.InfoApi; + +public class GetDocumentInformationExample { + public static void main(String[] args) { + String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + String clientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + + // Create instance of the API + Configuration configuration = new Configuration(clientId, clientSecret); + InfoApi api = new InfoApi(configuration); + + try { + // Prepare request + FileInfo fileInfo = new FileInfo(); + fileInfo.setFilePath("wordprocessing/four-pages.docx"); + + GetInfoRequest request = new GetInfoRequest(fileInfo); + + // Get document information + InfoResult result = api.getInfo(request); + + // Document information + System.out.println("Document properties:"); + System.out.println("File format: " + result.getFileFormat()); + System.out.println("Extension: " + result.getExtension()); + System.out.println("Size in bytes: " + result.getSize()); + + // Page information + System.out.println("\nPage information:"); + for (PageInfo page : result.getPages()) { + System.out.println("\nPage #" + page.getPageNumber()); + System.out.println("Width: " + page.getWidth() + "px"); + System.out.println("Height: " + page.getHeight() + "px"); + System.out.println("Visible: " + page.isVisible()); + } + } catch (Exception e) { + System.out.println("Error: " + e.getMessage()); + e.printStackTrace(); + } + } +} +``` + +## Try It Yourself: Practice Exercises + +Now that you understand how to retrieve document information, try these exercises to reinforce your learning: + +1. Exercise 1: Retrieve information for different file types (PDF, PPTX, etc.) and compare the responses. Notice how different document formats may have different page properties. + +2. Exercise 2: Create a simple application that displays document thumbnails based on the page dimensions retrieved from the API. + +3. Exercise 3: Use the page visibility property to identify and list only visible pages in a document with hidden pages. + +## Troubleshooting Tips + +- Authentication errors: Ensure your Client ID and Client Secret are correct and that your account has appropriate permissions. +- File not found errors: Verify that the file path in your request matches the actual location in your cloud storage. +- Invalid format errors: Confirm that the document format is supported by GroupDocs.Merger Cloud by using the "Get Supported File Formats" API. + +## What You've Learned + +In this tutorial, you've learned how to: +- Retrieve comprehensive information about documents stored in the cloud +- Access detailed page properties for document manipulation +- Implement document information retrieval using different programming languages +- Interpret and utilize the API response to understand document structure + +## Next Steps + +Now that you can retrieve document information, a logical next step is to learn about the file formats supported by GroupDocs.Merger Cloud. Continue to our [Tutorial: Getting Supported File Formats](/getting-started/get-supported-file-formats/) to expand your knowledge. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +## Feedback + +Did you find this tutorial helpful? Do you have questions about retrieving document information? Let us know in our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/getting_started/get_supported_file_formats/_index.md b/content/merger/english/getting_started/get_supported_file_formats/_index.md new file mode 100644 index 0000000..7e7bbed --- /dev/null +++ b/content/merger/english/getting_started/get_supported_file_formats/_index.md @@ -0,0 +1,338 @@ +--- +title: How to Get Supported File Formats with GroupDocs.Merger Cloud API Tutorial +weight: 2 +url: /getting-started/get-supported-file-formats/ +description: Learn how to programmatically retrieve all supported file formats for document merging with GroupDocs.Merger Cloud in this developer tutorial. +--- + +# Tutorial: How to Get Supported File Formats with GroupDocs.Merger Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to retrieve a list of all file formats that are supported by the GroupDocs.Merger Cloud API. This knowledge is critical for determining which document types you can work with before implementing document merging operations in your applications. + +## Prerequisites + +Before starting this tutorial, ensure you have: + +1. A GroupDocs.Merger Cloud account (or [sign up for a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret from the [GroupDocs Cloud Dashboard](https://dashboard.groupdocs.cloud/) +3. Basic understanding of REST API concepts +4. Development environment for your preferred language (optional for cURL examples) + +## Use Case Scenario + +Imagine you're developing a document management application that needs to validate file formats before users upload documents. You need to: +- Present users with a list of supported file types +- Validate uploaded files against supported formats +- Filter documents based on format compatibility + +This tutorial will show you how to programmatically retrieve all supported formats to implement these features. + +## Step 1: Understanding the Supported File Formats API + +The GroupDocs.Merger Cloud API provides a dedicated endpoint for retrieving all supported file formats. This REST API returns a list of file extensions along with their corresponding format descriptions. + +The API endpoint for this operation is: + +``` +HTTP GET ~/formats +``` + +## Step 2: Preparing Your Request + +To retrieve supported file formats, you'll need to: + +1. Obtain an access token using your Client ID and Client Secret +2. Make a GET request to the formats endpoint + +Let's break this down: + +### Step 2.1: Get Your Access Token + +First, you need to authenticate with the API to receive a JSON Web Token (JWT): + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual credentials. + +The response will contain an access token that you'll use in the next step. + +### Step 2.2: Formulate Your File Formats Request + +Now, construct a GET request to retrieve supported file formats: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/formats" \ +-X GET \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with the token you received in Step 2.1. + +## Step 3: Understanding the Response + +When you execute the request, you'll receive a JSON response like this (abbreviated for clarity): + +```json +{ + "formats": [ + { + "extension": ".doc", + "fileFormat": "Microsoft Word Document" + }, + { + "extension": ".docm", + "fileFormat": "Word Open XML Macro-Enabled Document" + }, + { + "extension": ".docx", + "fileFormat": "Microsoft Word Open XML Document" + }, + ... + { + "extension": ".xlsx", + "fileFormat": "Microsoft Excel Open XML Spreadsheet" + } + ] +} +``` + +This response includes an array of format objects, each containing: +- `extension`: The file extension (e.g., ".docx") +- `fileFormat`: A human-readable description of the file format + +## Step 4: Implementing with SDK in Your Application + +While you can use direct REST API calls as shown above, GroupDocs provides SDKs for various programming languages to simplify integration. Let's see how to get supported file formats using these SDKs. + +### C# Example + +```csharp +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new InfoApi(configuration); + +var response = apiInstance.GetSupportedFileFormats(); + +Console.WriteLine("Supported File Formats:"); +foreach (var format in response.Formats) +{ + Console.WriteLine($"{format.Extension} - {format.FileFormat}"); +} + +// Group formats by type +Console.WriteLine("\nWord Processing Formats:"); +foreach (var format in response.Formats.Where(f => f.FileFormat.Contains("Word") || f.Extension == ".rtf" || f.Extension == ".txt")) +{ + Console.WriteLine($"{format.Extension} - {format.FileFormat}"); +} + +Console.WriteLine("\nSpreadsheet Formats:"); +foreach (var format in response.Formats.Where(f => f.FileFormat.Contains("Excel") || f.Extension == ".csv")) +{ + Console.WriteLine($"{format.Extension} - {format.FileFormat}"); +} + +Console.WriteLine("\nPresentation Formats:"); +foreach (var format in response.Formats.Where(f => f.FileFormat.Contains("PowerPoint"))) +{ + Console.WriteLine($"{format.Extension} - {format.FileFormat}"); +} +``` + +### Python Example + +```python +# For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud + +client_id = "YOUR_CLIENT_ID" # Get your client ID and secret from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get your client ID and secret from https://dashboard.groupdocs.cloud + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(client_id, client_secret) +api = groupdocs_merger_cloud.InfoApi(configuration) + +# Retrieve supported file formats +result = api.get_supported_file_formats() + +# Print all supported formats +print("Supported File Formats:") +for format_info in result.formats: + print(f"{format_info.extension} - {format_info.file_format}") + +# You can also filter formats by type +print("\nDocument Formats:") +doc_formats = [f for f in result.formats if "Word" in f.file_format or "PDF" in f.file_format] +for format_info in doc_formats: + print(f"{format_info.extension} - {format_info.file_format}") + +print("\nSpreadsheet Formats:") +spreadsheet_formats = [f for f in result.formats if "Excel" in f.file_format or f.extension == ".csv"] +for format_info in spreadsheet_formats: + print(f"{format_info.extension} - {format_info.file_format}") +``` + +### Java Example + +```java +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +import com.groupdocs.cloud.merger.client.*; +import com.groupdocs.cloud.merger.model.*; +import com.groupdocs.cloud.merger.api.InfoApi; + +import java.util.List; +import java.util.stream.Collectors; + +public class GetSupportedFileFormatsExample { + public static void main(String[] args) { + String clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + String clientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + + // Create instance of the API + Configuration configuration = new Configuration(clientId, clientSecret); + InfoApi api = new InfoApi(configuration); + + try { + // Get supported file formats + FormatsResult result = api.getSupportedFileFormats(); + + // Display all supported formats + System.out.println("Supported File Formats:"); + for (Format format : result.getFormats()) { + System.out.println(format.getExtension() + " - " + format.getFileFormat()); + } + + // Filter and group formats by type + System.out.println("\nDocument Formats:"); + List docFormats = result.getFormats().stream() + .filter(f -> f.getFileFormat().contains("Word") || f.getFileFormat().contains("PDF")) + .collect(Collectors.toList()); + + for (Format format : docFormats) { + System.out.println(format.getExtension() + " - " + format.getFileFormat()); + } + + System.out.println("\nPresentation Formats:"); + List presentationFormats = result.getFormats().stream() + .filter(f -> f.getFileFormat().contains("PowerPoint")) + .collect(Collectors.toList()); + + for (Format format : presentationFormats) { + System.out.println(format.getExtension() + " - " + format.getFileFormat()); + } + + } catch (Exception e) { + System.out.println("Error: " + e.getMessage()); + e.printStackTrace(); + } + } +} +``` + +## Step 5: Implementing Format Validation in Your Application + +Now that you can retrieve supported formats, let's implement a practical file validation function: + +### JavaScript Example (Node.js) + +```javascript +// For complete examples and data files, please go to https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-node-samples +const { InfoApi, Configuration } = require("groupdocs-merger-cloud"); + +const clientId = "YOUR_CLIENT_ID"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +const clientSecret = "YOUR_CLIENT_SECRET"; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +// Create instance of the API +const configuration = new Configuration(clientId, clientSecret); +const api = new InfoApi(configuration); + +// Function to validate file extension +async function isFileFormatSupported(fileExtension) { + try { + // Ensure extension starts with a dot + if (!fileExtension.startsWith('.')) { + fileExtension = '.' + fileExtension; + } + + // Convert to lowercase for comparison + fileExtension = fileExtension.toLowerCase(); + + // Get all supported formats + const result = await api.getSupportedFileFormats(); + + // Check if the extension exists in supported formats + const supported = result.formats.some(format => + format.extension.toLowerCase() === fileExtension + ); + + return supported; + } catch (error) { + console.error("Error validating format:", error); + return false; + } +} + +// Example usage +async function validateFiles() { + console.log("Validating formats..."); + console.log("Is .docx supported?", await isFileFormatSupported(".docx")); + console.log("Is .doc supported?", await isFileFormatSupported("doc")); // Note: no dot prefix + console.log("Is .xyz supported?", await isFileFormatSupported(".xyz")); // Made-up extension +} + +validateFiles(); +``` + +## Try It Yourself: Practice Exercises + +Now that you understand how to retrieve and use supported file formats, try these exercises to reinforce your learning: + +1. Exercise 1: Create a utility function that groups supported formats by category (Word Processing, Spreadsheets, Presentations, etc.) based on file extensions or format descriptions. + +2. Exercise 2: Build a simple file upload component that validates files against supported formats before allowing upload. + +3. Exercise 3: Create a dropdown menu that displays all supported formats, categorized by document type. + +## Troubleshooting Tips + +- Authentication errors: Ensure your Client ID and Client Secret are correct and that your account has appropriate permissions. +- Filtering issues: When grouping formats, remember that some format descriptions may not contain the exact keywords you're filtering on. Consider using multiple conditions or partial matches. +- Extension validation: When validating file extensions, ensure you account for case sensitivity and consistently handle the dot prefix. + +## What You've Learned + +In this tutorial, you've learned how to: +- Retrieve a complete list of file formats supported by GroupDocs.Merger Cloud +- Process and categorize file formats by type +- Implement file format validation in your applications +- Leverage different programming languages for format retrieval and validation + +## Next Steps + +Now that you can retrieve and validate supported file formats, a logical next step is to learn how to manage files in your cloud storage. Continue to our [Tutorial: Working with Files](/getting-started/working-with-files/) to expand your knowledge. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +## Feedback + +Did you find this tutorial helpful? Do you have questions about supported file formats? Let us know in our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/getting_started/working_with_files/_index.md b/content/merger/english/getting_started/working_with_files/_index.md new file mode 100644 index 0000000..7f9e546 --- /dev/null +++ b/content/merger/english/getting_started/working_with_files/_index.md @@ -0,0 +1,585 @@ +--- +title: How to Work with Files in GroupDocs.Merger Cloud API Tutorial +weight: 3 +url: /getting-started/working-with-files/ +description: Learn essential file operations with GroupDocs.Merger Cloud API in this step-by-step tutorial covering uploading, downloading, and managing your documents. +--- + +# Tutorial: How to Work with Files in GroupDocs.Merger Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to perform essential file operations using the GroupDocs.Merger Cloud API. These operations include uploading files to cloud storage, downloading files, copying, moving, and deleting files. Mastering these fundamental file operations is crucial for implementing document processing workflows in your applications. + +## Prerequisites + +Before starting this tutorial, ensure you have: + +1. A GroupDocs.Merger Cloud account (or [sign up for a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret from the [GroupDocs Cloud Dashboard](https://dashboard.groupdocs.cloud/) +3. Basic understanding of REST API concepts +4. Development environment for your preferred language (optional for cURL examples) +5. Sample files to upload and test with + +## Use Case Scenario + +Consider building a document management system where users need to: +- Upload documents to cloud storage +- Download documents for viewing or editing +- Copy documents between folders for organization +- Move documents as part of workflow processes +- Delete documents when no longer needed + +This tutorial will show you how to implement all these operations programmatically, providing the foundation for a robust document management system. + +## Step 1: Understanding File API Operations + +The GroupDocs.Merger Cloud API provides several endpoints for file management: + +- Download File API: Download files from cloud storage +- Upload File API: Upload files to cloud storage +- Delete File API: Remove files from cloud storage +- Copy File API: Copy files between locations in cloud storage +- Move File API: Move files between locations in cloud storage + +These APIs form the foundation of document management in your applications. + +## Step 2: Downloading Files from Cloud Storage + +Let's start by learning how to download files from your cloud storage. This is often the first step when you need to process or display a document to users. + +### API Endpoint + +``` +GET ~/storage/file/{path} +``` + +Where `{path}` is the path of the file including the filename and extension. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Path of the file including filename and extension. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | +| versionId | File version ID (for storages that support versioning). | + +### cURL Example for Downloading a File + +```bash +curl -X GET "https://api.groupdocs.cloud/v1.0/merger/storage/file/one-page.docx?storageName=MyStorage" \ +-H "accept: multipart/form-data" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Step-by-Step Implementation + +1. Authentication: Obtain your access token using Client ID and Client Secret +2. Construct the URL: Form the correct path to your file +3. Send the Request: Make a GET request to the file endpoint +4. Process the Response: Save the downloaded file locally + +Let's implement file download using different programming languages. + +### C# Example + +```csharp +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +// Create API instance +var fileApi = new FileApi(configuration); + +// File name and path +var filePath = "one-page.docx"; +var storageName = "MyStorage"; + +// Download file +var response = fileApi.DownloadFile(new DownloadFileRequest(filePath, storageName)); + +// Save to local file +using (var fileStream = File.Create("downloaded-document.docx")) +{ + response.CopyTo(fileStream); +} + +Console.WriteLine("File downloaded successfully to 'downloaded-document.docx'"); +``` + +### Python Example + +```python +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud +from groupdocs_merger_cloud import FileApi, DownloadFileRequest + +client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(client_id, client_secret) +file_api = FileApi(configuration) + +# File name in storage +file_path = "one-page.docx" +storage_name = "MyStorage" # Optional: if not specified, default storage is used + +# Download file +request = DownloadFileRequest(file_path, storage_name) +response = file_api.download_file(request) + +# Save to local file +with open("downloaded-document.docx", 'wb') as f: + for chunk in response: + f.write(chunk) + +print("File downloaded successfully to 'downloaded-document.docx'") +``` + +## Step 3: Uploading Files to Cloud Storage + +Now, let's learn how to upload files to your cloud storage. This is essential when you need to add new documents to your system. + +### API Endpoint + +``` +POST ~/storage/file/{path} +``` + +Where `{path}` is the destination path including filename and extension. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Path in the storage where the file should be uploaded. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | +| File | File content to be uploaded. | + +### cURL Example for Uploading a File + +```bash +curl -X POST "https://api.groupdocs.cloud/v1.0/merger/storage/file/uploaded-document.docx?storageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" \ +-H "Content-Type: multipart/form-data" \ +-F "fileContent=@local-document.docx" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Step-by-Step Implementation + +1. Authentication: Obtain your access token +2. Prepare the File: Read the local file you want to upload +3. Construct the Request: Form the correct path and parameters +4. Send the Request: Upload the file content +5. Verify the Response: Check that the upload was successful + +Let's implement file upload using different programming languages. + +### C# Example + +```csharp +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +// Create API instance +var fileApi = new FileApi(configuration); + +// Source file on local disk +var localFilePath = "C:\\Temp\\sample-document.docx"; +var fileStream = File.OpenRead(localFilePath); + +// Destination path in cloud storage +var uploadPath = "uploaded-document.docx"; +var storageName = "MyStorage"; // Optional + +// Upload file +var request = new UploadFileRequest(uploadPath, fileStream, storageName); +var response = fileApi.UploadFile(request); + +if (response.Uploaded.Count > 0) +{ + Console.WriteLine($"File uploaded successfully: {response.Uploaded[0]}"); +} +else if (response.Errors != null && response.Errors.Count > 0) +{ + Console.WriteLine($"Error uploading file: {response.Errors[0].Message}"); +} +``` + +### Python Example + +```python +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud +from groupdocs_merger_cloud import FileApi, UploadFileRequest + +client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(client_id, client_secret) +file_api = FileApi(configuration) + +# Source file on local disk +local_file_path = "sample-document.docx" + +# Destination path in cloud storage +upload_path = "uploaded-document.docx" +storage_name = "MyStorage" # Optional + +# Upload file +with open(local_file_path, 'rb') as file_stream: + request = UploadFileRequest(upload_path, file_stream, storage_name) + response = file_api.upload_file(request) + + if len(response.uploaded) > 0: + print(f"File uploaded successfully: {response.uploaded[0]}") + elif response.errors and len(response.errors) > 0: + print(f"Error uploading file: {response.errors[0].message}") +``` + +## Step 4: Deleting Files from Cloud Storage + +Now let's learn how to delete files from your cloud storage. This operation is important for managing storage space and removing documents that are no longer needed. + +### API Endpoint + +``` +DELETE ~/storage/file/{path} +``` + +Where `{path}` is the path of the file to delete. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Path of the file to delete. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | +| versionId | File version ID (for storages supporting versioning). | + +### cURL Example for Deleting a File + +```bash +curl -X DELETE "https://api.groupdocs.cloud/v1.0/merger/storage/file/document-to-delete.docx?storageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Java Example + +```java +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +import com.groupdocs.cloud.merger.client.*; +import com.groupdocs.cloud.merger.model.requests.*; +import com.groupdocs.cloud.merger.api.FileApi; + +public class DeleteFileExample { + public static void main(String[] args) { + String clientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud + String clientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud + + // Create instance of the API + Configuration configuration = new Configuration(clientId, clientSecret); + FileApi fileApi = new FileApi(configuration); + + try { + // File to delete + String filePath = "document-to-delete.docx"; + String storageName = "MyStorage"; // Optional + + // Delete file + DeleteFileRequest request = new DeleteFileRequest(filePath, storageName, null); + fileApi.deleteFile(request); + + System.out.println("File deleted successfully: " + filePath); + + } catch (Exception e) { + System.out.println("Error deleting file: " + e.getMessage()); + e.printStackTrace(); + } + } +} +``` + +## Step 5: Copying Files in Cloud Storage + +Copying files within your cloud storage allows you to duplicate documents without downloading and re-uploading them. This is useful for creating backup copies or organizing files. + +### API Endpoint + +``` +PUT ~/storage/file/copy/{srcPath} +``` + +Where `{srcPath}` is the source file path. + +### Request Parameters + +| Parameter | Description | +|---|---| +| srcPath | Source file path e.g. /Folder1/file.ext. Required. | +| destPath | Destination file path. Required. | +| srcStorageName | Source storage name. If not specified, the default storage is used. | +| destStorageName | Destination storage name. If not specified, the default storage is used. | +| versionId | Source file version ID (for storages supporting versioning). | + +### cURL Example for Copying a File + +```bash +curl -X PUT "https://api.groupdocs.cloud/v1.0/merger/storage/file/copy/original-document.docx?destPath=copied-document.docx&srcStorageName=MyStorage&destStorageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Node.js Example + +```javascript +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-node-samples +const { FileApi, Configuration, CopyFileRequest } = require("groupdocs-merger-cloud"); + +const clientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud +const clientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud + +// Create instance of the API +const configuration = new Configuration(clientId, clientSecret); +const fileApi = new FileApi(configuration); + +// Source and destination paths +const srcPath = "original-document.docx"; +const destPath = "copied-document.docx"; +const srcStorageName = "MyStorage"; // Optional +const destStorageName = "MyStorage"; // Optional + +// Copy file +const request = new CopyFileRequest(srcPath, destPath, srcStorageName, destStorageName); +fileApi.copyFile(request) + .then(() => { + console.log(`File copied successfully from '${srcPath}' to '${destPath}'`); + }) + .catch(error => { + console.error("Error copying file:", error.message); + }); +``` + +## Step 6: Moving Files in Cloud Storage + +Moving files allows you to relocate documents between folders in your cloud storage without downloading and re-uploading them. This is useful for organizing documents or implementing workflow processes. + +### API Endpoint + +``` +PUT ~/storage/file/move/{srcPath} +``` + +Where `{srcPath}` is the source file path. + +### Request Parameters + +| Parameter | Description | +|---|---| +| srcPath | Source file path e.g. /Folder1/file.ext. Required. | +| destPath | Destination file path. Required. | +| srcStorageName | Source storage name. If not specified, the default storage is used. | +| destStorageName | Destination storage name. If not specified, the default storage is used. | +| versionId | Source file version ID (for storages supporting versioning). | + +### cURL Example for Moving a File + +```bash +curl -X PUT "https://api.groupdocs.cloud/v1.0/merger/storage/file/move/source-location/document.docx?destPath=destination-location/document.docx&srcStorageName=MyStorage&destStorageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### PHP Example + +```php +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-php-samples +setAppSid($client_id); +$configuration->setAppKey($client_secret); +$fileApi = new GroupDocs\Merger\FileApi($configuration); + +// Source and destination paths +$srcPath = "source-location/document.docx"; +$destPath = "destination-location/document.docx"; +$srcStorageName = "MyStorage"; // Optional +$destStorageName = "MyStorage"; // Optional + +try { + // Move file + $request = new Requests\MoveFileRequest($srcPath, $destPath, $srcStorageName, $destStorageName); + $fileApi->moveFile($request); + + echo "File moved successfully from '{$srcPath}' to '{$destPath}'"; +} catch (Exception $e) { + echo "Error moving file: " . $e->getMessage(); +} +``` + +## Building a Complete File Management System + +Now that you've learned each individual file operation, let's combine them to create a simple file management system. The following example demonstrates how to implement a basic file manager: + +### Ruby Example: Simple File Manager + +```ruby +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-ruby-samples +require 'groupdocs_merger_cloud' + +class SimpleFileManager + def initialize(client_id, client_secret) + # Create configuration and API instances + @configuration = GroupDocsMergerCloud::Configuration.new(client_id, client_secret) + @file_api = GroupDocsMergerCloud::FileApi.from_config(@configuration) + @storage_name = "MyStorage" # Default storage + end + + def upload_file(local_path, cloud_path) + puts "Uploading file '#{local_path}' to '#{cloud_path}'..." + + File.open(local_path, 'rb') do |file| + request = GroupDocsMergerCloud::UploadFileRequest.new(cloud_path, file, @storage_name) + result = @file_api.upload_file(request) + + if result.uploaded.length > 0 + puts "✓ File uploaded successfully: #{result.uploaded[0]}" + return true + else + puts "✗ Upload failed" + return false + end + end + end + + def download_file(cloud_path, local_path) + puts "Downloading file '#{cloud_path}' to '#{local_path}'..." + + request = GroupDocsMergerCloud::DownloadFileRequest.new(cloud_path, @storage_name) + response = @file_api.download_file(request) + + File.open(local_path, 'wb') do |file| + file.write(response) + end + + puts "✓ File downloaded successfully" + return true + end + + def copy_file(src_path, dest_path) + puts "Copying file from '#{src_path}' to '#{dest_path}'..." + + request = GroupDocsMergerCloud::CopyFileRequest.new(src_path, dest_path, @storage_name, @storage_name) + @file_api.copy_file(request) + + puts "✓ File copied successfully" + return true + end + + def move_file(src_path, dest_path) + puts "Moving file from '#{src_path}' to '#{dest_path}'..." + + request = GroupDocsMergerCloud::MoveFileRequest.new(src_path, dest_path, @storage_name, @storage_name) + @file_api.move_file(request) + + puts "✓ File moved successfully" + return true + end + + def delete_file(cloud_path) + puts "Deleting file '#{cloud_path}'..." + + request = GroupDocsMergerCloud::DeleteFileRequest.new(cloud_path, @storage_name) + @file_api.delete_file(request) + + puts "✓ File deleted successfully" + return true + end +end + +# Usage example +client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + +file_manager = SimpleFileManager.new(client_id, client_secret) + +# Example workflow +file_manager.upload_file("./local-document.docx", "document.docx") +file_manager.copy_file("document.docx", "document-backup.docx") +file_manager.move_file("document.docx", "archive/document.docx") +file_manager.download_file("archive/document.docx", "./downloaded-document.docx") +file_manager.delete_file("document-backup.docx") +``` + +## Try It Yourself: Practice Exercises + +Now that you understand how to perform file operations, try these exercises to reinforce your learning: + +1. Exercise 1: Create a script that recursively uploads all files from a local folder to your cloud storage, preserving the folder structure. + +2. Exercise 2: Implement a "sync" function that compares local and cloud folders and ensures they contain the same files, uploading or downloading as necessary. + +3. Exercise 3: Build a simple file backup system that creates timestamped copies of important documents on a regular schedule. + +## Troubleshooting Tips + +- Authentication errors: Ensure your Client ID and Client Secret are correct and your access token is valid. +- File not found errors: Verify file paths are correct and include proper URL encoding for special characters. +- Permission errors: Check that you have the appropriate permissions for the storage and files you're trying to access. +- Storage quota errors: Ensure you have sufficient storage space when uploading files. + +## What You've Learned + +In this tutorial, you've learned how to: +- Download files from your cloud storage +- Upload files to your cloud storage +- Delete files that are no longer needed +- Copy files between locations without re-uploading +- Move files to organize your document storage +- Combine these operations into a simple file management system + +These fundamental file operations form the basis for more complex document processing workflows and are essential for building robust document management applications. + +## Next Steps + +Now that you know how to manage individual files, a logical next step is to learn how to work with folders to better organize your documents. Continue to our [Tutorial: Working with Folders](/getting-started/working-with-folder/) to expand your knowledge. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +## Feedback + +Did you find this tutorial helpful? Do you have questions about file operations? Let us know in our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/getting_started/working_with_folder/_index.md b/content/merger/english/getting_started/working_with_folder/_index.md new file mode 100644 index 0000000..91a183a --- /dev/null +++ b/content/merger/english/getting_started/working_with_folder/_index.md @@ -0,0 +1,584 @@ +--- +title: How to Work with Folders in GroupDocs.Merger Cloud API Tutorial +weight: 4 +url: /getting-started/working-with-folder/ +description: Master folder management techniques with GroupDocs.Merger Cloud API - learn to create, list, delete, copy, and move folders in this comprehensive tutorial. +--- + +# Tutorial: How to Work with Folders in GroupDocs.Merger Cloud API + +## Learning Objectives + +In this tutorial, you'll learn how to manage folders in your cloud storage using the GroupDocs.Merger Cloud API. You'll master techniques for creating folders, listing their contents, copying, moving, and deleting folders. These skills are essential for organizing documents effectively in your cloud-based applications. + +## Prerequisites + +Before starting this tutorial, ensure you have: + +1. A GroupDocs.Merger Cloud account (or [sign up for a free trial](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret from the [GroupDocs Cloud Dashboard](https://dashboard.groupdocs.cloud/) +3. Basic understanding of REST API concepts +4. Development environment for your preferred language (optional for cURL examples) +5. Completed the [Working with Files tutorial](/getting-started/working-with-files/) + + +## Use Case Scenario + +Consider developing a document management solution where efficient folder organization is critical. You need to: +- Create logical folder structures for different document types +- List folder contents to display in your application's UI +- Copy entire folders for backup purposes +- Move folders to reorganize your document hierarchy +- Delete folders that are no longer needed + +This tutorial will show you how to implement these essential folder operations programmatically. + +## Step 1: Understanding Folder API Operations + +The GroupDocs.Merger Cloud API provides several endpoints for folder management: + +- List Files API: Gets a list of all files within a specific folder +- Create Folder API: Creates a new folder in the storage +- Delete Folder API: Removes a folder from the storage +- Copy Folder API: Copies a folder to another location +- Move Folder API: Moves a folder to another location + +Let's explore each of these operations in detail. + +## Step 2: Listing Files in a Folder + +First, let's learn how to retrieve a list of all files within a specific folder. This is useful for displaying folder contents to users in your application. + +### API Endpoint + +``` +GET ~/storage/folder/{path} +``` + +Where `{path}` is the folder path. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Folder path e.g. /Folder1. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | + +### cURL Example for Listing Files + +```bash +curl -X GET "https://api.groupdocs.cloud/v1.0/merger/storage/folder/conversiondocs?storageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Expected Response + +```json +{ + "value": [ + { + "name": "four-pages.docx", + "isFolder": false, + "modifiedDate": "2019-03-20T12:35:38+00:00", + "size": 8651, + "path": "/conversiondocs/four-pages.docx" + }, + { + "name": "one-page.docx", + "isFolder": false, + "modifiedDate": "2019-03-20T12:17:34+00:00", + "size": 351348, + "path": "/conversiondocs/one-page.docx" + }, + { + "name": "password-protected.docx", + "isFolder": false, + "modifiedDate": "2019-03-20T12:35:40+00:00", + "size": 10240, + "path": "/conversiondocs/password-protected.docx" + } + // ... other files + ] +} +``` + +### C# Example + +```csharp +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-dotnet-samples +string MyClientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud +string MyClientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +// Create API instance +var folderApi = new FolderApi(configuration); + +// Folder path +var folderPath = "conversiondocs"; +var storageName = "MyStorage"; // Optional + +// Get files list +var response = folderApi.GetFilesList(new GetFilesListRequest(folderPath, storageName)); + +Console.WriteLine($"Files in folder '{folderPath}':"); +foreach (var fileInfo in response.Value) +{ + string entityType = fileInfo.IsFolder ? "Folder" : "File"; + Console.WriteLine($"{entityType}: {fileInfo.Name}"); + Console.WriteLine($" Path: {fileInfo.Path}"); + Console.WriteLine($" Size: {fileInfo.Size} bytes"); + Console.WriteLine($" Modified: {fileInfo.ModifiedDate}"); + Console.WriteLine(); +} +``` + +### Python Example + +```python +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud +from groupdocs_merger_cloud import FolderApi, GetFilesListRequest + +client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(client_id, client_secret) +folder_api = FolderApi(configuration) + +# Folder path +folder_path = "conversiondocs" +storage_name = "MyStorage" # Optional + +# Get files list +request = GetFilesListRequest(folder_path, storage_name) +response = folder_api.get_files_list(request) + +print(f"Files in folder '{folder_path}':") +for file_info in response.value: + entity_type = "Folder" if file_info.is_folder else "File" + print(f"{entity_type}: {file_info.name}") + print(f" Path: {file_info.path}") + print(f" Size: {file_info.size} bytes") + print(f" Modified: {file_info.modified_date}") + print() +``` + +## Step 3: Creating New Folders + +Now, let's learn how to create new folders in your cloud storage. This is essential for organizing documents into logical categories. + +### API Endpoint + +``` +POST ~/storage/folder/{path} +``` + +Where `{path}` is the folder path to create. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Target folder's path e.g. Folder1/Folder2/. The folders will be created recursively. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | + +### cURL Example for Creating a Folder + +```bash +curl -X POST "https://api.groupdocs.cloud/v1.0/merger/storage/folder/documents/contracts?storageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Java Example + +```java +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-java-samples +import com.groupdocs.cloud.merger.client.*; +import com.groupdocs.cloud.merger.model.requests.*; +import com.groupdocs.cloud.merger.api.FolderApi; + +public class CreateFolderExample { + public static void main(String[] args) { + String clientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud + String clientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud + + // Create instance of the API + Configuration configuration = new Configuration(clientId, clientSecret); + FolderApi folderApi = new FolderApi(configuration); + + try { + // Folder path to create + String folderPath = "documents/contracts"; + String storageName = "MyStorage"; // Optional + + // Create folder + CreateFolderRequest request = new CreateFolderRequest(folderPath, storageName); + folderApi.createFolder(request); + + System.out.println("Folder created successfully: " + folderPath); + + } catch (Exception e) { + System.out.println("Error creating folder: " + e.getMessage()); + e.printStackTrace(); + } + } +} +``` + +## Step 4: Deleting Folders + +Sometimes, you need to remove folders that are no longer necessary. The Delete Folder API allows you to remove a folder and optionally all its contents recursively. + +### API Endpoint + +``` +DELETE ~/storage/folder/{path} +``` + +Where `{path}` is the folder path to delete. + +### Request Parameters + +| Parameter | Description | +|---|---| +| path | Folder path e.g. /Folder1. Required. | +| storageName | Name of the storage. If not specified, the default storage is used. | +| recursive | Remove folders, subfolders, and files. Default is false. | + +### cURL Example for Deleting a Folder + +```bash +curl -X DELETE "https://api.groupdocs.cloud/v1.0/merger/storage/folder/documents/old-contracts?storageName=MyStorage&recursive=true" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Node.js Example + +```javascript +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-node-samples +const { FolderApi, Configuration, DeleteFolderRequest } = require("groupdocs-merger-cloud"); + +const clientId = "YOUR_CLIENT_ID"; // Get from https://dashboard.groupdocs.cloud +const clientSecret = "YOUR_CLIENT_SECRET"; // Get from https://dashboard.groupdocs.cloud + +// Create instance of the API +const configuration = new Configuration(clientId, clientSecret); +const folderApi = new FolderApi(configuration); + +// Folder path to delete +const folderPath = "documents/old-contracts"; +const storageName = "MyStorage"; // Optional +const recursive = true; // Set to true to delete subfolders and files + +// Delete folder +const request = new DeleteFolderRequest(folderPath, storageName, recursive); +folderApi.deleteFolder(request) + .then(() => { + console.log(`Folder deleted successfully: ${folderPath}`); + }) + .catch(error => { + console.error("Error deleting folder:", error.message); + }); +``` + +## Step 5: Copying Folders + +The Copy Folder API allows you to duplicate an entire folder structure from one location to another in your cloud storage. This is useful for creating backups or organizing documents without modifying the originals. + +### API Endpoint + +``` +PUT ~/storage/folder/copy/{srcPath} +``` + +Where `{srcPath}` is the source folder path. + +### Request Parameters + +| Parameter | Description | +|---|---| +| srcPath | Source folder path e.g. /Folder1. Required. | +| destPath | Destination folder path. Required. | +| srcStorageName | Name of the source storage. If not specified, the default storage is used. | +| destStorageName | Name of the destination storage. If not specified, the default storage is used. | + +### cURL Example for Copying a Folder + +```bash +curl -X PUT "https://api.groupdocs.cloud/v1.0/merger/storage/folder/copy/documents/contracts?destPath=backup/contracts&srcStorageName=MyStorage&destStorageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### PHP Example + +```php +// For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-php-samples +setAppSid($client_id); +$configuration->setAppKey($client_secret); +$folderApi = new GroupDocs\Merger\FolderApi($configuration); + +// Source and destination paths +$srcPath = "documents/contracts"; +$destPath = "backup/contracts"; +$srcStorageName = "MyStorage"; // Optional +$destStorageName = "MyStorage"; // Optional + +try { + // Copy folder + $request = new Requests\CopyFolderRequest($srcPath, $destPath, $srcStorageName, $destStorageName); + $folderApi->copyFolder($request); + + echo "Folder copied successfully from '{$srcPath}' to '{$destPath}'"; +} catch (Exception $e) { + echo "Error copying folder: " . $e->getMessage(); +} +``` + +## Step 6: Moving Folders + +The Move Folder API allows you to relocate an entire folder structure from one location to another in your cloud storage. This is useful for reorganizing your document hierarchy. + +### API Endpoint + +``` +PUT ~/storage/folder/move/{srcPath} +``` + +Where `{srcPath}` is the source folder path. + +### Request Parameters + +| Parameter | Description | +|---|---| +| srcPath | Source folder path e.g. /Folder1. Required. | +| destPath | Destination folder path. Required. | +| srcStorageName | Name of the source storage. If not specified, the default storage is used. | +| destStorageName | Name of the destination storage. If not specified, the default storage is used. | + +### cURL Example for Moving a Folder + +```bash +curl -X PUT "https://api.groupdocs.cloud/v1.0/merger/storage/folder/move/documents/old-contracts?destPath=archive/contracts/2023&srcStorageName=MyStorage&destStorageName=MyStorage" \ +-H "accept: application/json" \ +-H "authorization: Bearer YOUR_ACCESS_TOKEN" +``` + +Replace `YOUR_ACCESS_TOKEN` with your actual access token. + +### Ruby Example + +```ruby +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-ruby-samples +require 'groupdocs_merger_cloud' + +class FolderManager + def initialize(client_id, client_secret) + # Create configuration and API instances + @configuration = GroupDocsMergerCloud::Configuration.new(client_id, client_secret) + @folder_api = GroupDocsMergerCloud::FolderApi.from_config(@configuration) + @storage_name = "MyStorage" # Default storage + end + + def move_folder(src_path, dest_path) + puts "Moving folder from '#{src_path}' to '#{dest_path}'..." + + request = GroupDocsMergerCloud::MoveFolderRequest.new(src_path, dest_path, @storage_name, @storage_name) + @folder_api.move_folder(request) + + puts "✓ Folder moved successfully" + return true + end +end + +# Usage example +client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud +client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + +folder_manager = FolderManager.new(client_id, client_secret) +folder_manager.move_folder("documents/old-contracts", "archive/contracts/2023") +``` + +## Building a Complete Folder Management System + +Now that you've learned each individual folder operation, let's combine them to create a simple folder management system. The following example demonstrates how to implement a basic folder manager: + +### Python Example: Folder Management System + +```python +# For complete examples, please visit: https://github.com/groupdocs-merger-cloud/groupdocs-merger-cloud-python-samples +import groupdocs_merger_cloud +from groupdocs_merger_cloud import Configuration, FolderApi +from groupdocs_merger_cloud import GetFilesListRequest, CreateFolderRequest +from groupdocs_merger_cloud import DeleteFolderRequest, CopyFolderRequest, MoveFolderRequest + +class FolderManager: + def __init__(self, client_id, client_secret): + # Create configuration and API instances + self.configuration = Configuration(client_id, client_secret) + self.folder_api = FolderApi(self.configuration) + self.storage_name = "MyStorage" # Default storage + + def list_folder_contents(self, folder_path): + """List all files and folders within a specified folder""" + print(f"Listing contents of folder '{folder_path}'...") + + request = GetFilesListRequest(folder_path, self.storage_name) + response = self.folder_api.get_files_list(request) + + folders = [] + files = [] + + # Separate folders and files + for item in response.value: + if item.is_folder: + folders.append(item) + else: + files.append(item) + + # Print folders first + print(f"\nFolders ({len(folders)}):") + for folder in folders: + print(f" {folder.name}/") + + # Then print files + print(f"\nFiles ({len(files)}):") + for file in files: + print(f" {file.name} ({file.size} bytes)") + + return response.value + + def create_folder(self, folder_path): + """Create a new folder at the specified path""" + print(f"Creating folder '{folder_path}'...") + + request = CreateFolderRequest(folder_path, self.storage_name) + self.folder_api.create_folder(request) + + print(f"✓ Folder created successfully") + return True + + def delete_folder(self, folder_path, recursive=True): + """Delete a folder at the specified path""" + print(f"Deleting folder '{folder_path}'...") + + request = DeleteFolderRequest(folder_path, self.storage_name, recursive) + self.folder_api.delete_folder(request) + + print(f"✓ Folder deleted successfully") + return True + + def copy_folder(self, src_path, dest_path): + """Copy a folder from source to destination path""" + print(f"Copying folder from '{src_path}' to '{dest_path}'...") + + request = CopyFolderRequest(src_path, dest_path, self.storage_name, self.storage_name) + self.folder_api.copy_folder(request) + + print(f"✓ Folder copied successfully") + return True + + def move_folder(self, src_path, dest_path): + """Move a folder from source to destination path""" + print(f"Moving folder from '{src_path}' to '{dest_path}'...") + + request = MoveFolderRequest(src_path, dest_path, self.storage_name, self.storage_name) + self.folder_api.move_folder(request) + + print(f"✓ Folder moved successfully") + return True + +# Example usage +if __name__ == "__main__": + client_id = "YOUR_CLIENT_ID" # Get from https://dashboard.groupdocs.cloud + client_secret = "YOUR_CLIENT_SECRET" # Get from https://dashboard.groupdocs.cloud + + folder_manager = FolderManager(client_id, client_secret) + + # Example workflow + print("FOLDER MANAGEMENT DEMO") + print("=====================") + + # Create a project structure + folder_manager.create_folder("projects/merger-app") + folder_manager.create_folder("projects/merger-app/documents") + folder_manager.create_folder("projects/merger-app/templates") + + # List the project structure + folder_manager.list_folder_contents("projects/merger-app") + + # Create a backup + folder_manager.copy_folder("projects/merger-app", "backups/merger-app-backup") + + # Reorganize folders + folder_manager.move_folder("projects/merger-app/templates", "projects/merger-app/resources/templates") + + # Clean up (uncomment when ready to test) + # folder_manager.delete_folder("projects/merger-app", recursive=True) + # folder_manager.delete_folder("backups/merger-app-backup", recursive=True) +``` + +## Try It Yourself: Practice Exercises + +Now that you understand how to perform folder operations, try these exercises to reinforce your learning: + +1. Exercise 1: Create a script that builds a standard folder hierarchy for a new project (e.g., `/project/docs`, `/project/source`, `/project/resources`). + +2. Exercise 2: Implement a function that lists all files recursively through a folder structure, not just the top level. + +3. Exercise 3: Build a folder cleanup utility that automatically archives folders that haven't been modified in over 30 days by moving them to an archive location. + +## Troubleshooting Tips + +- Path Format Issues: Ensure folder paths are properly formatted. Include leading slashes when required by the API. +- Recursive Operation Warnings: Be careful with recursive deletions. Always double-check paths before executing such operations. +- Destination Already Exists: When copying or moving folders, check if the destination already exists to avoid unexpected overwrites. +- Permission Errors: Verify you have appropriate permissions for the storage and folders you're working with. + +## What You've Learned + +In this tutorial, you've learned how to: +- List files and folders to display folder contents +- Create new folders to organize your documents +- Delete folders that are no longer needed +- Copy folders to create backups or duplicates +- Move folders to reorganize your document hierarchy +- Combine these operations into a comprehensive folder management system + +These folder management techniques are essential for maintaining an organized document structure in your cloud applications. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +## Feedback + +Did you find this tutorial helpful? Do you have questions about folder management? Let us know in our [support forum](https://forum.groupdocs.cloud/c/merger/18/)!}) (recommended) diff --git a/content/merger/english/page-processes/_index.md b/content/merger/english/page-processes/_index.md new file mode 100644 index 0000000..ac6cc9d --- /dev/null +++ b/content/merger/english/page-processes/_index.md @@ -0,0 +1,58 @@ +--- +title: GroupDocs.Merger Cloud API Document Page Processes Tutorials +weight: 4 +url: /page-processes/ +description: Learn document page manipulation with these step-by-step tutorials for GroupDocs.Merger Cloud API +--- + +# Document Page Processes Tutorials for GroupDocs.Merger Cloud + +Welcome to our comprehensive tutorial series on document page manipulation using GroupDocs.Merger Cloud API. These hands-on tutorials are designed to help developers learn how to efficiently perform various page operations on documents stored in the cloud. + +## Learning Path + +This tutorial series follows a progressive learning path, starting with basic page operations and advancing to more complex manipulation techniques: + +1. Basic Page Operations - Learn fundamental techniques for extracting and removing pages +2. Page Arrangement - Master the skills of swapping and moving pages to reorganize documents +3. Page Transformation - Discover advanced operations like rotating and changing page orientation + +## Available Tutorials + +### Basic Page Operations + +- [Tutorial: How to Extract Pages from Documents](/page-processes/extract-pages/) - Learn to extract specific pages or page ranges from your documents to create new files containing only the content you need. +- [Tutorial: How to Remove Pages from Documents](/page-processes/remove-pages/) - Master the technique of permanently removing unwanted pages from documents while preserving the rest of the content. + +### Page Arrangement + +- [Tutorial: How to Swap Pages in Documents](/page-processes/swap-pages/) - Learn to exchange the positions of two pages within a document, perfect for correcting page order errors. +- [Tutorial: How to Move Pages in Documents](/page-processes/move-pages/) - Discover how to change a page's position by moving it to a new location within your document. + +### Page Transformation + +- [Tutorial: How to Rotate Pages in Documents](/page-processes/rotate-pages/) - Master the technique of changing page rotation angles to 90, 180, or 270 degrees for specified pages. +- [Tutorial: How to Change Page Orientation](/page-processes/change-page-orientation/) - Learn to switch between portrait and landscape orientations for specific pages in your documents. + +## Prerequisites for All Tutorials + +Before starting any tutorial in this series, ensure you have: + +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. Basic knowledge of RESTful APIs and your preferred programming language +4. The appropriate SDK installed for your language (or ability to use cURL for direct REST API calls) + +Each tutorial provides step-by-step instructions and complete code examples in multiple programming languages to ensure you can implement these features in your own applications. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [Live Demo](https://products.groupdocs.app/merger/family) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Blog](https://blog.groupdocs.cloud/categories/groupdocs.merger-cloud-product-family/) +- [Free Support](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +We encourage you to follow these tutorials in sequence to build a solid understanding of document page manipulation techniques. If you have any questions or feedback about these tutorials, please visit our [support forum](https://forum.groupdocs.cloud/c/merger/18/). diff --git a/content/merger/english/page-processes/change-page-orientation/_index.md b/content/merger/english/page-processes/change-page-orientation/_index.md new file mode 100644 index 0000000..ab60b9c --- /dev/null +++ b/content/merger/english/page-processes/change-page-orientation/_index.md @@ -0,0 +1,264 @@ +--- +title: How to Change Page Orientation in Documents Tutorial +weight: 6 +url: /page-processes/change-page-orientation/ +description: Learn how to switch between portrait and landscape orientations for specific pages in your documents using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Change Page Orientation in Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Change page orientation between portrait and landscape for specific pages +- Apply orientation changes using either exact page numbers or page ranges +- Filter page ranges to change orientation for only even or odd pages +- Work with both unprotected and password-protected documents +- Implement page orientation changes in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Imagine you're preparing a report that contains both text and wide data tables. Most pages should be in portrait orientation for the text sections, but specific pages containing tables (like pages 2 and 4) would be better presented in landscape orientation to accommodate the wide data. This tutorial will teach you how to create such a mixed-orientation document efficiently. + +## Understanding Page Orientation Options + +Before implementation, let's understand the available orientation options: +- Portrait: The page is taller than it is wide (standard orientation) +- Landscape: The page is wider than it is tall (horizontal orientation) + +## Method 1: Change Orientation for Specific Pages + +This approach allows you to specify exactly which pages should have their orientation changed. + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Page Orientation Request + +Create a JSON request that specifies: +- The source document path +- The exact page numbers to change orientation +- The orientation mode (Portrait or Landscape) +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/orientation" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/four-pages.docx'}, + 'Pages': [ 2, 4 ], + 'Mode': 'Landscape', + 'OutputPath': 'output/change-page-orientation.docx' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document, which will have pages 2 and 4 changed to landscape orientation. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see that pages 2 and 4 are now in landscape orientation, while pages 1 and 3 maintain their original portrait orientation. + +## Method 2: Change Orientation by Page Range + +This approach allows you to change orientation for pages based on a range and filter them by even or odd page numbers. + +### Step 1: Define Your Range Orientation Request + +Create a JSON request that specifies: +- The source document path +- The start and end page numbers of your range +- The range mode (All, EvenPages, or OddPages) +- The orientation mode (Portrait or Landscape) +- The destination path for the new document + +### Step 2: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/orientation" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/ten-pages.docx'}, + 'StartPageNumber': 1, + 'EndPageNumber': 10, + 'RangeMode': 'EvenPages', + 'Mode': 'Landscape', + 'OutputPath': 'output/change-even-pages-orientation.docx' + }" +``` + +#### Try it yourself! + +Run this command with your own JWT token. The resulting document will have all even-numbered pages (2, 4, 6, 8, 10) changed to landscape orientation, while all odd-numbered pages maintain their original portrait orientation. + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/orientation" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': '/WordProcessing/protected-document.docx', + 'Password': 'your_password' + }, + 'Pages': [ 2, 4 ], + 'Mode': 'Landscape', + 'OutputPath': 'output/change-orientation-protected.docx' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Change Page Orientation using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new OrientationOptions +{ + FileInfo = new FileInfo + { + FilePath = "WordProcessing/four-pages.docx" + }, + Pages = new List { 2, 4 }, + Mode = OrientationMode.Landscape, + OutputPath = "output/change-page-orientation.docx" +}; + +var response = apiInstance.Orientation(new OrientationRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Change Page Orientation using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("WordProcessing/four-pages.docx"); + +OrientationOptions options = new OrientationOptions(); +options.setFileInfo(fileInfo); +options.setPages(Arrays.asList(2, 4)); +options.setMode(OrientationMode.LANDSCAPE); +options.setOutputPath("output/change-page-orientation.docx"); + +OrientationRequest request = new OrientationRequest(options); +DocumentResult response = apiInstance.orientation(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Change Page Orientation using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "WordProcessing/four-pages.docx" + +options = groupdocs_merger_cloud.OrientationOptions() +options.file_info = file_info +options.pages = [2, 4] +options.mode = "Landscape" +options.output_path = "output/change-page-orientation.docx" + +request = groupdocs_merger_cloud.OrientationRequest(options) +response = api_instance.orientation(request) +print("Output file path: " + response.path) +``` + +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- Invalid Page Numbers: Ensure that you've specified valid page numbers that exist in your source document. +- Invalid Orientation Mode: Make sure you're using one of the supported orientation modes: Portrait or Landscape. +- Password Issues: If working with protected documents, check that the provided password is correct. +- File Format Limitations: Some document formats may have limitations regarding page orientation changes. Word documents (DOCX, DOC) and PDF files typically work best for orientation operations. + +## What You've Learned + +In this tutorial, you've learned how to: +- Change page orientation between portrait and landscape for specific pages +- Apply orientation changes using both exact page numbers and page ranges +- Filter page ranges to change orientation for only even or odd pages +- Handle password-protected documents +- Implement page orientation changes using various programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Create a document where all odd pages are in portrait and all even pages are in landscape +2. Change the orientation of only the first and last pages of a document +3. Combine page orientation changes with other operations like rotation or page extraction + +## Next Steps + +Congratulations! You've completed the Document Page Processes Tutorial series. To continue expanding your knowledge of the GroupDocs.Merger Cloud API, explore other tutorial categories or try combining multiple operations to create more complex document processing workflows. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/page-processes/extract-pages/_index.md b/content/merger/english/page-processes/extract-pages/_index.md new file mode 100644 index 0000000..27ea129 --- /dev/null +++ b/content/merger/english/page-processes/extract-pages/_index.md @@ -0,0 +1,246 @@ +--- +title: How to Extract Pages from Documents Tutorial +weight: 1 +url: /page-processes/extract-pages/ +description: Learn how to extract specific pages from documents to create new files using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Extract Pages from Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Extract specific pages from a document by providing exact page numbers +- Extract pages using a page range with options for even/odd pages +- Work with both unprotected and password-protected documents +- Implement page extraction in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Imagine you have a 10-page report and need to extract pages 2, 4, and 7 to create a summary document. Alternatively, you might need to extract all even pages from pages 1-10 for a two-sided printing job. This tutorial will teach you both approaches. + +## Method 1: Extract Pages by Exact Page Numbers + +This approach allows you to specify exactly which pages you want to extract. This is useful when you need specific, non-sequential pages from your document. + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Extraction Request + +Now, create a JSON request that specifies: +- The source document path +- The exact page numbers to extract +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/sample-10-pages.docx'}, + 'Pages': [ 2, 4, 7 ], + 'OutputPath': 'output/extract-pages-by-numbers.docx' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document containing only pages 2, 4, and 7. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see a document with only the three pages you specified. + +## Method 2: Extract Pages by Page Range + +This approach allows you to extract pages based on a range and filter them by even or odd page numbers. + +### Step 1: Define Your Range Extraction Request + +Create a JSON request that specifies: +- The source document path +- The start and end page numbers of your range +- The range mode (All, EvenPages, or OddPages) +- The destination path for the new document + +### Step 2: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/sample-10-pages.docx'}, + 'StartPageNumber': 1, + 'EndPageNumber': 10, + 'RangeMode': 'EvenPages', + 'OutputPath': 'output/extract-pages-by-range.docx' + }" +``` + +#### Try it yourself! + +Run this command with your own JWT token. The resulting document will contain only the even-numbered pages (2, 4, 6, 8, 10) from your source document. + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/extract" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': '/WordProcessing/protected-document.docx', + 'Password': 'your_password' + }, + 'Pages': [ 2, 4, 7 ], + 'OutputPath': 'output/extract-pages-protected.docx' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Extract Pages using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new ExtractOptions +{ + FileInfo = new FileInfo + { + FilePath = "WordProcessing/sample-10-pages.docx" + }, + Pages = new List { 2, 4, 7 }, + OutputPath = "output/extract-pages-by-numbers.docx" +}; + +var response = apiInstance.Extract(new ExtractRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Extract Pages using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("WordProcessing/sample-10-pages.docx"); + +ExtractOptions options = new ExtractOptions(); +options.setFileInfo(fileInfo); +options.setPages(Arrays.asList(2, 4, 7)); +options.setOutputPath("output/extract-pages-by-numbers.docx"); + +ExtractRequest request = new ExtractRequest(options); +DocumentResult response = apiInstance.extract(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Extract Pages using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "WordProcessing/sample-10-pages.docx" + +options = groupdocs_merger_cloud.ExtractOptions() +options.file_info = file_info +options.pages = [2, 4, 7] +options.output_path = "output/extract-pages-by-numbers.docx" + +request = groupdocs_merger_cloud.ExtractRequest(options) +response = api_instance.extract(request) +print("Output file path: " + response.path) +``` + +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- Empty Result Document: Ensure you've specified valid page numbers that exist in your source document. +- Password Issues: If working with protected documents, check that the provided password is correct. + +## What You've Learned + +In this tutorial, you've learned how to: +- Extract specific pages from a document by providing exact page numbers +- Extract pages using a range with filtering for even or odd pages +- Handle password-protected documents +- Implement page extraction functionality using various programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Extract the first and last page from a document +2. Extract all odd pages from a 20-page document +3. Combine both methods to extract pages 1, 3, and all even pages between 10-20 + +## Next Tutorial + +Ready to learn more? Continue to the next tutorial: [How to Remove Pages from Documents](/page-processes/remove-pages/) to learn how to permanently delete pages from your documents. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/page-processes/move-pages/_index.md b/content/merger/english/page-processes/move-pages/_index.md new file mode 100644 index 0000000..25f5af1 --- /dev/null +++ b/content/merger/english/page-processes/move-pages/_index.md @@ -0,0 +1,244 @@ +--- +title: How to Move Pages in Documents Tutorial +url: /page-processes/move-pages/ +weight: 4 +description: Learn how to change a page's position by moving it to a new location within your document using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Move Pages in Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Move a page from one position to another within a document +- Work with both unprotected and password-protected documents +- Implement page movement in multiple programming languages +- Understand how page renumbering works when moving pages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Imagine you have a document where page 1 contains introductory content that would be better positioned after the table of contents on page 2. Rather than recreating the document, you can simply move page 1 to position 2. This tutorial will teach you how to perform such page reordering efficiently. + +## Understanding Page Movement Mechanics + +Before diving into the implementation, it's important to understand how page movement works: + +1. When you move a page, the content of that page is relocated to a new position +2. All other pages are shifted accordingly +3. Page numbers refer to the current order (page 1 is the first page, page 2 is the second, etc.) +4. After moving, pages are renumbered sequentially in the new order + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Page Move Request + +Create a JSON request that specifies: +- The source document path +- The page number to move +- The new page number (destination position) +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/move" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': 'words/four-pages.docx'}, + 'PageNumber': 1, + 'NewPageNumber': 2, + 'OutputPath': 'output/move-page.docx' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document, which will have page 1 moved to position 2. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see that: +- The content that was originally on page 1 is now on page 2 +- The content that was originally on page 2 is now on page 1 +- All other pages maintain their relative order, just shifted accordingly + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/move" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'words/protected-document.docx', + 'Password': 'your_password' + }, + 'PageNumber': 1, + 'NewPageNumber': 2, + 'OutputPath': 'output/move-page-protected.docx' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Move Pages using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new MoveOptions +{ + FileInfo = new FileInfo + { + FilePath = "words/four-pages.docx" + }, + PageNumber = 1, + NewPageNumber = 2, + OutputPath = "output/move-page.docx" +}; + +var response = apiInstance.Move(new MoveRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Move Pages using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("words/four-pages.docx"); + +MoveOptions options = new MoveOptions(); +options.setFileInfo(fileInfo); +options.setPageNumber(1); +options.setNewPageNumber(2); +options.setOutputPath("output/move-page.docx"); + +MoveRequest request = new MoveRequest(options); +DocumentResult response = apiInstance.move(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Move Pages using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "words/four-pages.docx" + +options = groupdocs_merger_cloud.MoveOptions() +options.file_info = file_info +options.page_number = 1 +options.new_page_number = 2 +options.output_path = "output/move-page.docx" + +request = groupdocs_merger_cloud.MoveRequest(options) +response = api_instance.move(request) +print("Output file path: " + response.path) +``` + +## Special Case: Moving to the End of the Document + +If you want to move a page to the end of the document, you need to specify the total number of pages plus 1 as the new page number. For example, in a 4-page document, to move page 1 to the end: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/move" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': 'words/four-pages.docx'}, + 'PageNumber': 1, + 'NewPageNumber': 5, + 'OutputPath': 'output/move-to-end.docx' + }" +``` + +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- Invalid Page Numbers: Ensure that the page number to move exists in the source document and the new page number is valid (between 1 and total pages + 1). +- Same Page Number: If the page number and new page number are the same, the API will not make any changes to the document. +- Password Issues: If working with protected documents, check that the provided password is correct. + +## What You've Learned + +In this tutorial, you've learned how to: +- Move a page from one position to another within a document +- Work with both regular and password-protected documents +- Implement page movement functionality using various programming languages +- Handle special cases like moving a page to the end of a document + +## Further Practice + +To reinforce your learning, try these exercises: +1. Move the last page of a document to the first position +2. Move a page from the middle of the document to the end +3. Create a program that reverses the order of all pages in a document by performing multiple move operations + +## Next Tutorial + +Ready to learn more? Continue to the next tutorial: [How to Rotate Pages in Documents](/page-processes/rotate-pages/) to learn how to change page rotation angles for specific pages in your documents. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/page-processes/remove-pages/_index.md b/content/merger/english/page-processes/remove-pages/_index.md new file mode 100644 index 0000000..39e104e --- /dev/null +++ b/content/merger/english/page-processes/remove-pages/_index.md @@ -0,0 +1,248 @@ +--- +title: How to Remove Pages from Documents Tutorial +weight: 2 +url: /page-processes/remove-pages/ +description: Learn how to permanently remove specific pages from documents using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Remove Pages from Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Permanently remove specific pages from a document +- Remove pages using either exact page numbers or page ranges +- Filter page ranges to remove only even or odd pages +- Handle password-protected documents +- Implement page removal in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Consider a scenario where you have a 20-page contract document, but pages 5 and 12 contain outdated clauses that need to be removed. Alternatively, you might need to remove all even-numbered pages from a document that contains duplicate information on alternating pages. This tutorial will teach you both approaches. + +## Method 1: Remove Pages by Exact Page Numbers + +This approach allows you to specify exactly which pages should be removed from the document. + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Page Removal Request + +Create a JSON request that specifies: +- The source document path +- The exact page numbers to remove +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/four-pages.docx'}, + 'Pages': [ 2, 4 ], + 'OutputPath': 'output/remove-pages.docx' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document, which will contain all pages except pages 2 and 4. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see that pages 2 and 4 have been removed, and the document now contains only pages 1 and 3 (renumbered as pages 1 and 2). + +## Method 2: Remove Pages by Page Range + +This approach allows you to remove pages based on a range and filter them by even or odd page numbers. + +### Step 1: Define Your Range Removal Request + +Create a JSON request that specifies: +- The source document path +- The start and end page numbers of your range +- The range mode (All, EvenPages, or OddPages) +- The destination path for the new document + +### Step 2: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/WordProcessing/sample-20-pages.docx'}, + 'StartPageNumber': 1, + 'EndPageNumber': 10, + 'RangeMode': 'EvenPages', + 'OutputPath': 'output/remove-even-pages.docx' + }" +``` + +#### Try it yourself! + +Run this command with your own JWT token. The resulting document will have all even-numbered pages (2, 4, 6, 8, 10) removed from the range 1-10, keeping only the odd-numbered pages in that range, plus all pages after page 10. + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/remove" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': '/WordProcessing/protected-document.docx', + 'Password': 'your_password' + }, + 'Pages': [ 3, 5 ], + 'OutputPath': 'output/remove-pages-protected.docx' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Remove Pages using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new RemoveOptions +{ + FileInfo = new FileInfo + { + FilePath = "WordProcessing/four-pages.docx" + }, + Pages = new List { 2, 4 }, + OutputPath = "output/remove-pages.docx" +}; + +var response = apiInstance.Remove(new RemoveRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Remove Pages using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("WordProcessing/four-pages.docx"); + +RemoveOptions options = new RemoveOptions(); +options.setFileInfo(fileInfo); +options.setPages(Arrays.asList(2, 4)); +options.setOutputPath("output/remove-pages.docx"); + +RemoveRequest request = new RemoveRequest(options); +DocumentResult response = apiInstance.remove(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Remove Pages using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "WordProcessing/four-pages.docx" + +options = groupdocs_merger_cloud.RemoveOptions() +options.file_info = file_info +options.pages = [2, 4] +options.output_path = "output/remove-pages.docx" + +request = groupdocs_merger_cloud.RemoveRequest(options) +response = api_instance.remove(request) +print("Output file path: " + response.path) +``` + +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- No Changes in Document: If all pages remain in the document, check that you've specified valid page numbers that exist in your source document. +- Password Issues: If working with protected documents, check that the provided password is correct. +- Empty Document: If you try to remove all pages from a document, the API may return an error. Always leave at least one page in the document. + +## What You've Learned + +In this tutorial, you've learned how to: +- Remove specific pages from a document by providing exact page numbers +- Remove pages using a range with filtering for even or odd pages +- Handle password-protected documents +- Implement page removal functionality using various programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Remove the first page from a document +2. Remove all odd pages from a specific range in a document +3. Combine both methods to remove pages 1, 3, and all even pages between 10-20 + +## Next Tutorial + +Ready to learn more? Continue to the next tutorial: [How to Swap Pages in Documents](/page-processes/swap-pages/) to learn how to exchange the positions of pages within your documents. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/page-processes/rotate-pages/_index.md b/content/merger/english/page-processes/rotate-pages/_index.md new file mode 100644 index 0000000..50d4420 --- /dev/null +++ b/content/merger/english/page-processes/rotate-pages/_index.md @@ -0,0 +1,265 @@ +--- +title: How to Rotate Pages in Documents Tutorial +weight: 5 +url: /page-processes/rotate-pages/ +description: Learn how to change page rotation angles to 90, 180, or 270 degrees for specific pages in your documents using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Rotate Pages in Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Rotate specific pages in a document to 90, 180, or 270 degrees +- Rotate pages using either exact page numbers or page ranges +- Filter page ranges to rotate only even or odd pages +- Work with both unprotected and password-protected documents +- Implement page rotation in multiple programming languages + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Consider a scenario where you have a PDF document containing scanned pages, but some pages (like pages 2 and 4) were scanned in the wrong orientation. Rather than rescanning those pages, you can simply rotate them to the correct orientation using the GroupDocs.Merger Cloud API. This tutorial will teach you how to accomplish this task efficiently. + +## Understanding Rotation Angles + +Before implementation, let's understand the available rotation options: +- Rotate90: Rotates the page 90 degrees clockwise +- Rotate180: Rotates the page 180 degrees (upside down) +- Rotate270: Rotates the page 270 degrees clockwise (or 90 degrees counterclockwise) + +## Method 1: Rotate Pages by Exact Page Numbers + +This approach allows you to specify exactly which pages should be rotated in the document. + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Page Rotation Request + +Create a JSON request that specifies: +- The source document path +- The exact page numbers to rotate +- The rotation angle (Mode) +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/rotate" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/Pdf/ten-pages.pdf'}, + 'Pages': [ 2, 4 ], + 'Mode': 'Rotate90', + 'OutputPath': 'output/rotate-pages.pdf' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document, which will have pages 2 and 4 rotated 90 degrees clockwise. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see that pages 2 and 4 have been rotated 90 degrees clockwise, while all other pages maintain their original orientation. + +## Method 2: Rotate Pages by Page Range + +This approach allows you to rotate pages based on a range and filter them by even or odd page numbers. + +### Step 1: Define Your Range Rotation Request + +Create a JSON request that specifies: +- The source document path +- The start and end page numbers of your range +- The range mode (All, EvenPages, or OddPages) +- The rotation angle (Mode) +- The destination path for the new document + +### Step 2: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/rotate" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': '/Pdf/ten-pages.pdf'}, + 'StartPageNumber': 1, + 'EndPageNumber': 5, + 'RangeMode': 'OddPages', + 'Mode': 'Rotate180', + 'OutputPath': 'output/rotate-odd-pages.pdf' + }" +``` + +#### Try it yourself! + +Run this command with your own JWT token. The resulting document will have all odd-numbered pages (1, 3, 5) within the range 1-5 rotated 180 degrees, while all other pages maintain their original orientation. + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/rotate" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': '/Pdf/protected-document.pdf', + 'Password': 'your_password' + }, + 'Pages': [ 2, 4 ], + 'Mode': 'Rotate90', + 'OutputPath': 'output/rotate-pages-protected.pdf' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Rotate Pages using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new RotateOptions +{ + FileInfo = new FileInfo + { + FilePath = "Pdf/ten-pages.pdf" + }, + Pages = new List { 2, 4 }, + Mode = RotateMode.Rotate90, + OutputPath = "output/rotate-pages.pdf" +}; + +var response = apiInstance.Rotate(new RotateRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Rotate Pages using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("Pdf/ten-pages.pdf"); + +RotateOptions options = new RotateOptions(); +options.setFileInfo(fileInfo); +options.setPages(Arrays.asList(2, 4)); +options.setMode(RotateMode.ROTATE90); +options.setOutputPath("output/rotate-pages.pdf"); + +RotateRequest request = new RotateRequest(options); +DocumentResult response = apiInstance.rotate(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Rotate Pages using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "Pdf/ten-pages.pdf" + +options = groupdocs_merger_cloud.RotateOptions() +options.file_info = file_info +options.pages = [2, 4] +options.mode = "Rotate90" +options.output_path = "output/rotate-pages.pdf" + +request = groupdocs_merger_cloud.RotateRequest(options) +response = api_instance.rotate(request) +print("Output file path: " + response.path) +``` + +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- Invalid Page Numbers: Ensure that you've specified valid page numbers that exist in your source document. +- Invalid Rotation Mode: Make sure you're using one of the supported rotation modes: Rotate90, Rotate180, or Rotate270. +- Password Issues: If working with protected documents, check that the provided password is correct. +- File Format Limitations: Some document formats may have limitations regarding page rotation. PDF files typically work best for rotation operations. + +## What You've Learned + +In this tutorial, you've learned how to: +- Rotate specific pages in a document to different angles +- Use both exact page numbers and page ranges for rotation +- Filter page ranges to rotate only even or odd pages +- Handle password-protected documents +- Implement page rotation functionality using various programming languages + +## Further Practice + +To reinforce your learning, try these exercises: +1. Rotate all pages in a document by 180 degrees +2. Create a document where alternating pages have different rotations +3. Combine page rotation with other operations like page extraction or moving + +## Next Tutorial + +Ready to learn more? Continue to the next tutorial: [How to Change Page Orientation](/page-processes/change-page-orientation/) to learn how to switch between portrait and landscape orientations for specific pages in your documents. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! diff --git a/content/merger/english/page-processes/swap-pages/_index.md b/content/merger/english/page-processes/swap-pages/_index.md new file mode 100644 index 0000000..74be4c1 --- /dev/null +++ b/content/merger/english/page-processes/swap-pages/_index.md @@ -0,0 +1,215 @@ +--- +title: How to Swap Pages in Documents Tutorial +weight: 3 +url: /page-processes/swap-pages/ +description: Learn how to exchange the positions of two pages within a document using GroupDocs.Merger Cloud API in this step-by-step tutorial. +--- + +# Tutorial: How to Swap Pages in Documents + +## Learning Objectives + +In this tutorial, you'll learn how to: +- Exchange the positions of two pages within a document +- Work with both unprotected and password-protected documents +- Implement page swapping in multiple programming languages +- Verify the results of page swapping operations + +## Prerequisites + +Before starting this tutorial, make sure you have: +1. A GroupDocs.Merger Cloud account (get a [free trial here](https://dashboard.groupdocs.cloud/#/apps) +2. Your Client ID and Client Secret (available in the [API dashboard](https://dashboard.groupdocs.cloud/#/apps) +3. A document uploaded to your cloud storage +4. The appropriate SDK installed for your language of choice + +## Practical Scenario + +Imagine you've created a document but later discover that two pages are in the wrong order. For example, in a four-page document, pages 2 and 4 need to be swapped because they contain related information that should be presented in a different sequence. This tutorial will teach you how to quickly fix this issue without having to recreate the document. + +## Step-by-Step Guide to Swapping Pages + +### Step 1: Obtain Your JWT Token + +Before making any API request, you need to authenticate with the GroupDocs.Merger Cloud API: + +```bash +curl -v "https://api.groupdocs.cloud/connect/token" \ +-X POST \ +-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \ +-H "Content-Type: application/x-www-form-urlencoded" \ +-H "Accept: application/json" +``` + +The response will include your JWT token that you'll use in subsequent requests. + +### Step 2: Define Your Page Swap Request + +Create a JSON request that specifies: +- The source document path +- The first page number to swap +- The second page number to swap +- The destination path for the new document + +### Step 3: Execute the API Request + +#### Using cURL + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/swap" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { 'FilePath': 'words/four-pages.docx'}, + 'FirstPageNumber': 2, + 'SecondPageNumber': 4, + 'OutputPath': 'output/swap-pages.docx' + }" +``` + +#### Try it yourself! + +Replace the placeholder values with your actual Client ID, Client Secret, and file paths, then run the command. The API will return a JSON response with the path to your newly created document, which will have pages 2 and 4 exchanged. + +### Step 4: Verify the Results + +Download the resulting document from your storage and open it. You should see that the content that was previously on page 2 is now on page 4, and vice versa. The content of pages 1 and 3 remains unchanged. + +## Working with Password-Protected Documents + +If your document is password-protected, you need to include the password in your request: + +```bash +curl -v "https://api.groupdocs.cloud/v1.0/merger/pages/swap" \ +-X POST \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +-H "Authorization: Bearer YOUR_JWT_TOKEN" \ +-d "{ + 'FileInfo': { + 'FilePath': 'words/protected-document.docx', + 'Password': 'your_password' + }, + 'FirstPageNumber': 2, + 'SecondPageNumber': 4, + 'OutputPath': 'output/swap-pages-protected.docx' + }" +``` + +## SDK Implementation Examples + +### C# Example + +```csharp +// Swap Pages using C# SDK +string MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +string MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +var configuration = new Configuration(MyClientId, MyClientSecret); + +var apiInstance = new PagesApi(configuration); + +var options = new SwapOptions +{ + FileInfo = new FileInfo + { + FilePath = "words/four-pages.docx" + }, + FirstPageNumber = 2, + SecondPageNumber = 4, + OutputPath = "output/swap-pages.docx" +}; + +var response = apiInstance.Swap(new SwapRequest(options)); +Console.WriteLine("Output file path: " + response.Path); +``` + +### Java Example + +```java +// Swap Pages using Java SDK +String MyClientSecret = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud +String MyClientId = ""; // Get ClientId and ClientSecret from https://dashboard.groupdocs.cloud + +Configuration configuration = new Configuration(MyClientId, MyClientSecret); +PagesApi apiInstance = new PagesApi(configuration); + +FileInfo fileInfo = new FileInfo(); +fileInfo.setFilePath("words/four-pages.docx"); + +SwapOptions options = new SwapOptions(); +options.setFileInfo(fileInfo); +options.setFirstPageNumber(2); +options.setSecondPageNumber(4); +options.setOutputPath("output/swap-pages.docx"); + +SwapRequest request = new SwapRequest(options); +DocumentResult response = apiInstance.swap(request); +System.out.println("Output file path: " + response.getPath()); +``` + +### Python Example + +```python +# Swap Pages using Python SDK +import groupdocs_merger_cloud + +# Get your app_sid and app_key at https://dashboard.groupdocs.cloud +my_client_id = "" +my_client_secret = "" + +# Create instance of the API +configuration = groupdocs_merger_cloud.Configuration(my_client_id, my_client_secret) +api_instance = groupdocs_merger_cloud.PagesApi(configuration) + +file_info = groupdocs_merger_cloud.FileInfo() +file_info.file_path = "words/four-pages.docx" + +options = groupdocs_merger_cloud.SwapOptions() +options.file_info = file_info +options.first_page_number = 2 +options.second_page_number = 4 +options.output_path = "output/swap-pages.docx" + +request = groupdocs_merger_cloud.SwapRequest(options) +response = api_instance.swap(request) +print("Output file path: " + response.path) +``` +## Troubleshooting Tips + +- Error 401: If you receive an authentication error, make sure your JWT token is valid and hasn't expired. +- Error 400: Verify that the file path is correct and the file exists in your storage. +- Invalid Page Numbers: Ensure that both page numbers exist in the source document. If you try to swap with a non-existent page, the API will return an error. +- Password Issues: If working with protected documents, check that the provided password is correct. +- Same Page Numbers: If you specify the same page number for both first and second page, the API may return an error or create an identical document with no changes. + +## What You've Learned + +In this tutorial, you've learned how to: +- Exchange the positions of two pages within a document +- Work with both regular and password-protected documents +- Implement page swapping functionality using various programming languages +- Verify the successful completion of the page swap operation + +## Further Practice + +To reinforce your learning, try these exercises: +1. Swap the first and last pages of a document +2. Swap multiple pairs of pages in sequence (e.g., swap pages 1-2, then swap pages 3-4 in the resulting document) +3. Create a program that reverses the order of all pages in a document by performing multiple swap operations + +## Next Tutorial + +Ready to learn more? Continue to the next tutorial: [How to Move Pages in Documents](/page-processes/move-pages) to learn how to change a page's position by moving it to a new location within your document. + +## Helpful Resources + +- [Product Page](https://products.groupdocs.cloud/merger/) +- [Documentation](https://docs.groupdocs.cloud/merger/) +- [API Reference](https://reference.groupdocs.cloud/merger/) +- [Free Support Forum](https://forum.groupdocs.cloud/c/merger/18/) +- [Free Trial](https://dashboard.groupdocs.cloud/#/apps) + +If you have any questions about this tutorial, please let us know in the comments below or through our [support forum](https://forum.groupdocs.cloud/c/merger/18/)! \ No newline at end of file