ngx-doc-viewer 15.0.1 → 21.0.1

package/README.md

@@ -6,7 +6,7 @@ Documents that are publicly available can be shown in an iframe using the google
 
 Pdf files and word document that are not publicly available can be shown using the mammoth viewer or pdf viewer by passing an objectUrl.
 
-<a href="https://angular-doc-viewer.firebaseapp.com/">View demo</a>
+<a href="https://angular-doc-viewer.web.app/">View demo</a>
 
 <a href="https://github.com/Marcelh1983/document-viewer/blob/main/packages/ngx-doc-viewer/changelog.md">Changes</a>
 
@@ -37,6 +37,8 @@ export class AppModule {}
 ></ngx-doc-viewer>
 ```
 
+The component now shows an internal loading overlay while external viewers such as Google Docs Viewer and Office Online are initializing, so viewer switches do not appear as a blank panel.
+
 To
 
 #### API:
@@ -52,7 +54,76 @@ Input:
   - all: adds an overlay to the whole iframe, which makes nothing in the document clickable/selectable
   - popout: adds an overlay over googles popout button or office popout and menu which disables just this button/menu but keeps giving the possibility to select text. The popout button is still visible (for google during a few seconds) but not clickable.
   - popout-hide: see popup, instead of an transparent overlay a white one. This really hides the button but you'll see a white block while loading for the google viewer.
- - overrideLocalhost: documents from the assets folder are not publicly available and therefor won't show in an external viewer (google, office). If the site is already published to public server, then pass that url and if will replace localhost by the other url. Like: overrideLocalhost="https://angular-doc-viewer.firebaseapp.com/"
+ - overrideLocalhost: documents from the assets folder are not publicly available and therefor won't show in an external viewer (google, office). If the site is already published to public server, then pass that url and if will replace localhost by the other url. Like: overrideLocalhost="https://angular-doc-viewer.web.app/"
+ - loadingText: fallback text shown in the built-in loading overlay. Defaults to `Loading document...`
+ - errorTextOverride: fallback text shown in the built-in error overlay. Defaults to the runtime error message.
+ - retryButtonText: text used by the built-in retry button in the default error overlay. Defaults to `Retry`
+ - googleFinalRetryDelay: waits this many milliseconds and retries Google once more before showing the error overlay. Defaults to `0`
+ - officeAutoRetry: automatically retries the Office viewer once after `officeRetryDelay`. Defaults to `false`
+ - officeRetryDelay: delay in milliseconds before the one-time Office auto retry. Defaults to `3000`
+ - officeReloadButtonText: text shown in the persistent Office reload button. Defaults to `↻`
+ - officeReloadButtonTitle: tooltip/title for the persistent Office reload button. Defaults to `Reload document`
+ - secondaryActionText: optional text for a built-in secondary error action button, for example `Open source` or `Download`
+ - secondaryActionMode: controls the built-in secondary action behavior. Supported values: `open` or `download`. Defaults to `open`
+
+For custom loading markup in Angular, project an `ng-template` named `loadingContent`.
+The template receives `$implicit` and `state` with:
+- `viewer`
+- `url`
+- `phase`
+- `errorText`
+- `retry()`
+- `actionUrl`
+
+```html
+<ngx-doc-viewer [url]="doc" viewer="office">
+  <ng-template #loadingContent let-state>
+    <div style="display:flex;gap:8px;align-items:center;">
+      <span class="spinner"></span>
+      <span>Preparing {{ state.viewer }} preview...</span>
+    </div>
+  </ng-template>
+</ngx-doc-viewer>
+```
+
+To replace the persistent Office reload control, project an `ng-template` named `officeReloadContent`:
+
+```html
+<ngx-doc-viewer [url]="doc" viewer="office">
+  <ng-template #officeReloadContent let-state>
+    <span>Reload</span>
+  </ng-template>
+</ngx-doc-viewer>
+```
+
+For custom error markup in Angular, project an `ng-template` named `errorContent`.
+It receives the same context and can call `retry()` directly:
+
+```html
+<ngx-doc-viewer [url]="doc" viewer="office">
+  <ng-template #errorContent let-state>
+    <div style="text-align:center;">
+      <div>Preview unavailable for {{ state.viewer }}.</div>
+      <div>{{ state.actionUrl }}</div>
+      <button type="button" (click)="state.retry()">Retry</button>
+      <a [href]="state.actionUrl" target="_blank" rel="noreferrer">Open source</a>
+    </div>
+  </ng-template>
+</ngx-doc-viewer>
+```
+
+If you want to keep the default error layout but replace just the actions area, project an `ng-template` named `errorActions`:
+
+```html
+<ngx-doc-viewer [url]="doc" viewer="office" retryButtonText="Try again">
+  <ng-template #errorActions let-state>
+    <div style="margin-top: 14px; display: flex; gap: 8px; justify-content: center;">
+      <button type="button" (click)="state.retry()">Try again</button>
+      <a [href]="state.actionUrl" target="_blank" rel="noreferrer">Open source</a>
+    </div>
+  </ng-template>
+</ngx-doc-viewer>
+```
 
 There are some issues loading document in the google viewer. See: https://stackoverflow.com/questions/40414039/google-docs-viewer-returning-204-responses-no-longer-working-alternatives. If loading pdf's and Word documents, seems to work now with this hack let me know via a Github issue.
 
@@ -61,7 +132,16 @@ There are some issues loading document in the google viewer. See: https://stacko
 - googleMaxChecks = 5 | max number of retries
 Output:
 
-- loaded: google only, notifies when iframe is loaded. Can be used to show progress while loading
+- loaded: emitted when the current iframe is ready. Can be used to hook into custom loading or telemetry flows.
+- loading: emitted when the viewer enters the `loading` phase. Payload includes `viewer`, `url`, `phase`, `errorText`, `retry()`, and `actionUrl`.
+- error: emitted when the viewer enters the `error` phase. Payload includes `viewer`, `url`, `phase`, `errorText`, `retry()`, and `actionUrl`.
+- phaseChange: emitted whenever the internal phase changes to `idle`, `loading`, `ready`, or `error`.
+
+### Recent behavior improvements
+
+- External viewer switches now remount the iframe cleanly when changing between viewers such as Google and Office.
+- A built-in loading overlay is shown while remote viewers are loading.
+- Mammoth rendering now refreshes correctly when switching from an iframe-based viewer back to inline document rendering.
 
 ### File type support
 
@@ -90,9 +170,8 @@ Google Drive viewer helps you preview over 15 different file types, listed below
 - PostScript (.EPS, .PS)
 - TrueType (.TTF)
 - XML Paper Specification (.XPS)
-- Archive file types (.ZIP and .RAR)
 
-<a href="https://gist.githubusercontent.com/tzmartin/1cf85dc3d975f94cfddc04bc0dd399be/raw/d4263c8faf7b68f4bbfd33b386ec33ed2bc11e7d/embedded-file-viewer.md">Source</a>
+> **Note:** Archive files (.ZIP, .RAR) are **not** supported by the Google Docs embedded viewer despite some community sources claiming otherwise. For the current official list of supported formats, see the [Google Drive Help Center](https://support.google.com/drive/answer/2423485).
 
 #### url