|
2 | 2 |
|
3 | 3 | [](https://github.com/star7js/vm-visualizer/actions/workflows/ci.yml) |
4 | 4 |
|
5 | | -A modern, feature-rich PyQt5 application for previewing and rendering Velocity templates with real-time syntax highlighting, validation, and export capabilities. |
| 5 | +Desktop application for previewing and rendering Velocity templates with syntax highlighting and validation. |
6 | 6 |
|
7 | 7 |  |
8 | 8 |
|
9 | 9 | ## Features |
10 | 10 |
|
11 | | -### 🎨 **Modern UI/UX** |
12 | | -- Clean, modern interface with tabbed layout |
13 | 11 | - Syntax highlighting for Velocity templates and JSON data |
14 | | -- Responsive design with customizable splitter panes |
15 | | -- Professional styling with hover effects |
16 | | - |
17 | | -### ⚡ **Enhanced Functionality** |
18 | | -- **Real-time syntax highlighting** for Velocity templates and JSON data |
19 | | -- **Background rendering** for better performance |
20 | | -- **Auto-save functionality** (every 30 seconds) |
21 | | -- **Recent files support** with quick access menu |
22 | | -- **Template and data validation** with detailed error messages |
23 | | -- **Export to HTML** with professional styling |
24 | | - |
25 | | -### 🔧 **Developer Tools** |
26 | | -- Template syntax validation (Ctrl+Shift+V) |
27 | | -- JSON data validation (Ctrl+Shift+D) |
28 | | -- Error highlighting and detailed error messages |
29 | | -- Progress indicators for long operations |
30 | | -- Settings persistence across sessions |
31 | | - |
32 | | -### 📁 **File Management** |
33 | | -- Open/save Velocity templates (.vm files) |
34 | | -- Load JSON data files |
35 | | -- Recent files tracking |
| 12 | +- Real-time template validation with error messages |
| 13 | +- Background rendering for performance |
| 14 | +- Auto-save (every 30 seconds) |
36 | 15 | - Export rendered output to HTML |
37 | | -- Auto-save with silent operation |
| 16 | +- Recent files tracking |
| 17 | +- Dark mode support |
38 | 18 |
|
39 | 19 | ## Installation |
40 | 20 |
|
41 | | -### Prerequisites |
42 | | -- Python 3.9 or higher |
43 | | -- PyQt5 |
44 | | -- Airspeed (Velocity template engine) |
45 | | - |
46 | | -### Quick Start |
47 | | - |
48 | | -1. **Clone or download the project** |
49 | | - ```bash |
50 | | - git clone <repository-url> |
51 | | - cd vm-visualizer |
52 | | - ``` |
53 | | - |
54 | | -2. **Install dependencies** |
55 | | - ```bash |
56 | | - # Using pip |
57 | | - pip install PyQt5 airspeed |
58 | | - |
59 | | - # Or using the project's dependency management |
60 | | - pip install -e . |
61 | | - ``` |
62 | | - |
63 | | -3. **Run the application** |
64 | | - ```bash |
65 | | - python main.py |
66 | | - ``` |
| 21 | +Requires Python 3.9+ |
67 | 22 |
|
68 | | -## Usage |
| 23 | +```bash |
| 24 | +git clone https://github.com/star7js/vm-visualizer.git |
| 25 | +cd vm-visualizer |
| 26 | +pip install PyQt5 airspeed |
| 27 | +python main.py |
| 28 | +``` |
69 | 29 |
|
70 | | -### Basic Workflow |
| 30 | +## Usage |
71 | 31 |
|
72 | | -1. **Open a template**: Use `File > Open Template` or drag a `.vm` file |
73 | | -2. **Add data**: Switch to the "Data" tab and enter JSON data |
74 | | -3. **Render**: Click "Render Template" or press F5 |
75 | | -4. **Export**: Use `Tools > Export as HTML` to save the output |
| 32 | +1. Open a Velocity template (.vm file) |
| 33 | +2. Add JSON data in the Data tab |
| 34 | +3. Press F5 to render |
| 35 | +4. Export to HTML if needed |
76 | 36 |
|
77 | 37 | ### Keyboard Shortcuts |
78 | 38 |
|
79 | 39 | | Action | Shortcut | |
80 | 40 | |--------|----------| |
| 41 | +| Render Template | F5 | |
81 | 42 | | Open Template | Ctrl+O | |
82 | 43 | | Save Template | Ctrl+S | |
83 | | -| Save Template As | Ctrl+Shift+S | |
84 | | -| Render Template | F5 | |
85 | 44 | | Validate Template | Ctrl+Shift+V | |
86 | 45 | | Validate Data | Ctrl+Shift+D | |
87 | | -| Exit | Ctrl+Q | |
88 | | - |
89 | | -### Example Files |
90 | 46 |
|
91 | | -The project includes example files to get you started: |
| 47 | +See `example-template.vm` and `example-data.json` for examples. |
92 | 48 |
|
93 | | -- `example-template.vm` - A comprehensive Velocity template demonstrating various features |
94 | | -- `example-data.json` - Sample JSON data that works with the example template |
| 49 | +## Supported Velocity Features |
95 | 50 |
|
96 | | -## Template Features |
97 | | - |
98 | | -The application supports all standard Velocity template features: |
99 | | - |
100 | | -### Variables |
101 | | -```velocity |
102 | | -$variable |
103 | | -${variable} |
104 | | -``` |
105 | | - |
106 | | -### Directives |
107 | | -```velocity |
108 | | -#set($variable = "value") |
109 | | -#if($condition) |
110 | | - content |
111 | | -#end |
112 | | -#foreach($item in $list) |
113 | | - $item |
114 | | -#end |
115 | | -``` |
116 | | - |
117 | | -### Comments |
118 | | -```velocity |
119 | | -## Single line comment |
120 | | -#* |
121 | | - Multi-line comment |
122 | | -*# |
123 | | -``` |
124 | | - |
125 | | -## Project Structure |
126 | | - |
127 | | -``` |
128 | | -vm-visualizer/ |
129 | | -├── main.py # Main application entry point |
130 | | -├── utils.py # Utility functions and constants |
131 | | -├── syntax_highlighters.py # Syntax highlighting classes |
132 | | -├── example-template.vm # Example Velocity template |
133 | | -├── example-data.json # Example JSON data |
134 | | -├── pyproject.toml # Project configuration |
135 | | -└── README.md # This file |
136 | | -``` |
| 51 | +Supports standard Velocity syntax: variables (`$var`), directives (`#if`, `#foreach`, `#set`), and comments (`##`). |
137 | 52 |
|
138 | 53 | ## Development |
139 | 54 |
|
140 | | -### Code Organization |
141 | | - |
142 | | -The application is organized into modular components: |
| 55 | +Project structure: |
| 56 | +- `main.py` - Application UI and logic |
| 57 | +- `utils.py` - Template processing and utilities |
| 58 | +- `syntax_highlighters.py` - Syntax highlighting |
143 | 59 |
|
144 | | -- **`main.py`**: Main application window and UI logic |
145 | | -- **`utils.py`**: Utility functions, constants, and template processing |
146 | | -- **`syntax_highlighters.py`**: Syntax highlighting for different languages |
147 | | - |
148 | | -### Adding Features |
149 | | - |
150 | | -1. **New syntax highlighting**: Add classes to `syntax_highlighters.py` |
151 | | -2. **Utility functions**: Add to `utils.py` |
152 | | -3. **UI features**: Extend the main window class in `main.py` |
153 | | - |
154 | | -### Building |
155 | | - |
156 | | -The project uses modern Python packaging: |
157 | | - |
158 | | -```bash |
159 | | -# Install in development mode |
160 | | -pip install -e . |
161 | | - |
162 | | -# Build distribution |
163 | | -python -m build |
164 | | -``` |
165 | | - |
166 | | -## Configuration |
167 | | - |
168 | | -### Settings |
169 | | - |
170 | | -The application automatically saves and restores: |
171 | | -- Window geometry and position |
172 | | -- Splitter pane sizes |
173 | | -- Recent files list (last 10 files) |
174 | | - |
175 | | -Settings are stored in the system's application data directory. |
176 | | - |
177 | | -### Customization |
178 | | - |
179 | | -You can customize the application by modifying: |
180 | | -- `utils.py` - Constants and styling |
181 | | -- `syntax_highlighters.py` - Color schemes |
182 | | -- `main.py` - UI layout and behavior |
| 60 | +Settings (window size, recent files) are automatically saved to your system's app data directory. |
183 | 61 |
|
184 | 62 | ## Troubleshooting |
185 | 63 |
|
186 | | -### Common Issues |
187 | | - |
188 | | -1. **Template not rendering**: Check for syntax errors using `Tools > Validate Template` |
189 | | -2. **JSON errors**: Use `Tools > Validate Data` to check JSON syntax |
190 | | -3. **Performance issues**: Large templates are rendered in background threads |
191 | | - |
192 | | -### Error Messages |
193 | | - |
194 | | -The application provides detailed error messages for: |
195 | | -- Template syntax errors |
196 | | -- JSON parsing errors |
197 | | -- File I/O errors |
198 | | -- Rendering errors |
199 | | - |
200 | | -## Contributing |
201 | | - |
202 | | -1. Fork the repository |
203 | | -2. Create a feature branch |
204 | | -3. Make your changes |
205 | | -4. Add tests if applicable |
206 | | -5. Submit a pull request |
| 64 | +- **Template errors**: Use `Tools > Validate Template` (Ctrl+Shift+V) |
| 65 | +- **JSON errors**: Use `Tools > Validate Data` (Ctrl+Shift+D) |
| 66 | +- **Performance**: Large templates render in background threads |
207 | 67 |
|
208 | 68 | ## License |
209 | 69 |
|
210 | | -This project is open source and available under the MIT License. |
211 | | - |
212 | | -## Acknowledgments |
213 | | - |
214 | | -- Built with [PyQt5](https://www.riverbankcomputing.com/software/pyqt/) |
215 | | -- Uses [Airspeed](https://github.com/purcell/airspeed) for Velocity template processing |
216 | | -- Inspired by modern code editors and IDEs |
| 70 | +MIT License |
217 | 71 |
|
218 | | ---- |
| 72 | +## Built With |
219 | 73 |
|
220 | | -**Happy templating!** 🚀 |
| 74 | +- [PyQt5](https://www.riverbankcomputing.com/software/pyqt/) - UI framework |
| 75 | +- [Airspeed](https://github.com/purcell/airspeed) - Velocity template engine |
0 commit comments