Entity XML CRUD Application

A modern GTK3 desktop application for managing entity-based data with XML storage. This application provides a user-friendly interface for performing CRUD (Create, Read, Update, Delete) operations on entities defined in an XML configuration file, following the Lua ArtNazarov/luassg site generator XML format.

🌟 New Feature: Configuration Menu with XML Tree Editor Integration

XML Tree Editor Integration

The application now includes a Configuration menu that allows you to directly edit XML configuration files using an integrated XML tree editor:

Added Features:

• Configuration Menu: Main menu with "Configuration" dropdown
• Direct XML Editing: Two menu items for editing common configuration files:
  • Open ./data/CONST.xml: Edit the CONST.xml configuration file
  • Open ./data/pagination.xml: Edit the pagination.xml configuration file
• Integrated Editor: Launches
  dialog_xml_tree_editor.py
  as a standalone process
• Automatic File Creation: Missing XML files are automatically created if they don't exist

How It Works:

1. Click Configuration in the main menu bar
2. Select either "Open ./data/CONST.xml" or "Open ./data/pagination.xml"
3. The application automatically:
   • Checks if the XML file exists (creates it if missing)
   • Verifies the XML tree editor script is available
   • Launches the editor in a new process with the selected file
4. Edit the XML file in a dedicated tree-based editor interface
5. Changes are saved back to the original file

Technical Details:

• Process Isolation: XML editor runs as a separate process, keeping the main app responsive
• File Validation: Ensures XML files follow proper structure before editing
• Path Resolution: Automatically finds the editor script in the same directory as app.py
• Error Handling: Comprehensive error messages if files or editor are missing

Benefits:

• 🔧 Direct Configuration Editing: Edit XML configs without leaving the application
• 🌳 Visual XML Editing: Use a tree-based editor for complex XML structures
• 🔄 Live Updates: Changes made in the editor are immediately saved
• ⚡ Non-blocking: Main application remains responsive while editing

Screenshots

Video

Watch video

✨ Features

• Multi-Entity Management: Automatically creates tabs for each entity defined in XML
• CRUD Operations: Full Create, Read, Update, Delete functionality for records
• Dynamic Entity Definition: Define custom entities with configurable fields
• Field Type Support: Two field types supported:
  oneline
  (single-line text) and
  multiline
  (multi-line text area)
• Entity Management: Create, edit, and delete entities with automatic file system updates
• luassg XML Format: Compatible with ArtNazarov/luassg XML structure
• Persistent XML Storage: All data stored in structured XML files
• Clean Architecture: Clear separation between data loading and UI rendering
• Comprehensive Testing: 11 tests with full coverage using pytest
• Configuration Menu: Integrated XML tree editor for editing configuration files

📁 File Structure

./
├── app.py                      # Main application
├── tests.py                    # Pytest test suite (11 tests)
├── dialog_xml_tree_editor.py   # XML tree editor for configuration files
├── entities_description.xml    # Entity definitions
├── README.md                   # This file
└── data/                       # Data storage directory
    ├── CONST.xml               # Configuration file (editable via menu)
    ├── pagination.xml          # Configuration file (editable via menu)
    ├── posts/                  # Example entity directory
    │   ├── posts-[uuid].xml    # Entity files follow: entity-entityId.xml format
    │   └── ...
    ├── news/
    ├── quotes/
    └── gallery/
        └── gallery-37158403-3cfe-4922-92e2-46326f0eb571.xml  # Example file

🚀 Quick Start

1. Clone and install

2. Run tests

🛠️ Requirements

Arch Linux

Ubuntu/Debian

Fedora

Using pip

🏗️ Architecture

The application follows a clean architecture with clear separation of concerns:

Data Layer

• load_xml_data()
  : Loads all data from XML files into memory
• save_entities_to_xml()
  : Saves entity definitions to XML
• In-memory data structure with entities, fields, and records

Presentation Layer

• render_xml_data_state()
  : Clears UI and renders tabs based on in-memory data
• create_entity_tab()
  : Creates individual entity tabs
• create_management_tab()
  : Creates the management tab (always last)
• create_menu_bar()
  : Creates the main menu with configuration options

Configuration Management

• on_open_const_xml()
  : Handles opening CONST.xml in the XML tree editor
• on_open_pagination_xml()
  : Handles opening pagination.xml in the XML tree editor
• open_xml_in_editor()
  : Common method for launching the XML tree editor

Key Benefits

• No UI flickering: Tabs don't disappear during refresh
• Robust updates: Entity structure changes handled gracefully
• Clean separation: Data operations separate from UI rendering
• Integrated configuration: Edit XML files directly from the application

🎮 Using the Application

Initial Setup

The application automatically creates necessary directories and files:

• Creates
  ./data/
  directory if it doesn't exist
• Creates
  ./entities_description.xml
  with default structure if missing
• Loads existing entities and data on startup

Editing Configuration Files

1. Click Configuration in the main menu bar
2. Select "Open ./data/CONST.xml" to edit the CONST.xml file
3. Select "Open ./data/pagination.xml" to edit the pagination.xml file
4. The XML tree editor opens in a new window for visual XML editing
5. Make changes and save - they are immediately reflected in the file

Entity Definition Format

Entities are defined in

Supported Field Types

• oneline
  : Single-line text input field (Gtk.Entry)
• multiline
  : Multi-line text area with scrollbars (Gtk.TextView in Gtk.ScrolledWindow)

Record Operations (per entity tab)

• New Record: Create new record with dialog
• Edit Record: Modify selected record
• Delete Record: Remove selected record with confirmation
• Refresh: Reload data for this entity only

Entity Operations (management tab)

• New Entity: Define new entity with custom fields
• Edit Entity: Modify entity structure (automatically renames files)
• Delete Entity: Remove entity and all associated data with confirmation
• Refresh All: Reload all data and refresh entire UI

Configuration Operations (main menu)

• Open CONST.xml: Edit the CONST.xml configuration file
• Open pagination.xml: Edit the pagination.xml configuration file

💾 Data Storage

File Naming Convention

./data/{entity_name}/{entity_name}-{unique_id}.xml

Example:

Configuration Files

• ./data/CONST.xml
  : Application configuration constants
• ./data/pagination.xml
  : Pagination settings and configuration

Record XML Format (luassg compatible)

The application saves records in the ArtNazarov/luassg XML format:

Key characteristics:

• Root element name matches entity name
• id
  attribute on root element contains the record identifier
• Field elements as direct children of root
• XML declaration with encoding
• Proper indentation for readability

Example Files Structure

entities_description.xml:

data/gallery/gallery-37158403-3cfe-4922-92e2-46326f0eb571.xml:

🧪 Testing

The project includes 11 comprehensive pytest tests that verify:

🔧 Key Implementation Details

luassg XML Format Compatibility

The application is specifically designed to work with the ArtNazarov/luassg XML format:

• Records are saved with root element name = entity name
• id
  attribute on root element contains record identifier
• Field values are stored as child elements
• Automatic handling of filename pattern:
  {entity_name}-{entity_id}.xml

Configuration Menu Implementation

The new configuration menu feature integrates seamlessly:

• Menu Bar Integration: Added to main window without disrupting existing layout
• Process Management: Uses
  subprocess.Popen
  to launch editor independently
• File Validation: Checks if XML files exist and creates them if missing
• Error Handling: Provides user feedback if editor script is not found
• Path Resolution: Automatically locates
  dialog_xml_tree_editor.py
  in the same directory

Fixed Bugs

1. Empty window on startup - Proper initialization sequence
2. Tabs disappearing on refresh - Separate data loading from UI rendering
3. Entity Management tab position - Always appears as last tab
4. Window blanking on entity updates - Added safety checks and proper UI refresh

Performance Optimizations

• In-memory data caching for quick access
• Selective UI updates (entity vs full refresh)
• Efficient XML parsing with error handling
• Proper handling of luassg format files
• Independent process for XML editing (non-blocking)

User Experience

• Confirmation dialogs for destructive actions
• Real-time data synchronization
• Clear error messages
• Responsive UI with proper scrolling
• Automatic file renaming when entity names change
• Integrated configuration editing via menu
• Visual XML tree editing for complex structures

🐛 Troubleshooting

Common Issues

Issue: "ModuleNotFoundError: No module named 'gi'" Solution: Install python-gobject package

Issue: Window appears empty on startup Solution: Ensure

Issue: Tabs disappear after refresh Solution: This bug has been fixed in current version. Update to latest code.

Issue: XML files not loading correctly Solution: Ensure files follow luassg format with

Issue: "XML tree editor not found" error Solution: Ensure

Issue: Configuration menu items don't work Solution: Install python-lxml:

Debug Mode

Add debug prints to

🤝 Contributing

1. Fork the repository
2. Create a feature branch (
   git checkout -b feature/amazing-feature
   )
3. Commit changes (
   git commit -m 'Add amazing feature'
   )
4. Push to branch (
   git push origin feature/amazing-feature
   )
5. Open a Pull Request

Development Guidelines

• Write tests for new features
• Maintain backward compatibility with luassg format
• Follow Python PEP 8 style guide
• Update documentation as needed
• Ensure all 11 tests pass before submitting PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GTK3 team for the excellent GUI toolkit
• Python community for amazing libraries
• Pytest team for robust testing framework
• All contributors who helped fix bugs and improve the application
• ArtNazarov/luassg for the XML format specification

📧 Contact

Artem Nazarov - GitHub

Project Link: https://github.com/ArtNazarov/entity_xml_crud_app

🎯 Quick Reference

Key Classes

• EntityCRUDApp
  : Main application class
• RecordDialog
  : Dialog for creating/editing records
• EntityDialog
  : Dialog for managing entity definitions

Key Methods

• load_xml_data()
  : Master data loader
• render_xml_data_state()
  : Master UI renderer
• on_refresh_all()
  : Refresh everything (management tab)
• on_refresh_entity()
  : Refresh single entity
• open_xml_in_editor()
  : Launch XML tree editor

Data Flow

User Action → Load XML Data → Update Memory → Render UI State → Show Window
Configuration Menu → Launch Editor → Edit XML → Save Changes

🚀 Example Workflow

1. Launch application:
   python app.py
2. Edit configuration: Click Configuration → Open ./data/CONST.xml
   • XML tree editor opens in a new window
   • Edit the XML structure visually
   • Save changes
3. Add new entity: Go to "Entity Management" tab → "New Entity"
   • Name: "tasks"
   • Fields: "name" (oneline), "description" (multiline)
4. Add records: Go to "tasks" tab → "New Record"
   • Fill in fields and save (creates
     tasks-{uuid}.xml
     in luassg format)
5. Edit structure: Go to "Entity Management" → Select "tasks" → "Edit Entity"
   • Add field: "priority" (oneline)
   • UI automatically updates with new column
6. Refresh data: Click "Refresh All" to reload from disk
7. Edit pagination: Click Configuration → Open ./data/pagination.xml
   • Configure pagination settings for your data

That's it! Your data is automatically saved in the luassg XML format and configuration files can be edited directly from the application menu.

📱 Responsive UI Layout

The application features a fully responsive GTK3 interface that adapts to different window sizes and screen resolutions.

🎨 Adaptive Design Features

Dynamic Layout Behavior

• Column Resizing: TreeView columns automatically adjust width based on available space
• Minimum Window Size: Set to 800×600 pixels to ensure usability
• Form Adaptation: Input fields and labels rearrange from horizontal to vertical layout on narrow screens

Responsive Components

• Entity List: Columns hide or resize based on available width
• Dialog Forms: Field layouts adapt to dialog size with intelligent spacing
• Tab Interface: Tab labels truncate with ellipsis when space is limited

Implementation Highlights