Translate
Overview
The Sdl.Community.UsefulTips.Service is a service provider for updating the Useful Tips that are displayed in SDL Trados Studio 2019+.
Add Sdl.Community.UsefulTips.Service to your project
Package Manager UI
1. In Solution Explorer, right-click References and choose Manage NuGet Packages
2. Choose nuget.org as the Package source, select the Browse tab, search for Sdl.Community.UsefulTips.Service, select that package in the list, and select Install:
3. Accept any license prompts.
Package Manager Console
1. Select the Tools > NuGet Package Manager > Package Manager Console menu command.
2. From the Package Manager Console, enter the command:
Install-Package Sdl.Community.UsefulTips.Service -Version 1.1.7
Examples
The following example creates an instance of the TipsProvider and adds a new Tip for a single language (i.e. en).
using System.Collections.Generic;usingSdl.Community.UsefulTipsService;usingSdl.Community.UsefulTipsService.Model;usingSdl.Community.UsefulTipsService.Services;
namespace Sdl.Community.Example.Services{public class UsefulTipsService{public void AddUsefulTips(){var tipsProvider = new TipsProvider(new PathService());tipsProvider.AddTips(GetTipContexts(), "[My Plugin Name]");}private static List<TipContext> GetTipContexts(){var tipContexts = new List<TipContext>{new TipContext{LanguageId = "en",Tips = new List<Tip>{new Tip{Category = "[the plugin name]",Context = "[the Id associated wth the plugin View]",Content = "[full path to the Markdown File]",Title = "My Tip",Description = "This is an awesome Tip",DescriptionImage = "[full path to the image file]"}}}};return tipContexts;}}}
Remarks
When SDL Trados Studio (2019+) is launched, the Sdl.Community.UsefulTips.Service checks if there are any new tips to be added from the plugin. If new tips are identified, then the service will attempt to add them to the Useful Tips collection in Studio.
Depending on whether or not Studio was launched as Administrator, the user may receive a message from the service indicating a requirement to elevate the user rights to "Administrator", to update the Useful Tips collection in Studio with the new Tips from the plugin.
Note: It is required by the system to elevate the user rights to "Administrator" through the User Access Control (UAC), as the locale tip files that manage the collection of Useful Tips in Studio are located in the SDL Trados Studio 2019+ installation directory.
UpdateHistory
The Sdl.Community.UsefulTips.Service records the attempts made to add new tips to the Useful Tips collection in Studio. This is necessary in cases where the user opts out to the message asking if they would like to proceed and update Usefule Tips collection in Studio; in this case, the decision from the user will be persisted and no further attempt is made for those tips to Studio.
Where is can I locate the UpdateHistory.xml and Settings.xml files of the Sdl.Community.UsefulTips.Service?
They are both located in users roaming directory:
Note: replace [username] with you OS login account name
C:\Users\[username]\AppData\Roaming\SDL Community\UsefulTipsService\Settings
How can the user add the tips from the plugin to the Useful Tips collection in Studio if they have previously opted out to adding them?
The decision taken by the user to add (or otherwise) the tips from the plugin to the Useful Tips collection in Studio is persised in the UpdateHistory.xml file, and also the MaxUpdateAttempts is taken from the Settings.xml file. You could simply delete the UpdateHistory.xml file, or change the UpdateAttempts property value for each record to be less than the MaxUpdateAttempts value managed in the Settings.xml
API
Model
public class TipContext
{
/// <summary>
/// The UI language Id supported by SDL Trados Studio; supported values [de, en, es, fr, it, ja, ko, ru, zh]
/// </summary>
public string LanguageId { get; set; }
/// <summary>
/// Tips available in the current language context
/// </summary>
public List<Tip> Tips { get; set; }
}
public class Tip
{
public string Id { get; set; }
/// <summary>
/// The title displayed in the 'Useful Tips' view part
/// </summary>
public string Title { get; set; }
/// <summary>
/// The description displayed in the 'Useful Tips' view
/// </summary>
public string Description { get; set; }
/// <summary>
/// Full path to the description image that is displayed in the 'Useful Tips' view part
/// </summary>
public string DescriptionImage { get; set; }
/// <summary>
/// The link text displayed in the 'Useful Tips' view part
/// </summary>
public string LinkText { get; set; }
/// <summary>
/// The view or view part Id; this ensure that the tip is only visible in that context
/// </summary>
public string Context { get; set; }
/// <summary>
/// The category used to group the Tips; recommend to use the plugin name or view name
/// </summary>
public string Category { get; set; }
/// <summary>
/// Full path to the icon
/// </summary>
public string Icon { get; set; }
/// <summary>
/// Full path to the Markdown file that is loaded when the user clicks on the 'Link Text' link
/// </summary>
public string Content { get; set; }
/// <summary>
/// Identify whether the Tip should be recognized as a new Tip
/// </summary>
public bool IsNew { get; set; }
public bool ShowOnWelcomeWizard { get; set; }
}
Properties
/// <summary>
/// The supported UI languages for SDL Trados Studio 2019+
/// </summary>
public List<string> SupportedLanguages
Methods
/// <summary>
/// Add Tips to the 'Useful Tips' collection in SDL Trados Studio 2019+
/// </summary>
/// <param name="tipContexts">A list of Tips that you would like to add to
/// the 'Useful Tips' collection in SDL Trados Studio 2019+</param>
/// <param name="applicationName">The name of the application</param>
/// <param name="runasAdmin">Elevate the user rights via the User Account
/// Control (UAC) in Windows</param>
/// <returns>The number of Tips added to 'Useful Tips' collection in SDL Trados
/// Studio 2019+</returns>
public int AddTips(List<TipContext> tipContexts, string applicationName,
bool runasAdmin = true)
/// <summary>
/// Remove Tips from the 'Useful Tips' collection in SDL Trados Studio 2019+
/// </summary>
/// <param name="tipContexts">A list of Tips that you would like to remove from
/// the 'Useful Tips' collection.</param>
/// <param name="applicationName">The name of the application</param>
/// <param name="runasAdmin">Elevate the rights via the User Account Control (UAC)
/// in Windows</param>
/// <returns>The number of Tips that were removed</returns>
public int RemoveTips(List<TipContext> tipContexts, string applicationName,
bool runasAdmin = true)
/// <summary>
/// Get all Tips from the 'Useful Tips' collection in SDL Trados Studio 2019+
/// </summary>
/// <returns>A list of Tips</returns>
public List<TipContext> GetAllTips()
/// <summary>
/// Read the Tip Contexts from the import file; required in the transaction when
/// reading in the Tips with elevated access
/// rights via UAC.
/// </summary>
/// <param name="filePath">full path to the Tips import file</param>
/// <returns>A list of Tips</returns>
public List<TipContext> ReadTipContextsImportFile(string filePath)
/// <summary>
/// Read the Tips the import file
/// </summary>
/// <param name="filePath">full path to the Tips import file</param>
/// <returns>A list of Tips</returns>
public List<Tip> ReadTipsImportFile(string filePath)
/// <summary>
/// Creates an Tips import file, required during the transaction when reading
/// in Tips with elevated access
/// rights via UAC to update the 'Tips.xml' file in the SDL Trados Studio 2019+
/// installation directory.
/// </summary>
/// <param name="filePath">full path to the Tips import file</param>
/// <param name="tips">A list of Tips used to import to the 'Useful Tips'
/// collection</param>
/// <returns>True if the file was created successfully</returns>
public bool CreateTipContextsImportFile(string filePath, List<TipContext> tips)
/// <summary>
/// Create a Tips import file
/// </summary>
/// <param name="filePath">full path to the Tips import file</param>
/// <param name="tips">A list of Tips used to import to the 'Useful Tips'
/// collection</param>
/// <returns>Returns true if successful</returns>
public bool CreateTipsImportFile(string filePath, List<Tip> tips)