Skip to main content

Editor - File Management

The O2VEND Theme Editor provides comprehensive file management capabilities. This guide covers browsing, editing, creating, and managing theme files.

File Explorer​

The file explorer displays the complete theme structure:

theme-name/
  ├── layout/
  │   └── theme.liquid
  ├── templates/
  │   ├── index.liquid
  │   ├── product.liquid
  │   └── ...
  ├── sections/
  │   ├── header.liquid
  │   └── ...
  ├── snippets/
  │   ├── product-card.liquid
  │   └── ...
  ├── assets/
  │   ├── theme.css
  │   ├── theme.js
  │   └── ...
  └── config/
      ├── settings_schema.json
      └── settings_data.json

Browsing Files​

  • Click folders to expand/collapse
  • Click files to open in editor
  • Use search to find files quickly
  • Filter by file type

File Types​

The editor supports:

  • Liquid Templates (.liquid) - Theme templates
  • CSS (.css) - Stylesheets
  • JavaScript (.js) - Scripts
  • JSON (.json) - Configuration files
  • Images (.png, .jpg, .svg) - Image assets
  • Fonts (.woff, .woff2) - Font files

Opening Files​

Click to Open​

  1. Navigate to file in explorer
  2. Click file name
  3. File opens in editor panel
  4. Start editing

Search Files​

  1. Use search box in file explorer
  2. Type file name or path
  3. Click result to open

Editing Files​

Code Editor​

The editor provides:

  • Syntax highlighting
  • Code completion
  • Line numbers
  • Find and replace
  • Undo/redo

Making Changes​

  1. Open file in editor
  2. Make your changes
  3. Changes are highlighted
  4. Save when ready

Auto-Save​

  • Changes are auto-saved periodically
  • Manual save available via Save button
  • Unsaved changes indicator shown

Creating Files​

New File​

  1. Right-click in file explorer
  2. Select "New File"
  3. Enter file name with extension
  4. File created and opened
  5. Start editing

New Folder​

  1. Right-click in file explorer
  2. Select "New Folder"
  3. Enter folder name
  4. Folder created

File Templates​

Some file types have templates:

  • New Liquid template → Basic template structure
  • New CSS file → Empty stylesheet
  • New JavaScript → Module structure

Deleting Files​

Delete File​

  1. Right-click on file
  2. Select "Delete"
  3. Confirm deletion
  4. File removed from theme

Delete Folder​

  1. Right-click on folder
  2. Select "Delete"
  3. Confirm deletion
  4. Folder and contents removed

Warning: Deletion is permanent. Use version control to restore if needed.

File Operations​

Rename File​

  1. Right-click on file
  2. Select "Rename"
  3. Enter new name
  4. Press Enter to confirm

Duplicate File​

  1. Right-click on file
  2. Select "Duplicate"
  3. New file created with "-copy" suffix
  4. Rename as needed

Move File​

  1. Drag file to new location
  2. Or cut and paste
  3. File moved to new folder

File Versioning​

View Versions​

  1. Right-click on file
  2. Select "View Versions"
  3. See version history
  4. Compare versions

Restore Version​

  1. Open version history
  2. Select version to restore
  3. Click "Restore"
  4. File restored to selected version

Version Information​

Each version shows:

  • Timestamp
  • Author (if available)
  • File size
  • Changes summary

Search in Files​

  1. Use search box
  2. Enter search term
  3. Results shown with context
  4. Click to navigate

Replace in Files​

  1. Open find/replace (Ctrl+F / Cmd+F)
  2. Enter search term
  3. Enter replacement
  4. Replace all or one-by-one

File Validation​

Syntax Checking​

The editor validates:

  • Liquid syntax
  • JSON syntax
  • CSS syntax
  • JavaScript syntax

Error Highlighting​

  • Errors shown with red underline
  • Warnings shown with yellow underline
  • Hover for error details

File Permissions​

Read-Only Files​

Some files may be read-only:

  • System files
  • Protected files
  • Files in use

Edit Permissions​

Ensure you have edit permissions:

  • Verify tenant repository access
  • Verify tenant configuration
  • Contact administrator if needed

File Organization​

Best Practices​

  1. Logical Structure: Organize files in folders
  2. Naming Conventions: Use descriptive names
  3. Group Related Files: Keep related files together
  4. Remove Unused Files: Clean up unused files
theme-name/
  layout/          # Layout templates
  templates/       # Page templates
  sections/        # Page sections
  snippets/        # Reusable components
  assets/          # CSS, JS, images
    css/
    js/
    images/
  config/          # Configuration files
  locales/         # Translations

Theme Download and Upload​

Download Theme (New - January 2025)​

Download the current theme as a ZIP file for backup or sharing.

Download Process​

  1. Select Theme

    • Ensure a theme is selected in the theme selector
    • The download includes the currently selected theme

  2. Click Download Button

    • Click the download icon button in the toolbar (bottom of sidebar)
    • Theme is prepared for download

  3. Download ZIP File

    • Theme is packaged as a ZIP file
    • ZIP file automatically downloads to your computer
    • File name: {theme-name}.zip

What's Included​

The downloaded ZIP file contains:

  • All theme files (templates, sections, snippets, assets)
  • All folders and subfolders
  • File structure preserved
  • Binary files (images, fonts) included correctly

Exclusions​

The following are NOT included:

  • .versions folder (version history)
  • System folders (_active, _active_backup)
  • Temporary files

Requirements​

  • Authentication: Valid JWT token required
  • S3 Configuration: Theme download requires S3 to be configured
  • Theme Selection: A theme must be selected before downloading

API Endpoint​

  • GET /editor/webstoreapi/themes/:themeName/download - Downloads theme as ZIP

Download Features​

  • Maximum Compression: ZIP files use maximum compression (level 9)
  • Binary File Support: Images, fonts, and other binary files are handled correctly
  • Complete Theme: All files and folders are included
  • Preserved Structure: File and folder structure is maintained

Upload Theme (New - January 2025)​

Upload a theme from a ZIP file to add it to your tenant repository.

Upload Process​

  1. Click Upload Button

    • Click the upload icon button in the toolbar (bottom of sidebar)
    • File picker dialog opens

  2. Select ZIP File

    • Choose a valid theme ZIP file
    • File must be .zip format
    • Maximum file size: 50MB

  3. Theme Validation

    • ZIP file is extracted to temporary directory
    • theme.json file is validated
    • Theme structure is checked

  4. Upload to S3

    • All files are uploaded to S3
    • Theme becomes available in theme selector
    • Upload progress shown

  5. Theme Activation

    • Uploaded theme is automatically selected
    • Ready for editing and publishing

ZIP File Requirements​

The uploaded ZIP file must:

  1. Contain theme.json in the root directory with:

    • id (string): Unique theme identifier
    • name (string): Theme display name
    • version (string): Semantic version (e.g., "1.0.0")
    • author (string): Theme author name
    • description (string): Theme description

  2. Valid Theme Structure

    • Recommended folders: templates, sections, assets, config
    • Can contain any valid theme files

  3. File Size

    • Maximum size: 50MB
    • Exceeds limit: Upload rejected with error

  4. Theme Name Validation

    • Theme name cannot start with underscore (_)
    • System folders (_active, _active_backup) are reserved

Example theme.json​

{
  "id": "my-custom-theme",
  "name": "My Custom Theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A custom theme for my store"
}

ZIP File Structure​

my-theme.zip
├── theme.json                    (Required metadata)
├── templates/
│   ├── index.liquid
│   └── product.liquid
├── sections/
│   ├── header.liquid
│   └── footer.liquid
├── snippets/
│   └── product-card.liquid
├── assets/
│   ├── theme.css
│   └── theme.js
└── config/
    ├── settings_schema.json
    └── settings_data.json

Upload Validation​

Before uploading, the system validates:

  1. File Format

    • Must be a valid ZIP file
    • File extension must be .zip

  2. File Size

    • Must not exceed 50MB
    • Validated before extraction

  3. theme.json Presence

    • Must exist in ZIP root
    • Validated after extraction

  4. theme.json Structure

    • All required fields must be present
    • Version must follow semantic versioning (X.Y.Z)

  5. Theme Name

    • Cannot be system folder name
    • Cannot start with underscore

Upload Features​

  • Binary File Support: Images, fonts, and other binary files are handled correctly
  • Automatic Content Type Detection: File content types are automatically detected
  • Complete File Upload: All files and folders are uploaded
  • Error Handling: Detailed error messages for validation failures
  • Progress Feedback: Upload progress and file count shown

Upload Errors​

Common upload errors:

  • "No files found": ZIP file is empty or invalid
  • "theme.json not found": Missing metadata file
  • "Invalid theme.json": JSON syntax or structure error
  • "Missing required fields": Required fields missing from theme.json
  • "Invalid version format": Version must be semantic (X.Y.Z)
  • "File size exceeds 50MB limit": ZIP file too large
  • "Invalid theme name": Theme name conflicts with system folders

API Endpoint​

  • POST /editor/webstoreapi/themes/upload - Uploads theme from ZIP file
    • Content-Type: multipart/form-data
    • Field name: themeZip

Post-Upload Actions​

After successful upload:

  1. Theme Available: Theme appears in theme selector
  2. Auto-Select: Uploaded theme is automatically selected
  3. Ready to Edit: Theme is ready for editing and publishing
  4. File Tree Updated: File explorer shows new theme files

Upload Best Practices​

  1. Validate ZIP Before Upload

    • Ensure theme.json is valid
    • Check file size is under 50MB
    • Verify theme structure

  2. Use Descriptive Theme Names

    • Use clear, descriptive IDs in theme.json
    • Avoid special characters

  3. Include All Required Files

    • Include all templates, sections, and assets
    • Don't forget configuration files

  4. Test Theme Locally First

    • Validate theme works before uploading
    • Check for missing files or broken references

File Backup​

Automatic Backup​

  • Files backed up before major changes
  • Versions maintained automatically
  • Restore from version history

Manual Backup​

  1. Download Theme: Use download button to get ZIP backup
  2. Store Securely: Save ZIP file to secure location
  3. Version Control: Download before major changes

File Sync​

Files are synced to the tenant repository:

  • Files synced automatically
  • Changes uploaded on save
  • Sync status shown

Troubleshooting​

File Not Opening​

  • Check file permissions
  • Verify file exists
  • Refresh file explorer
  • Check browser console

Changes Not Saving​

  • Check tenant repository access
  • Verify network connection
  • Check file size limits
  • Review error messages

File Explorer Not Loading​

  • Refresh page
  • Check browser console
  • Verify theme access
  • Contact support

Keyboard Shortcuts​

  • Ctrl+S / Cmd+S: Save file
  • Ctrl+F / Cmd+F: Find
  • Ctrl+H / Cmd+H: Replace
  • Ctrl+Z / Cmd+Z: Undo
  • Ctrl+Y / Cmd+Y: Redo
  • Ctrl+/ / Cmd+/: Toggle comment

Next Steps​