Utility Functions

Navify Kdu ships with several utility functions that you can use in your application to make certain tasks easier such as managing the on-screen keyboard and the hardware back button.

Router

Functions

useNavRouter

▸ useNavRouter(): UseNavRouterResult

Returns the Navify router instance, containing API methods for navigating, customizing page transitions and routing context for native features. This function can be used in combination with the useRouter from Kdu.

Customizing Page Transitions

import { NavPage, useNavRouter } from '@navify/kdu';
import { defineComponent } from 'kdu';
import { customAnimation } from '@/animations/customAnimation';

export default defineComponent({
  components: { NavPage },
  setup() {
    const router = useNavRouter();
    const push = () => {
      router.push('/page2', customAnimation);
    };
    const back = () => {
      router.back(customAnimation);
    };

    return { push, back };
  },
});

Hardware back button on Android

You may want to know if you are at the root page of the application when a user presses the hardware back button on Android.

import { useNavRouter } from '@navify/kdu';

...

export default {
  setup() {
    const navRouter = useNavRouter();
    if (navRouter.canGoBack()) {
      // Perform some action here
    }
  }
}

For additional APIs with Kdu routing, please refer to the Kdu Router documentation.

Interfaces

UseNavRouterResult

import { AnimationBuilder } from '@navify/kdu';
import { RouteLocationRaw } from 'kdu-router';

interface UseNavRouterResult {
  canGoBack: (deep?: number) => boolean;
  push: (location: RouteLocationRaw, routerAnimation?: AnimationBuilder) => void;
  replace: (location: RouteLocationRaw, routerAnimation?: AnimationBuilder) => void;
  back: (routerAnimation?: AnimationBuilder) => void;
  forward: (routerAnimation?: AnimationBuilder) => void;
  navigate: (
    location: string | Location,
    routerDirection?: 'forward' | 'back' | 'root' | 'none',
    routerAction?: 'push' | 'pop' | 'replace',
    routerAnimation?: AnimationBuilder
  ) => void;
}

useNavRouter(): UseNavRouterResult;

• The push method is the equivalent of calling navRouter.navigate(location, 'forward', 'push', animation).

• The replace method is the equivalent of calling navRouter.navigate(location, 'root', 'replace', animation).

See the Kdu Navigation Documentation for more usage examples.

Hardware Back Button

The useBackButton function can be used to register a callback function to fire whenever the hardware back button on Android is pressed. Additionally it accepts a priority parameter, allowing developers to customize which handler fires first if multiple handlers are registered.

import { useBackButton } from '@navify/kdu';

...

useBackButton(10, () => {
  console.log('Hardware Back Button was called!');
});

Interfaces

type Handler = (processNextHandler: () => void) => Promise<any> | void | null;
interface UseBackButtonResult {
  unregister: () => void;
}

useBackButton(priority: number, handler: Handler): UseBackButtonResult;

See the Hardware Back Button Documentation for more information and usage examples.

note

The useBackButton callback will only fire when your app is running in Jigra or Cordova. See Hardware Back Button in Jigra and Cordova for more information.

Keyboard

The useKeyboard function returns an object that contains the state of the on-screen keyboard. This object provides information such as whether or not the on-screen keyboard is presented and what the height of the keyboard is in pixels. This information is provided in a Kdu ref so it will be reactive in your application.

import { watch } from 'kdu';
import { useKeyboard } from '@navify/kdu';

const { isOpen, keyboardHeight } = useKeyboard();

watch(keyboardHeight, () => {
  console.log(`Keyboard height is ${keyboardHeight.value}px`);
});

Interfaces

interface UseKeyboardResult {
  isOpen: Ref<boolean>;
  keyboardHeight: Ref<number>;
  unregister: () => void
}

useKeyboard(): UseKeyboardResult;

See the Keyboard Documentation for more information and usage examples.

Navify Lifecycles

Navify Kdu provides several lifecycle hooks for the setup() function to tap into the Navify Framework page lifecycle.

import { NavPage, onNavViewWillEnter, onNavViewDidEnter, onNavViewWillLeave, onNavViewDidLeave } from '@navify/kdu';
import { defineComponent } from 'kdu';

export default defineComponent({
  components: { NavPage },
  setup() {
    onNavViewDidEnter(() => {
      console.log('Page did enter');
    });

    onNavViewDidLeave(() => {
      console.log('Page did leave');
    });

    onNavViewWillEnter(() => {
      console.log('Page will enter');
    });

    onNavViewWillLeave(() => {
      console.log('Page will leave');
    });
  },
});

note

Pages in your app need to be using the NavPage component in order for lifecycle methods and hooks to fire properly.

See the Kdu Lifecycle Documentation for more information and usage examples.