Platform.Function.ContentAreaByName
→ stringRetrieves rendered content from a classic Content Area by name. Salesforce documents Content Areas as deprecated in favour of Content Builder blocks.
Runtime verified
Differs from official docs
Test scripts included
Syntax
Platform.Function.ContentAreaByName(name[, regionName, stopOnError, fallbackContent])
1–4 arguments
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Name of the Content Area. The bare name works; the "folder\myArea" form works too. Matching is case-insensitive. |
regionName |
string | No | Impression region for content tracking. ⚠️ Supplying it makes the call throw a resolved-value error — see below. |
stopOnError |
boolean | No | When true, throws on retrieval failure; when false, the call continues. ⚠️ Unreachable — the call already throws on regionName. |
fallbackContent |
string | No | Content to display when the area cannot be retrieved. ⚠️ Unreachable — never emitted at runtime. |
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Parameters —
* Platform.Function.ContentAreaByName(name[, regionName, stopOnError, fallbackContent])
*
* 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. The required `name` parameter alone — the minimal documented call —
* returns the content area's markup, once the name is one that has
* been read back from the created fixture.
* 3. DEV the documented optional `regionName` (parameter 2) does not
* work: it is rejected as a resolved-value parameter. A string
* literal, the empty string and null all throw.
* 4. Because parameter 2 is rejected, the documented `stopOnError`
* (parameter 3) and `fallbackContent` (parameter 4) are UNREACHABLE:
* arity 3 and arity 4 throw the same ImpressionRegionName error, so
* neither stopOnError:false nor the fallback string ever takes effect.
* 5. Arities outside the documented 1..4 range (0 and 5) throw the
* overloaded "security descriptor" error. Because arity 1 succeeds in
* this same request, that message settles ARITY here — it is not
* evidence about whether the member exists.
*
* 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");
}
/* Fixture: create a Content Area and read its stored Name back. */
var prox = new Script.Util.WSProxy();
var caName = "ssjsg-ca-" + Platform.Function.GUID().substring(0, 8);
var caBody = "BODY-" + caName;
var created = prox.createItem("ContentArea", { Name: caName, CustomerKey: caName, Content: caBody, IsDynamicContent: false });
var caId = created.Results[0].NewObjectID;
var readBack = prox.retrieve("ContentArea", ["ID", "Name"], { Property: "ID", SimpleOperator: "equals", Value: caId });
assert("the fixture's stored Name reads back as created", String(readBack.Results[0].Name), caName);
/* 1. The member resolves as a host CLR method. */
assert("typeof Platform.Function.ContentAreaByName is clrmethodinfo", String(typeof Platform.Function.ContentAreaByName), "clrmethodinfo");
/* 2. The minimal documented call (name only) returns the content. */
assert("arity 1 with the verified name returns the content", String(Platform.Function.ContentAreaByName(caName)), caBody);
/* 3. DEV the documented optional regionName is rejected as a resolved value. */
assertThrows("DEV arity 2 regionName string literal throws (docs: optional impression region)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion");
});
assertThrows("DEV arity 2 empty-string regionName throws as well", function () {
return Platform.Function.ContentAreaByName(caName, "");
});
assertThrows("DEV arity 2 null regionName throws as well", function () {
return Platform.Function.ContentAreaByName(caName, null);
});
/* 4. stopOnError and fallbackContent are unreachable behind that rejection. */
assertThrows("DEV arity 3 stopOnError=false still throws (docs: false lets the call proceed)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", false);
});
assertThrows("DEV arity 3 stopOnError=true throws", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", true);
});
assertThrows("DEV arity 4 fallbackContent never emitted, call throws (docs: fallback is displayed)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", false, "Fallback text here");
});
/* 5. Off-signature arities throw the overloaded security-descriptor error. */
assertThrows("arity 0 throws", function () {
return Platform.Function.ContentAreaByName();
});
assertThrows("arity 5 throws", function () {
return Platform.Function.ContentAreaByName(caName, "reg", false, "fb", "extra");
});
/* Cleanup. */
prox.deleteItem("ContentArea", { ID: caId });
</script>
Description
Platform.Function.ContentAreaByName() retrieves and renders content from a classic (legacy) SFMC Content Area identified by its name.
Salesforce’s documentation marks Content Areas as deprecated in favour of Content Builder. For new work, migrate content to Content Builder blocks and use Platform.Function.ContentBlockByName().
Runtime note: only the single-argument form works. Given the name of a Content Area that actually exists, the 1-argument call returns that area’s content. Matching is case-insensitive and the "folder\myArea" form resolves as well, while the area’s CustomerKey, a name padded with spaces and an unknown name are all rejected with an evaluation error — a throw at arity 1 means the name did not resolve. Adding the documented regionName throws a different, resolved-value error, which makes stopOnError and fallbackContent unreachable. The bare-name ContentAreaByName() Core form behaves the same.
Differs from official Salesforce docs
The official docs present all four parameters as usable. At runtime only the first one is: supplying regionName fails with a resolved-value error before stopOnError or fallbackContent can take effect, so the documented 4-argument form never works.
Show test script — only the 1-argument form works
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Differs-from-docs claim: the official Salesforce documentation presents
* Platform.Function.ContentAreaByName(name, regionName, stopOnError,
* fallbackContent) as a four-parameter callable, with stopOnError:false
* letting a failed call proceed and fallbackContent shown when nothing is
* returned. At runtime ONLY the single-argument form works.
*
* Official docs: ContentAreaByName("My Content\\myContentArea",
* "impressionRegion", false, "defaultContentHere")
* returns the content the area produced.
* SFMC runtime: arity 1 -> returns the content area's markup
* arity 2/3/4 -> "A ContentAreaByName function call includes
* an invalid parameter value. … must be a
* literal (constant) values."
* Parameter Name: ImpressionRegionName
* Parameter Ordinal: 2
* Parameter Type: ResolvedValueParameter
* arity 0/5+ -> "Unable to retrieve security descriptor for
* this frame."
* (each message is printed verbatim by its assertion below)
*
* Proves every part of the claim:
* 1. Arity 1 returns the content for a name read back from the fixture.
* 2. DEV arity 2 throws the resolved-value error for every regionName
* shape: string literal, concatenation, variable, empty string and
* null. So the failure is not "literal vs variable" — the parameter
* cannot be supplied at all.
* 3. DEV arity 3 and arity 4 throw the same parameter-2 error, which is
* what makes stopOnError and fallbackContent unreachable: the fallback
* string is never emitted.
* 4. Arity 0 and arity 5 throw the overloaded security-descriptor error.
* Since arity 1 succeeds in this same request, that message settles
* ARITY here and says nothing about the member's existence.
* 5. The bare-name Core alias matches the qualified form exactly, so the
* deviation is not specific to the Platform.Function namespace.
*
* EXPECTED OUTPUT: every line starts with PASS.
*/
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");
}
/* Fixture: create a Content Area and read its stored Name back. */
var prox = new Script.Util.WSProxy();
var caName = "ssjsg-ca-" + Platform.Function.GUID().substring(0, 8);
var caBody = "BODY-" + caName;
var created = prox.createItem("ContentArea", { Name: caName, CustomerKey: caName, Content: caBody, IsDynamicContent: false });
var caId = created.Results[0].NewObjectID;
var readBack = prox.retrieve("ContentArea", ["ID", "Name"], { Property: "ID", SimpleOperator: "equals", Value: caId });
assert("the fixture's stored Name reads back as created", String(readBack.Results[0].Name), caName);
/* 1. Arity 1 works. */
assert("arity 1 returns the content", String(Platform.Function.ContentAreaByName(caName)), caBody);
/* 2. DEV every regionName shape is rejected as a resolved value. */
assertThrows("DEV arity 2 string literal regionName throws", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion");
});
assertThrows("DEV arity 2 concatenated regionName throws", function () {
return Platform.Function.ContentAreaByName(caName, "impression" + "Region");
});
var dynRegion = "impressionRegion";
assertThrows("DEV arity 2 variable regionName throws", function () {
return Platform.Function.ContentAreaByName(caName, dynRegion);
});
assertThrows("DEV arity 2 empty-string regionName throws", function () {
return Platform.Function.ContentAreaByName(caName, "");
});
assertThrows("DEV arity 2 null regionName throws", function () {
return Platform.Function.ContentAreaByName(caName, null);
});
/* 3. DEV stopOnError and fallbackContent never take effect. */
assertThrows("DEV arity 3 stopOnError=false throws (docs: the call proceeds)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", false);
});
assertThrows("DEV arity 3 stopOnError=true throws", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", true);
});
assertThrows("DEV arity 4 throws so fallbackContent is never emitted (docs: fallback shown)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", false, "FALLBACK");
});
assertThrows("DEV arity 4 with a null regionName throws as well", function () {
return Platform.Function.ContentAreaByName(caName, null, false, "FALLBACK");
});
/* 4. Off-signature arities throw the overloaded security-descriptor error. */
assertThrows("arity 0 throws", function () {
return Platform.Function.ContentAreaByName();
});
assertThrows("arity 5 throws", function () {
return Platform.Function.ContentAreaByName(caName, "reg", false, "fb", "extra");
});
/* 5. The bare-name Core alias matches the qualified form. */
assert("bare-name arity 1 returns the same content", String(ContentAreaByName(caName)), caBody);
assertThrows("DEV bare-name arity 2 throws as well", function () {
return ContentAreaByName(caName, "impressionRegion");
});
assertThrows("DEV bare-name arity 3 errorMsg throws, so errorMsg is unreachable", function () {
return ContentAreaByName(caName, "impressionRegion", "err");
});
assertThrows("DEV bare-name arity 4 throws, so its fallbackContent is unreachable", function () {
return ContentAreaByName(caName, "impressionRegion", "err", "FALLBACK");
});
assertThrows("bare-name arity 0 throws", function () {
return ContentAreaByName();
});
assertThrows("bare-name arity 5 throws", function () {
return ContentAreaByName(caName, "reg", "err", "fb", "extra");
});
/* Cleanup. */
prox.deleteItem("ContentArea", { ID: caId });
</script>
Difference from the global ContentAreaByName() form
The bare-name global ContentAreaByName() function accepts the same first two parameters but differs in the 3rd and 4th:
Platform.Function.ContentAreaByName() |
ContentAreaByName() (global) |
|
|---|---|---|
| 3rd parameter | stopOnError: boolean |
errorMsg: string |
Requires Platform.Load |
No | Yes — Platform.Load("core", "1.1.5") |
See ContentAreaByName for the bare-name Core variant.
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Description — what the by-name form actually resolves, and how
* the bare-name Core form compares.
*
* Proves:
* 1. A name that has been read back from a freshly created Content Area
* resolves and returns that area's content.
* 2. Name matching is case-insensitive: the same name uppercased returns
* the same content.
* 3. The "folder\name" form resolves too.
* 4. A throw at arity 1 means the NAME did not resolve, nothing more:
* the area's own CustomerKey, a space-padded copy of the working name
* and an unknown name all throw the evaluate-function-call error while
* the working name keeps succeeding in the same request.
* 5. The bare-name Core form IS defined as a real function after
* Platform.Load("core", "1.1.5") — typeof is "function", not the
* "clrmethodinfo" marker the Platform.Function form reports — and it
* returns the same content for the same name.
* 6. The recommended replacement path is real: Platform.Function
* resolves ContentBlockByName as a host method (the documented modern
* substitute for classic Content Areas).
*
* NOT ASSERTED: that the Salesforce deprecation notice has any runtime
* effect. Deprecation is a documentation fact; nothing observable in this
* request distinguishes a deprecated member from a supported one.
*
* EXPECTED OUTPUT: every line starts with PASS.
*/
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");
}
/* Fixture: create a Content Area and read its stored Name back. */
var prox = new Script.Util.WSProxy();
var caName = "ssjsg-ca-" + Platform.Function.GUID().substring(0, 8);
var caBody = "BODY-" + caName;
var created = prox.createItem("ContentArea", { Name: caName, CustomerKey: caName, Content: caBody, IsDynamicContent: false });
var caId = created.Results[0].NewObjectID;
var readBack = prox.retrieve("ContentArea", ["ID", "Name", "CustomerKey"], { Property: "ID", SimpleOperator: "equals", Value: caId });
assert("the fixture's stored Name reads back as created", String(readBack.Results[0].Name), caName);
/* 1-3. Name shapes that resolve. */
assert("the verified name returns the content", String(Platform.Function.ContentAreaByName(caName)), caBody);
assert("matching is case-insensitive", String(Platform.Function.ContentAreaByName(caName.toUpperCase())), caBody);
assert("the folder-path form resolves too", String(Platform.Function.ContentAreaByName("my contents\\" + caName)), caBody);
/* 4. Name shapes that do not resolve. */
assertThrows("the CustomerKey is not accepted in place of the Name", function () {
return Platform.Function.ContentAreaByName(String(readBack.Results[0].CustomerKey) + "-not-a-name");
});
assertThrows("a space-padded name throws", function () {
return Platform.Function.ContentAreaByName(" " + caName + " ");
});
assertThrows("an unknown name throws", function () {
return Platform.Function.ContentAreaByName("zzz-no-such-content-area");
});
/* 5. The bare-name Core form behaves identically. */
assert("typeof the bare-name ContentAreaByName is function after Platform.Load", String(typeof ContentAreaByName), "function");
assert("the bare-name form returns the same content", String(ContentAreaByName(caName)), caBody);
/* 6. The documented modern replacement resolves as a host method. */
assert("typeof Platform.Function.ContentBlockByName is clrmethodinfo", String(typeof Platform.Function.ContentBlockByName), "clrmethodinfo");
/* Cleanup. */
prox.deleteItem("ContentArea", { ID: caId });
</script>
Examples
The single-argument form works when the name resolves to an existing Content Area:
// returns the content area's rendered markup
var content = Platform.Function.ContentAreaByName("myContentArea");
Platform.Response.Write(content);
The documented 4-argument form does not — it is shown as the documented shape, not as working code:
// throws: A ContentAreaByName function call includes an invalid parameter value.
// … Parameter Name: ImpressionRegionName
var content = Platform.Function.ContentAreaByName("myContentArea", "impressionRegion", false, "Fallback text here");
Platform.Response.Write(content);
For new content, use Platform.Function.ContentBlockByName() instead.
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Examples — the working single-argument example, the documented
* 4-argument example, and the replacement.
*
* Proves:
* 1. Example 1, the plain 1-argument call, returns the content area's
* markup exactly as the docs show — provided the name resolves.
* 2. DEV example 2, the full 4-argument call, throws — the documented
* fallbackContent is never written to the response.
* 3. Because that call throws, the variable it assigns to stays
* undefined and the fallback string is not the result.
* 4. The page's recommended replacement,
* Platform.Function.ContentBlockByName, resolves as a host CLR method.
*
* NOT ASSERTED: whether an impression is recorded for the region. Parameter
* 2 cannot be supplied at all, and impression counts only surface in
* Marketing Cloud tracking reports after a send is processed, which is not
* observable from within this request.
*
* EXPECTED OUTPUT: every line starts with PASS.
*/
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");
}
/* Fixture: create a Content Area and read its stored Name back. */
var prox = new Script.Util.WSProxy();
var caName = "ssjsg-ca-" + Platform.Function.GUID().substring(0, 8);
var caBody = "BODY-" + caName;
var created = prox.createItem("ContentArea", { Name: caName, CustomerKey: caName, Content: caBody, IsDynamicContent: false });
var caId = created.Results[0].NewObjectID;
var readBack = prox.retrieve("ContentArea", ["ID", "Name"], { Property: "ID", SimpleOperator: "equals", Value: caId });
assert("the fixture's stored Name reads back as created", String(readBack.Results[0].Name), caName);
/* 1. Example 1 — the plain 1-argument call. */
var content1 = Platform.Function.ContentAreaByName(caName);
assert("example 1: ContentAreaByName(name) returns the content", String(content1), caBody);
/* 2. DEV example 2 — the full 4-argument call with a fallback. */
assertThrows("DEV example 2: the 4-argument call throws (docs: shows the fallback)", function () {
return Platform.Function.ContentAreaByName(caName, "impressionRegion", false, "Fallback text here");
});
/* 3. The variable that call assigns to therefore never receives a value. */
var content2;
try { content2 = Platform.Function.ContentAreaByName(caName, "impressionRegion", false, "Fallback text here"); } catch (ex2) { /* documented throw */ }
assert("example 2: the fallback is never assigned", String(typeof content2), "undefined");
assert("example 2: the fallback string is NOT the result", content2 === "Fallback text here" ? "true" : "false", "false");
/* 4. The recommended replacement resolves as a host method. */
assert("typeof Platform.Function.ContentBlockByName is clrmethodinfo", String(typeof Platform.Function.ContentBlockByName), "clrmethodinfo");
/* Cleanup. */
prox.deleteItem("ContentArea", { ID: caId });
</script>