saveFile

Category: Dialog Operations

Namespace: web.dialogs.saveFile

Description

Display a native Windows Save File dialog that allows users to choose where to save a file. Returns the full path where the user wants to save, or an empty string if cancelled.

Syntax

const savePath = await web.dialogs.saveFile({
    title: string,
    fileName: string,
    fileTypes: string,
    overwritePrompt: boolean
});

Parameters

• title (optional) - Dialog window title. Default: "Save File"
• fileName (optional) - Default filename to suggest. Default: ""
• fileTypes (optional) - File type filter string in format: "Description|.ext|Description2|.ext2". Default: "All Files|."
• overwritePrompt (optional) - Show warning if file already exists. Default: true

Returns

Promise<string> - Full path where user wants to save, or empty string "" if cancelled

Example

Simple example

const savePath = await web.dialogs.saveFile();

if (savePath) {
    console.log('Save to:', savePath);
}

Practical example

const content = document.getElementById('editor').value;

const savePath = await web.dialogs.saveFile({
    title: 'Save Text File',
    fileName: 'document.txt',
    fileTypes: 'Text Files|*.txt|All Files|*.*'
});

if (savePath) {
    await web.files.writeTextFile({
        path: savePath,
        contents: content
    });
    alert('File saved successfully!');
} else {
    console.log('Save cancelled');
}

Advanced example

async function exportData(data) {
    const savePath = await web.dialogs.saveFile({
        title: 'Export Data',
        fileName: 'export.json',
        fileTypes: 'JSON Files|*.json|CSV Files|*.csv|Text Files|*.txt',
        overwritePrompt: true
    });
    
    if (!savePath) {
        return; // User cancelled
    }
    
    const extension = savePath.split('.').pop().toLowerCase();
    let content;
    
    if (extension === 'json') {
        content = JSON.stringify(data, null, 2);
    } else if (extension === 'csv') {
        content = convertToCSV(data);
    } else {
        content = JSON.stringify(data);
    }
    
    await web.files.writeTextFile({
        path: savePath,
        contents: content
    });
    
    alert(`Exported to ${savePath}`);
}

Use Cases

• Let users choose where to save files
• Export data to user-selected location
• Save documents with custom names
• Export reports or logs
• Save configuration files
• Create backups with user-chosen location
• Export application data
• Replace HTML download links with native save dialog

Error Handling

Returns empty string "" if user cancels. Always check before saving.

const savePath = await web.dialogs.saveFile({
    title: 'Save Document',
    fileName: 'document.txt'
});

if (!savePath) {
    console.log('Save cancelled');
    return;
}

// Proceed with save operation
await web.files.writeTextFile({
    path: savePath,
    contents: content
});

Performance Tips

• Suggest appropriate default filenames
• Use specific file type filters
• Provide clear dialog titles
• Always handle the cancel case (empty string)
• Set overwritePrompt: true to prevent accidental overwrites
• Set overwritePrompt: false for auto-save scenarios

Related Methods

• web.dialogs.openFile() - Open file dialog
• web.dialogs.selectFolder() - Folder selection dialog
• web.files.writeTextFile() - Write file content
• web.files.fileExists() - Check if file exists

Notes

• Native Windows dialog (not HTML download)
• Returns full absolute path (e.g., "C:\Users\Documents\file.txt")
• Returns empty string "" on cancel (not null)
• Dialog warns if file already exists (when overwritePrompt is true)
• File type filter format: "Description|*.ext"
• Suggested filename appears in dialog
• User can change filename and location
• Dialog remembers last used directory