{ "cells": [ { "cell_type": "code", "execution_count": null, "id": "763b3af3", "metadata": {}, "outputs": [], "source": [ "import panel as pn\n", "import panel_material_ui as pmui\n", "\n", "pn.extension()" ] }, { "cell_type": "markdown", "id": "d035619c", "metadata": {}, "source": [ "The `LiteralInput` widget allows entering any valid Python literal (such as a number, string, list, dict, or tuple) using a text input box. This is useful for quickly entering and editing Python objects in dashboards and notebooks.\n", "\n", "You can optionally set a `type` to validate the literal before updating the parameter. The `serializer` parameter lets you choose between Python's `ast.literal_eval` (default) and JSON serialization for parsing and formatting values.\n", "\n", "#### Parameters:\n", "\n", "##### Core\n", "\n", "* **`disabled`** (boolean): Whether the widget is editable\n", "* **`enter_pressed`** (event): An event that triggers when the `` key is pressed.\n", "- **`serializer`**: The serialization method to use (`'ast'` or `'json'`).\n", "- **`type`**: The expected Python type (e.g., `dict`, `list`, `tuple`, `int`, `float`, `bool`, `str`).\n", "- **`value`**: The current value, parsed as a Python literal.\n", "- **`value_input`** (`str`): The current value as a string, updated on every key press.\n", "\n", "##### Display\n", "\n", "* **`color`** (str): The color variant of the input, which must be one of `'default'` (white), `'primary'` (blue), `'success'` (green), `'info'` (yellow), `'light'` (light), or `'danger'` (red).\n", "- **`error_state`**: Indicates if the input could not be parsed as a valid literal.\n", "* **`max_length`** (int): The maximum number of allowed characters.\n", "* **`label`** (str): The title of the widget\n", "* **`placeholder`** (str): A placeholder string displayed when no value is entered.\n", "* **`size`** (`Literal[\"small\", \"medium\"]`): The size variant of the widget.\n", "* **`variant`** (`Literal[\"filled\", \"outlined\", \"standard\"]`): The variant of the input field.\n", "\n", "##### Styling\n", "\n", "- **`sx`** (dict): Component level styling API.\n", "- **`theme_config`** (dict): Theming API.\n", "\n", "##### Aliases\n", "\n", "For compatibility with Panel certain parameters are allowed as aliases:\n", "\n", "- **`name`**: Alias for `label`\n", "\n", "For more details on customization, see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html), [layout](https://panel.holoviz.org/how_to/layout/index.html), and [styling](https://panel.holoviz.org/how_to/styling/index.html) how-to guides.\n", "\n", "___" ] }, { "cell_type": "markdown", "id": "c80d1d9a", "metadata": {}, "source": [ "### Basic Usage\n", "\n", "The `LiteralInput` widget can be used to enter any valid Python literal. For example, you can enter a number, a string, a list, a dictionary, or a tuple" ] }, { "cell_type": "code", "execution_count": null, "id": "7fcaf820", "metadata": {}, "outputs": [], "source": [ "literal_input = pmui.LiteralInput(label='Enter a literal', value={\"a\", 1})\n", "literal_input" ] }, { "cell_type": "markdown", "id": "5749bd81-d27a-4efc-a7a8-e040b7949c9c", "metadata": {}, "source": [ "`LiteralInput.value` returns a literal type that can be read out and set like other widgets:" ] }, { "cell_type": "code", "execution_count": null, "id": "5f6a01a7-27ae-43e1-ba20-99973528d7eb", "metadata": {}, "outputs": [], "source": [ "literal_input.value" ] }, { "cell_type": "markdown", "id": "35d11fb8-d30c-4894-b252-f5b64f375904", "metadata": {}, "source": [ "### Placeholder\n", "\n", "The `LiteralInput` widget supports a `placeholder` which is displayed when the `value` is `None`:" ] }, { "cell_type": "code", "execution_count": null, "id": "64792695-50f2-4fe8-8830-5d1554c01389", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='Enter a literal', value=None, placeholder='e.g. 42, [1,2,3], {\"a\": 1}')" ] }, { "cell_type": "markdown", "id": "1a323493-2a05-4394-b1d3-4b3437248ea6", "metadata": {}, "source": [ "### Value Input\n", "\n", "The `LiteralInput.value` is updated after an `enter_pressed` event or when switching focus, i.e. when clicking or tabbing away from the widget. To get the current `str` value after every keystroke you can inspect the `value_input` instead:" ] }, { "cell_type": "code", "execution_count": null, "id": "80545bbd-e3f8-49fa-9c15-8a3bc5a9a538", "metadata": {}, "outputs": [], "source": [ "literal_input = pmui.LiteralInput(label='Value', value={\"a\": 1})\n", "\n", "pmui.Column(\n", " literal_input,\n", " pmui.Row(pn.pane.Str(literal_input.param.value), pn.pane.Str(literal_input.param.value_input))\n", ")" ] }, { "cell_type": "markdown", "id": "58a013c6-369e-4dfd-8663-9329c9ab64a8", "metadata": {}, "source": [ "### Enter Pressed\n", "\n", "The `enter_pressed` parameter is triggered when the ENTER key is pressed" ] }, { "cell_type": "code", "execution_count": null, "id": "f212e3c0-9850-4a53-b1f3-d735b30f3cab", "metadata": {}, "outputs": [], "source": [ "literal_input_enter = pmui.LiteralInput(label=\"Press ENTER\", value=\"abc\")\n", "\n", "enter_count = pn.rx(0)\n", "def update_enter_count(event):\n", " enter_count.rx.value += 1\n", "pn.bind(update_enter_count, literal_input_enter.param.enter_pressed, watch=True)\n", "\n", "pmui.Column(literal_input_enter, enter_count)" ] }, { "cell_type": "markdown", "id": "8982bc57-1f27-4b59-b90c-247a42e3b1f5", "metadata": {}, "source": [ "### Maximum Length\n", "\n", "The `max_length` controls the maximum number of characters that can be entered:" ] }, { "cell_type": "code", "execution_count": null, "id": "62072533-fb2e-4388-aa53-132c0ca25562", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='Enter a literal', value={\"a\", 1}, max_length=12)" ] }, { "cell_type": "markdown", "id": "7606db5b", "metadata": {}, "source": [ "### Error State\n", "\n", "If the input cannot be parsed as a valid Python literal, the widget will indicate an error state, e.g. try entering `[]` and hit enter:" ] }, { "cell_type": "code", "execution_count": null, "id": "1e18c88c", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='Invalid input', type=dict, value={})" ] }, { "cell_type": "markdown", "id": "662f44ff-476a-425a-b5c9-9beaf69d6717", "metadata": {}, "source": [ "By changing the value to `[}` you will change the `error_state`." ] }, { "cell_type": "markdown", "id": "e02f424c-181f-4430-97ec-f85f6d5c8c8c", "metadata": {}, "source": [ "### Type and Serializer\n", "\n", "Optionally, you can specify the expected `type` and the `serializer` method (either `'ast'` for Python literals or `'json'` for JSON data). " ] }, { "cell_type": "code", "execution_count": null, "id": "5f4e8126-6e4b-4480-bbfa-bb6dabd82ef1", "metadata": {}, "outputs": [], "source": [ "ast_input = pmui.LiteralInput(label='Enter a literal', type=dict, serializer=\"ast\", value={'a': 1}, placeholder='e.g. 42, [1,2,3], {\"a\": 1}')\n", "json_input = pmui.LiteralInput(label='Enter a literal', type=dict, serializer=\"json\", value={'a': 1}, placeholder='e.g. 42, [1,2,3], {\"a\": 1}')\n", "\n", "def to_type(value):\n", " return str(type(value))\n", "\n", "pmui.Row(\n", " pmui.Column(ast_input, pn.pane.Str(ast_input.param.value)),\n", " pmui.Column(json_input, pn.pane.Str(json_input.param.value)),\n", ")" ] }, { "cell_type": "markdown", "id": "8561a540", "metadata": {}, "source": [ "### DictInput, ListInput, and TupleInput\n", "\n", "Specialized versions of `LiteralInput` are available for entering dictionaries, lists, and tuples. These widgets ensure the value is always of the expected type." ] }, { "cell_type": "code", "execution_count": null, "id": "73e2a5e7", "metadata": {}, "outputs": [], "source": [ "pmui.DictInput(label='Enter a dictionary', placeholder=\"e.g. {'a': 1, 'b': 2}\")" ] }, { "cell_type": "code", "execution_count": null, "id": "26df0ba3", "metadata": {}, "outputs": [], "source": [ "pmui.ListInput(label='Enter a list', placeholder='e.g. [1, 2, 3]')" ] }, { "cell_type": "code", "execution_count": null, "id": "08e28196", "metadata": {}, "outputs": [], "source": [ "pmui.TupleInput(label='Enter a tuple', placeholder='e.g. (1, 2, 3)')" ] }, { "cell_type": "markdown", "id": "18f379ec-be19-437c-bbbf-b29873d7186e", "metadata": {}, "source": [ "### Disabled and Loading" ] }, { "cell_type": "code", "execution_count": null, "id": "3dbb5d3f-f1d0-49fd-9719-d56acdbfc0ac", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='Enter a literal', value=42, placeholder='e.g. 42, [1,2,3], {\"a\": 1}', disabled=True, loading=True)" ] }, { "cell_type": "markdown", "id": "2f032ecc-4bde-499a-aab4-2b8be9416deb", "metadata": {}, "source": [ "### Color Options\n", "\n", "You can set the `color` parameter to visually distinguish the `LiteralInput` when active. Available options include \"default\", \"primary\", \"secondary\", \"error\", \"info\", \"success\", \"warning\", \"light\", \"dark\", and \"danger\":" ] }, { "cell_type": "code", "execution_count": null, "id": "3d2d7042-23ea-4ef7-9e58-aa78d3e24300", "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " *[pmui.LiteralInput(label=color, color=color) for color in pmui.TextInput.param.color.objects]\n", ")" ] }, { "cell_type": "markdown", "id": "a1a9e59d-675a-4916-bcaa-c37c75f703c5", "metadata": {}, "source": [ "### Size\n", "\n", "The `size` parameter allows toggling between \"small\", \"medium\" (default) and \"large\" sized input fields:" ] }, { "cell_type": "code", "execution_count": null, "id": "dd66f0d1-866d-4c7d-bed7-589c8cb90287", "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " pmui.LiteralInput(label='Small', size=\"small\"),\n", " pmui.LiteralInput(label='Medium', size=\"medium\"),\n", ")" ] }, { "cell_type": "markdown", "id": "b62c479d-2ffa-4f6d-b420-fe1aa025cbea", "metadata": {}, "source": [ "### Variant\n", "\n", "The `variant` parameter controls the visual style of the input. Choose from \"filled\", \"outlined\" (default), or \"standard\":" ] }, { "cell_type": "code", "execution_count": null, "id": "6254c2b1-e76c-4145-a5cb-aee7d9ae6429", "metadata": {}, "outputs": [], "source": [ "pmui.FlexBox(\n", " pmui.LiteralInput(label='Filled', variant=\"filled\"),\n", " pmui.LiteralInput(label='Outlined', variant=\"outlined\"),\n", " pmui.LiteralInput(label='Standard', variant=\"standard\"),\n", ")" ] }, { "cell_type": "markdown", "id": "b384244d-66e0-4198-bfd2-e7c1d252a2e5", "metadata": {}, "source": [ "### Description Tooltip" ] }, { "cell_type": "code", "execution_count": null, "id": "33bc2954-19af-4507-9011-bb0f2838fe0a", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='Enter a literal', value=42, description=\"A tooltip shown when hovering\")" ] }, { "cell_type": "markdown", "id": "c9170b5f", "metadata": {}, "source": [ "### API Reference\n", "\n", "#### Parameters\n", "\n", "The `LiteralInput` exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:" ] }, { "cell_type": "code", "execution_count": null, "id": "2bf4cb5f", "metadata": {}, "outputs": [], "source": [ "pmui.LiteralInput(label='LiteralInput').api(jslink=True)" ] }, { "cell_type": "markdown", "id": "cd6937e0", "metadata": {}, "source": [ "### References\n", "\n", "**Panel Documentation:**\n", "\n", "- [How-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html)\n", "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html)\n", "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html)\n", "\n", "**Material UI TextField:**\n", "\n", "- [Material UI TextField Reference](https://mui.com/material-ui/react-text-field)\n", "- [Material UI TextField API](https://mui.com/material-ui/api/text-field/)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.2" } }, "nbformat": 4, "nbformat_minor": 5 }