ContentImageByID

Parameters

Name	Type	Required	Description
`id`	string \| number	Yes	Numeric ID of the image in Content Builder
`fallbackId`	string \| number	No	ID of a replacement image when the primary cannot be resolved

Show test script

<script runat="server">
Platform.Load("core", "1.1.5");

/*
 * Chapter: Parameters —
 *   Platform.Function.ContentImageByID(id[, fallbackId])
 *
 * Proves:
 *   1. The member resolves on Platform.Function (typeof "clrmethodinfo",
 *      the engine's uniform marker for a host CLR method — it proves
 *      nothing about existence, only invocation does).
 *   2. `id` is required and the documented minimal 1-argument call resolves
 *      the image (min_args: 1).
 *   3. TYPE-ACCEPTANCE (Number↔string): `id` is accepted as a number AND as
 *      a numeric STRING with the SAME meaningful result (same thid), and
 *      also as a VARIABLE. Dual acceptance widens the Parameters type to
 *      string | number.
 *   4. `fallbackId` is genuinely OPTIONAL and genuinely REACHABLE from
 *      SSJS: the documented 2-argument call works. This is worth stating
 *      explicitly because the sibling ContentBlockBy* family rejects every
 *      2nd argument from SSJS — ContentImageByID does NOT share that
 *      restriction.
 *   5. `fallbackId` is only used when the primary cannot be resolved: with a
 *      resolvable primary the fallback is ignored, with a missing primary
 *      the fallback image is returned instead.
 *   6. TYPE-ACCEPTANCE (Number↔string): `fallbackId` is accepted as a
 *      number AND as a numeric STRING with the SAME meaningful result
 *      (same thid), and also as a VARIABLE — widens to string | number.
 *   7. `id` must reference an existing IMAGE asset: a non-existent id
 *      throws, and so does the id of a non-image (HTML block) asset.
 *   8. When BOTH the primary and the fallback are missing, the call throws —
 *      the fallback does not suppress the error.
 *   9. `fallbackId` must be a numeric asset id: null and a non-numeric
 *      string are rejected with the overloaded security-descriptor error.
 *  10. Arities outside the documented 1..2 range (0 and 3) throw the same
 *      security-descriptor error (min_args: 1, max_args: 2).
 *
 * SCOPE: CloudPage only — the same calls inside an email send were not
 * exercised.
 *
 * NOT ASSERTED: the exact text of the thrown messages. Any string operation
 * on these CLR exception messages (.length / .indexOf / .substring) aborts
 * the CloudPage with HTTP 422, so each message is printed verbatim next to
 * its assertion for the reader instead of being matched programmatically.
 *
 * EXPECTED OUTPUT: every line starts with PASS. A FAIL means the runtime no
 * longer matches the documented claim and the page must be revised.
 */

function assert(id, actual, expected) {
    Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
    var threw = false, msg = "";
    try { fn(); } catch (ex) { threw = true; msg = ex.message; }
    Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
/* The returned tag is ~190 chars — reduce it to the asset id it points at. */
function thid(tag) {
    return String(tag).indexOf('thid="1133955"') > -1 ? "IMG-1133955"
         : String(tag).indexOf('thid="1201143"') > -1 ? "IMG-1201143"
         : "OTHER";
}

var IMG = 1133955;    /* png "sfdcmarketingcloud" */
var IMG2 = 1201143;   /* png "copado-logo.png"    */

/* 1. The member resolves as a host CLR method. */
assert("typeof Platform.Function.ContentImageByID is clrmethodinfo", String(typeof Platform.Function.ContentImageByID), "clrmethodinfo");

/* 2. The required numeric `id` alone resolves the image. */
assert("arity 1 with a real image id resolves that image", thid(Platform.Function.ContentImageByID(IMG)), "IMG-1133955");

/* 3. TYPE-ACCEPTANCE: number, numeric string and variable all accepted for `id` with the same image. */
var idAsNumber = thid(Platform.Function.ContentImageByID(IMG));
var idAsString = thid(Platform.Function.ContentImageByID("1133955"));
assert("arity 1 accepts the id as a number", idAsNumber, "IMG-1133955");
assert("arity 1 accepts the id as a numeric string", idAsString, "IMG-1133955");
assert("TYPE-ACCEPT number and numeric-string id return the same image", idAsNumber === idAsString ? "true" : "false", "true");
var varId = IMG;
assert("arity 1 accepts a VARIABLE id", thid(Platform.Function.ContentImageByID(varId)), "IMG-1133955");

/* 4. The documented optional fallbackId IS reachable from SSJS. */
assert("arity 2 with fallbackId works from SSJS (unlike the ContentBlockBy* family)", thid(Platform.Function.ContentImageByID(IMG, IMG2)), "IMG-1133955");

/* 5. The fallback is used only when the primary cannot be resolved. */
assert("a resolvable primary IGNORES the fallback", thid(Platform.Function.ContentImageByID(IMG, IMG2)), "IMG-1133955");
assert("a missing primary RETURNS the fallback image", thid(Platform.Function.ContentImageByID(12345, IMG2)), "IMG-1201143");

/* 6. TYPE-ACCEPTANCE: fallbackId accepts a number, a numeric string and a variable with the same image. */
var fbAsNumber = thid(Platform.Function.ContentImageByID(12345, IMG));
var fbAsString = thid(Platform.Function.ContentImageByID(12345, "1133955"));
assert("fallbackId as a number is accepted", fbAsNumber, "IMG-1133955");
assert("fallbackId as a numeric string is accepted", fbAsString, "IMG-1133955");
assert("TYPE-ACCEPT number and numeric-string fallbackId return the same image", fbAsNumber === fbAsString ? "true" : "false", "true");
var varFallback = IMG;
assert("fallbackId as a VARIABLE is accepted", thid(Platform.Function.ContentImageByID(12345, varFallback)), "IMG-1133955");

/* 7. The id must reference an existing IMAGE asset. */
assertThrows("arity 1 with a non-existent id throws", function () {
    return Platform.Function.ContentImageByID(12345);
});
assertThrows("the id of a non-image asset (an HTML block) throws", function () {
    return Platform.Function.ContentImageByID(1469165);
});

/* 8. A missing fallback does not rescue a missing primary. */
assertThrows("both primary and fallback missing throws", function () {
    return Platform.Function.ContentImageByID(12345, 54321);
});

/* 9. fallbackId must be a numeric asset id. */
assertThrows("a null fallbackId throws the security-descriptor error", function () {
    return Platform.Function.ContentImageByID(IMG, null);
});
assertThrows("a non-numeric string fallbackId throws the security-descriptor error", function () {
    return Platform.Function.ContentImageByID(IMG, "abc");
});

/* 10. Off-signature arities throw the overloaded security-descriptor error. */
assertThrows("arity 0 throws", function () {
    return Platform.Function.ContentImageByID();
});
assertThrows("arity 3 throws", function () {
    return Platform.Function.ContentImageByID(IMG, IMG2, "extra");
});
</script>

Return value

A string containing an img tag (including typical attributes such as src, alt, and title as provided by the platform).

Show test script

<script runat="server">
Platform.Load("core", "1.1.5");

/*
 * Chapter: Return value — "A string containing an `img` tag (including
 * typical attributes such as `src`, `alt`, and `title` as provided by the
 * platform)."
 *
 * Proves:
 *   1. The return type is a STRING (return_type: string), and a non-empty
 *      one.
 *   2. The string IS an img element: it starts with "<img " and ends with
 *      ">".
 *   3. It carries the documented typical attributes — src=, alt= and title=
 *      are all present.
 *   4. The `src` is a real platform-hosted image URL (https://), not a
 *      relative path or a placeholder.
 *   5. The tag identifies the requested asset: it contains thid="<id>" for
 *      the id that was asked for, which is how the other chapters' short
 *      assertions distinguish one image from another.
 *   6. The value is RETURNED, not emitted: the call alone puts nothing on
 *      the page; the content only appears when the result is passed to
 *      Write(). A probe line delimits the raw Write() output.
 *   7. The sibling Platform.Function.ContentImageByKey returns a tag of the
 *      same shape for the same asset, addressed by its external key.
 *   8. There is no bare-name Core form: typeof ContentImageByID is
 *      "undefined" even after Platform.Load("core", "1.1.5"), and invoking
 *      the bare name throws "Object expected: ContentImageByID".
 *
 * SCOPE: CloudPage only. Whether the generated src URL renders in an email
 * client, and the tag's behaviour inside an email send, were not exercised.
 *
 * EXPECTED OUTPUT: every line starts with PASS, except the single
 * WRITE-PROBE line between the assertions, which IS the raw Write() output
 * being proven in point 6.
 */

function assert(id, actual, expected) {
    Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
    var threw = false, msg = "";
    try { fn(); } catch (ex) { threw = true; msg = ex.message; }
    Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
function has(tag, needle) {
    return String(tag).indexOf(needle) > -1 ? "true" : "false";
}

var IMG = 1133955;

/* 1. It returns a non-empty string. */
var tag = Platform.Function.ContentImageByID(IMG);
assert("the return value is a string", String(typeof tag), "string");
assert("the returned string is non-empty", tag.length > 0 ? "true" : "false", "true");

/* 2. The string is an img element. */
assert("the returned string starts with an img tag", tag.substring(0, 5), "<img ");
assert("the returned string ends with the tag close", tag.substring(tag.length - 1), ">");

/* 3. The documented typical attributes are present. */
assert("the tag carries a src attribute", has(tag, "src="), "true");
assert("the tag carries an alt attribute", has(tag, "alt="), "true");
assert("the tag carries a title attribute", has(tag, "title="), "true");

/* 4. The src points at a platform-hosted https URL. */
assert("the src is an https platform URL", has(tag, 'src="https://'), "true");

/* 5. The tag identifies the requested asset. */
assert("the tag names the requested asset id", has(tag, 'thid="1133955"'), "true");

/* 6. The value is returned, not emitted. */
Platform.Response.Write("WRITE-PROBE-START ");
Write(tag);
Platform.Response.Write(" WRITE-PROBE-END\n");
assert("typeof the bare-name Write is function after Platform.Load", String(typeof Write), "function");
var returned = Platform.Function.ContentImageByID(IMG);
assert("the call returns the tag rather than emitting it", has(returned, 'thid="1133955"'), "true");

/* 7. The sibling ContentImageByKey returns the same shape for the same asset. */
assert("typeof Platform.Function.ContentImageByKey is clrmethodinfo", String(typeof Platform.Function.ContentImageByKey), "clrmethodinfo");
var byKey = Platform.Function.ContentImageByKey("sfdcmarketingcloud-518005426");
assert("ContentImageByKey returns the tag for the same asset", has(byKey, 'thid="1133955"'), "true");
assert("both forms return the identical tag", byKey === tag ? "true" : "false", "true");

/* 8. No bare-name Core form exists. */
assert("there is no bare-name ContentImageByID global", String(typeof ContentImageByID), "undefined");
assertThrows("invoking the bare name throws Object expected", function () {
    return ContentImageByID(IMG);
});
</script>

Examples

var banner = Platform.Function.ContentImageByID(1234567);
Write(banner);

var icon = Platform.Function.ContentImageByID(555, 999);
Write(icon);

Show test script

<script runat="server">
Platform.Load("core", "1.1.5");

/*
 * Chapter: Examples —
 *   var banner = Platform.Function.ContentImageByID(1234567);
 *   Write(banner);
 * and
 *   var icon = Platform.Function.ContentImageByID(555, 999);
 *   Write(icon);
 *
 * The page's example ids are placeholders, so this script runs the same two
 * SHAPES against the QA business unit's real fixture images:
 *   1133955  png "sfdcmarketingcloud"   (stands in for 1234567 / 555)
 *   1201143  png "copado-logo.png"      (stands in for 999)
 *
 * Proves:
 *   1. Example 1's shape works verbatim: the 1-argument call assigns a
 *      string to the variable and that string is the asset's img tag.
 *   2. The bare-name Write() global used by both examples is available
 *      after Platform.Load("core", "1.1.5") and emits its argument
 *      unchanged.
 *   3. Example 2's shape works: the 2-argument call with a fallback id is
 *      accepted and assigns the primary image's tag when the primary
 *      resolves.
 *   4. Example 2's stated PURPOSE holds — when the primary cannot be
 *      resolved the SECOND id is what comes back, which is the only
 *      observable difference between the two example shapes.
 *   5. Using the page's literal placeholder ids (555 / 999 — neither exists
 *      on this business unit) throws, confirming they are placeholders and
 *      that both ids must reference real image assets.
 *
 * SCOPE: CloudPage only. Write() in an email-send context was not
 * exercised.
 *
 * EXPECTED OUTPUT: every line starts with PASS, except the two WRITE-PROBE
 * lines between the assertions, which ARE the raw Write() output being
 * proven in point 2.
 */

function assert(id, actual, expected) {
    Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
    var threw = false, msg = "";
    try { fn(); } catch (ex) { threw = true; msg = ex.message; }
    Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
function thid(tag) {
    return String(tag).indexOf('thid="1133955"') > -1 ? "IMG-1133955"
         : String(tag).indexOf('thid="1201143"') > -1 ? "IMG-1201143"
         : "OTHER";
}

/* 1. Example 1 — the single-argument form. */
var banner = Platform.Function.ContentImageByID(1133955);
assert("example 1: the variable receives a string", String(typeof banner), "string");
assert("example 1: the variable holds that image's tag", thid(banner), "IMG-1133955");

/* 2. The bare-name Write() global from the examples is available and faithful. */
assert("typeof the bare-name Write is function after Platform.Load", String(typeof Write), "function");
Platform.Response.Write("WRITE-PROBE-1-START ");
Write(banner.substring(0, 5));
Platform.Response.Write(" WRITE-PROBE-1-END\n");

/* 3. Example 2 — the two-argument form with a fallback id. */
var icon = Platform.Function.ContentImageByID(1133955, 1201143);
assert("example 2: the two-argument form returns a string", String(typeof icon), "string");
assert("example 2: the resolvable primary wins over the fallback", thid(icon), "IMG-1133955");
Platform.Response.Write("WRITE-PROBE-2-START ");
Write(icon.substring(0, 5));
Platform.Response.Write(" WRITE-PROBE-2-END\n");

/* 4. Example 2's purpose — the fallback replaces an unresolvable primary. */
assert("example 2: an unresolvable primary yields the FALLBACK image", thid(Platform.Function.ContentImageByID(12345, 1201143)), "IMG-1201143");

/* 5. The page's literal placeholder ids do not exist. */
assertThrows("the page's placeholder id 1234567 does not resolve", function () {
    return Platform.Function.ContentImageByID(1234567);
});
assertThrows("the page's placeholder pair 555 / 999 does not resolve", function () {
    return Platform.Function.ContentImageByID(555, 999);
});
</script>

ContentImageByID

Syntax

Parameters

Return value

Examples

See Also

See Also