@mikezimm/fps-core-v7
Version:
Library of reusable core interfaces, types and constants migrated from fps-library-v2
67 lines • 4.21 kB
TypeScript
/**
* Controls how `replaceHandleBarsValues` handles handlebars whose key is missing,
* null, or undefined on the item object.
*
* 'omitAll' - If ANY value is missing, return `''` for the whole result string.
* 'empty' - Replace missing values with `''` (param stays, e.g. `&Category=`).
* 'omit' - Replace missing values with `''`, then strip those URL query params entirely.
* Intended for URL strings only.
* 'preserve' - Leave the original `{{key}}` handlebars intact for any missing values.
*/
export type THandleBarEmptyHandling = 'omitAll' | 'empty' | 'omit' | 'preserve';
/**
* Replaces `{{key}}` handlebars in a template string with matching property values from `item`.
*
* Originally handled only two replacements. Refactored to support any number of handlebars,
* specifically to support Drilldown `linkSubstitute` where multiple field values are substituted
* into a single URL string (e.g. to pre-fill a SharePoint form via query parameters).
*
* Key normalization: each `{{key}}` is trimmed and any `/` characters are removed before
* looking up the value on `item`. This is consistent with how Drilldown handles lookup columns
* (e.g. `{{AssignedTo/Title}}` becomes `AssignedToTitle`).
*
* NOTE: A similar general-purpose function exists at src/logic/Strings/handleBarsHTML.tsx
* (`replaceHTMLHandleBars`) — consider that for non-URL use cases.
*
* @param item - The list item object whose properties fill the handlebars.
* Values are coerced to string via String(). Null/undefined are treated as missing.
*
* @param handleBarString - The template string containing one or more `{{key}}` placeholders.
* Example: `"https://example.com?Title={{Title}}&Category={{Category}}"`
*
* @param emptyIfSubEmpty - Legacy parameter. When true and any substitution value is missing,
* the entire result is returned as `''`.
* Equivalent to passing `emptyHandling = 'omitAll'`.
* Ignored when `emptyHandling` is set.
*
* @param maxReplacements - Optional. Limits how many handlebars are substituted, left to right.
* Any handlebars beyond the limit are left intact as `{{key}}`.
* Omit or pass undefined to replace all handlebars.
*
* @param emptyHandling - Optional. Controls what happens when a value is missing/null/undefined.
* Each slot is handled independently — only the missing ones are affected.
*
* 'omitAll' - If ANY value is missing, return `''` for the whole string.
* Explicit equivalent of `emptyIfSubEmpty = true`.
*
* 'empty' - Substitute missing values with `''`, leaving the placeholder param in the result.
* Example: `&Category=` (empty value, param stays).
* Safe for use with URLs and plain text strings.
*
* 'omit' - Substitute missing values with `''`, then strip those entire query parameters
* from the URL result. Intended for URL strings only.
* Example: `&Category=` is removed entirely.
* Only slots with missing values are removed — all others remain intact.
*
* 'preserve' - Leave the original `{{key}}` handlebars unchanged for any missing values.
* Useful when the template may be re-processed later, or when you want
* to return the original string unchanged for unmatched fields.
*
* default - When no `emptyHandling` is set and `emptyIfSubEmpty` is false,
* behaves the same as 'preserve': missing values keep their `{{key}}` intact.
*
* @returns The substituted string, or `''` if `emptyIfSubEmpty`/`'omitAll'` is triggered.
* Returns `handleBarString` unchanged if it is not a string type.
*/
export declare function replaceHandleBarsValues(item: any, handleBarString: string, emptyIfSubEmpty: boolean, maxReplacements?: number, emptyHandling?: THandleBarEmptyHandling): string;
//# sourceMappingURL=handleBarsSub.d.ts.map