Placeholders

Hi %PROPERTY_{PD.Contact}%,

You have %OBJTYPE_10.COUNT% assignments:
%OBJTYPE_10.FOREACH%
    - %OBJTITLE%, Deadline: %PROPERTY_42%
%NEXT%

[DataContract]
public class Configuration
{
	/// <summary>
	/// Placeholder template using default settings and placeholder commands.
	/// </summary>
	[DataMember]
	public PlaceholderTextEx Template { get; set; }
}

// New way to expand placeholders using PlaceholderTextEx methods.
string text =  conf.Template.ExpandText( env.ObjVerEx );  // Expand to text.
ExpandedPlaceholderTemplate expTemplate =
		conf.Template.Expand( env.ObjVerEx );  // Expand to model.

[DataContract]
public class Configuration
{
	/// <summary>
	/// Legacy Placeholder template property.
	/// </summary>
	/// <remarks>
	/// We can't tell which placeholder commands can be used,
	/// which settings should be used for expansion or if any extra
	/// context needs to be provided for the expansion.
	/// </remarks>
	[DataMember]
	[JsonConfEditor( TypeEditor = "placeholderText" )]
	public string Template { get; set; }
}

// Old way to expand placeholder template string, 
// using default environment and expansion settings.
string text = env.OjVerEx.ExpandPlaceholderText( conf.Template );  // Expand to text.
ExpandedPlaceholderTemplate expTemplate = 
		env.ObjVerEx.ExpandPlaceholders( conf.Template );  // Expand to model.

public class MyPlaceholderEnvironment: PlaceholderEnvironment
{
	public virtual PlaceholderTemplateSettings GetSettings( TemplateContext context )
	{
		// Modify default settings.
		PlaceholderTemplateSettings settings = base.GetSettings( context );
		settings.DefaultEncoder = new EncodeHtmlPlaceholder();
		return settings;
	}	

	protected override CommandProviders GetCommandProviders( TemplateContext context )
	{
		// Get default command providers.
		CommandProviders providers = base.GetCommandProviders( context );

		// Add placeholders for application information.
		providers.AddRange(
			new StaticContextPlaceholderProvider( "APPNAME", "ApplicationName",
					new TextContext{ ApplicationDefinition.Name } ),
			new StaticContextPlaceholderProvider( "APPVER", "ApplicationVersion",
					new TextContext{ ApplicationDefinition.Version.ToString() } ),
			new StaticContextPlaceholderProvider( "APPGUID", "ApplicationID",
					new TextContext{ ApplicationDefinition.Guid.ToString( "B" ) } ) );

		return providers;
	}
}

[DataContract]
public class Configuration
{
	/// <summary>
	/// Placeholder template with my custom settings and placeholders.
	/// </summary>
	[DataMember]
	public PlaceholderTextEx<MyPlaceholderEnvironment> Template { get; set; }
}


// The new expansion calls no longer need to be aware of the correct settings or placeholders
// they are already defined in the Template's type and will be used automatically.
string text =  conf.Template.ExpandText( env.ObjVerEx );
ExpandedPlaceholderTemplate expTemplate = conf.Template.Expand( env.ObjVerEx );

/// <summary>
/// Custom context for providing current user/employee to use when expanding placeholders.
/// </summary>
public class CurrentUserContext : TemplateContext
{
	public int? CurrentUserId { get; set; }

	public ObjVerEx CurrentEmployee { get; set; }

	public static CurrentUserContext Create(
		EventHandlerEnvironment env,
		MFIdentifier employeeObjType,
		MFIdentifier userPropDef,
	)
	{
		return new CurrentUserContext()
		{
			Vault = env.Vault,
			Target = env.ObjVerEx,
			CurrentUserId = env.CurrentUserID,
			CurrentEmployee = new MFSearchBuilder( env.Vault )
					.ObjType( employeeObjType )
					.Property( userPropDef, MFDataType.MFDatatypeLookup, env.CurrentUserID )
					.FindOneEx()
		};
	}
}

/// <summary>
/// Custom placeholders including current user/employee.
/// </summary>
public class CurrentUserPlaceholders : PlaceholderEnvironment<CurrentUserContext>
{
	protected override CommandProviders GetCommandProviders( CurrentUserContext context )
	{
		// Get default command providers.
		CommandProviders providers = base.GetCommandProviders( context );

		// Add placeholders for application information.
		providers.AddRange(
			new StaticContextPlaceholderProvider( "CURRENTUSER", "CurrentUser", 
					new UserAccountContext( context?.CurrentUserId ) ),
			new StaticContextPlaceholderProvider( "CURRENTEMPLOYEE", "CurrentEmployee", 
					new ObjectContext { context?.CurrentEmployee } ) );

		return providers;
	}
}

[DataContract]
public class Configuration
{
	/// <summary>
	/// Reference to the employee object type that holds additional information about vault users.
	/// </summary>
	[DataMember]
	[MFObjType]
	public MFIdentifier EmployeeObjType { get; set; }

	/// <summary>
	/// Reference to the property def that holds the associated vault user on UserObjType objects.
	/// </summary>
	[DataMember]
	[MFPropertyDef]
	public MFIdentifier UserPropDef { get; set; }

	/// <summary>
	/// Placeholder template with my custom settings and placeholders.
	/// </summary>
	[DataMember]
	public PlaceholderTextEx<CurrentUserPlaceholders, CurrentUserContext> Template { get; set; }
}

// The new expansion calls no longer need to be aware of the correct settings or placeholders
// they are already defined in the Template's type and will be used automatically.
var context = TemplateContextWithCurrentUser.Create( env, conf.EmployeeObjType, conf.UserPropDef );
string text =  conf.Template.ExpandText( context );
ExpandedPlaceholderTemplate expTemplate = conf.Template.Expand( context );

/// <summary>
/// A custom placholder template context allowing custom culture
/// and formats to be passed in at expansion time.
/// </summary>
public class FormattableContext : TemplateContext
{
	public PlaceholderFormatter Formatter { get; set; }
}

/// <summary>
/// Placeholder environment with an additional FORMAT command,
/// that also allows custom culture and date formatting to be specified.
/// </summary>
public class FormattableEnv : PlaceholderEnvironment<FormattableContext>
{
	public override PlaceholderTemplateSettings GetSettings( FormattableContext context )
	{
		// Update settings with the culture from the context.
		PlaceholderTemplateSettings settings = base.GetSettings( context );
		if( context?.Formatter != null )
			settings.Formatter = context.Formatter;
		return settings;
	}

	protected override CommandProviders GetCommandProviders( FormattableContext context )
	{
		// Get default providers.
		CommandProviders providers = base.GetCommandProviders( context );

		// Include FORMAT command provider.
		providers.Add( new PlaceholderCommandProvider<FormatPlaceholder>( "FORMAT", "Format" ) );

		return providers;
	}
}


/// <summary>
/// Configuration that allows specifying a placeholder template and
/// the culture and date format to use when expanded.
/// </summary>
[DataContract]
public class Configuration
{
	[DataMember]
	[JsonConfEditor( HelpText = "The culture to use when expanding the template (and formating values). " +
			"Try things like 'EN-US', 'EN-GB' or 'FI-FI'.  If empty the default server culture will be used." )]
	public string Culture { get; set; }

	[DataMember]
	public string TimestampFormat { get; set; }

	[DataMember]
	public PlaceholderTextEx Template { get; set; }

	public string ExpandPlaceholderTemplate( ObjVerEx objVerEx )
	{
		// Create context.
		var context = new FormattableContext()
		{
			Vault = vault,
			Target = ObjVerEx.Latest( vault, this.Object.ObjID ),
			Formatter = new PlaceholderFormatter()
		};

		// Set the custom culture if provided.
		if( !string.IsNullOrEmpty( this.Culture ) )
			context.Formatter.Culture = CultureInfo.CreateSpecificCulture( this.Culture );

		// Set the custom date format if provided.
		if( !string.IsNullOrWhiteSpace( this.TimestampFormat ) )
			context.Formatter.TimestampFormat = this.TimestampFormat;

		// Expand.
		return this.Template.ExpandText( context );
	}
}

// Call configuration expansion method with following values:
// Culture: "DE-de"
// TimestampFormat: "D"
// Template: "Modified: %PROPERTY_21%, Value: %PROPERTY_{PD.Value}.FORMAT_{C}%"
conf.ExpandPlaceholderTemplate( objVerEx ); 
// -> "Modified: Dienstag, 12. M?rz 2024, Value: 600,00 ?"

// Override TimestampFormat defined in configuration/settings with FORMAT command. 
// (Underscores are used for spaces, literal underscores must be escaped with backslash.)
// Template: "Modified: %PROPERTY_21.FORMAT_{ddd,_dd\_MMM\_yy}%, Value: %PROPERTY_{PD.Value}.FORMAT_{C}%"
conf.ExpandPlaceholderTemplate( objVerEx ); 
// -> "Modified: : Di, 12_Mrz_24, Value: 600,00 ?"

/// <summary>
/// Custom placeholder command that calculates the average of the values it receives.
/// </summary>
public class AveragePlaceholder : PlaceholderCommandHandler
{
	/// <summary>
	/// The expansion context types the command can take as input.
	/// </summary>
	/// <remarks>
	/// Works on either float or integer contexts.
	/// </remarks>
	public override ExpansionContextType[] AcceptsContextTypes =>
			new ExpansionContextType[] { ExpansionContextType.Float, ExpansionContextType.Integer };

	/// <summary>
	/// The expansion context type the command emits.
	/// </summary>
	/// <remarks>
	/// Always outputs float context.
	/// </remarks>
	public override ExpansionContextType ContextType => ExpansionContextType.Float;

	/// <summary>
	/// The type of command this is.
	/// </summary>
	/// <remarks>
	/// Simple command only. No arguments allowed!
	/// </remarks>
	protected override PlaceholderLevelType[] SupportedTypes =>
			new PlaceholderLevelType[] { PlaceholderLevelType.Simple };

	/// <summary>
	/// Expands the placeholder level based on the input context.
	/// </summary>
	/// <remarks>
	/// Calculates the average of the values in the input context.
	/// </remarks>
	/// <param name="input">The expansion context.</param>
	/// <param name="cache">The object cache.</param>
	/// <returns><see cref="ExpandedLevel"/></returns>
	public override ExpandedLevel Expand(
		IExpansionContext input,
		ObjVerExReadCache cache
	)
	{
		// Calculate average base on input type.
		var output = new FloatContext();
		List<PlaceholderExpansionIssue> issues = null;
		if( input is FloatContext floatInput && input.Count > 0)
		{
			// Average floats.
			output.Add( floatInput.SafeCast<double>().Average() );
		}
		else if( input is IntegerContext intInput && input.Count > 0)
		{
			// Average integers.
			output.Add( intInput.SafeCast<int>().Average() );
		}

		// Return an exanded level holding the output and/or issues.
		return new ExpandedLevel( this.Level, input, output, null, issues );
	}
}

/// <summary>
/// Custom template context that takes a list of review values given.
/// <summary>
public class ReviewContext : TemplateContext
{
	/// <summary>
	/// List of review values.
	/// <summary>
	/// <remarks>
	/// This is used to provide a set of integer values that we can
	/// use our custom AveragePlaceholder with clearly in  the example code.
	/// The set of values could just as easily come from a property value
	/// on a set of objects.
	/// <remarks>
	public IntegerContext StarReviews { get; set; }
}

/// <summary>
/// Custom placeholder environment that takes requires the ReviewContext for expansion
/// and that exposes the built-in CountPlaceholder as the COUNT command,
/// our newly created AveragePlaceholder as the AVG command,
/// and the static StarReviews value passed in the ReviewContext as the STARS command.
/// <summary>
public class ReviewPlaceholders : PlaceholderEnvironment<ReviewContext>
{
	protected override CommandProviders GetCommandProviders( ReviewContext context )
	{
		return new CommandProviders
		{
			new PlaceholderCommandProvider<AveragePlaceholder>( "AVG", "Avg" ),
			new PlaceholderCommandProvider<CountPlaceholder>( "COUNT", "Count" ),
			new StaticContextPlaceholderProvider( "STARS", "Stars", context.StarReviews )
		};
	}
}

[DataContract]
public class Configuration
{
	/// <summary>
	/// Placeholder property whose type plainly reveals it is intended to be used
	/// with our custom ReviewPlaceholders environment and custom ReviewContext.
	/// <summary>
	[DataMember]
	public PlaceholderTextEx<ReviewPlaceholders, ReviewContext> Template { get; set; }
}

// Usage.
var conf = new Configuration { Template = "%STARS.AVG% Stars / %STARS.COUNT% Reviews" };
var context = new ReviewContext { StarReviews = new IntegerContext { 4, 3, 5, 1, 4, 2, 4, 5 } };
string reviewSummary = conf.Template.ExpandText( context );  // OUTPUTS: "3.5 Stars / 8 Reviews"

/// <summary>
/// Placeholder command that outputs the ambient context if it is an object,
/// otherwise an empty object context.
/// </summary>
public class SelfPlaceholder : PlaceholderCommandHandler
{
	/// <summary>
	/// The expansion context types the command can take as input.
	/// </summary>
	public override ExpansionContextType[] AcceptsContextTypes => new [] { ExpansionContextType.None };

	/// <summary>
	/// The expansion context type the command emits.
	/// </summary>
	public override ExpansionContextType ContextType => ExpansionContextType.Object;

	/// <summary>
	/// The type of command this is.
	/// </summary>
	protected override PlaceholderLevelType[] SupportedTypes => new [] { PlaceholderLevelType.Simple };

	/// <summary>
	/// Expands the placeholder level based on the input context.
	/// </summary>
	/// <param name="input">The expansion context.</param>
	/// <param name="cache">The object cache.</param>
	/// <returns><see cref="ExpandedLevel"/></returns>
	public override ExpandedLevel Expand(
		IExpansionContext input,
		ObjVerExReadCache cache
	)
	{
		// We can only receive the abmient context because our input type is none.
		// If the ambient context is an object, return it as the output, otherwise
		// return an empty object context as there is no "self" to return.
		IExpansionContext output = ( input.Clone() as ObjectContext )?.Clone() ?? new ObjectContext();
			
		// Return an exanded level holding the output and/or issues.
		return new ExpandedLevel( this.Level, input, output, null, null );
	}

	/// <summary>
	/// Gets the client definitions for this handler.
	/// </summary>
	/// <param name="commandName">The command name.</param>
	/// <param name="displayName">The display name.</param>
	/// <returns>Client command definitions.</returns>
	public override IEnumerable<ClientPlaceholderCommand> GetClientDefinitions(
		string commandName,
		string displayName
	)
	{
		// Generate definitions as normal, then augment each before returning.
		foreach( ClientPlaceholderCommand cmd in base.GetClientDefinitions( commandName, displayName ) )
		{
			// Make the command unchainable and return.
			cmd.Chainable = false;
			yield return cmd;
		}
	}
}

/// <summary>
/// Placeholder environment for defining/resolving object references from a target object.
/// </summary>
public class ObjectRefsEnv: PlaceholderEnvironment
{
	protected override CommandProviders GetCommandProviders( TemplateContext context )
	{
		// Only provide commands that can yield object references,
		// or can be chained to commands that yield object references.
		return new CommandProviders
		{
			new PlaceholderCommandProvider<PropertyPlaceholder>( "PROPERTY", "Property" ),
			new PlaceholderCommandProvider<ObjTypePlaceholder>( "OBJTYPE", "ObjType" ),
			new PlaceholderCommandProvider<SelfPlaceholder>( "SELF", "Self" ),
			new PlaceholderCommandProvider<ParentPlaceholder>( "PARENT", "Parent" ),
		};
	}
}

[DataContract]
public class Configuration
{
	[DataMember]
	public PlaceholderTextEx<ObjectRefsEnv> Template { get; set; }
}


// USAGE: Resolve references of a single object.
var objRefs = this.Template.Expand( objVerEx ).GetExpandedValues<ObjVerEx>().ToHashSet();

// USAGE: Resolve refererences of many objects efficiently.
// - We parse the template only once using a null context, as nothing special is needed.
// - Use a common cache so objects are only ever loaded once even if referenced by multiple objects.
PlaceholderTemplate parsedTemplate = this.Template.CreateTemplate( null );
var cache = new ObjVerExReadCache( vault );
foreach( ObjVerEx objVerEx in targets ) {
	var objRefs = parsedTemplate.Expand( objVerEx ).GetExpandedValues<ObjVerEx>().ToHashSet();
	// ...do something with refs.
}

/// <summary>
/// Gets the client definitions for this handler.
/// </summary>
/// <param name="commandName">The command name.</param>
/// <param name="displayName">The display name.</param>
/// <returns>Client command definitions.</returns>
public override IEnumerable<ClientPlaceholderCommand> GetClientDefinitions(
	string commandName,
	string displayName
)
{
	// Generate definitions as normal, then augment each before returning.
	foreach( ClientPlaceholderCommand cmd in base.GetClientDefinitions( commandName, displayName ) )
	{
		// Include the user string constructor, so the editor knows to allow
		// generating options with a custom user string from the reference panel.
		cmd.OptionConstructor = ClientPlaceholderOptionConstructor.UserString;
		yield return cmd;
	}
}

/// <summary>
/// Gets the client command definitions matching the environment's available placeholders command handlers.
/// These are used by MFAdmin's placeholder tempate editor, so it can suggest the correct placeholders
/// in the correct places and do some basic client-side validation.
/// </summary>
/// <param name="context">The context of the request.</param>
/// <returns>The client command definitions available in this environment.</returns>
public virtual IEnumerable<ClientPlaceholderCommand> GetClientCommandDefinitions(
	IConfigurationRequestContext context
)
{
	// Prevent all commands from being chainable.
	foreach( ClientPlaceholderCommand cmd in base.GetClientCommandDefinitions( context ) ) {
	
		// Make the command unchainable and return.
		cmd.Chainable = false;
		yield return def;
	}
}