> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/android/get-started/frameworks/react-native/add-an-api.md). # Add an API for React Native Learn how to define a ReactProp in Android for PDFTron's DocumentView with this step-by-step guide. Implement methods, add event constants, and set up event listeners for seamless development. The Apr ## Introduction The React Native API for Apryse Mobile SDK includes all of the most used functions and methods for viewing, annotating and saving PDF documents. However, it is possible your app may need access to APIs that are available as part of the native API, but are not directly available to React Native. This guide provides an example of how to add the following to the React Native interface: * `pageChangeOnTap` prop that determines whether page will turn left or right when tapping corresponding edges. * `getField` function which retrieves information about a field using its name. * `onLayoutChanged` event listener that is raised when the layout of viewer has changed. You can follow the same pattern to add new functions and props that your React Native app may need. The new additions could be simple ones, which expose one piece of functionality, or custom ones, that expose a series of native commands under the hood. Prior to following this guide, we highly recommend you to go through the official guide here: [Native UI Components](https://reactnative.dev/docs/native-components-android/) to have a better understanding of the system. ### 1. Fork and clone Apryse's React Native Repo The source is hosted on GitHub here: [https://github.com/ApryseSDK/pdftron-react-native](https://github.com/ApryseSDK/pdftron-react-native/) Fork the project and clone a copy of the repository to your disk. ## Adding the `pageChangeOnTap` prop ### 2. Add prop to DocumentView\.tsx interface file The `DocumentView.tsx` interface file lists all of the React Native props on the DocumentView component. Add the prop declaration: {% tabs %} {% tab title="JavaScript" %} {% code lineNumbers="true" %} ```js static propTypes = { pageChangeOnTap: PropTypes.bool, }; ``` {% endcode %} {% endtab %} {% endtabs %} For props that accept `Config` constants or arrays of `Config` constants, use the `oneOf` and `arrayOf` helper methods. These helpers return flexible types that allow custom checks for TypeScript users, while maintaining standard run-time checks for all users. ### 3. Define a ReactProp matches the TS declaration Open file `/android/src/main/java/com/pdftron/reactnative/viewmanagers/DocumentViewViewManager.java`. Add the method key that matches the TS declaration: {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java @ReactProp(name = "pageChangeOnTap") public void setPageChangeOnTap(DocumentView documentView, boolean pageChangeOnTap) { documentView.setPageChangeOnTap(pageChangeOnTap); } ``` {% endcode %} {% endtab %} {% endtabs %} ### 4. Implement the method to set the property Open file `/android/src/main/java/com/pdftron/reactnative/views/DocumentView.java`. Add the implementation: {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java public void setPageChangeOnTap(boolean pageChangeOnTap) { Context context = getContext(); if (context != null) { PdfViewCtrlSettingsManager.setAllowPageChangeOnTap(context, pageChangeOnTap); } } ``` {% endcode %} {% endtab %} {% endtabs %} The actual implementation will depend on the actual functionality. ## Adding the `getField` function ### 2. Add function to DocumentView\.tsx interface file The `DocumentView.tsx` interface file lists all of the React Native functions on the DocumentView component. Add the function declaration: {% tabs %} {% tab title="JavaScript" %} {% code lineNumbers="true" %} ```js getField = (fieldName: string): Promise => { const tag = findNodeHandle(this._viewerRef); if(tag != null) { return DocumentViewManager.getField(tag, fieldName); } return Promise.resolve(); } ``` {% endcode %} {% endtab %} {% endtabs %} All functions return `Promise` where `T` is the expected return type upon success. If the function returns `void` upon success, simply put `Promise`. While you are adding types, consider representing objects with reusable object types. You can use existing ones, or create a new type alias or interface in `AnnotOptions.ts` (see [Object Types](https://www.typescriptlang.org/docs/handbook/2/objects.html)). ### 3. Receive the new method from JavaScript Add this method to `/android/src/main/java/com/pdftron/reactnative/modules/DocumentViewModule.java`: {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java @ReactMethod public void getField(final int tag, final String fieldName, final Promise promise) { getReactApplicationContext().runOnUiQueueThread(new Runnable() { @Override public void run() { try { WritableMap field = mDocumentViewInstance.getField(tag, fieldName); promise.resolve(field); } catch (Exception ex) { promise.reject(ex); } } }); } ``` {% endcode %} {% endtab %} {% endtabs %} ### 4. Define the caller method Add the following to `/android/src/main/java/com/pdftron/reactnative/viewmanagers/DocumentViewViewManager.java`: {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java public WritableMap getField(int tag, String fieldName) throws PDFNetException { DocumentView documentView = mDocumentViews.get(tag); if (documentView != null) { return documentView.getField(fieldName); } else { throw new PDFNetException("", 0L, getName(), "getField", "Unable to find DocumentView."); } } ``` {% endcode %} {% endtab %} {% endtabs %} ### 5. Implement the helper method Add the following to `/android/src/main/java/com/pdftron/reactnative/views/DocumentView.java`: {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java public WritableMap getField(String fieldName) throws PDFNetException { PDFViewCtrl pdfViewCtrl = getPdfViewCtrl(); PDFDoc pdfDoc = pdfViewCtrl.getDoc(); WritableMap fieldMap = null; boolean shouldUnlock = false; try { pdfViewCtrl.docLockRead(); shouldUnlock = true; Field field = pdfDoc.getField(fieldName); if (field != null && field.isValid()) { fieldMap = Arguments.createMap(); int fieldType = field.getType(); String typeString; switch (fieldType) { case Field.e_button: typeString = FIELD_TYPE_BUTTON; break; case Field.e_check: typeString = FIELD_TYPE_CHECKBOX; fieldMap.putBoolean(KEY_FIELD_VALUE, field.getValueAsBool()); break; case Field.e_radio: typeString = FIELD_TYPE_RADIO; fieldMap.putString(KEY_FIELD_VALUE, field.getValueAsString()); break; case Field.e_text: typeString = FIELD_TYPE_TEXT; fieldMap.putString(KEY_FIELD_VALUE, field.getValueAsString()); break; case Field.e_choice: typeString = FIELD_TYPE_CHOICE; fieldMap.putString(KEY_FIELD_VALUE, field.getValueAsString()); break; case Field.e_signature: typeString = FIELD_TYPE_SIGNATURE; break; default: typeString = FIELD_TYPE_UNKNOWN; break; } fieldMap.putString(KEY_FIELD_NAME, fieldName); fieldMap.putString(KEY_FIELD_TYPE, typeString); } } finally { if (shouldUnlock) { pdfViewCtrl.docUnlockRead(); } } return fieldMap; } ``` {% endcode %} {% endtab %} {% endtabs %} The logic is to get the PDF view controller and if the field names are valid, use the controller to get the fields from the current document. ## Adding the `onLayoutChanged` event listener ### 2. Define the new listener in TS Event listeners are handled in `DocumentView.tsx`. Add the following to the file: {% tabs %} {% tab title="JavaScript" %} {% code lineNumbers="true" %} ```js static propTypes = { ... onLayoutChanged: func<() => void>(), } onChange = (event) => { if (event.nativeEvent.onLeadingNavButtonPressed) { ... } else if (event.nativeEvent.onLayoutChanged) { if (this.props.onLayoutChanged) { this.props.onLayoutChanged(); } } } ``` {% endcode %} {% endtab %} {% endtabs %} The `onLayoutChanged` event listener does not require any arguments. If your event listener requires arguments, access them using `event.nativeEvent.exampleArg`. For event listeners and other props that accept functions, use the `func` helper method. This helper returns flexible types that allow custom checks for TypeScript users, while maintaining standard run-time checks for all users. While you are adding types, consider representing objects with reusable object types. You can use existing ones, or create a new type alias or interface in `AnnotOptions.ts` (see [Object Types](https://www.typescriptlang.org/docs/handbook/2/objects.html)). ### 3. Add event constant for Android In `android/src/main/java/com/pdftron/reactnative/utils/Constants.java`, add a constant to represent the event. {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java // EVENTS ... public static final String ON_LAYOUT_CHANGED = "onLayoutChanged"; ``` {% endcode %} {% endtab %} {% endtabs %} ### 4. Implement event listener In `/android/src/main/java/com/pdftron/reactnative/views/DocumentView.java`, create a new event listener to send the event to JS. This event listener will call the existing method `onReceiveNativeEvent` when layout changes. Note that the event you want to implement may be a part of an existing event listener. {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java private View.OnLayoutChangeListener mLayoutChangedListener = new OnLayoutChangeListener() { @Override public void onLayoutChange(View view, int i, int i1, int i2, int i3, int i4, int i5, int i6, int i7) { WritableMap params = Arguments.createMap(); params.putString(ON_LAYOUT_CHANGED, ON_LAYOUT_CHANGED); onReceiveNativeEvent(params); } }; ``` {% endcode %} {% endtab %} {% endtabs %} ### 5. Set up and remove event listener In the same file, `/android/src/main/java/com/pdftron/reactnative/views/DocumentView.java`, add the event listener to our `PDFViewCtrl` when the document has loaded, and remove the listener when it is no longer necessary. {% tabs %} {% tab title="Java" %} {% code lineNumbers="true" %} ```java @Override public void onTabDocumentLoaded(String tag) { super.onTabDocumentLoaded(tag); ... getPdfViewCtrl().addOnLayoutChangeListener(mLayoutChangedListener); ... } @Override protected void onDetachedFromWindow() { if (getPdfViewCtrl() != null) { ... getPdfViewCtrl().removeOnLayoutChangeListener(mLayoutChangedListener); } ... } ``` {% endcode %} {% endtab %} {% endtabs %} The actual implementation will depend on the actual functionality. ## Finishing steps ### 1. Push the code and integrate the updated source Now `npm install` your forked version to your application. The new functionality is now ready to use. ### 2. Access the new functionality The app can now access the new API as follows: {% tabs %} {% tab title="JavaScript" %} {% code lineNumbers="true" %} ```js onDocumentLoaded = () => { this._viewer.getField('someFieldName').then((field) => { if (field !== undefined) { console.log('field name:', field.fieldName); console.log('field value:', field.fieldValue); console.log('field type:', field.fieldType); } }); } onLayoutChanged = () => { console.log("Layout changed"); } this._viewer = c} pageChangeOnTap={false} onDocumentLoaded={this.onDocumentLoaded} onLayoutChanged={this.onLayoutChanged} document={this.state.document} /> ``` {% endcode %} {% endtab %} {% endtabs %} ### 3. All done! If you're only developing for Android, then you're all done! If you're also deploying on iOS, you'll need to complete the necessary steps for iOS. If you're developing for both iOS and Android, please consider [submitting a PR](https://github.com/ApryseSDK/pdftron-react-native/blob/master/CONTRIBUTING.md), as upstreaming the change will simplify your developing and make the APIs available for other Apryse customers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.apryse.com/android/get-started/frameworks/react-native/add-an-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.