Client exports

Custom apps

Client exports that add your own app to the notebook, open it, send it data and remove it.

These exports add an app made in another resource to the notebook's launcher. The full walk-through is in Custom apps overview. The server side is in Custom app actions.

They work only while Config.CustomApps.Enabled is true.

#AddCustomApp

Adds your app to the launcher. The calling resource becomes the app's owner.

lua---@param definition table { identifier, name, ui, icon? }
---@return boolean ok
---@return string idOrError the app id on success, a short reason on failure
exports['fx-pocketbook']:AddCustomApp(definition)
lualocal ok, result = exports['fx-pocketbook']:AddCustomApp({
    identifier = 'ranch_ledger',
    name = 'Ranch Ledger',
    ui = 'ui/index.html',
    icon = 'ui/icon.png',
})
Field Also accepted as Rules
identifier appId Lowercase letters, numbers and _, starts with a letter, up to 32 characters. Built-in app ids are reserved.
name label Title in the launcher. Up to 64 bytes, not blank.
ui Page of your own resource: 'ui/index.html', 'my-resource/ui/index.html' or 'https://cfx-nui-my-resource/ui/index.html'.
icon Optional image of your own resource, same forms as ui. Without it the launcher shows a notebook icon.
  • ui and icon must point into the calling resource. Paths with .., %, \, spaces, ?, # or a leading / are refused, and so is a link to any other site.
  • Returns false when custom apps are off, the id is invalid, reserved or already used (by you or anyone), the limit Config.CustomApps.Maximum is reached, or the name or a path is invalid.
  • Registering the same id again returns false and keeps the first registration.
  • When your resource stops, its app is removed. Register again on start and on [fx-pocketbook:ready](/phone/docs/pocketbook/events/client-events).
  • List the page, its scripts, styles and the icon under files in your own fxmanifest.lua. Do not set a ui_page for it.

#RemoveCustomApp

Removes your app from the launcher. If it is open, it closes.

lua---@param id string
---@return boolean removed false when the app is not yours or does not exist
exports['fx-pocketbook']:RemoveCustomApp(id)
luaexports['fx-pocketbook']:RemoveCustomApp('ranch_ledger')

#OpenApp

Opens the notebook, then its cover, then your app. If the book is open it switches to your app.

lua---@param id string
---@return boolean ok
exports['fx-pocketbook']:OpenApp(id)
luaRegisterCommand('ledger', function()
    exports['fx-pocketbook']:OpenApp('ranch_ledger')
end, false)
  • Returns false when the app is not yours, or when the book cannot open (see [Open](/phone/docs/pocketbook/exports/client/notebook)).
  • To open a built-in app, use [OpenApplication](/phone/docs/pocketbook/exports/client/notebook).

#SendCustomAppMessage

Sends data to your app's page while it is on screen. The page receives it with Pocketbook.onMessage.

lua---@param id string
---@param data any table, string, number or boolean
---@return boolean sent
exports['fx-pocketbook']:SendCustomAppMessage(id, data)
luaexports['fx-pocketbook']:SendCustomAppMessage('ranch_ledger', { kind = 'hint', text = 'The cattle are fed.' })
  • Returns false when the app is not yours, or data is too large: more than 32 KiB as JSON, deeper than 8 levels, more than 128 keys in one table, or a string over 16384 bytes.
  • The message is delivered only to the page that is mounted at that moment. It is not stored. If the app is closed it is dropped.