updated search index

website/static/search_index.json

@@ -159,6 +159,11 @@
     "content": "create SVG preview and PDF download from input form elements",
     "url": "https://github.com/zauberzeug/nicegui/tree/main/examples/generate_pdf/main.py"
   },
+  {
+    "title": "Example: Custom Binding",
+    "content": "create a custom binding for a label with a bindable background color",
+    "url": "https://github.com/zauberzeug/nicegui/tree/main/examples/custom_binding/main.py"
+  },
   {
     "title": "Basic Elements",
     "content": "This is **Markdown**.",
@@ -289,6 +294,11 @@
     "content": "Overview",
     "url": "/documentation/#lifecycle"
   },
+  {
+    "title": "URLs",
+    "content": "You can access the list of all URLs on which the NiceGUI app is available via app.urls. The URLs are not available in app.on_startup because the server is not yet running. Instead, you can access them in a page function or register a callback with app.urls.on_change.",
+    "url": "/documentation/#urls"
+  },
   {
     "title": "Shutdown",
     "content": "Shut down NiceGUI.  This will programmatically stop the server. Only possible when auto-reload is disabled.",
@@ -331,7 +341,7 @@
   },
   {
     "title": "Package for Installation",
-    "content": "NiceGUI apps can also be bundled into an executable with PyInstaller. This allows you to distribute your app as a single file that can be executed on any computer.  Just take care your ui.run command does not use the reload argument. Running the build.py below will create an executable myapp in the dist folder: python from nicegui import native_mode, ui  ui.label('Hello from PyInstaller')  ui.run(reload=False, native_mode.find_open_port()) python import os import subprocess from pathlib import Path import nicegui  cmd = [ 'python', '-m', 'PyInstaller', 'main.py', # your main file with ui.run() '--name', 'myapp', # name of your app '--onefile', #'--windowed', # prevent console appearing, only use with ui.run(native=True, ...) '--add-data', f'Path(nicegui.__file__).parentos.pathsepnicegui' ] subprocess.call(cmd) **Packaging Tips**  - When building a PyInstaller app, your main script can use a native window (rather than a browser window) by using ui.run(reload=False, native=True). The native parameter can be True or False depending on whether you want a native window or to launch a page in the user's browser - either will work in the PyInstaller generated app.  - Specifying --windowed to PyInstaller will prevent a terminal console from appearing. However you should only use this option if you have also specified native=True in your ui.run command. Without a terminal console the user won't be able to exit the app by pressing Ctrl-C. With the native=True option, the app will automatically close when the window is closed, as expected.  - Specifying --windowed to PyInstaller will create an .app file on Mac which may be more convenient to distribute. When you double-click the app to run it, it will not show any console output. You can also run the app from the command line with ./myapp.app/Contents/MacOS/myapp to see the console output.  - Specifying --onefile to PyInstaller will create a single executable file. Whilst convenient for distribution, it will be slower to start up. This is not NiceGUI's fault but just the way Pyinstaller zips things into a single file, then unzips everything into a temporary directory before running. You can mitigate this by removing --onefile from the PyInstaller command, and zip up the generated dist directory yourself, distribute it, and your end users can unzip once and be good to go, without the constant expansion of files due to the --onefile flag.  - Summary of user experience for different options:  | PyInstaller              | ui.run(...)  | Explanation | | :---                     | :---           | :---        | | onefile                | native=False | Single executable generated in dist/, runs in browser | | onefile                | native=True  | Single executable generated in dist/, runs in popup window | | onefile and windowed | native=True  | Single executable generated in dist/ (on Mac a proper dist/myapp.app generated incl. icon), runs in popup window, no console appears | | onefile and windowed | native=False | Avoid (no way to exit the app) | | Specify neither          |                | A dist/myapp directory created which can be zipped manually and distributed; run with dist/myapp/myapp |  - If you are using a Python virtual environment, ensure you pip install pyinstaller within your virtual environment so that the correct PyInstaller is used, or you may get broken apps due to the wrong version of PyInstaller being picked up. That is why the build script invokes PyInstaller using python -m PyInstaller rather than just pyinstaller. bash python -m venv venv source venv/bin/activate pip install nicegui pip install pyinstaller **Note:** If you're getting an error \"TypeError: a bytes-like object is required, not 'str'\", try adding the following lines to the top of your main.py file: py import sys sys.stdout = open('logs.txt', 'w')  See <https://github.com/zauberzeug/nicegui/issues/681> for more information.",
+    "content": "NiceGUI apps can also be bundled into an executable with PyInstaller. This allows you to distribute your app as a single file that can be executed on any computer.  Just take care your ui.run command does not use the reload argument. Running the build.py below will create an executable myapp in the dist folder: python from nicegui import native_mode, ui  ui.label('Hello from PyInstaller')  ui.run(reload=False, port=native_mode.find_open_port()) python import os import subprocess from pathlib import Path import nicegui  cmd = [ 'python', '-m', 'PyInstaller', 'main.py', # your main file with ui.run() '--name', 'myapp', # name of your app '--onefile', #'--windowed', # prevent console appearing, only use with ui.run(native=True, ...) '--add-data', f'Path(nicegui.__file__).parentos.pathsepnicegui' ] subprocess.call(cmd) **Packaging Tips**  - When building a PyInstaller app, your main script can use a native window (rather than a browser window) by using ui.run(reload=False, native=True). The native parameter can be True or False depending on whether you want a native window or to launch a page in the user's browser - either will work in the PyInstaller generated app.  - Specifying --windowed to PyInstaller will prevent a terminal console from appearing. However you should only use this option if you have also specified native=True in your ui.run command. Without a terminal console the user won't be able to exit the app by pressing Ctrl-C. With the native=True option, the app will automatically close when the window is closed, as expected.  - Specifying --windowed to PyInstaller will create an .app file on Mac which may be more convenient to distribute. When you double-click the app to run it, it will not show any console output. You can also run the app from the command line with ./myapp.app/Contents/MacOS/myapp to see the console output.  - Specifying --onefile to PyInstaller will create a single executable file. Whilst convenient for distribution, it will be slower to start up. This is not NiceGUI's fault but just the way Pyinstaller zips things into a single file, then unzips everything into a temporary directory before running. You can mitigate this by removing --onefile from the PyInstaller command, and zip up the generated dist directory yourself, distribute it, and your end users can unzip once and be good to go, without the constant expansion of files due to the --onefile flag.  - Summary of user experience for different options:  | PyInstaller              | ui.run(...)  | Explanation | | :---                     | :---           | :---        | | onefile                | native=False | Single executable generated in dist/, runs in browser | | onefile                | native=True  | Single executable generated in dist/, runs in popup window | | onefile and windowed | native=True  | Single executable generated in dist/ (on Mac a proper dist/myapp.app generated incl. icon), runs in popup window, no console appears | | onefile and windowed | native=False | Avoid (no way to exit the app) | | Specify neither          |                | A dist/myapp directory created which can be zipped manually and distributed; run with dist/myapp/myapp |  - If you are using a Python virtual environment, ensure you pip install pyinstaller within your virtual environment so that the correct PyInstaller is used, or you may get broken apps due to the wrong version of PyInstaller being picked up. That is why the build script invokes PyInstaller using python -m PyInstaller rather than just pyinstaller. bash python -m venv venv source venv/bin/activate pip install nicegui pip install pyinstaller **Note:** If you're getting an error \"TypeError: a bytes-like object is required, not 'str'\", try adding the following lines to the top of your main.py file: py import sys sys.stdout = open('logs.txt', 'w')  See <https://github.com/zauberzeug/nicegui/issues/681> for more information.",
     "url": "/documentation/#package_for_installation"
   },
   {
@@ -646,7 +656,7 @@
   },
   {
     "title": "Toggle",
-    "content": "The options can be specified as a list of values, or as a dictionary mapping values to labels. After manipulating the options, call update() to update the options in the UI.  :param options: a list ['value1', ...] or dictionary 'value1':'label1', ... specifying the options :param value: the initial value :param on_change: callback to execute when selection changes",
+    "content": "The options can be specified as a list of values, or as a dictionary mapping values to labels. After manipulating the options, call update() to update the options in the UI.  :param options: a list ['value1', ...] or dictionary 'value1':'label1', ... specifying the options :param value: the initial value :param on_change: callback to execute when selection changes :param clearable: whether the toggle can be cleared by clicking the selected option",
     "url": "/documentation/toggle"
   },
   {
@@ -656,7 +666,7 @@
   },
   {
     "title": "Stepper",
-    "content": "This element represents Quasar's QStepper <https://quasar.dev/vue-components/stepper#qstepper-api>_ component. It contains individual steps.  :param value: ui.step or name of the step to be initially selected (default: None meaning the first step) :param on_value_change: callback to be executed when the selected step changes on_value_change next previous",
+    "content": "This element represents Quasar's QStepper <https://quasar.dev/vue-components/stepper#qstepper-api>_ component. It contains individual steps.  To avoid issues with dynamic elements when switching steps, this element uses Vue's keep-alive <https://vuejs.org/guide/built-ins/keep-alive.html>_ component. If client-side performance is an issue, you can disable this feature.  :param value: ui.step or name of the step to be initially selected (default: None meaning the first step) :param on_value_change: callback to be executed when the selected step changes :param keep_alive: whether to use Vue's keep-alive component on the content (default: True) on_value_change next previous",
     "url": "/documentation/stepper"
   },
   {
@@ -736,7 +746,7 @@
   },
   {
     "title": "Table",
-    "content": "A table based on Quasar's QTable <https://quasar.dev/vue-components/table>_ component.  :param columns: list of column objects :param rows: list of row objects :param row_key: name of the column containing unique data identifying the row (default: \"id\") :param title: title of the table :param selection: selection type (\"single\" or \"multiple\"; default: None) :param pagination: number of rows per page (None hides the pagination, 0 means \"infinite\"; default: None) :param on_select: callback which is invoked when the selection changes  If selection is 'single' or 'multiple', then a selected property is accessible containing the selected rows. set_fullscreen Set fullscreen mode.toggle_fullscreen Toggle fullscreen mode.add_rows Add rows to the table.remove_rows Remove rows from the table.",
+    "content": "A table based on Quasar's QTable <https://quasar.dev/vue-components/table>_ component.  :param columns: list of column objects :param rows: list of row objects :param row_key: name of the column containing unique data identifying the row (default: \"id\") :param title: title of the table :param selection: selection type (\"single\" or \"multiple\"; default: None) :param pagination: A dictionary correlating to a pagination object or number of rows per page (None hides the pagination, 0 means \"infinite\"; default: None). :param on_select: callback which is invoked when the selection changes  If selection is 'single' or 'multiple', then a selected property is accessible containing the selected rows. set_fullscreen Set fullscreen mode.toggle_fullscreen Toggle fullscreen mode.add_rows Add rows to the table.remove_rows Remove rows from the table.",
     "url": "/documentation/table"
   },
   {
@@ -774,6 +784,11 @@
     "content": "You can toggle the fullscreen mode of a table using the toggle_fullscreen() method.",
     "url": "/documentation/table#toggle_fullscreen"
   },
+  {
+    "title": "Table: Pagination",
+    "content": "You can provide either a single integer or a dictionary to define pagination.  The dictionary can contain the following keys:  - rowsPerPage: The number of rows per page. - sortBy: The column name to sort by. - descending: Whether to sort in descending order. - page: The current page (1-based).",
+    "url": "/documentation/table#pagination"
+  },
   {
     "title": "Notification",
     "content": "Displays a notification on the screen.  :param message: content of the notification :param position: position on the screen (\"top-left\", \"top-right\", \"bottom-left\", \"bottom-right\", \"top\", \"bottom\", \"left\", \"right\" or \"center\", default: \"bottom\") :param close_button: optional label of a button to dismiss the notification (default: False) :param type: optional type (\"positive\", \"negative\", \"warning\", \"info\" or \"ongoing\") :param color: optional color name :param multi_line: enable multi-line notifications  Note: You can pass additional keyword arguments according to Quasar's Notify API <https://quasar.dev/quasar-plugins/notify#notify-api>_.",
@@ -791,7 +806,7 @@
   },
   {
     "title": "Storage",
-    "content": "NiceGUI offers a straightforward method for data persistence within your application. It features three built-in storage types:  - app.storage.user: Stored server-side, each dictionary is associated with a unique identifier held in a browser session cookie. Unique to each user, this storage is accessible across all their browser tabs. - app.storage.general: Also stored server-side, this dictionary provides a shared storage space accessible to all users. - app.storage.browser: Unlike the previous types, this dictionary is stored directly as the browser session cookie, shared among all browser tabs for the same user. However, app.storage.user is generally preferred due to its advantages in reducing data payload, enhancing security, and offering larger storage capacity.  The user storage and browser storage are only available within page builder functions </documentation/page>_ because they are accessing the underlying Request object from FastAPI. Additionally these two types require the storage_secret parameter inui.run() to encrypt the browser session cookie.",
+    "content": "NiceGUI offers a straightforward method for data persistence within your application. It features three built-in storage types:  - app.storage.user: Stored server-side, each dictionary is associated with a unique identifier held in a browser session cookie. Unique to each user, this storage is accessible across all their browser tabs. app.storage.browser['id'] is used to identify the user. - app.storage.general: Also stored server-side, this dictionary provides a shared storage space accessible to all users. - app.storage.browser: Unlike the previous types, this dictionary is stored directly as the browser session cookie, shared among all browser tabs for the same user. However, app.storage.user is generally preferred due to its advantages in reducing data payload, enhancing security, and offering larger storage capacity. By default, NiceGUI holds a unique identifier for the browser session in app.storage.browser['id'].  The user storage and browser storage are only available within page builder functions </documentation/page>_ because they are accessing the underlying Request object from FastAPI. Additionally these two types require the storage_secret parameter inui.run() to encrypt the browser session cookie.",
     "url": "/documentation/storage"
   },
   {
@@ -1031,7 +1046,7 @@
   },
   {
     "title": "Generic Events",
-    "content": "Most UI elements come with predefined events. For example, a ui.button like \"A\" in the demo has an on_click parameter that expects a coroutine or function. But you can also use the on method to register a generic event handler like for \"B\". This allows you to register handlers for any event that is supported by JavaScript and Quasar.  For example, you can register a handler for the mousemove event like for \"C\", even though there is no on_mousemove parameter for ui.button. Some events, like mousemove, are fired very often. To avoid performance issues, you can use the throttle parameter to only call the handler every throttle seconds (\"D\").  The generic event handler can be synchronous or asynchronous and optionally takes GenericEventArguments as argument (\"E\"). You can also specify which attributes of the JavaScript or Quasar event should be passed to the handler (\"F\"). This can reduce the amount of data that needs to be transferred between the server and the client.",
+    "content": "Most UI elements come with predefined events. For example, a ui.button like \"A\" in the demo has an on_click parameter that expects a coroutine or function. But you can also use the on method to register a generic event handler like for \"B\". This allows you to register handlers for any event that is supported by JavaScript and Quasar.  For example, you can register a handler for the mousemove event like for \"C\", even though there is no on_mousemove parameter for ui.button. Some events, like mousemove, are fired very often. To avoid performance issues, you can use the throttle parameter to only call the handler every throttle seconds (\"D\").  The generic event handler can be synchronous or asynchronous and optionally takes GenericEventArguments as argument (\"E\"). You can also specify which attributes of the JavaScript or Quasar event should be passed to the handler (\"F\"). This can reduce the amount of data that needs to be transferred between the server and the client.  Here you can find more information about the events that are supported:  - https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement#events for HTML elements - https://quasar.dev/vue-components for Quasar-based elements (see the \"Events\" tab on the individual component page)",
     "url": "/documentation/generic_events"
   },
   {