diff --git a/modules/ROOT/pages/customize-icons.adoc b/modules/ROOT/pages/customize-icons.adoc index 1bf01eb29..7d3648ecb 100644 --- a/modules/ROOT/pages/customize-icons.adoc +++ b/modules/ROOT/pages/customize-icons.adoc @@ -8,14 +8,61 @@ You can customize the icons on a ThoughtSpot page using an icon sprite SVG file and load it from a Web server or CDN. -To override an icon: +== Before you begin -. Open the ThoughtSpot application page and locate the icon you want to replace. -.. Right-click on the icon and select *Inspect*. +* Identify the icons that you want to override. +.. On your ThoughtSpot instance, right-click on the icon and select *Inspect*. .. Inspect the `` element. .. Note the icon ID. -. Make sure you have SVG code for the icon that you want to use. For example, if you are using icons from an external site, copy its SVG code. -. Create an icon sprite file and add the SVG code and icon ID. The following code snippet shows how to override the chart icon (`rd-icon-chart`) on the *Answers* page. +* Add the SVG hosting domain is added to the following allowlists on the *Develop* > *Security Settings* page: +** xref:security-settings.adoc#csp-connect-src[CSP connect-src domains allowlist] +** xref:security-settings.adoc#csp-trusted-domain[CSP img-src domains allowlist] ++ +* xref:customize-icons.adoc#_try_it_out_in_the_embed_playground[Try out] the icon override code in the embed Playground. For ease of testing, the domain `cdn.jsdeliver.net` is already whitelisted on ThoughtSpot Embedded link:https://try-everywhere.thoughtspot.cloud/v2/#/everywhere/playground/search[public playground] and trial sites. + +== Create an icon override +The basic structure of an icon override file is shown in the following snippet: + +[source,svg] +---- + + + + + + +---- + +The `` portion within the `` tags is the definition of the actual drawing. + +You are defining a small icon, so it should fit within a square boundary and have a single solid color. + +There are many simple SVG icon examples available online, for example, the link:https://www.svgviewer.dev/[SVG viewer site, window=_blank]. + +You only need to copy the `` tags from your example SVG within the ` ` tags. + +=== viewBox property + +The link:https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox[viewBox property^] is in the order `min-x`, `min-y`, `width`, and `height`. + +The first two properties should be `0 0` while the second should match any `width` and `height` properties from the source of your SVG paths. + +The `width` and `height` properties may be added directly in the `` tag, or as part of `viewBox` property in that tag, or perhaps in another tag above ``. Use the values from your source SVG in the `viewBox` property of the `` element within your override file. + +=== fill property +You can add the `fill` property to the `` tag to define a different fill color than the default: + +[source,svg] +---- + +---- + +== Override an icon +To override an icon: + +. Create an icon sprite file with the SVG element, properties, and the icon ID. ++ +The following code snippet shows how to override the chart icon (`rd-icon-chart`) on the *Answers* page. + [source,HTML] ---- @@ -44,10 +91,10 @@ To override multiple icons, use the following format: + . Save the icon sprite file on a Web server. -. Add the SVG hosting domain to the *CSP connect-src domains* allowlist on the *Develop* > *Security Settings* page. For more information, see xref:security-settings.adoc#csp-connect-src[Security Settings]. . To override the icons on the ThoughtSpot page, specify the icon sprite URL in the `iconSpriteURL` property of the `customizations` object in Visual Embed SDK. + -The following code snippet uses the `icon-override1.svg` file hosted on the link:https://github.com/thoughtspot/custom-css-demo/blob/main/css-variables.css[Custom CSS demo GitHub Repo, window=_blank] to override the chart icon on the *Answers* page (`rd-icon-chart`): +For example, the following code snippets use the link:https://github.com/thoughtspot/custom-css-demo/blob/main/icon-override1.svg[icon-override1.svg] and link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg] files in the link:https://github.com/thoughtspot/custom-css-demo[Custom CSS demo GitHub Repo, window=_blank] to override the chart (`rd-icon-chart`) and Spotter (`rd-icon-spotter`) icons respectively: + + [source,JavaScript] ---- @@ -55,58 +102,43 @@ The following code snippet uses the `icon-override1.svg` file hosted on the link iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/icon-override1.svg" } ---- + ++ +[source,JavaScript] +---- + init({ + //... + customizations: { + iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg" + } + }); +---- . Load the application page and check the icon. + The following figures show the icons before and after the override. + [width="100%" cols="6,6"] |====== -a|**Before** + +|| +2+|**Chart icon** on Answers +a|Before + image::./images/pre-icon-override.png[Before icon override] -a|**After** + +a|After + image::./images/post-icon-override.png[After icon override] -|====== - -== Creating an icon override -The basic structure of an icon override file is shown in the following snippet: - -[source,svg] ----- - - - - - - ----- - -The `` portion within the `` tags is the definition of the actual drawing. - -You are defining a small icon, so it should fit within a square boundary and have a single solid color. - -There are many simple SVG icon examples available online, for example, the link:https://www.svgviewer.dev/[SVG viewer site, window=_blank]. -You only need to copy the `` tags from your example SVG within the ` ` tags. - -=== viewBox property +2+|**Spotter icon** +a|Before + +[.bordered] +image::./images/spotter-icon.png[Conversation embed] +a|After + +[.bordered] +image::./images/spotter-icon-customization.png[Spotter icon customization] -The link:https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox[viewBox property^] is in the order `min-x`, `min-y`, `width`, and `height`. - -The first two properties should be `0 0` while the second should match any `width` and `height` properties from the source of your SVG paths. - -The `width` and `height` properties may be added directly in the `` tag, or as part of `viewBox` property in that tag, or perhaps in another tag above ``. Use the values from your source SVG in the `viewBox` property of the `` element within your override file. - -=== fill property -You can add the `fill` property to the `` tag to define a different fill color than the default: - -[source,svg] ----- - ----- +|====== -== Testing an icon override file +== Try it out in the embed Playground The +++Visual Embed SDK Playground +++ allows you to try out the icon customization framework. To view the code for customization: @@ -121,9 +153,3 @@ The `customizations` code appears for CSS modifications appears in the code pane iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/icon-override1.svg" } ---- - -[NOTE] -==== -The `cdn.jsdeliver.net` domain is allowed on ThoughtSpot Embedded link:https://try-everywhere.thoughtspot.cloud/v2/#/everywhere/playground/search[public playground] and trial sites. -On your ThoughtSpot application instance, make sure to add the domain that will host the SVG file to xref:security-settings.adoc#csp-trusted-domain[the *CSP img-src domains* allowlist]. -==== \ No newline at end of file diff --git a/static/doc-images/images/spotter-icon-customization.png b/static/doc-images/images/spotter-icon-customization.png new file mode 100644 index 000000000..9ae918a51 Binary files /dev/null and b/static/doc-images/images/spotter-icon-customization.png differ diff --git a/static/doc-images/images/spotter-icon.png b/static/doc-images/images/spotter-icon.png new file mode 100644 index 000000000..c8a00cb54 Binary files /dev/null and b/static/doc-images/images/spotter-icon.png differ