Updated README

README.md

@@ -1,5 +1,152 @@
-# Flask CRUD application  
-Example app for inventory management, built using python flask. Forked from [this project](https://github.com/MovieTone/crud-flask-export-csv).  
+# Python Flask CRUD Application  
 
-**Preview of original app:**  
-![image](https://github.com/MovieTone/crud-flask-export-csv/assets/15722914/442353d3-4064-4fc7-b796-5c40ac532338)  
+A minimal python flask app for inventory management, with some basic functionality:  
+- Fetch and display items from the MySQL db as an html table  
+- Add new items to the db (individually) using a form  
+- Edit existing (individual)items in the db using a for  
+- Delete (individual)items in the db  
+- Add a batch of new items from a csv file  
+- Edit a batch of existing items with new data from a csv file  
+- Let the user preview and edit the csv data in a table before submission  
+- Use an admin-defined configuration to decide the attributes of an item, and how to manage the db and data  
+
+## Acknowledgment  
+
+This project was originally forked from [this project](https://github.com/MovieTone/crud-flask-export-csv), although it has undergone significant improvent, and resembles nothing like it.
+
+## File structure:  
+.  
+├── app.py  
+├── config.py  
+├── definitions  
+│   ├── attribute.py  
+│   └── models.py  
+├── functions  
+│   ├── process_csv.py  
+│   ├── validate_config.py  
+│   └── validate_values.py  
+├── routes  
+│   ├── confirm_save.py  
+│   ├── create.py  
+│   ├── delete.py  
+│   ├── export_csv.py  
+│   ├── update.py  
+│   ├── upload.py  
+│   └── viewall.py  
+├── static  
+│   └── edited_csv.js  
+└── templates  
+    ├── create.html  
+    ├── csv_preview.html  
+    ├── delete.html  
+    ├── update.html  
+    ├── upload.html  
+    └── viewList.html  
+
+## Files:  
+
+**`app.py`:**  
+- The main application file.  
+- The app does not start if the configuration is invalid.  
+
+**`config.py`:**  
+Configuration of the app  
+- Mysql details  
+- The attributes of items are listed in a list, `item_attributes`  
+- The list concists of items of the class `Attribute` and its sub-classes, defined in `definitions/attribute.py`  
+
+**`definitions/attribute.py`:**  
+- Defines the type of data we use in the app
+- Classes:  
+  - `Attribute`:  
+    - Base class with basic properties.  
+	- Not used in the app directly.  
+  - `textAttribute`:  
+    - Sub-class of `Attribute` for string data.  
+	- Html input type is usually `text`.  
+  - `intAttribute`:  
+    - A type of `number`, but only accepts integers.  
+  - `floatAttribute`:  
+    - A type of `number`, but only accepts integers.  
+  - `dateAttribute`:  
+    - HTML input type `date`  
+  - `selectAttribute`:  
+    - For drop-down selection menu to choose from pre-defined options  
+- Other data types are not defined now. They may be implemented in future versions, but not now.  
+- The classes/subclass have their own `__init__` functions, as well as a `validate()` functions to validate the configuration  
+- Additional validation is done in `functions/validate_config.py`  
+
+**`definitions/models.py`:**  
+- Uses `SQLAlchemy` from `flask_sqlalchemy`  
+- Handles creation of tables and managing its data  
+- Function `create_asset_model` dynamically defines a class based on the configuration in `config.py`  
+
+**`functions/validate_config.py`:**  
+- A function validate the configure file.  
+- Returns "Ok" or some error message  
+- Most of the validation is handled by the class's own `validate()`, but some things need external validation  
+
+**`functions/validate_values.py`:**  
+- Checks for invalid values in data submitted by the user  
+- Returns None or some error messages  
+
+**`functions/process_csv.py`:**  
+- Extract data from the uploaded csv file  
+- The delimiter is '|'  
+
+**`routes/viewall.py`** & **`templates/viewList.html`:**
+- Fetch and display all items in the db  
+
+**`routes/export_csv.py`**:  
+- Download all the data as a csv file  
+
+**`routes/delete.py`** & **`templates/delete.html`:**  
+- Delete a single item.  
+- Preview the item and ask for confirmation before deletion  
+
+**`routes/create.py`** & **`templates/create.html`:**  
+- Form to insert a new item to the db  
+- Validate data on submit before insertion  
+- Display validation errors  
+
+**`routes/update.py`** & **`templates/update.html`:**  
+- Form to edit an existing item in the db  
+- Validate data on submit before updating  
+- Display validation errors  
+
+**`routes/upload.py`**, **`templates/upload.html`**, **`templates/csv_preview.html`**, **`static/edited_csv.js`:**  
+- Upload a csv file  
+- Check file format and data validity  
+- Error messages in case of invalid file or data  
+- If no errors and data is valid, proceed to redirect and preview the csv data in 2 tables:
+  - New items:  
+    - Editable table  
+	- Submit in a hidden `form` after editing  
+  - Existing items:  
+    - Non-editable table  
+	- Not submitted in the form or added to db  
+- The javascript function ensures the edited final data in the editable table is submitted instead of the original data from the file  
+- Data is submitted to `/confirm_save`  
+
+**`routes/confirm_save.py`:**  
+- Validate the submitted form data in the csv/table  
+- Insert data to db in case of successful validation  
+- Redirect to `templates/csv_preview.html` in case of validation errors.  
+- `templates/csv_preview.html` will display the error messages.  
+
+## Requires fixing  
+
+- The csv uploading code is buggy  
+
+## To be implemented  
+
+**Edit a batch of items using csv:**  
+- Same work-flow as adding new data from csv:  
+  - Upload csv  
+  - Validate  
+  - Preview existing items in an editable table  
+  - Preview non-existant items in a non-editable, non-submittable table  
+  - Submit edited table data  
+  - Validate data  
+  - Update items in db or show error messages  
+- Can be done by reusing the code for adding new data from csv