From 0d4a9fc2f8611a734672e616a25133df4f81e9a0 Mon Sep 17 00:00:00 2001 From: Shihaam Abdul Rahman Date: Sun, 22 Mar 2026 00:27:31 +0500 Subject: [PATCH] add docs --- README.md | 97 ++++++++++++++++ docs/adding-templates.md | 235 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 332 insertions(+) create mode 100644 README.md create mode 100644 docs/adding-templates.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7135353 --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +# Roadworthiness Sticker Generator + +A web-based tool for generating vehicle roadworthiness stickers. Built with vanilla HTML, CSS, and JavaScript - no backend required. Perfect for hosting on GitHub Pages. + +## Features + +- Material Design UI with dark/light theme (follows system preference) +- Mobile and desktop responsive +- Multiple garage/template support +- Live sticker preview +- PDF export +- Auto-generated barcodes +- Easy template system (HTML + CSS per template) + +## Quick Start + +1. Clone the repository +2. Serve the files with any static server: + ```bash + # Python + python -m http.server 8080 + + # Node.js + npx serve + ``` +3. Open `http://localhost:8080` in your browser + +## Deployment + +### GitHub Pages + +1. Push to your GitHub repository +2. Go to **Settings** > **Pages** +3. Select your branch (e.g., `main`) and click **Save** +4. Access at `https://.github.io//` + +### Other Static Hosts + +Works with any static hosting: Netlify, Vercel, Cloudflare Pages, etc. Just upload the files. + +## Project Structure + +``` +├── index.html # Main application +├── styles.css # App styles (Material Design) +├── app.js # Application logic +├── templates/ # Sticker templates +│ ├── index.json # Template registry +│ ├── rs-auto.html # RS AUTO template +│ ├── rs-auto.css # RS AUTO styles +│ ├── motca.html # Ministry template +│ └── motca.css # Ministry styles +└── docs/ # Documentation + └── adding-templates.md +``` + +## Adding New Templates + +See [docs/adding-templates.md](docs/adding-templates.md) for detailed instructions. + +**Quick version:** + +1. Create `templates/your-template.html` with placeholders like `{{regNumber}}` +2. Create `templates/your-template.css` with styles +3. Add entry to `templates/index.json` + +## Available Placeholders + +| Placeholder | Description | +|-------------|-------------| +| `{{regNumber}}` | Vehicle registration (formatted with spaces) | +| `{{barcodeNumber}}` | Generated barcode number | +| `{{fromDate}}` | Start date (DD-MM-YYYY) | +| `{{toDate}}` | End date (DD-MM-YYYY) | +| `{{modelNumber}}` | Vehicle model number | +| `{{chassisNumber}}` | Chassis/VIN number | +| `{{engineSerial}}` | Engine serial number | +| `{{engineCapacity}}` | Engine capacity (CC) | + +## Browser Support + +Modern browsers with ES6+ support: +- Chrome/Edge 80+ +- Firefox 75+ +- Safari 13+ + +## Dependencies + +All loaded via CDN (no npm required): +- [JsBarcode](https://github.com/lindell/JsBarcode) - Barcode generation +- [jsPDF](https://github.com/parallax/jsPDF) - PDF creation +- [html2canvas](https://html2canvas.hertzen.com/) - HTML to image conversion +- [Google Fonts](https://fonts.google.com/) - Roboto font & Material Icons + +## License + +MIT diff --git a/docs/adding-templates.md b/docs/adding-templates.md new file mode 100644 index 0000000..511c0b2 --- /dev/null +++ b/docs/adding-templates.md @@ -0,0 +1,235 @@ +# Adding New Templates + +This guide explains how to create and add new sticker templates to the generator. + +## Overview + +Each template consists of three parts: + +1. **HTML file** (`templates/.html`) - The sticker structure with placeholders +2. **CSS file** (`templates/.css`) - The sticker styles +3. **Registry entry** (`templates/index.json`) - Registers the template in the dropdown + +## Step-by-Step Guide + +### Step 1: Create the HTML Template + +Create a new file `templates/your-garage.html`: + +```html +
+
+ {{regNumber}} +
+
+ {{barcodeNumber}} + +
+
+
+
From: {{fromDate}}
+
To: {{toDate}}
+
{{modelNumber}}
+
{{chassisNumber}}
+
{{engineSerial}}
+
{{engineCapacity}} cc
+
+ + +
+
Your Garage Name, TEL: XXX XXXX
+
+``` + +### Step 2: Create the CSS Styles + +Create a new file `templates/your-garage.css`: + +```css +/* Your Garage Template Styles */ +.sticker-your-garage { + width: 280px; + border: 2px solid #000; + font-family: Arial, sans-serif; + font-size: 11px; + background: #fff; + color: #000; +} + +.sticker-your-garage .sticker-header { + background-color: #000; + color: #fff; + text-align: center; + padding: 6px 8px; + font-size: 18px; + font-weight: bold; + letter-spacing: 4px; +} + +.sticker-your-garage .sticker-barcode-row { + display: flex; + align-items: center; + border-bottom: 1px solid #000; + padding: 4px 8px; + gap: 8px; +} + +.sticker-your-garage .sticker-barcode-row .barcode-number { + font-size: 11px; + font-weight: 500; +} + +.sticker-your-garage .sticker-barcode-row .barcode { + height: 30px; + flex: 1; +} + +.sticker-your-garage .sticker-body { + display: flex; + border-bottom: 1px solid #000; +} + +.sticker-your-garage .sticker-info { + flex: 1; + padding: 6px 8px; + font-size: 10px; + line-height: 1.4; +} + +.sticker-your-garage .sticker-logo { + width: 80px; + border-left: 1px solid #000; + display: flex; + align-items: center; + justify-content: center; + padding: 4px; +} + +.sticker-your-garage .sticker-footer { + text-align: center; + padding: 4px 8px; + font-size: 10px; + font-weight: 500; +} +``` + +### Step 3: Register the Template + +Add your template to `templates/index.json`: + +```json +{ + "templates": [ + { + "id": "rs-auto", + "name": "RS AUTO" + }, + { + "id": "motca", + "name": "Min. of Transport & Civil Aviation" + }, + { + "id": "your-garage", + "name": "Your Garage Name" + } + ] +} +``` + +**Important:** The `id` must match your filename (without extension). + +## Available Placeholders + +Use these placeholders in your HTML template. They will be replaced with user input: + +| Placeholder | Description | Example Output | +|-------------|-------------|----------------| +| `{{regNumber}}` | Registration number (with spaces) | `A 0 F 7 9 3 0` | +| `{{barcodeNumber}}` | Auto-generated 10-digit number | `1162603748` | +| `{{fromDate}}` | Start date | `21-03-2026` | +| `{{toDate}}` | End date | `20-03-2027` | +| `{{modelNumber}}` | Vehicle model | `55S400-010C` | +| `{{chassisNumber}}` | Chassis/VIN | `MH355S004DK117181` | +| `{{engineSerial}}` | Engine serial | `55S-118388` | +| `{{engineCapacity}}` | Engine CC | `135.000` | + +## Barcode Element + +To include a barcode in your template, add an SVG element with the class `barcode`: + +```html + +``` + +The app will automatically generate and render the barcode into this element. + +## Tips + +### Naming Convention +- Use lowercase kebab-case for IDs: `my-garage`, `auto-shop-123` +- Use the same ID for HTML filename, CSS filename, and registry entry + +### Scoping Styles +Always prefix your CSS rules with your template's class to avoid conflicts: + +```css +/* Good - scoped to template */ +.sticker-your-garage .sticker-header { ... } + +/* Bad - affects all templates */ +.sticker-header { ... } +``` + +### Logo Options + +**SVG (inline):** +```html + + + LOGO + +``` + +**Image file:** +```html +Logo +``` + +**No logo:** +Simply omit the logo section from your HTML. + +### Testing + +1. Add your template files +2. Update `index.json` +3. Refresh the browser +4. Select your template from the dropdown +5. Fill in test data and verify the preview +6. Generate a PDF to test the output + +## Example Templates + +Study the existing templates for reference: + +- `rs-auto.html` / `rs-auto.css` - Template with logo +- `motca.html` / `motca.css` - Template without logo, different layout + +## Troubleshooting + +**Template not appearing in dropdown:** +- Check `index.json` syntax (valid JSON) +- Verify the `id` matches your filename + +**Styles not loading:** +- Check CSS filename matches the `id` +- Check browser console for 404 errors + +**Barcode not showing:** +- Ensure you have `` in your HTML +- Check browser console for errors + +**PDF looks different from preview:** +- Ensure all styles are in the template CSS file +- Avoid using external images that might not load