# st-flexible-callout-elements
![example](https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/example.png)
[Live Demo](https://flexible-callout-elements.streamlit.app)
## About
A package for flexible, customizable callout status elements in Streamlit.
## Installation
```bash
pip install st-flexible-callout-elements
```
## Usage
`flexible_callout()` is the main function of the package and can handle several arguments responsible for customization.
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout(message, container=st, background_color="#D9D9D9", font_color="#000000", font_size=16, alignment="left", line_height=1.5, border_radius=8, padding=15, margin_bottom=20)
Arguments:
- message (str): The message to display.
- container: The Streamlit container to render the message in (default is st).
- background_color (str): The background color of the message box.
- font_color (str): The font color of the message text.
- font_size (int): The font size of the message text in pixels.
- alignment (str): The text alignment inside the message box ("left", "center", "right", "justify").
- line_height (float): The line height of the message text.
- border_radius (int): The border radius of the message box.
- padding (int): The padding inside the message box in pixels.
- margin_bottom (int): The margin below the message box in pixels.
```
Calling the function with just a message and no other arguments, e.g.:
``` python
flexible_callout("This is the standard flexible callout.")
```
Will result in:
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/standard.png">
</p>
<br>
The package contains four other functions `flexible_error()`, `flexible_success()`, `flexible_warning()`, and `flexible_info()` emulating the style of `st.error`, `st.success`, `st.warning`, and `st.info`, respectively. They have most of the same arguments as `flexible_callout()` with the exception of `background_color` and `font_color` which are fixed to match their counterparts.
``` python
from st_flexible_callout_elements import flexible_error, flexible_success, flexible_warning, flexible_info
flexible_error("This is a slightly larger error message.", font_size=20)
flexible_success("This is a centered success message", alignment="center")
flexible_warning("This is right aligned a warning message <b><u>with html elements</b></u>", alignment="right")
flexible_info("This is a slightly smaller info message", font_size=10)
```
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/emulate.png">
</p>
<br>
### Customization
#### Container
The `container` argument will define the where your callout element will be displayed. The default is the main container (by using `st`). It can be altered to move the element to the sidebar:
```python
from st_flexible_callout_elements import flexible_info
flexible_info("Can be used in the sidebar.", container=st.sidebar)
```
You can also specify other containers such as specific columns:
```python
from st_flexible_callout_elements import flexible_info
col1, col2 = st.columns(2)
flexible_info("Can be used in a column of choice.", container=col2)
```
**Note:** These arguments are **not text elements**, it should directly reference the container!
<br>
#### Background and font color.
The box background and font colors can be customized with `background_color` and `font_color` respectively. Accepted values include HEX color codes and [HTML color names](https://www.w3schools.com/tags/ref_colornames.asp).
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout("You can use custom colors!", background_color="#E0B0FF", font_color="#301934")
```
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/custom_colors.png">
</p>
<br>
#### Font size and alignment
As seen previously, font size (in px) can be changed with the argument `font_size`. Text alignment inside the box can be changed with `alignment`, its options are `left` (default), `center`, `right`, and `justify`.
#### Line height
Line spacing can be changed with the `line_height` argument.
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout("Line height can also be customized within the element", container=st.sidebar, background_color="#FFD1C1", font_color="#CC5733", line_height=2)
```
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/line_height.png">
</p>
<br>
#### Border radius, padding, margin-bottom
The borders of the box can be made rounder or less round by adjusting `border_radius` (default is 8).
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout("Can have rounded boxes.", container=st.sidebar, background_color="#FFCCF2", font_color="#CC3385", border_radius=25)
```
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/rounded.png">
</p>
<br>
The distinction between padding and margin can be see in the box element model below:
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/css_box_elements.png">
</p>
The distance between the content and the border can be changed using the `padding` parameter (default is 15):
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout("The boxes can be slimmer", padding=5)
```
The distance between the box and the next element can be customized using the `margin_bottom` argument (default value is 20):
```python
from st_flexible_callout_elements import flexible_callout
flexible_callout("The boxes can be slimmer", margin_bottom=30)
```
#### Integration with other streamlit elements
The flexible callout elements can be integrated with other streamlit functions:
```python
from st_flexible_callout_elements import flexible_callout
@st.fragment
def display_rainbow_text():
colors = [
{"text": "You", "bg_color": "#D8A0D8", "font_color": "#6A0D91"},
{"text": "can", "bg_color": "#C2C2F0", "font_color": "#4B0082"},
{"text": "also", "bg_color": "#99CCFF", "font_color": "#0033CC"},
{"text": "do", "bg_color": "#B3FFB3", "font_color": "#009900"},
{"text": "some", "bg_color": "#FFFF99", "font_color": "#CCCC00"},
{"text": "fun", "bg_color": "#FFCC99", "font_color": "#CC6600"},
{"text": "stuff", "bg_color": "#FFB3B3", "font_color": "#B30000"}
]
with st.container():
cols = st.columns(len(colors))
for col, color in zip(cols, colors):
with col:
flexible_callout(
color["text"],
background_color=color["bg_color"],
font_color=color["font_color"],
font_size=18,
alignment="center",
padding=5
)
sleep(0.5)
display_rainbow_text()
```
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/fun_stuff.gif">
</p>
<br>
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/st-flexible-status-elements",
"name": "st-flexible-callout-elements",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Your Name",
"author_email": "your.email@example.com",
"download_url": null,
"platform": null,
"description": "# st-flexible-callout-elements\n\n![example](https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/example.png)\n[Live Demo](https://flexible-callout-elements.streamlit.app)\n\n## About\nA package for flexible, customizable callout status elements in Streamlit.\n\n## Installation\n```bash\npip install st-flexible-callout-elements\n```\n\n## Usage\n`flexible_callout()` is the main function of the package and can handle several arguments responsible for customization.\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(message, container=st, background_color=\"#D9D9D9\", font_color=\"#000000\", font_size=16, alignment=\"left\", line_height=1.5, border_radius=8, padding=15, margin_bottom=20)\n\nArguments:\n- message (str): The message to display.\n- container: The Streamlit container to render the message in (default is st).\n- background_color (str): The background color of the message box.\n- font_color (str): The font color of the message text.\n- font_size (int): The font size of the message text in pixels.\n- alignment (str): The text alignment inside the message box (\"left\", \"center\", \"right\", \"justify\").\n- line_height (float): The line height of the message text.\n- border_radius (int): The border radius of the message box.\n- padding (int): The padding inside the message box in pixels.\n- margin_bottom (int): The margin below the message box in pixels.\n```\n\nCalling the function with just a message and no other arguments, e.g.:\n\n``` python\nflexible_callout(\"This is the standard flexible callout.\")\n```\n\nWill result in:\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/standard.png\"> \n </p>\n<br>\nThe package contains four other functions `flexible_error()`, `flexible_success()`, `flexible_warning()`, and `flexible_info()` emulating the style of `st.error`, `st.success`, `st.warning`, and `st.info`, respectively. They have most of the same arguments as `flexible_callout()` with the exception of `background_color` and `font_color` which are fixed to match their counterparts.\n\n``` python\nfrom st_flexible_callout_elements import flexible_error, flexible_success, flexible_warning, flexible_info\n\nflexible_error(\"This is a slightly larger error message.\", font_size=20)\n\nflexible_success(\"This is a centered success message\", alignment=\"center\")\n\nflexible_warning(\"This is right aligned a warning message <b><u>with html elements</b></u>\", alignment=\"right\")\n\nflexible_info(\"This is a slightly smaller info message\", font_size=10)\n```\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/emulate.png\"> \n </p>\n<br>\n\n### Customization\n\n#### Container\n\nThe `container` argument will define the where your callout element will be displayed. The default is the main container (by using `st`). It can be altered to move the element to the sidebar:\n\n```python\nfrom st_flexible_callout_elements import flexible_info\n\nflexible_info(\"Can be used in the sidebar.\", container=st.sidebar)\n```\n\nYou can also specify other containers such as specific columns:\n\n```python\nfrom st_flexible_callout_elements import flexible_info\n\ncol1, col2 = st.columns(2)\n\nflexible_info(\"Can be used in a column of choice.\", container=col2)\n```\n**Note:** These arguments are **not text elements**, it should directly reference the container!\n<br>\n\n#### Background and font color.\nThe box background and font colors can be customized with `background_color` and `font_color` respectively. Accepted values include HEX color codes and [HTML color names](https://www.w3schools.com/tags/ref_colornames.asp).\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(\"You can use custom colors!\", background_color=\"#E0B0FF\", font_color=\"#301934\")\n```\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/custom_colors.png\"> \n </p>\n<br>\n\n#### Font size and alignment\nAs seen previously, font size (in px) can be changed with the argument `font_size`. Text alignment inside the box can be changed with `alignment`, its options are `left` (default), `center`, `right`, and `justify`.\n\n#### Line height\n\nLine spacing can be changed with the `line_height` argument.\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(\"Line height can also be customized within the element\", container=st.sidebar, background_color=\"#FFD1C1\", font_color=\"#CC5733\", line_height=2)\n```\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/line_height.png\"> \n </p>\n<br>\n\n#### Border radius, padding, margin-bottom\n\nThe borders of the box can be made rounder or less round by adjusting `border_radius` (default is 8).\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(\"Can have rounded boxes.\", container=st.sidebar, background_color=\"#FFCCF2\", font_color=\"#CC3385\", border_radius=25)\n```\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/rounded.png\"> \n </p>\n<br>\n\nThe distinction between padding and margin can be see in the box element model below:\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/css_box_elements.png\"> \n </p>\n\nThe distance between the content and the border can be changed using the `padding` parameter (default is 15):\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(\"The boxes can be slimmer\", padding=5)\n```\n\nThe distance between the box and the next element can be customized using the `margin_bottom` argument (default value is 20):\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\nflexible_callout(\"The boxes can be slimmer\", margin_bottom=30)\n```\n\n#### Integration with other streamlit elements\n\nThe flexible callout elements can be integrated with other streamlit functions:\n\n```python\nfrom st_flexible_callout_elements import flexible_callout\n\n@st.fragment\ndef display_rainbow_text():\n colors = [\n {\"text\": \"You\", \"bg_color\": \"#D8A0D8\", \"font_color\": \"#6A0D91\"},\n {\"text\": \"can\", \"bg_color\": \"#C2C2F0\", \"font_color\": \"#4B0082\"},\n {\"text\": \"also\", \"bg_color\": \"#99CCFF\", \"font_color\": \"#0033CC\"},\n {\"text\": \"do\", \"bg_color\": \"#B3FFB3\", \"font_color\": \"#009900\"},\n {\"text\": \"some\", \"bg_color\": \"#FFFF99\", \"font_color\": \"#CCCC00\"},\n {\"text\": \"fun\", \"bg_color\": \"#FFCC99\", \"font_color\": \"#CC6600\"},\n {\"text\": \"stuff\", \"bg_color\": \"#FFB3B3\", \"font_color\": \"#B30000\"}\n ]\n\n with st.container():\n cols = st.columns(len(colors))\n for col, color in zip(cols, colors):\n with col:\n flexible_callout(\n color[\"text\"],\n background_color=color[\"bg_color\"],\n font_color=color[\"font_color\"],\n font_size=18,\n alignment=\"center\",\n padding=5\n )\n sleep(0.5)\n\ndisplay_rainbow_text()\n```\n\n<p align=\"center\" width=\"100%\">\n <img src=\"https://raw.githubusercontent.com/jlnetosci/st-flexible-callout-elements/main/img/fun_stuff.gif\"> \n </p>\n<br>\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Streamlit package for flexible, customizable status elements",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/st-flexible-status-elements"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "333511bc95234ab6e526ccf3c6c756dcdd62e0e1d5102db305196511bd983900",
"md5": "7aaaee97c780450c3ef638a9db82e1ac",
"sha256": "49e72081cee0e0ed277cfcd56f6beaf09782dc873c5296c59bb8e192f82dea42"
},
"downloads": -1,
"filename": "st_flexible_callout_elements-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7aaaee97c780450c3ef638a9db82e1ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5665,
"upload_time": "2024-09-03T19:49:23",
"upload_time_iso_8601": "2024-09-03T19:49:23.450277Z",
"url": "https://files.pythonhosted.org/packages/33/35/11bc95234ab6e526ccf3c6c756dcdd62e0e1d5102db305196511bd983900/st_flexible_callout_elements-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-03 19:49:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "st-flexible-status-elements",
"github_not_found": true,
"lcname": "st-flexible-callout-elements"
}