Snippet assets (@param asset)

Created: 2026-07-18 · Updated: 2026-07-19

A snippet can ship its own files — images, icons or data lists. They live in the snippet's folder, travel with it when you publish, back up or upload it, and the script reaches them through ppptools.*.

The asset parameter type turns those files into a picker with a thumbnail, driven by a CSV file that sits next to the snippet.

This page explains both, using one running example: a country flag snippet with 271 countries, two aspect ratios, as PNG and SVG.

The snippet folder

Assets sit next to code.cs. Subfolders are allowed:

<snippet folder>\
├── code.cs             ← created by the editor
├── snippet.xml         ← created by the editor
├── preview.png         ← created by the editor
├── countries.csv       ← your own data list
├── flags_png\
│   ├── 1x1\  ch.png · de.png · …
│   └── 4x3\  ch.png · de.png · …
└── flags_svg\
    ├── 1x1\  ch.svg · de.svg · …
    └── 4x3\  ch.svg · de.svg · …

How the files get there: save the snippet once, then click "Open folder" in Manage snippets and copy the files in via Explorer. Saving again only overwrites code.cs and snippet.xml — the assets stay.

Allowed file types

Anything else is rejected when exporting a ZIP or uploading. That keeps unwanted files from spreading through the library.

The data list

The CSV needs a header row and uses a semicolon as separator. Columns are addressed by name later, so their order is up to you:

iso;de;en;svg_1x1;svg_4x3;png_1x1;png_4x3
CH;Schweiz;Switzerland;flags_svg\1x1\ch.svg;flags_svg\4x3\ch.svg;flags_png\1x1\ch.png;flags_png\4x3\ch.png
DE;Deutschland;Germany;flags_svg\1x1\de.svg;flags_svg\4x3\de.svg;flags_png\1x1\de.png;flags_png\4x3\de.png

Paths are relative to the snippet folder. Rename a folder and you only adjust the CSV — not the code.

A picker with preview: @param asset

// @param asset <name> "<label>" source="<file.csv>" labelcol="<column>"
//              [valuecol="<column>"] [previewcol="<column>"] [default="<value>"] [tooltip="…"]

• source — the CSV inside the snippet folder
• labelcol — column shown in the list
• valuecol — column handed to the script (omit it and the label is returned)
• previewcol — column holding the thumbnail
• default — entry preselected on open (a value from labelcol)

In the script, Params.GetString("<name>") returns the valuecol content.

For the flag example:

// @param asset Land "Country" source="countries.csv" labelcol="en" valuecol="en"
//              previewcol="png_1x1" default="Switzerland" tooltip="Pick a country"

Reaching assets from the script

For security reasons scripts must not use System.IO. Access goes through ppptools instead, and stays confined to the snippet's own folder:

Path segments are passed individually. Absolute paths and upward jumps (..) are rejected.

// "flags_png\4x3\ch.png" from the CSV becomes a full path:
string[] parts = path.Split('\\');
string file = ppptools.AssetPath(parts);

Complete example

// @param asset Land "Country" source="countries.csv" labelcol="en" valuecol="en"
//              previewcol="png_1x1" default="Switzerland"
// @param enum Format "File format" options="PNG (image)|SVG (vector)" default="PNG (image)"
// @param float Width "Width (pt)" default=120 min=8 max=720

string country = Params.GetString("Land", "Switzerland");
bool   isPng   = Params.GetString("Format", "PNG (image)").StartsWith("PNG");
float  width   = (float)Params.GetFloat("Width", 120.0);
float  height  = width * 3f / 4f;

string file = null, hint = null;

if (!ppptools.AssetExists("countries.csv"))
{
    hint = "countries.csv is missing from the snippet folder.";
}
else
{
    foreach (string line in ppptools.ReadAssetLines("countries.csv"))
    {
        if (line.Length == 0 || line.StartsWith("iso;")) continue;   // header
        string[] sp = line.Split(';');
        if (sp.Length < 7) continue;
        if (!string.Equals(sp[2], country, StringComparison.OrdinalIgnoreCase)) continue;

        string rel = isPng ? sp[6] : sp[4];         // png_4x3 or svg_4x3
        string[] parts = rel.Split('\\');
        if (ppptools.AssetExists(parts)) file = ppptools.AssetPath(parts);
        else                             hint = "File missing: " + rel;
        break;
    }
}

if (file != null)
{
    var flag = ppptools.AddPicture(file, 100f, 100f, width, height);
    flag.Name = "Flag_" + country;
}
else
{
    // No throw — see the pitfalls below
    var ph = ppptools.AddRect(100f, 100f, width, height);
    ph.TextFrame.TextRange.Text = hint;
}

Three pitfalls

1. Never throw when assets are missing

Saving in the Advanced Snippet Editor runs the script to generate the preview image. If it throws, the snippet cannot be saved — and without a saved snippet there is no folder to put the assets into.

Draw a visible placeholder on the slide instead. That way you can create the snippet first and copy the files in afterwards.

2. In the editor, only a saved snippet knows its folder

ppptools.SnippetDir stays empty until the snippet has been saved. To test with real assets: save first, then insert from the gallery.

3. SVG is inserted as a group

PowerPoint turns an inserted SVG into a group of individual shapes. Setting Line on it draws borders inside the graphic. Two ways around it: use PNG, or place a separate rectangle over the graphic and group the two.

An inserted SVG should also not be ungrouped — that can crash PowerPoint.

Sharing

Large asset bundles ask for confirmation before uploading.

From the online library, assets are fetched individually on demand rather than as one bundle: inserting a snippet downloads only the files it actually touches and stores them locally. The second time round everything comes from that cache. A snippet with a thousand images is therefore as fast as one with a single image — as long as only one is needed.

See also

• Parameterized Snippets
• Snippet parameter (@param snippet)
• ppptools reference
• Security