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.9
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();tipsProvider.AddTips(GetTipContexts(), null);}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 adding tips, the Sdl.Community.UsefulTips.Service first checks if they already exist in the Useful Tips collection from Studio and then attempts to add only those that are identified as new.
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 prior to updating the Useful Tips collection in Studio with the new tips from the plugin.
Note: It is required by the OS to elevate the user rights to administrator through the User Access Control (UAC), as the locale tip files that manage the Useful Tips collection in Studio reside in the SDL Trados Studio 2019+ installation directory. Only a user with administrator access rights can modify files in the installation direcotry.
UpdateHistory
The Sdl.Community.UsefulTips.Service records all attempts made to add new tips to the Useful Tips collection in Studio. This is necessary in cases where the user opted-out when responding to the message asking if they would like to proceed and update Useful Tips collection in Studio; in this case, the decision from the user will be persisted and no further attempt is made to add those tips to Studio.
Q: Where can I locate the UpdateHistory.xml and Settings.xml files of the Sdl.Community.UsefulTips.Service?
A: They are both located in the users roaming directory:
C:\Users\[username]\AppData\Roaming\SDL Community\UsefulTipsService\Settings
Note: replace [username] with your OS login account name
Q: How can the user add tips from the plugin to the Useful Tips collection in Studio if they previously opted-out to adding them?
A: The decision taken by the user to add (or otherwise) the tips from the plugin to the Useful Tips collection in Studio is persisted in the UpdateHistory.xml file. You can 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
{ /// <summary>
/// The unique Id that identifies the tip in the collection.
/// If an Id is provided then the service will first confirm if
/// it is unique in the 'Useful Tips' collection; if not a new
/// unique Id will be provided automatically.
/// </summary>
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+
///supported values [de, en, es, fr, it, ja, ko, ru, zh]</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; can be null
/// </param>
/// <param name="runasAdmin">
/// Elevate the user rights to admin; default: true. If the app environment
/// is not running with Admin rights, then the user will receive a message from
/// 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; can be null
/// </param>
/// <param name="runasAdmin">
/// Elevate the user rights to admin; default: true. If the app environment
/// is not running with Admin rights, then the user will receive a message from
/// the User Account Control (UAC) in Windows</param>
/// <returns>The number of Tips removed from the collection</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)