[Hot Cards] Improve README for clearer text and some code enhancements (

#356) * Fix data is undefined error The error wasn't breaking anything, but it was unnecesary for it to happen. * Add flexibility to also modify style presets The gradient angle and animation, as well as the border color and border animation of the style presets can now be modified using the field format. * Update README with images and enhancements * Update version * Update README
stashapp · Jul 5, 2024 · 9e3f6ae · 9e3f6ae
1 parent 263f6fd
commit 9e3f6ae
Show file tree

Hide file tree

Showing 6 changed files with 116 additions and 80 deletions.
diff --git a/plugins/hotCards/README.md b/plugins/hotCards/README.md
@@ -1,6 +1,6 @@
 # Hot Cards
 
-Hot Cards is a Stash CommunityScript plugin designed to enhance your visual experience by applying custom styling to card elements based on a Tag ID or a Rating Threshold. This plugin is perfect for highlighting certain performers, scenes, studios, movies, images, or galleries.
+Hot Cards is a Stash CommunityScript plugin designed to enhance your visual experience by applying custom styling to card elements based on a Tag ID or a Rating Threshold. This plugin is perfect for highlighting certain performers or scenes and making sure you don't forget them!
 
 ## Features
 
@@ -20,106 +20,114 @@ Hot Cards is a Stash CommunityScript plugin designed to enhance your visual expe
 
 After installation, you can configure the plugin to suit your needs. Set a desired Tag ID or Rating Threshold and enable Hot Cards for the card types you want. Customize the appearance of Hot Cards for each type of card (scene, image, movie, gallery, performer, studio) using the format provided or leave the fields empty to apply the default style.
 
-### Custom String Format:
+### Configure the field format:
 
 _[criterion]\_[value]\_[style]\_[gradient-opts]\_[border-opts]_
 
 **Important**: If you have previously installed the plugin, after updating to `1.1.0`, be sure to update your settings from the old boolean format to the new string format. Refresh the page for the changes to take effect.
 
-1. **criterion**: `<criterion>`
+| Parameter         | Description                                                                                                                                                                                                                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<criterion>`     | Defines the basis for applying styles. Use `t` for tag-based criteria, `r` for rating-based criteria, or `d` to disable. If left empty, it will default to the global Tag ID or Rating Threshold configuration. If both options are enabled and unspecified, the Tag ID will be used by default. |
+| `<value>`         | Specifies the exact value for the Tag ID or Rating Threshold to be used.                                                                                                                                                                                                                         |
+| `<style>`         | Defines the styling options as a comma-separated list of colors or presets. Options include: a fixed color (e.g., #5ff2a2), a style preset (e.g., hot), or a gradient (e.g., #ef1313,#3bd612,... with hex color codes or color names).                                                           |
+| `<gradient-opts>` | Specifies gradient options as a comma-separated list: `<gradient type>,<gradient angle>,<gradient animation>`. Example: **linear,35deg,4s alternate infinite** for a linear gradient with a 35-degree angle and a 4-second alternating infinite animation.                                       |
+| `<border-opts>`   | Specifies border options as a comma-separated list: `<border color>,<border animation>`. Example: **#ff0000,2s ease infinite** for a border with a color of #ff0000 and a 2-second ease infinite animation.                                                                                      |
 
-   `t` for tag-based, `r` for rating-based,`d` for disabled. You can also leave it `<empty>` and it will grab the global value of the _Tag ID_ or _Rating Threshold_ as configured.
-
-2. **value**: `<value>`
-
-   Specific value for Tag ID or Rating Threshold.
-
-3. **style**: `<color, color, color, ...>` (comma separated)
-
-   - Fixed color: **#5ff2a2**
-   - Style preset: **hot**
-   - Gradient: **#ef1313,#3bd612,...** (Hex color codes, color names)
-
-4. **gradient_opts**: `<gradient type>,<gradient angle>,<gradient animation>` (comma separated)
+<br />
 
-   Example: **linear,35deg,4s alternate infinite**
+**Note**: _It is recommended to refresh the page once you are done configuring for the changes to take effect and the previous style to be overwritten._
 
-5. **border_opts**: `<border color>,<border animation>` (comma separated)
+## Examples
 
-   Example: **#ff0000,2s ease infinite**
+**Style Preset**:
 
-<br />
+`t_123_gold`
 
-**Note**: _It is recommended to refresh the page once you are done configuring for the changes to take effect and the previous style to be rewritten._
+| Segment       | Value | Meaning           |
+| ------------- | ----- | ----------------- |
+| criterion     | t     | Tag-based         |
+| value         | 123   | Use 123 as Tag ID |
+| style         | gold  | Use Gold preset   |
+| gradient-opts |       | No gradient       |
+| border-opts   |       | No border         |
 
-## Examples
+---
 
-**Style Preset**:
+**Modify an existing Style Preset**:
 
-t_123_gold
+`__hot_,,none_pink,none`
 
-| Segment       | Value |      Meaning      |
-| ------------- | :---: | :---------------: |
-| criterion     |   t   |     tag-based     |
-| value         |  123  | use 123 as Tag ID |
-| style         | gold  |  use gold preset  |
-| gradient_opts |       |        N/A        |
-| border_opts   |       |        N/A        |
+| Segment       | Value     | Meaning                               |
+| ------------- | --------- | ------------------------------------- |
+| criterion     |           | Use tag or rating as configured       |
+| value         |           | Use tag or rating global value        |
+| style         | hot       | Use Hot preset                        |
+| gradient-opts | ,,none    | No gradient animation                 |
+| border-opts   | pink,none | Set border color, no border animation |
 
 ---
 
 **Fixed Color**
 
-r\_\_#2673b8
+`r__#2673b8`
 
-| Segment       |  Value  |            Meaning            |
-| ------------- | :-----: | :---------------------------: |
-| criterion     |    r    |         rating-based          |
-| value         |         | use rating-based global value |
-| style         | #2673b8 |        use fixed color        |
-| gradient_opts |         |              N/A              |
-| border_opts   |         |              N/A              |
+| Segment       | Value   | Meaning                 |
+| ------------- | ------- | ----------------------- |
+| criterion     | r       | Rating-based            |
+| value         |         | Use rating global value |
+| style         | #2673b8 | Set fixed color         |
+| gradient-opts |         | No gradient             |
+| border-opts   |         | No border               |
 
 ---
 
 **Fixed Color with Border**
 
-\_\_#5ff2a2\_\_#5ff1a1
+`__#5ff2a2__#5ff1a1`
 
-| Segment       |  Value  |                   Meaning                    |
-| ------------- | :-----: | :------------------------------------------: |
-| criterion     |         | use tag-based or rating-based global enabled |
-| value         |         |  use tag-based or rating-based global value  |
-| style         | #5ff2a2 |               use fixed color                |
-| gradient_opts |         |                     N/A                      |
-| border_opts   | #5ff1a1 |     use border color when hovering cards     |
+| Segment       | Value   | Meaning                              |
+| ------------- | ------- | ------------------------------------ |
+| criterion     |         | Use tag or rating as configured      |
+| value         |         | Use tag or rating global value       |
+| style         | #5ff2a2 | Set fixed color                      |
+| gradient-opts |         | No gradient                          |
+| border-opts   | #5ff1a1 | Set border color when hovering cards |
 
 ---
 
 **Gradient with Border**
 
-\_67_pink,red,yellow,green,red,blue\_,30deg,5s ease infinite_red,1s ease-in-out infinite
+`_67_pink,red,yellow,green,red,blue_,30deg,5s ease infinite_red,1s ease-in-out infinite`
 
-| Segment       |             Value              |                   Meaning                    |
-| ------------- | :----------------------------: | :------------------------------------------: |
-| criterion     |                                | use tag-based or rating-based global enabled |
-| value         |               67               |     use 67 as Tag ID or Rating Threshold     |
-| style         | pink,red,yellow,green,red,blue |                 use gradient                 |
-| gradient_opts |    ,30deg,5s ease infinite     |  type not provided, use linear per default   |
-| border_opts   |  red,1s ease-in-out infinite   |
+| Segment       | Value                          | Meaning                              |
+| ------------- | ------------------------------ | ------------------------------------ |
+| criterion     |                                | Use tag or rating as configured      |
+| value         | 67                             | Use 67 as Tag ID or Rating Threshold |
+| style         | pink,red,yellow,green,red,blue | Make gradient                        |
+| gradient-opts | ,30deg,5s ease infinite        | Specify angle and animate gradient   |
+| border-opts   | red,1s ease-in-out infinite    | Set border color and animate border  |
+
+**Note**: _You can also skip inner values, notice the first comma in **gradient-opts**. The type is not provided, so linear gradient will be used by default._
 
 ## Style Presets
 
 These presets provide predefined styles for quick and easy customization.
 
-### default
+### Default
+
+![Default](/plugins/hotCards/assets/default.png)
+
+You can specify '\_\_default' for the card type you want the **default** preset to be applied and it will use the configured Tag ID or Rating Threshold. You can also leave the field empty and the default style will be applied anyway.
+
+### Hot
 
-You can specify '\_\_default' for the card type you want the **default** preset to be applied and it will use the globally configured Tag ID or Rating Threshold. You can also leave the field empty and the default style will be applied anyway.
+![Hot](/plugins/hotCards/assets/hot.png)
 
-### hot
+You can specify '\_\_hot' for the card type you want the **hot** preset to be applied and it will use the configured Tag ID or Rating Threshold.
 
-You can specify '\_\_hot' for the card type you want the **hot** preset to be applied and it will use the globally configured Tag ID or Rating Threshold.
+### Gold
 
-### gold
+![Gold](/plugins/hotCards/assets/gold.png)
 
-You can specify '\_\_gold' for the card type you want the **gold** preset to be applied and it will use the globally configured Tag ID or Rating Threshold.
+You can specify '\_\_gold' for the card type you want the **gold** preset to be applied and it will use the configured Tag ID or Rating Threshold.
diff --git a/plugins/hotCards/assets/default.png b/plugins/hotCards/assets/default.png
diff --git a/plugins/hotCards/assets/gold.png b/plugins/hotCards/assets/gold.png
diff --git a/plugins/hotCards/assets/hot.png b/plugins/hotCards/assets/hot.png
diff --git a/plugins/hotCards/hotCards.js b/plugins/hotCards/hotCards.js
@@ -288,9 +288,9 @@
                 createHotElementAndAttachToDOM(card, cardClass, isHome);
             });
           }
-        } else if (isCriterionRatingOrEmpty && data?.rating100 !== null) {
+        } else if (isCriterionRatingOrEmpty && data?.rating100) {
           const rating = isStarsRatingSystem
-            ? data?.rating100 / 20
+            ? data.rating100 / 20
             : data.rating100;
           // If the rating threshold for this card type is not set, use the default threshold.
           const ratingThreshold = valueNotSet ? RATING_THRESHOLD : config.value;
@@ -330,30 +330,58 @@
 
     const pseudoElementStyle =
       colors.length === 1
-        ? applySingleColorStyle(card, colors[0], border_opts)
+        ? applySingleColorStyle(card, colors[0], gradient_opts, border_opts)
         : applyCustomGradientStyle(card, colors, gradient_opts, border_opts);
 
     styleElement.innerHTML = pseudoElementStyle;
     document.head.appendChild(styleElement);
   }
 
   /**
-   * If there's only one color, it can be a style preset or a fixed color.
+   * Apply a single color style, which can be a style preset or a fixed color.
    */
-  function applySingleColorStyle(card, color, border_opts) {
-    if (STYLES[color]) {
-      const { border, gradient, filter } = STYLES[color];
-      setBorder(card, border.color, border.animation);
-      return getHotCardPseudoElementString(
-        card,
-        gradient.generated,
-        gradient.animation,
-        filter
-      );
-    } else {
-      setBorder(card, border_opts.color, border_opts.animation);
-      return getHotCardPseudoElementString(card, color);
-    }
+  function applySingleColorStyle(card, color, gradient_opts, border_opts) {
+    if (STYLES[color])
+      return applyPresetStyle(card, STYLES[color], gradient_opts, border_opts);
+    else return applyFixedColorStyle(card, color, border_opts);
+  }
+
+  /**
+   * Apply a style preset.
+   */
+  function applyPresetStyle(card, preset, gradient_opts, border_opts) {
+    const { gradient, border } = preset;
+    const { angle, animation } = gradient_opts;
+    const { color: borderColor, animation: borderAnimation } = border_opts;
+
+    // Update gradient options with preset defaults if not provided
+    const updatedGradientOpts = {
+      type: gradient.type,
+      angle: angle !== DEFAULTS.gradient_opts.angle ? angle : gradient.angle,
+      animation: animation || gradient.animation,
+    };
+
+    // Update border options with preset defaults if not provided
+    const updatedBorderOpts = {
+      color:
+        borderColor !== DEFAULTS.border_opts.color ? borderColor : border.color,
+      animation: borderAnimation || border.animation,
+    };
+
+    return applyCustomGradientStyle(
+      card,
+      gradient.colors,
+      updatedGradientOpts,
+      updatedBorderOpts
+    );
+  }
+
+  /**
+   * Apply a fixed color style.
+   */
+  function applyFixedColorStyle(card, color, border_opts) {
+    setBorder(card, border_opts.color, border_opts.animation);
+    return getHotCardPseudoElementString(card, color);
   }
 
   /**

diff --git a/plugins/hotCards/hotCards.yml b/plugins/hotCards/hotCards.yml
@@ -1,6 +1,6 @@
 name: Hot Cards
 description: Adds custom styling to card elements that match a tag ID or a rating threshold.
-version: 1.1.0
+version: 1.1.1
 url: https://github.com/stashapp/CommunityScripts/tree/main/plugins/hotCards
 # requires: CommunityScriptsUILibrary
 ui: