Handling Embedded Files in Content

Former Member — Tue, 04 Aug 2020 21:53:26 GMT

Current Revision posted to Developer Training by Former Member on 08/04/2020 21:53:26

When creating [[Creating Custom Applications and Content|custom content types]] to the Verint Community platform and utilizing the platform editor within the UI managing that content (using the [[api-documentation:core_v2_editor script api|$core_v2_editor widget API]]), the editor will allow drag-and-drop and menu-based file uploading into the HTML content if that content supports embedded files.

[toc]

Why Would I Want to Enable Embedded Files?

Embedded files are useful when authoring rich formatted content (HTML) to allow inclusion of images, videos, documents, and other media and files to provide more flexibility and interactivity.

Implementing Support for Embedded Files

To add support for embedded files within a [[Creating Custom Applications and Content|custom content type]], the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]] plugin type should also be implemented on your content type (which requires a reference to Telligent.Evolution.Core.dll). The IFileEmbeddableContentType interface extends [[api-documentation:IContentType Plugin Type|IContentType]] to add members that enable the content type to interact with the Verint Community platform regarding embedded files.

Basic Implementation

Because an implementation of IFileEmbeddableContentType is dependent on a custom content type which is out-of-scope for this topic, I'll show examples from private messaging in the core platform.

We'll implement the IFileEmbeddedContentType, which requires two members to be implemented. First, CanAddFiles() identifies whether a user can add files to this content type:

public bool CanAddFiles(int userId)
{
	var user = Users.GetUser(userId);
	if (user == null || user.IsAnonymous)
		return false;

	return true;
}

For private messaging, any non-anonymous user can embed files. For other applications, the ability to embed files may be dependent on the application or container/group the content is being created within. To detect the context of the request, the current page's context can be retrieved by analyzing [[api-documentation:Url In-Process API Service|Url.CurrentContext]] or using another mechanism for detecting the context of the CanAddFiles() request.

When CanAddFiles() returns true, file embedding functionality within the platform content editor will be enabled, otherwise, these functions will not be available.

The only remaining requirement for an IFileEmbeddableContentType implementation is the SetController() method:

private IFileEmbeddableContentTypeController _embeddedFileController;

public void SetController(IFileEmbeddableContentTypeController controller)
{
	_embeddedFileController = controller;
}

This method provides the plugin with a controller enabling the extraction and reassignment of embedded files within HTML content.

Using the Controller to Process Files

When files are uploaded through the editor, they're placed in a temporary file store within the [[Centralized File Storage|Centralized File System]]. Files placed in this temporary location are only accessible to the user who uploaded them and are automatically deleted after 2 hours (by default) of inactivity. Content supporting embedded files should move this temporary content to a final storage location suitably secured for the content type. To implement the movement of files to a final storage location, [[Handling Events|events]] related to the creation or editing of content should be handled and the [[api-documentation:IFileEmbeddableContentTypeController Plugin Supplementary Type|IFileEmbeddableContentTypeController]] provided to the plugin through the SetController() method should be used.

For private messaging, we attach handlers to the BeforeCreate event (since private messages do not support editing, otherwise, we'd also want to handle edit-events). As with all [[Plugins|plugins]], we [[Handling Events|register the event handler]] in the [[api-documentation:IPlugin Plugin Type|Initialize() method of IPlugin]]:

public void Initialize()
{
    var conversationMessageApi = Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IConversationMessages>();
	
	conversationMessageApi.Events.BeforeCreate += ConversationMessage_BeforeCreate;
    
    // other event handlers used for this plugin
}

void ConversationMessage_BeforeCreate(ConversationMessageBeforeCreateEventArgs e)
{
    if (_embeddedFileController == null)
		return;

	var hasPermission = CanAddFiles(e.Author.Id.Value);
	var targetFileStore = Telligent.Evolution.Extensibility.Storage.Version1.CentralizedFileStorage.GetFileStore("conversationfiles");

	e.Body = _embeddedFileController.SaveFilesInHtml(e.Body, f => {
		if (!hasPermission)
			_embeddedFileController.InvalidFile(f, "You do not have permission to add files to private messages");

		string message;
		if (!IsFileValid(e.Author.Id.Value, f.FileName, f.ContentLength, true, out message))
			EmbeddedFileController.InvalidFile(f, message);

		using (var stream = f.OpenReadStream())
		{
			var targetFile = targetFileStore.AddFile(e.ConversationId.Value.ToString("N"), f.FileName, stream, true);
			if (targetFile != null)
				return targetFile;
			else
				_embeddedFileController.InvalidFile(f, "An error occurred while saving an embedded file.");
		}

		return null;
	});
}

In the event handler, ConversationMessage_BeforeCreate, we retrieve the target [[Centralized File Storage|CFS]] file store, conversationfiles, using the [[api-documentation:CentralizedFileStorage In-Process API Service|CentralizedFileStorage API]] -- this is where valid files will be moved. Then, we use the [[api-documentation:IFileEmbeddableContentTypeController Plugin Supplementary Type|controller's SaveFilesInHtml() method]] to process each file found within the body (e.Body) of the private message. If we wanted to support embedding files in other properties of the message (in this case, there are none), we would call SaveFilesInHtml() for each property.

SaveFilesInHtml() calls the function defined by the last parameter to the method call for each temporary file in the provided content (in this case, e.Body). For each file, we'll verify the user has permission to save files and validate the file type (via the IsFileValid() method which would be defined in this plugin as well but is out-of-scope for this discussion -- it reviews the file details and returns false and sets the out message parameter if a the file is invalid). If there is an issue with any file (one of the validation procedures fails), we call [[api-documentation:IFileEmbeddableContentTypeController Plugin Supplementary Type|InvalidFile() on the controller]]. This stops processing and reports the provided message back to the user. In production code (this sample is a simplification), we'd want to ensure that this text is [[Translating Plugin Text|properly translated]].

After validating the file is valid, we'll move it to the proper target file store by calling [[api-documentation:ICentralizedFileStorageProvider In-Process API Supplementary Type|AddFile() on the target CFS file store]]. This will return the resulting [[api-documentation:ICentralizedFile In-Process API Supplementary Type|ICentralizedFile]] which then must be provided back to the controller.

SaveFileInHtml() returns the updated HTML with all temporary embedded files appropriately moved. This value should be saved back to the content. For private messages, we set e.Body to the new value and, because this is in the BeforeCreate event, the updates will be committed normally (if we processed content in AfterCreate, for example, the content would have already been committed and we'd need to explicitly save the updated value).

UI Considerations

To ensure that the content editor is aware of the type of content being edited and to enable the editor to detect if file embedding is supported, it is important that when rendering the editor through [[api-documentation:core_v2_editor script api|$core_v2_editor.Render()]] in a [[Widgets|widget]], that the ContentTypeId is specified. This identifier should match the ContentTypeId identified by the [[api-documentation:IContentType Plugin Type|IContentType]] implementation of the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]]. Without this option specified, the editor will not know what type of content is being edited and will never enable file embedding.

Tags: IFileEmbeddableContentType

Handling Embedded Files in Content

Former Member — Tue, 04 Aug 2020 21:52:58 GMT

Revision 4 posted to Developer Training by Former Member on 08/04/2020 21:52:58

[toc]

Why Would I Want to Enable Embedded Files?

Embedded files are useful when authoring rich formatted content (HTML) to allow inclusion of images, videos, documents, and other media and files to provide more flexibility and interactivity.

Implementing Support for Embedded Files

Basic Implementation

Because an implementation of IFileEmbeddableContentType is dependent on a custom content type which is out-of-scope for this topic, I'll show examples from private messaging in the core platform.

We'll implement the IFileEmbeddedContentType, which requires two members to be implemented. First, CanAddFiles() identifies whether a user can add files to this content type:

public bool CanAddFiles(int userId)
{
	var user = Users.GetUser(userId);
	if (user == null || user.IsAnonymous)
		return false;

	return true;
}

When CanAddFiles() returns true, file embedding functionality within the platform content editor will be enabled, otherwise, these functions will not be available.

The only remaining requirement for an IFileEmbeddableContentType implementation is the SetController() method:

private IFileEmbeddableContentTypeController _embeddedFileController;

public void SetController(IFileEmbeddableContentTypeController controller)
{
	_embeddedFileController = controller;
}

This method provides the plugin with a controller enabling the extraction and reassignment of embedded files within HTML content.

Using the Controller to Process Files

public void Initialize()
{
    var conversationMessageApi = Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IConversationMessages>();
	
	conversationMessageApi.Events.BeforeCreate += ConversationMessage_BeforeCreate;
    
    // other event handlers used for this plugin
}

void ConversationMessage_BeforeCreate(ConversationMessageBeforeCreateEventArgs e)
{
    if (_embeddedFileController == null)
		return;

	var hasPermission = CanAddFiles(e.Author.Id.Value);
	var targetFileStore = Telligent.Evolution.Extensibility.Storage.Version1.CentralizedFileStorage.GetFileStore("conversationfiles");

	e.Body = _embeddedFileController.SaveFilesInHtml(e.Body, f => {
		if (!hasPermission)
			_embeddedFileController.InvalidFile(f, "You do not have permission to add files to private messages");

		string message;
		if (!IsFileValid(e.Author.Id.Value, f.FileName, f.ContentLength, true, out message))
			EmbeddedFileController.InvalidFile(f, message);

		using (var stream = f.OpenReadStream())
		{
			var targetFile = targetFileStore.AddFile(e.ConversationId.Value.ToString("N"), f.FileName, stream, true);
			if (targetFile != null)
				return targetFile;
			else
				_embeddedFileController.InvalidFile(f, "An error occurred while saving an embedded file.");
		}

		return null;
	});
}

UI Considerations

Handling Embedded Files in Content

Former Member — Tue, 04 Aug 2020 21:52:28 GMT

Revision 3 posted to Developer Training by Former Member on 08/04/2020 21:52:28

[toc]

Why Would I Want to Enable Embedded Files?

Embedded files are useful when authoring rich formatted content (HTML) to allow inclusion of images, videos, documents, and other media and files to provide more flexibility and interactivity.

Implementing Support for Embedded Files

Basic Implementation

Because an implementation of IFileEmbeddableContentType is dependent on a custom content type which is out-of-scope for this topic, I'll show examples from private messaging in the core platform.

We'll implement the IFileEmbeddedContentType, which requires two members to be implemented. First, CanAddFiles() identifies whether a user can add files to this content type:

public bool CanAddFiles(int userId)
{
	var user = Users.GetUser(userId);
	if (user == null || user.IsAnonymous)
		return false;

	return true;
}

When CanAddFiles() returns true, file embedding functionality within the platform content editor will be enabled, otherwise, these functions will not be available.

The only remaining requirement for an IFileEmbeddableContentType implementation is the SetController() method:

private IFileEmbeddableContentTypeController _embeddedFileController;

public void SetController(IFileEmbeddableContentTypeController controller)
{
	_embeddedFileController = controller;
}

This method provides the plugin with a controller enabling the extraction and reassignment of embedded files within HTML content.

Using the Controller to Process Files

public void Initialize()
{
    var conversationMessageApi = Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IConversationMessages>();
	
	conversationMessageApi.Events.BeforeCreate += ConversationMessage_BeforeCreate;
    
    // other event handlers used for this plugin
}

void ConversationMessage_BeforeCreate(ConversationMessageBeforeCreateEventArgs e)
{
    if (_embeddedFileController == null)
		return;

	var hasPermission = CanAddFiles(e.Author.Id.Value);
	var targetFileStore = Telligent.Evolution.Extensibility.Storage.Version1.CentralizedFileStorage.GetFileStore("conversationfiles");

	e.Body = _embeddedFileController.SaveFilesInHtml(e.Body, f => {
		if (!hasPermission)
			_embeddedFileController.InvalidFile(f, "You do not have permission to add files to private messages");

		string message;
		if (!IsFileValid(e.Author.Id.Value, f.FileName, f.ContentLength, true, out message))
			EmbeddedFileController.InvalidFile(f, message);

		using (var stream = f.OpenReadStream())
		{
			var targetFile = targetFileStore.AddFile(e.ConversationId.Value.ToString("N"), f.FileName, stream, true);
			if (targetFile != null)
				return targetFile;
			else
				_embeddedFileController.InvalidFile(f, "An error occurred while saving an embedded file.");
		}

		return null;
	});
}

UI Considerations

To ensure that the content editor is aware of the type of content being edited and to enable the editor to detect if file embedding is supported, it is important that when rendering the editor through [[api-documentation:core_v2_editor script api#Render|$core_v2_editor.Render()]] in a [[Widgets|widget]], that the ContentTypeId is specified. This identifier should match the ContentTypeId identified by the [[api-documentation:IContentType Plugin Type|IContentType]] implementation of the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]]. Without this option specified, the editor will not know what type of content is being edited and will never enable file embedding.

Handling Embedded Files in Content

Former Member — Tue, 04 Aug 2020 21:51:56 GMT

Revision 2 posted to Developer Training by Former Member on 08/04/2020 21:51:56

When creating [[Creating Custom Applications and Content|custom content types]] to the Verint Community platform and utilizing the platform editor within the UI managing that content (using the [[api-documentation:core v2 editor script api|$core_v2_editor widget API]]), the editor will allow drag-and-drop and menu-based file uploading into the HTML content if that content supports embedded files.

[toc]

Why Would I Want to Enable Embedded Files?

Embedded files are useful when authoring rich formatted content (HTML) to allow inclusion of images, videos, documents, and other media and files to provide more flexibility and interactivity.

Implementing Support for Embedded Files

Basic Implementation

Because an implementation of IFileEmbeddableContentType is dependent on a custom content type which is out-of-scope for this topic, I'll show examples from private messaging in the core platform.

We'll implement the IFileEmbeddedContentType, which requires two members to be implemented. First, CanAddFiles() identifies whether a user can add files to this content type:

public bool CanAddFiles(int userId)
{
	var user = Users.GetUser(userId);
	if (user == null || user.IsAnonymous)
		return false;

	return true;
}

When CanAddFiles() returns true, file embedding functionality within the platform content editor will be enabled, otherwise, these functions will not be available.

The only remaining requirement for an IFileEmbeddableContentType implementation is the SetController() method:

private IFileEmbeddableContentTypeController _embeddedFileController;

public void SetController(IFileEmbeddableContentTypeController controller)
{
	_embeddedFileController = controller;
}

This method provides the plugin with a controller enabling the extraction and reassignment of embedded files within HTML content.

Using the Controller to Process Files

public void Initialize()
{
    var conversationMessageApi = Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IConversationMessages>();
	
	conversationMessageApi.Events.BeforeCreate += ConversationMessage_BeforeCreate;
    
    // other event handlers used for this plugin
}

void ConversationMessage_BeforeCreate(ConversationMessageBeforeCreateEventArgs e)
{
    if (_embeddedFileController == null)
		return;

	var hasPermission = CanAddFiles(e.Author.Id.Value);
	var targetFileStore = Telligent.Evolution.Extensibility.Storage.Version1.CentralizedFileStorage.GetFileStore("conversationfiles");

	e.Body = _embeddedFileController.SaveFilesInHtml(e.Body, f => {
		if (!hasPermission)
			_embeddedFileController.InvalidFile(f, "You do not have permission to add files to private messages");

		string message;
		if (!IsFileValid(e.Author.Id.Value, f.FileName, f.ContentLength, true, out message))
			EmbeddedFileController.InvalidFile(f, message);

		using (var stream = f.OpenReadStream())
		{
			var targetFile = targetFileStore.AddFile(e.ConversationId.Value.ToString("N"), f.FileName, stream, true);
			if (targetFile != null)
				return targetFile;
			else
				_embeddedFileController.InvalidFile(f, "An error occurred while saving an embedded file.");
		}

		return null;
	});
}

UI Considerations

To ensure that the content editor is aware of the type of content being edited and to enable the editor to detect if file embedding is supported, it is important that when rendering the editor through [[api-documentation:core v2 editor script api#Render$core_v2_editor.Render()]] in a [[Widgets|widget]], that the ContentTypeId is specified. This identifier should match the ContentTypeId identified by the [[api-documentation:IContentType Plugin Type|IContentType]] implementation of the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]]. Without this option specified, the editor will not know what type of content is being edited and will never enable file embedding.

Handling Embedded Files in Content

Ben Tiedt — Thu, 13 Jun 2019 19:28:51 GMT

Revision 1 posted to Developer Training by Ben Tiedt on 06/13/2019 19:28:51

When creating [[Creating Custom Applications and Content|custom content types]] to the Telligent Community platform and utilizing the platform editor within the UI managing that content (using the [[api-documentation:core v2 editor widget extension|$core_v2_editor widget API]]), the editor will allow drag-and-drop and menu-based file uploading into the HTML content if that content supports embedded files.

[toc]

Why Would I Want to Enable Embedded Files?

Embedded files are useful when authoring rich formatted content (HTML) to allow inclusion of images, videos, documents, and other media and files to provide more flexibility and interactivity.

Implementing Support for Embedded Files

To add support for embedded files within a [[Creating Custom Applications and Content|custom content type]], the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]] plugin type should also be implemented on your content type (which requires a reference to Telligent.Evolution.Core.dll). The IFileEmbeddableContentType interface extends [[api-documentation:IContentType Plugin Type|IContentType]] to add members that enable the content type to interact with the Telligent Community platform regarding embedded files.

Basic Implementation

Because an implementation of IFileEmbeddableContentType is dependent on a custom content type which is out-of-scope for this topic, I'll show examples from private messaging in the core platform.

We'll implement the IFileEmbeddedContentType, which requires two members to be implemented. First, CanAddFiles() identifies whether a user can add files to this content type:

public bool CanAddFiles(int userId)
{
	var user = Users.GetUser(userId);
	if (user == null || user.IsAnonymous)
		return false;

	return true;
}

When CanAddFiles() returns true, file embedding functionality within the platform content editor will be enabled, otherwise, these functions will not be available.

The only remaining requirement for an IFileEmbeddableContentType implementation is the SetController() method:

private IFileEmbeddableContentTypeController _embeddedFileController;

public void SetController(IFileEmbeddableContentTypeController controller)
{
	_embeddedFileController = controller;
}

This method provides the plugin with a controller enabling the extraction and reassignment of embedded files within HTML content.

Using the Controller to Process Files

public void Initialize()
{
    var conversationMessageApi = Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IConversationMessages>();
	
	conversationMessageApi.Events.BeforeCreate += ConversationMessage_BeforeCreate;
    
    // other event handlers used for this plugin
}

void ConversationMessage_BeforeCreate(ConversationMessageBeforeCreateEventArgs e)
{
    if (_embeddedFileController == null)
		return;

	var hasPermission = CanAddFiles(e.Author.Id.Value);
	var targetFileStore = Telligent.Evolution.Extensibility.Storage.Version1.CentralizedFileStorage.GetFileStore("conversationfiles");

	e.Body = _embeddedFileController.SaveFilesInHtml(e.Body, f => {
		if (!hasPermission)
			_embeddedFileController.InvalidFile(f, "You do not have permission to add files to private messages");

		string message;
		if (!IsFileValid(e.Author.Id.Value, f.FileName, f.ContentLength, true, out message))
			EmbeddedFileController.InvalidFile(f, message);

		using (var stream = f.OpenReadStream())
		{
			var targetFile = targetFileStore.AddFile(e.ConversationId.Value.ToString("N"), f.FileName, stream, true);
			if (targetFile != null)
				return targetFile;
			else
				_embeddedFileController.InvalidFile(f, "An error occurred while saving an embedded file.");
		}

		return null;
	});
}

UI Considerations

To ensure that the content editor is aware of the type of content being edited and to enable the editor to detect if file embedding is supported, it is important that when rendering the editor through [[api-documentation:core v2 editor widget extension|$core_v2_editor.Render()]] in a [[Widgets|widget]], that the ContentTypeId is specified. This identifier should match the ContentTypeId identified by the [[api-documentation:IContentType Plugin Type|IContentType]] implementation of the [[api-documentation:IFileEmbeddableContentType Plugin Type|IFileEmbeddableContentType]]. Without this option specified, the editor will not know what type of content is being edited and will never enable file embedding.