EducationalResourceEditor Class

Technical Documentation - Multi-Format Educational Content Editor

The EducationalResourceEditor class is a sophisticated PySide6-based editor designed for creating and managing educational resources in multiple formats. It serves as a unified editing interface for plain text, rich text (RTF), HTML, LaTeX, images, PDF documents, and more. The editor implements a dual-content architecture with separate areas for educational content and answer sections, each supporting the full range of document formats.

This editor uses HTML as its underlying storage format, with specialized handling for different content types. All content is formatted to A4 paper width (6.19 inches after margins) to ensure consistency in printed output. The system intelligently detects content type and applies appropriate rendering and editing capabilities, making it a versatile tool for educators creating diverse learning materials.

📑 Table of Contents

🔍 1. Overview and Philosophy

The EducationalResourceEditor implements a comprehensive editing solution for educational materials with the following design principles:

📐

A4 Paper Standard

All content formatted to 6.19 inches width (A4 paper minus margins). Content width calculated as 6.19 × DPI pixels for consistent printing.

🔄

HTML as Universal Format

Uses HTML as underlying storage format with meta tags for type identification. Differentiates between raw content and processed HTML rendering.

🎯

Dual-Purpose Editing

Separate editing areas for educational content and answers. Each area supports full range of document formats with specialized toolbars.

Content Width Specification: The editor uses 6.19 inches as the available space for educational content on A4 paper. This accounts for 0.5 inches left/right margins and 0.54 inches for columns 1 and 3 in a 3-column paper layout. The pixel equivalent is calculated as app_context.EDU_ITEM_PIXELS = 6.19 × DPI.

Paper Layout Visualization

# A4 Paper Layout (inches): │ ┌──────┬─────────────────────────────────────────────────────────────────────┬──────┐ │ │ 0.5 │POINT │ HEADER │ ROW │ 0.5 │ │ ├──────┼─────────────────────────────────────────────────────────────────────┼──────┤ │ │ │ 0.54 │ CONTENT - 6.19 INCHES │ 0.54 │ │ │ ├──────┼─────────────────────────────────────────────────────────────────────┼──────┤ │ │ │ │ CONTENT │ │ │ │ │ │ │ │ │ │ │──────┼─────────────────────────────────────────────────────────────────────┼──────┤ │ │ │ SUM │ FOOTER │ │ │ │ └──────┴─────────────────────────────────────────────────────────────────────┴──────┘ │

Class Inheritance and Dependencies

class EducationalResourceEditor(QWidget): # Primary dependencies: # - PySide6.QtWidgets (UI components, dialogs) # - PySide6.QtGui (Text formatting, images, icons) # - pymupdf (PDF processing and text extraction) # - processing.Imaging.Tools (Image conversion utilities) # - processing.Imaging.SnippingTool (Screen capture) # - processing.utils.image_tools (PDF to image conversion) # - ui.widgets.widgets.RichTextEdit (Enhanced text editor) # - core.app_context.app_context (Configuration and constants) # - utils.helpers (LaTeX processing and format detection) # - PySideAbdhUI.Notify (User notification system)

🏗️ 2. Architecture and Layout

5×6 Grid Layout Structure

The editor uses a 5-row × 6-column grid layout for precise control over widget placement:

# Grid Layout Structure (5 rows × 6 columns): # Row 0: Page title (Column 0) and ID display (Columns 2-4) # Row 1: Content command toolbar (Column 0) # Row 2: Content editor (RichTextEdit, Column 0) # Row 3: Answer command toolbar (Column 0) # Row 4: Answer editor (QTextEdit, Column 0) # Column 1-5: Right panel (source, details, score, navigation) main_layout = QGridLayout(self) main_layout.addWidget(page_title, 0, 0, 1, 1, Qt.AlignmentFlag.AlignTop) main_layout.addWidget(self.content_description_input, 2, 0) main_layout.addWidget(self.answer_input, 4, 0)

Dual-Editor Architecture

Editor Area Widget Type Width Purpose Supported Formats
Content Editor RichTextEdit EDU_ITEM_PIXELS + 35 Primary educational content All formats (text, HTML, LaTeX, images, PDF)
Answer Editor QTextEdit EDU_ITEM_PIXELS + 35 Answer/solution content All formats (text, HTML, LaTeX, images, PDF)

Width Calculation and Layout

# Width calculation for editor widgets: # Base width: EDU_ITEM_PIXELS (6.19 × DPI) # Additional space: 35 pixels (10+10 margins + 15 scrollbar) content_width = app_context.EDU_ITEM_PIXELS + 35 self.content_description_input.setFixedWidth(content_width) self.answer_input.setFixedWidth(content_width)
Design Note: The fixed width ensures all content fits within the printable area of A4 paper. The 35-pixel addition accounts for widget margins and scrollbar, ensuring the actual content area matches the 6.19-inch specification.

🎨 3. UI Components and Layout

Header and Navigation Section

# Header components (Row 0): # 1. Page title: "RESOURCE EDITOR" (Column 0) page_title = QLabel('RESOURCE EDITOR') page_title.setProperty('class', 'heading2') # 2. ID label: Shows current record ID or "(New item)" self.Id_label = QLabel() self.Id_label.setProperty('class', 'caption') # 3. Navigation buttons: Back and Next for record navigation back_button = QPushButton() back_button.setIcon(QIcon(':icons/chevron-left.svg')) back_button.clicked.connect(lambda _, direction='<': self.load_record(direction)) next_button = QPushButton() next_button.setIcon(QIcon(':icons/chevron-right.svg')) next_button.clicked.connect(lambda _, direction='>': self.load_record(direction))

Right Panel Components

The right panel (columns 1-5) contains metadata and configuration fields:

Component Type Purpose Row/Column
Source Input QLineEdit Resource source/book reference Row 1, Columns 2-3
Additional Details QTextEdit Notes, comments, metadata Row 2, Columns 1-4
Score Input QLineEdit Point value for assessment Row 3, Column 2
Delete Button QPushButton Remove current record Row 3, Column 3
Save Button QPushButton Save to database Row 3, Column 4

Command Toolbars Structure

Both content and answer sections have dedicated command toolbars with similar functionality:

# Content Command Toolbar includes: # 1. LaTeX button with New/Run options # 2. HTML button with New/Run options # 3. Insert Image button # 4. Screen Snipping Tool button # 5. Upload menu (multiple file types) # 6. Database search widget # 7. New Content button # 8. Bookmark button for marking items # Answer Command Toolbar has identical structure # but operates on the answer editor

Editor Interface Layout

[UI LAYOUT DIAGRAM: Showing the 5×6 grid structure:
• Top row: Title and navigation • Rows 1-4: Content/Answer with toolbars
• Right panel: Metadata fields • Bottom: Action buttons
• Color-coded sections showing widget relationships]

📄 4. Supported Content Types

Format Overview and Storage Strategy

📝

Plain Text

Storage: Converted to HTML via toHtml()
Restoration: Loaded via setHtml()
Limitations: No formatting, math, or images

🎨

Rich Text (RTF)

Storage: Saved as HTML via toHtml()
Restoration: Loaded via setHtml()
Features: Formatting, images, tables

📐

LaTeX

Storage: Saved raw via toPlainText()
Restoration: Loaded via setPlainText()
Processing: Requires LaTeX engine

🌐

HTML

Storage: Saved raw via toPlainText()
Restoration: Loaded via setPlainText()
Processing: Interpreted via setHtml()

🖼️

Image

Storage: Base64 encoded in HTML <img> tag
Restoration: Loaded via setHtml()
Width: Fixed to EDU_ITEM_PIXELS

📄

PDF

Options: Editable (text) or Readonly (image)
Processing: PyMuPDF for extraction
Limitation: First page only for multi-page PDFs

Content Type Detection and Handling

helpers.is_rtf() - Format Detection

The system uses helpers.is_rtf() to distinguish between raw text (HTML/LaTeX) and processed text (Plain Text/RTF):

if not helpers.is_rtf(row[3]): # Raw content (HTML/LaTeX) self.content_description_input.document().setPlainText(row[3]) else: # Processed content (Plain Text/RTF) self.content_description_input.document().setHtml(row[3])

HTML Meta Tag Strategy

The editor uses HTML meta tags to identify content types in the database:

# Content identification via meta tags: # - name='qrichtext': Processed content (rendered HTML) # - name='viewport': Raw content (HTML/LaTeX source) # Example HTML structure with meta tags: <!DOCTYPE HTML> <html><head> <meta name="qrichtext" content="1" /> <meta charset="utf-8" /> </head><body>...</body></html>
Storage Philosophy: Plain text and RTF are saved as HTML for easy rendering. HTML and LaTeX are saved as raw source code for editing. Images and PDFs are converted to base64 and embedded in HTML. This dual-strategy allows both WYSIWYG editing and source code manipulation.

🔄 5. Content Processing Pipeline

Upload and Conversion Workflow

upload_file() - Unified File Processing

This method handles all file uploads with type-specific processing:

def upload_file(self, sender: QTextEdit, arg: str = app_context.SupportedFileTypes.IMAGE, options=None): # 1. Open file dialog with type-specific filter # 2. Determine file type from 'arg' parameter # 3. Apply type-specific processing: if arg == app_context.SupportedFileTypes.IMAGE: # Convert to base64, embed in HTML img tag html_content = f'<img src="data:image/png;base64,{base64_image}" width="{app_context.EDU_ITEM_PIXELS}"/>' elif arg == app_context.SupportedFileTypes.PDF: if options == 'Editable': # Extract text via PyMuPDF self.upload_PDF_as_html(file_path, sender) else: # Convert to image, embed in HTML html_content = f'<img src="data:image/png;base64,{base64s[0]}" width="{app_context.EDU_ITEM_PIXELS}"/>' elif arg in [app_context.SupportedFileTypes.TEXT, app_context.SupportedFileTypes.LaTeX, ...]: # Read as plain text self.read_plain_text(sender, file_path)

Image Processing Pipeline

Source Processing Output Insertion Method
File Upload pixmap_to_base64() Base64 string setHtml() or insertHtml()
Screen Capture SnippingWindow → pixmap_to_base64() Base64 string insertHtml()
PDF Conversion pdf_to_base64() Base64 string array setHtml() (first page only)
LaTeX Rendering helpers.run_latex() HTML with embedded image insertHtml()

LaTeX Processing System

The editor provides comprehensive LaTeX support through multiple methods:

# 1. Template creation: def ___config_latex(self, sender: QTextEdit): # Creates basic LaTeX template with Persian support latex_content = ('\\documentclass{{article}}\n' '\\usepackage{{xepersian}}\n' '\\settextfont{{Yas}}\n' '\\begin{{document}}\n{}\n' '\\end{{document}}').format('Add here main content') # 2. Compilation and rendering: def run_latex(self, sender: QTextEdit): html = helpers.run_latex(sender.toPlainText(), compile='xepersian', output_PDF_name='edu-resource.PDF') sender.clear() sender.insertHtml(html) # Embeds rendered PDF as image
LaTeX Dependency: The run_latex() method requires a working LaTeX installation with xepersian package. This is an external dependency that must be installed separately on the user's system.

Screen Capture Integration

The editor integrates a snipping tool for capturing screen content:

def run_snipping_tool(self, target: QTextEdit): active = QApplication.activeWindow() active.hide() # Hide main window during capture snipping_window = SnippingWindow(self) # Connect capture signal to insertion handler snipping_window.screen_captured.connect(lambda data: ( target.insertHtml(f'<img src="data:image/png;base64,{pixmap_to_base64(data)}" width="{app_context.EDU_ITEM_PIXELS}"/>'), active.show() )) snipping_window.showFullScreen() # Fullscreen for complete coverage

💾 6. Database Integration

Database Schema and Fields

Field Name Type Purpose Editor Widget
Id Primary Key Unique resource identifier Id_label (display only)
source_ Text Resource source/book reference source_input (QLineEdit)
score_ Numeric Point value for assessment score_input (QLineEdit)
content_description_ Text Primary educational content content_description_input (RichTextEdit)
answer_ Text Answer/solution content answer_input (QTextEdit)
additional_details_ Text Notes, comments, metadata additional_details_input (QTextEdit)

CRUD Operations Implementation

save_to_database() - Intelligent Save Logic

This method handles both insert (new) and update (existing) operations:

def save_to_database(self): # 1. Collect data from all widgets source = self.source_input.text() score = self.score_input.text() # ... additional fields # 2. Determine content type and format appropriately content = self.content_description_input.document().toPlainText() if helpers.is_rtf(content): content = self.content_description_input.toHtml() # 3. Choose INSERT or UPDATE based on ID if self.id > 0: # UPDATE existing record query = "UPDATE educational_resources SET source_ = %s, score_= %s, ... WHERE Id= %s RETURNING id;" variables = (source, score, content, answer, details, self.id) else: # INSERT new record query = "INSERT INTO educational_resources (source_, score_, ...) VALUES (%s, %s, ...) RETURNING id;" variables = (source, score, content, answer, details) # 4. Execute query and update ID self.db_cursor.execute(query, variables) self.id = self.db_cursor.fetchone()[0]

load_record() - Navigation and Loading

Supports multiple navigation modes with intelligent content type detection:

def load_record(self, direction: str = ' >'): # Build query based on navigation direction if direction == '<': order = 'ORDER BY Id DESC' where = f'WHERE Id < {self.id} {order} LIMIT 1;' elif direction == '>': order = ' ORDER BY Id ASC' where = f'WHERE Id > {self.id} {order} LIMIT 1;' elif direction == '=': where = f'WHERE Id = {self.id};' # Execute query and load data query = "SELECT Id, source_, score_, content_description_, ... FROM educational_resources " + where row = app_context.database.fetchone(query) # Apply content type detection for proper loading if not helpers.is_rtf(row[3]): # Raw content (HTML/LaTeX) self.content_description_input.document().setPlainText(row[3]) else: # Processed content (Plain Text/RTF) self.content_description_input.document().setHtml(row[3])

Record Navigation System

Direction Query Logic Purpose
'<' (Back) Id < current_id ORDER BY Id DESC Previous record (lower ID)
'>' (Next) Id > current_id ORDER BY Id ASC Next record (higher ID)
'=' (Specific) Id = specific_id Load specific record by ID
'' (Empty) Id > 0 ORDER BY Id DESC Most recent record
Security Warning: The remove_record() method uses string concatenation for the DELETE query (f"DELETE FROM educational_resources WHERE id={self.id};"). While the ID comes from internal state, this pattern should be replaced with parameterized queries for consistency and security best practices.

⚙️ 7. Core Method Analysis

Initialization and Setup Methods

Method Purpose Complexity Key Operations
__init__(cursor) Constructor with database cursor O(1) Grid layout creation, widget initialization
create_right_panel() Build right-side metadata panel O(1) Add source, details, score, navigation widgets
create_content_commands() Build content command toolbar O(1) Create LaTeX, HTML, image, upload, search buttons
create_answer_commands() Build answer command toolbar O(1) Mirror of content toolbar for answer editor

Content Processing Methods

Method Primary Function Performance Dependencies
upload_file() Process file uploads of all types O(n) for file size File I/O, image conversion, PDF processing
read_plain_text() Load plain text files O(n) for file size File I/O, text encoding detection
upload_PDF_as_html() Extract text from PDFs O(p) for PDF pages PyMuPDF, HTML generation
run_latex() Compile and render LaTeX External process LaTeX engine, helpers.run_latex()
run_html() Interpret HTML source O(n) for HTML size HTML parser, Qt rendering
run_snipping_tool() Capture screen content O(1) + image processing SnippingWindow, image conversion

Template Generation Methods

___config_basic_html() - HTML Template Creation

Creates a basic HTML template with proper document structure:

html_template = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">\n' html_template += '<html lang="en">\n' html_template += '<head> <meta charset="UTF-8" name="viewport" content="width=device-width, initial-scale=1.0"></head>\n' html_template += f'<body style="width:{app_context.EDU_ITEM_PIXELS}px;">\n' html_template += ' <main>\n' html_template += ' <b>Add here main content.</b>\n' html_template += ' </main>\n' html_template += '</body>\n' html_template += '</html>' sender.document().setPlainText(html_template)

___config_latex() - LaTeX Template Creation

Creates a Persian-enabled LaTeX template with highlighting:

latex_content = ('\\documentclass{{article}}\n' '\\usepackage{{xepersian}}\n' '\\settextfont{{Yas}}\n' '\\begin{{document}}\n{}\n' '\\end{{document}}').format('Add here main content') sender.document().setPlainText(latex_content) self.___highlightText(sender, 'Add here main content')

Text Processing Utilities

Method Purpose Implementation
___highlightText() Highlight specific text in editor Uses QTextCursor and QTextCharFormat
clear_content() Reset all editor fields Calls clear() on all widgets
load_from_database() Load specific record by ID Wrapper for load_record('=')
remove_record() Delete current record DELETE query with confirmation dialog

📋 8. Format-Specific Handling

File Type Detection and Processing

File Extension Detection Method Processing Function Storage Format
.txt Extension check read_plain_text() → setHtml() HTML (via toHtml())
.tex Extension check read_plain_text() → setPlainText() Raw LaTeX
.html Extension check read_plain_text() → setPlainText() Raw HTML
.rtf Extension check pypandoc.convert_file() (commented) HTML (converted)
Image files MIME type filter pixmap_to_base64() → HTML <img> Base64 in HTML
.pdf Extension check + options pdf_to_base64() or upload_PDF_as_html() Base64 image or HTML text
.docx Extension check pypandoc.convert_file() (commented) HTML (converted)

Image Processing Details

📏

Dimension Control

All images resized to EDU_ITEM_PIXELS width via HTML width attribute. Maintains aspect ratio. Ensures print compatibility.

🔧

Base64 Encoding

Images converted to base64 strings for direct embedding. No external file dependencies. Increases database size but improves portability.

🎯

Insertion Modes

Replace: Clear editor, insert as new content.
Append: Insert at cursor position.
Controlled by options parameter.

LaTeX Processing Pipeline

# LaTeX processing steps: # 1. User writes LaTeX source in editor # 2. Run LaTeX via helpers.run_latex(): html = helpers.run_latex( sender.toPlainText(), # LaTeX source compile='xepersian', # Compiler with Persian support output_PDF_name='edu-resource.PDF' # Output file name ) # 3. Clear editor and insert rendered HTML sender.clear() sender.insertHtml(html) # HTML contains embedded PDF image

PDF Processing Options

Editable vs Readonly PDF Processing

The editor provides two PDF processing modes:

if options == 'Editable': # Text extraction mode (for editing) # Uses PyMuPDF to extract text as HTML PDF_document = pymupdf.open(PDF_path) html = page.get_text('html') sender.setHtml(html) else: # 'ReadOnly' or None # Image conversion mode (for display) # Converts first page to base64 image base64s = pdf_to_base64(file_path) html_content = f'<img src="data:image/png;base64,{base64s[0]}" width="{app_context.EDU_ITEM_PIXELS}"/>' sender.setHtml(html_content)
PDF Limitation: The editor only processes the first page of multi-page PDF documents. Additional pages are ignored. For educational resources, this is typically sufficient, but users should be aware of this limitation.

Content Type Detection Logic

The editor uses multiple strategies to determine content type:

# 1. File upload: Based on file extension and user selection # 2. Database loading: Uses helpers.is_rtf() to detect format # 3. Manual creation: User selects template (HTML/LaTeX) # 4. Content analysis: Regular expressions for LaTeX patterns # helpers.is_rtf() likely checks for: # - HTML tags presence # - LaTeX command patterns (\documentclass, \begin{document}) # - RTF formatting codes

⚡ 9. Performance Considerations

Memory Usage Analysis

🖼️

Image and PDF Content

Issue: Base64 encoding increases size by ~33%
Impact: Large images/PDFs consume significant memory
Solution: Fixed width limits, single-page PDF processing

📄

HTML/LaTeX Source

Issue: Large documents in text editors
Impact: Linear memory growth with document size
Solution: Qt's efficient text document management

🔧

External Process Calls

Issue: LaTeX compilation is external process
Impact: High CPU/memory during compilation
Solution: Async processing, progress indicators

Time Complexity Analysis

Operation Method Complexity Bottleneck Optimization Potential
File upload (image) upload_file() O(n) for image size Base64 encoding, pixmap loading Medium - Thumbnail generation
PDF processing upload_PDF_as_html() O(p) for PDF pages PyMuPDF text extraction Low - Already limited to first page
LaTeX compilation run_latex() External process LaTeX engine startup and compilation Low - External dependency
Database save/load save_to_database() O(1) + network Database connection, text size Medium - Connection pooling
Screen capture run_snipping_tool() O(1) + image processing Fullscreen capture, base64 encoding Low - Already efficient

Optimization Recommendations

Immediate Improvements

  1. Fix SQL Injection: Parameterize the DELETE query in remove_record()
  2. Progress Indicators: Add progress bars for large file uploads
  3. Image Compression: Implement quality settings for image conversion
  4. Caching: Cache recently used templates and configurations

Architectural Improvements

  1. Async Processing: Move LaTeX compilation to background thread
  2. Lazy Loading: Defer image rendering until visible
  3. Database Optimization: Implement BLOB storage for large content
  4. Memory Management: Implement content paging for very large documents
  5. Preview Mode: Add low-resolution previews for images/PDFs
Design Trade-off: The use of base64 encoding for images and PDFs increases storage requirements but eliminates external file dependencies. This simplifies deployment and backup at the cost of increased database size. For typical educational resources (small to medium images), this is an acceptable trade-off.

External Dependencies Management

Dependency Purpose Impact Alternative
PyMuPDF PDF text extraction Essential for editable PDFs PDFMiner, pdfplumber
LaTeX Engine Formula rendering Critical for math content MathJax (web), KaTeX
pypandoc Document conversion Optional (commented out) python-docx, mammoth

📚 10. API Reference

Public Methods Reference

Method Parameters Return Description Thread Safety
__init__(cursor) cursor: database cursor None Constructor with database connection UI thread only
upload_file(sender, arg, options) sender: QTextEdit
arg: file type
options: str or None		 None Upload and process file of specified type UI thread only
run_latex(sender) sender: QTextEdit None Compile LaTeX source and insert result UI thread (spawns external process)
run_html(sender) sender: QTextEdit None Interpret HTML source and render UI thread only
run_snipping_tool(target) target: QTextEdit None Capture screen and insert as image UI thread only
save_to_database() None None Save current content to database UI thread only
load_record(direction) direction: str ('<', '>', '=', '') None Load record based on navigation direction UI thread only
load_from_database(sender) sender: QLineEdit None Load specific record by ID from input UI thread only
remove_record() None None Delete current record with confirmation UI thread only
clear_content() None None Reset all editor fields to empty UI thread only

Internal/Helper Methods

Method Access Purpose Notes
___config_basic_html() Private Create HTML template Called from HTML button menu
___config_latex() Private Create LaTeX template Called from LaTeX button menu
___highlightText() Private Highlight text in editor Used in template creation
read_plain_text() Private Load plain text files Helper for upload_file()
upload_PDF_as_html() Private Extract PDF text as HTML PDF editable mode processing

Signal/Slot Connections

Signal Source Signal Slot/Method Purpose
Back navigation button clicked lambda: load_record('<') Load previous record
Next navigation button clicked lambda: load_record('>') Load next record
Save button clicked save_to_database Save current content
Delete button clicked remove_record Delete current record
SnippingWindow screen_captured Lambda inserting base64 image Insert captured screen image
Database search button clicked load_from_database Load record by ID

Dependencies and Requirements

Core Dependencies

  • PySide6: >= 6.4.0 (UI framework)
  • Python: >= 3.8 (f-strings, typing)
  • Database: PostgreSQL/MySQL with educational_resources table

Processing Dependencies

  • pymupdf (fitz): PDF text extraction and processing
  • LaTeX Distribution: Required for formula rendering (TeX Live, MiKTeX)
  • Persian LaTeX: xepersian package for Persian/arabic support

Custom Module Dependencies

  • ui.widgets.widgets.RichTextEdit: Enhanced text editor widget
  • processing.Imaging.Tools: pixmap_to_base64()
  • processing.Imaging.SnippingTool: SnippingWindow for screen capture
  • processing.utils.image_tools: pdf_to_base64()
  • utils.helpers: run_latex(), is_rtf()
  • core.app_context.app_context: Configuration, constants, tooltips
  • PySideAbdhUI.Notify: PopupNotifier for user feedback

Optional Dependencies

  • pypandoc: Document format conversion (currently commented out)
  • Pandoc: Required if pypandoc is used

Content Processing Pipeline

[FLOW DIAGRAM: Showing content processing pipeline:
Input Sources → Format Detection → Type-Specific Processing →
Storage Format Conversion → Database Integration → Output Rendering
With parallel paths for different content types and conversion options]