# Cardboard
---
A simple data dashboard for use in Flask apps. Each card on the board manages its own WebSocket connection to the server to be abe to handle multiple high bandwidth data sources such as audio or high frequency sensor data which could otherwise saturate a single multiplexed Flask SocketIO connection.
While this project was intended for use on localhost, it should be able to be deployed to the web as well, though we haven't needed to try this yet. This library is being created for a very specific use case in a private project, but perhaps someone out there will find it useful too.
## Prerequisites
- Python 3.7+
- Npm 10.8+
- GNU Make 3.8+
## Development
### Project Initialization
After cloning the repository, install backend and frontend dependencies. The make init target will install both backend and frontend dependencies.
#### Install Dependencies
```
make init
```
Alternatively, you can separately install the backend dependencies with pip and the frontend dependencies with npm.
#### Install Backend Dependencies with Pip
From the project root run pip install:
```
pip install -r requirements.txt
```
#### Install Frontend Dependencies with npm
From the cardboard_ui directory, run npm install:
```
cd cardboard_ui
npm install
```
### Start the Development Servers
For development, the Flask development server can be used to automatically reload when backend Python file changes are detected. The Vite development server can be used to automatically reload when front-end Javascript or CSS files change. The Flask server runs on http://127.0.0.1:5000. The Vite server runs on http://127.0.0.1:5173. When running the development servers, access the app from a webbrowser using the Vite server at http://127.0.0.1:5173.
1. Start the Flask development server:
```
make start_flask
```
2. Start the Vite development server:
```
make start_vite
```
### Start the WSGI Production Server
For production, Gunicorn is used to run the WSGI app on http://127.0.0.1:5000. The Vite server is not used. The front-end resources must be compiled and packaged and will be served by the production server.
1. Start the Gunicorn WSGI server:
```
make start_wsgi
```
## Installation of Published Packages
This section describes how to install the cardboard packages for development and production. This assumes cardboard is being integrated into a Python Flask application with a front-end built using Vite with the React plugin.
In this context, we assume the basic directory structures:
```
project-root/
.venv/
flask-dir/
app.py
ui-dir/
node_modules/
src/
main.jsx
index.css
vite.config.js
package.json
```
### Install Production Packages
### Backend
```
cd <project-root>
pip install cardboard
```
```
cd <ui-dir>
npm install cardboard-ui
```
### Installing from Local Dev Projects
This assums you've cloned the Cardboard git repository to `cardboard-project-root`.
#### Backend
```
pip install <cardboard-project-root>/dist/cardboard-<version>-py3-none-any.whl
```
#### Frontend
```
cd <cardboard-project-root>/cardboard_ui
npm link
```
```
cd <project-root>/<ui-dir>
npm link cardboard-ui
```
### Installing from TestPyPi
Use this command to install from the TestPyPi registry instead of the proeuction PyPi registry.
```
pip install -i https://test.pypi.org/simple/ cardboard
```
## Usage
1. Create an configure the Flask app for either developmet or production mode.
2. Load the Vite manifest
3. Import the cardboard blueprint into the Flask app.
4. Register the blueprint.
5. Load a json board configuration file.
6. Add the cardboard javascript and css assets to the Flask index.html template
7. Add a \<div> with the id 'root' to the \<body> of index.html.
8. Render the Board component into the root div in main.jsx.
### app.py
```python
"""
Example Flask cardboard server
"""
from flask import Flask, render_template, send_from_directory, jsonify, request
from cardboard import cardboard, blueprints
import os
import json
# Load environment variables
FLASK_ENV = os.environ.get("FLASK_ENV", default="production")
VITE_MANIFEST = os.environ.get("VITE_MANIFEST", default="./test_ui/dist/.vite/manifest.json")
# If development, serve static resources from the ui src, otherwise serve from ui dist
if FLASK_ENV == "development":
app = Flask(__name__, template_folder="templates", static_folder="../test_ui/src")
else:
app = Flask(__name__, template_folder="templates", static_folder="../test_ui/dist")
# Load the Vite manifest
manifest_file = "./test_ui/dist/.vite/manifest.json"
with open(manifest_file, "r") as f:
manifest = json.load(f)
# Register cardboard blueprint routes
app.register_blueprint(blueprints.cardboard_blueprint)
@app.route("/")
def index():
"""
Serve the index.html template, pass it the development mode and the server url
:return: rendered index.html template
"""
development = FLASK_ENV == "development"
cardboard_server="http://127.0.0.1:5000"
return render_template("index.html", development=development, cardboard_server=cardboard_server)
@app.route('/src/<path:file>')
def serve_src(file):
"""
Serve the Vite .jsx or .css assets defined in the Vite manifest.
This will be used only in production mode. In development, the assets get served by the Vite dev server.
:param file:
:return:
"""
global manifest
path = request.path
if path.startswith("/"):
path = path[1:]
if path.endswith(".css"):
key = path.replace(".css", ".jsx")
if key not in manifest:
return jsonify({"Error": f"Manifest entry not found: {key}"}), 404
if 'css' not in manifest[key]:
return jsonify({"Error": f"No css for manifest entry {key}"}), 404
css = manifest[key]['css']
if len(css) == 0:
return jsonify({"Error": f"CSS list for manifest entry {key} is empty"}), 404
f = css[0]
else:
if path not in manifest:
return jsonify({"Error": f"File not found: {path}"}), 404
f = manifest[f'{path}']['file']
return send_from_directory(app.static_folder, f)
if __name__ == "__main__":
print(f"Hello cardboard")
with open("./cards.json") as f:
board_json = json.load(f)
cardboard.configure_board(data=board_json)
app.run(host="127.0.0.1", port=5000, debug=True)
```
### index.html
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Hello, Cardboard</title>
</head>
<body style="width: 100vw; height: 100vh;">
<!-- React container, Cardboard components well be rendered here -->
<div id="root" style="width: 100%; height: 100%;"></div>
<!-- Load the template data passed from the Flask server -->
<script>
const cardboard_server = "{{cardboard_server}}"
const development = "{{development}}"
console.log("cardboard_server=" + cardboard_server)
console.log("development=" + development)
</script>
<!-- Refer to Vite Backend Integration documentation: -->
<!-- https://vite.dev/guide/backend-integration.html -->
{% if development %}
<!-- If development mode, setup proxying to the Vite dev server. -->
<!-- Make sure the Vite dev server is running on port 5173 -->
<script type="module">
console.log("DEV MODE!")
import RefreshRuntime from 'http://localhost:5173/@react-refresh'
RefreshRuntime.injectIntoGlobalHook(window)
window.$RefreshReg$ = () => {}
window.$RefreshSig$ = () => (type) => type
window.__vite_plugin_react_preamble_installed__ = true
</script>
<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/src/main.jsx"></script>
{% else %}
<!-- If production mode, we serve the compiled assets from the flask server -->
<!-- Vite dev server does not need to be running -->
<script type="module" crossorigin src="/src/main.jsx"></script>
<link rel="stylesheet" crossorigin href="/src/main.css">
{% endif %}
</body>
</html>
```
### main.jsx
```jsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { Board } from 'cardboard-ui'
import 'cardboard-ui/dist/style.css'
// Get the root div by Id and render the cardboard React component into it.
// Pass the cardboard_server template parameter (from the Flask server) to the Board component.
createRoot(document.getElementById('root')).render(
<StrictMode>
<div className="flex flex-col">
<Board cardboard_server={cardboard_server} />
</div>
</StrictMode>,
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jasnkwan/cardboard",
"name": "cardboard-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Jason Kwan",
"author_email": "Jason Kwan <jasnkwan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/39/09be0e6989d9adb14c5e8fb511323b29caff81b0d70c413bd20d8035111b/cardboard_server-0.1.1.tar.gz",
"platform": null,
"description": "# Cardboard\n\n\n\n---\nA simple data dashboard for use in Flask apps. Each card on the board manages its own WebSocket connection to the server to be abe to handle multiple high bandwidth data sources such as audio or high frequency sensor data which could otherwise saturate a single multiplexed Flask SocketIO connection.\n\nWhile this project was intended for use on localhost, it should be able to be deployed to the web as well, though we haven't needed to try this yet. This library is being created for a very specific use case in a private project, but perhaps someone out there will find it useful too.\n\n\n## Prerequisites\n- Python 3.7+\n- Npm 10.8+\n- GNU Make 3.8+\n\n\n## Development\n\n### Project Initialization\nAfter cloning the repository, install backend and frontend dependencies. The make init target will install both backend and frontend dependencies.\n\n#### Install Dependencies\n```\nmake init\n```\n\nAlternatively, you can separately install the backend dependencies with pip and the frontend dependencies with npm.\n\n#### Install Backend Dependencies with Pip\nFrom the project root run pip install:\n```\npip install -r requirements.txt\n```\n\n#### Install Frontend Dependencies with npm\nFrom the cardboard_ui directory, run npm install:\n```\ncd cardboard_ui\nnpm install\n```\n\n\n### Start the Development Servers\nFor development, the Flask development server can be used to automatically reload when backend Python file changes are detected. The Vite development server can be used to automatically reload when front-end Javascript or CSS files change. The Flask server runs on http://127.0.0.1:5000. The Vite server runs on http://127.0.0.1:5173. When running the development servers, access the app from a webbrowser using the Vite server at http://127.0.0.1:5173.\n\n1. Start the Flask development server:\n\n```\nmake start_flask\n```\n\n2. Start the Vite development server:\n\n```\nmake start_vite\n```\n\n### Start the WSGI Production Server\nFor production, Gunicorn is used to run the WSGI app on http://127.0.0.1:5000. The Vite server is not used. The front-end resources must be compiled and packaged and will be served by the production server.\n\n1. Start the Gunicorn WSGI server:\n\n```\nmake start_wsgi\n```\n\n\n## Installation of Published Packages\n\nThis section describes how to install the cardboard packages for development and production. This assumes cardboard is being integrated into a Python Flask application with a front-end built using Vite with the React plugin.\nIn this context, we assume the basic directory structures:\n```\nproject-root/\n .venv/\n flask-dir/ \n app.py\n ui-dir/ \n node_modules/ \n src/ \n main.jsx\n index.css\n vite.config.js\n package.json \n```\n\n\n### Install Production Packages\n### Backend\n```\ncd <project-root>\npip install cardboard\n```\n```\ncd <ui-dir>\nnpm install cardboard-ui\n```\n\n### Installing from Local Dev Projects\nThis assums you've cloned the Cardboard git repository to `cardboard-project-root`.\n#### Backend\n```\npip install <cardboard-project-root>/dist/cardboard-<version>-py3-none-any.whl\n```\n#### Frontend\n```\ncd <cardboard-project-root>/cardboard_ui\nnpm link\n```\n```\ncd <project-root>/<ui-dir>\nnpm link cardboard-ui\n```\n\n### Installing from TestPyPi\nUse this command to install from the TestPyPi registry instead of the proeuction PyPi registry.\n```\npip install -i https://test.pypi.org/simple/ cardboard\n```\n\n## Usage\n\n1. Create an configure the Flask app for either developmet or production mode.\n2. Load the Vite manifest\n3. Import the cardboard blueprint into the Flask app.\n4. Register the blueprint.\n5. Load a json board configuration file.\n6. Add the cardboard javascript and css assets to the Flask index.html template\n7. Add a \\<div> with the id 'root' to the \\<body> of index.html.\n8. Render the Board component into the root div in main.jsx.\n\n### app.py\n```python\n\"\"\"\nExample Flask cardboard server\n\"\"\"\nfrom flask import Flask, render_template, send_from_directory, jsonify, request\nfrom cardboard import cardboard, blueprints\nimport os\nimport json\n\n# Load environment variables\nFLASK_ENV = os.environ.get(\"FLASK_ENV\", default=\"production\")\nVITE_MANIFEST = os.environ.get(\"VITE_MANIFEST\", default=\"./test_ui/dist/.vite/manifest.json\")\n\n# If development, serve static resources from the ui src, otherwise serve from ui dist\nif FLASK_ENV == \"development\":\n app = Flask(__name__, template_folder=\"templates\", static_folder=\"../test_ui/src\")\nelse:\n app = Flask(__name__, template_folder=\"templates\", static_folder=\"../test_ui/dist\")\n\n# Load the Vite manifest\nmanifest_file = \"./test_ui/dist/.vite/manifest.json\"\nwith open(manifest_file, \"r\") as f:\n manifest = json.load(f)\n\n# Register cardboard blueprint routes\napp.register_blueprint(blueprints.cardboard_blueprint)\n\n\n@app.route(\"/\")\ndef index():\n \"\"\"\n Serve the index.html template, pass it the development mode and the server url\n :return: rendered index.html template\n \"\"\"\n development = FLASK_ENV == \"development\"\n cardboard_server=\"http://127.0.0.1:5000\"\n return render_template(\"index.html\", development=development, cardboard_server=cardboard_server)\n\n\n@app.route('/src/<path:file>')\ndef serve_src(file):\n \"\"\"\n Serve the Vite .jsx or .css assets defined in the Vite manifest.\n This will be used only in production mode. In development, the assets get served by the Vite dev server.\n :param file:\n :return:\n \"\"\"\n global manifest\n path = request.path\n if path.startswith(\"/\"):\n path = path[1:]\n\n if path.endswith(\".css\"):\n key = path.replace(\".css\", \".jsx\")\n if key not in manifest:\n return jsonify({\"Error\": f\"Manifest entry not found: {key}\"}), 404\n if 'css' not in manifest[key]:\n return jsonify({\"Error\": f\"No css for manifest entry {key}\"}), 404\n css = manifest[key]['css']\n if len(css) == 0:\n return jsonify({\"Error\": f\"CSS list for manifest entry {key} is empty\"}), 404\n f = css[0]\n else:\n if path not in manifest:\n return jsonify({\"Error\": f\"File not found: {path}\"}), 404\n f = manifest[f'{path}']['file']\n return send_from_directory(app.static_folder, f)\n\n\nif __name__ == \"__main__\":\n print(f\"Hello cardboard\")\n\n with open(\"./cards.json\") as f:\n board_json = json.load(f)\n cardboard.configure_board(data=board_json)\n\n app.run(host=\"127.0.0.1\", port=5000, debug=True)\n\n```\n\n### index.html\n```html\n<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\" />\n <link rel=\"icon\" type=\"image/svg+xml\" href=\"/vite.svg\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>Hello, Cardboard</title>\n </head>\n\n <body style=\"width: 100vw; height: 100vh;\">\n\n <!-- React container, Cardboard components well be rendered here -->\n <div id=\"root\" style=\"width: 100%; height: 100%;\"></div>\n\n <!-- Load the template data passed from the Flask server -->\n <script>\n const cardboard_server = \"{{cardboard_server}}\"\n const development = \"{{development}}\"\n console.log(\"cardboard_server=\" + cardboard_server)\n console.log(\"development=\" + development)\n </script>\n\n <!-- Refer to Vite Backend Integration documentation: -->\n <!-- https://vite.dev/guide/backend-integration.html -->\n\n {% if development %}\n\n <!-- If development mode, setup proxying to the Vite dev server. -->\n <!-- Make sure the Vite dev server is running on port 5173 -->\n <script type=\"module\">\n console.log(\"DEV MODE!\")\n import RefreshRuntime from 'http://localhost:5173/@react-refresh'\n RefreshRuntime.injectIntoGlobalHook(window)\n window.$RefreshReg$ = () => {}\n window.$RefreshSig$ = () => (type) => type\n window.__vite_plugin_react_preamble_installed__ = true\n </script>\n <script type=\"module\" src=\"http://localhost:5173/@vite/client\"></script>\n <script type=\"module\" src=\"http://localhost:5173/src/main.jsx\"></script>\n\n {% else %}\n\n <!-- If production mode, we serve the compiled assets from the flask server -->\n <!-- Vite dev server does not need to be running -->\n <script type=\"module\" crossorigin src=\"/src/main.jsx\"></script>\n <link rel=\"stylesheet\" crossorigin href=\"/src/main.css\">\n\n {% endif %}\n </body>\n</html>\n```\n\n### main.jsx\n```jsx\nimport { StrictMode } from 'react'\nimport { createRoot } from 'react-dom/client'\nimport { Board } from 'cardboard-ui'\nimport 'cardboard-ui/dist/style.css'\n\n// Get the root div by Id and render the cardboard React component into it.\n// Pass the cardboard_server template parameter (from the Flask server) to the Board component.\ncreateRoot(document.getElementById('root')).render(\n <StrictMode>\n <div className=\"flex flex-col\">\n <Board cardboard_server={cardboard_server} />\n </div>\n </StrictMode>,\n)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A Flask server for React data dashboards",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/jasnkwan/cardboard",
"Repository": "https://github.com/jasnkwan/cardboard.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d021e7788fda2890716c74f7c5e5e457b721f87cf1c6bb088ad3176755c49ac",
"md5": "2704c465b741fbe7092a03d584f98897",
"sha256": "925aebda5a38e93a59bf07c9ca261165100b33dc7414daeb8a0394d5b4ebeafe"
},
"downloads": -1,
"filename": "cardboard_server-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2704c465b741fbe7092a03d584f98897",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12119,
"upload_time": "2024-10-20T23:41:28",
"upload_time_iso_8601": "2024-10-20T23:41:28.304133Z",
"url": "https://files.pythonhosted.org/packages/3d/02/1e7788fda2890716c74f7c5e5e457b721f87cf1c6bb088ad3176755c49ac/cardboard_server-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "943909be0e6989d9adb14c5e8fb511323b29caff81b0d70c413bd20d8035111b",
"md5": "827b8429a50f9ff82d97b0800852e1d5",
"sha256": "1c07dd35d863131d0d60be24825e5a70404504f2e2753947be9dab9384ff1064"
},
"downloads": -1,
"filename": "cardboard_server-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "827b8429a50f9ff82d97b0800852e1d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14630,
"upload_time": "2024-10-20T23:41:29",
"upload_time_iso_8601": "2024-10-20T23:41:29.814802Z",
"url": "https://files.pythonhosted.org/packages/94/39/09be0e6989d9adb14c5e8fb511323b29caff81b0d70c413bd20d8035111b/cardboard_server-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 23:41:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jasnkwan",
"github_project": "cardboard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cardboard-server"
}
JSON
