Pict Template

▶ Read the Pict-Template Documentation — interactive docs with the full API reference.

The base class for Pict template expressions. Extend this class to create custom template tags that are resolved by the Pict template engine. Register start/end pattern markers, override the render method, and your template expression is available in any Pict template string.

---

Features

• Custom Template Expressions - Define your own template tags with any start/end pattern markers
• Pattern Trie Matching - Patterns are registered in Pict's Precedent word tree for efficient multi-pattern parsing
• State Resolution - Built-in resolveStateFromAddress for dot-notation lookups across Record, Context, Scope, and custom root objects
• Sync and Async - Both render and renderAsync variants for synchronous and callback-based rendering
• TypeScript Definitions - Ships with .d.ts type definitions
• Service Provider Pattern - Extends fable-serviceproviderbase and registers with a Pict instance via dependency injection

Installation

npm install pict-template

Quick Start

Create a custom template expression by extending PictTemplate and overriding render:

const libPictTemplate = require('pict-template');

class UpperCaseTemplate extends libPictTemplate
{
	constructor(pFable, pOptions, pServiceHash)
	{
		super(pFable, pOptions, pServiceHash);

		// Register the pattern markers: {UP: ... :UP}
		this.addPattern('{UP:', ':UP}');
	}

	render(pTemplateHash, pRecord, pContextArray, pScope, pState)
	{
		let tmpValue = this.resolveStateFromAddress(pTemplateHash, pRecord, pContextArray, null, pScope);
		return (typeof tmpValue === 'string') ? tmpValue.toUpperCase() : '';
	}
}

// Register with Pict
const libPict = require('pict');
let _Pict = new libPict();
_Pict.addTemplate(UpperCaseTemplate);

// Use in a template string
let result = _Pict.parseTemplate('Hello, {UP:Record.Name:UP}!', { Name: 'world' });
// => "Hello, WORLD!"

How It Works

1. Your subclass calls this.addPattern(startTag, endTag) in the constructor to register pattern markers with Pict's template engine
2. When pict.parseTemplate() encounters your markers in a string, it extracts the content between them (the "template hash") and calls your render method
3. Your render method receives the hash, the data record, context array, scope, and state -- and returns a string replacement

API

render(pTemplateHash, pRecord, pContextArray, pScope, pState)

Override this method to implement your template expression logic. Returns a string.

Parameter	Type	Description
pTemplateHash	String	The content between the start and end pattern markers
pRecord	Object	The data record passed to parseTemplate
pContextArray	Array	Array of context objects accessible via Context[N]
pScope	Object	Sticky scope for carrying state across template expressions
pState	Object	Catchall state object for plumbing data through processing

renderAsync(pTemplateHash, pRecord, fCallback, pContextArray, pScope, pState)

Async variant of render. The default implementation calls render and passes the result to the callback. Override for truly asynchronous rendering.

Parameter	Type	Description
fCallback	Function	Callback receiving (error, renderedString)

addPattern(pMatchStart, pMatchEnd)

Register start and end pattern markers with Pict's template trie. Call this in your constructor.

Parameter	Type	Description
pMatchStart	String	The opening pattern marker (e.g. '{UP:')
pMatchEnd	String	The closing pattern marker (e.g. ':UP}')

resolveStateFromAddress(pAddress, pRecord, pContextArray, pRootDataObject, pScope, pState)

Resolve a value from nested objects using dot-notation. Delegates to Pict's state resolver.

Parameter	Type	Description
pAddress	String	Dot-notation path (e.g. 'Record.Name', 'Context[0].Data', 'Scope.UserValue')
pRecord	Object	The data record
pContextArray	Array	Context objects array
pRootDataObject	Object	Optional custom root data object for address resolution
pScope	Object	Scope object
pState	Object	State object

Returns the resolved value or undefined.

Address Resolution

The resolveStateFromAddress method supports these address prefixes:

Prefix	Resolves From
Record.	The pRecord data object
Context[N].	The Nth element of the pContextArray
Scope.	The pScope object
(custom)	The pRootDataObject if provided

Part of the Retold Framework

Pict Template is the base class for all template expressions in the Pict ecosystem:

• pict - UI framework (includes many built-in template expressions)
• pict-provider - Provider base class
• pict-view - View base class
• precedent - Pattern trie engine used for template matching
• fable - Application services framework

Testing

Run the test suite:

npm test

Run with coverage:

npm run coverage

Related Packages

• pict - MVC application framework
• pict-view - View base class
• fable - Application services framework

License

MIT

Contributing

Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the Retold Contributing Guide.