From 896bfc5f12de7c748178cd815fb3a474eb9b01a1 Mon Sep 17 00:00:00 2001 From: cactuzhead Date: Tue, 13 May 2025 11:09:03 +0100 Subject: [PATCH] Add files via upload --- docs/box shadow.md | 30 ++++++++ docs/container.md | 12 +++ docs/dashboard++.md | 38 ++++++++++ docs/light & dark.md | 14 ++++ docs/override error warning.md | 24 ++++++ docs/progress bar color.md | 20 +++++ docs/progress bar.md | 57 ++++++++++++++ docs/section marks.md | 47 ++++++++++++ docs/tasks.md | 133 +++++++++++++++++++++++++++++++++ docs/text.md | 26 +++++++ 10 files changed, 401 insertions(+) create mode 100644 docs/box shadow.md create mode 100644 docs/container.md create mode 100644 docs/dashboard++.md create mode 100644 docs/light & dark.md create mode 100644 docs/override error warning.md create mode 100644 docs/progress bar color.md create mode 100644 docs/progress bar.md create mode 100644 docs/section marks.md create mode 100644 docs/tasks.md create mode 100644 docs/text.md diff --git a/docs/box shadow.md b/docs/box shadow.md new file mode 100644 index 0000000..8eec93f --- /dev/null +++ b/docs/box shadow.md @@ -0,0 +1,30 @@ +--- +title: Box Shadow +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 9 +--- + +# Box-Shadow +Starting in release `1.1.0`, You can now add a box shadow to your progress bars. + +Toggling the Box-shadow `on` will reveal a further 4 options. + +## Box-Shadow Type +If this is toggled `off` you will have a glow shadow that shows around your progress bars container. + +When you toggle this `on` you will be selecting a drop shadow and will additionally add two further settings. + +These two `H-Offset` and `V-Offset` sliders will allow you to set the horizontal and vertical offsets from a range of 1 to 5 pixels. + +> Note: The glow shadow option (obtained by toggling this `off`) is effectively setting both of these offsets to zero and is a quicker and simpler way to setup a glow shadow. + +## Blur +Define the blur of the drop-shadow from a range of 0 to 5 pixels. Zero is no blur whilst five gives a nice subtle blur. + +## Inset +When this is toggled `on` you invert the box-shadow so that it runs from the border of your progress bars container inwards rather than the more usual outwards. + +## Box-Shadow Color +Select your desired custom color for the box-shadow with the colorpicker or use one of the `Light` or `Dark` defaults. \ No newline at end of file diff --git a/docs/container.md b/docs/container.md new file mode 100644 index 0000000..74726ff --- /dev/null +++ b/docs/container.md @@ -0,0 +1,12 @@ +--- +title: Container +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 8 +--- + +## Container Settings +Similar to the text settings above, this section includes two pairs of options for customizing the Border and Background of the container. + +![Container](/assets/Obsidian Advanced Progress Bars - Settings - Container.png) \ No newline at end of file diff --git a/docs/dashboard++.md b/docs/dashboard++.md new file mode 100644 index 0000000..2bb32f9 --- /dev/null +++ b/docs/dashboard++.md @@ -0,0 +1,38 @@ +--- +title: Dashboard++ +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 13 +--- + +## Using in Dashboard++ +Dashboard++ (aka DashboardPlusPlus) is a CSS snippet that provides a homepage for organizing and navigating notes. +You can find it at https://github.com/TfTHacker/DashboardPlusPlus + +If you want to incude progress bars into the columns of your Dashboard++ page, you can not use a standard APB code block. +However, there is a workaround detailed below. + +### Progress Bar in Columns +You normally insert a progress bar by pasting in the standard APB code block which may look something like this:- +```` +```apb +My Title: 57/100 +``` +```` +You *can* still do this on the page, but it will not be able to be placed inside columns (as a list item). + +Instead, if you want to place them in the columns (as a list item) you will have to use a workaround by simply omitting the last three backticks so that it looks like this:- +```` +- ```apb +My Title: 57/100 +```` +As shown in the example above, the code block omits the closing backticks and begins with a hyphen and space to format it as a list item. + +> Note: tag linking for tasks and sub-tasks do not work on Dashboard++ pages only simple manually edited progress bars work. + +In earlier versions, this workaround worked, but starting with release `1.0.8`, I have refined it to hide the list bullet for progress bars, resulting in a cleaner, more polished look (see image below). + +![dashboardplusplus](/assets/Obsidian Advanced Progress Bars - DashboardPlusPlus.png) + +Now, you can effortlessly place simple progress bars anywhere in column lists without a list bullet on the left, enhancing visual clarity. \ No newline at end of file diff --git a/docs/light & dark.md b/docs/light & dark.md new file mode 100644 index 0000000..5831c95 --- /dev/null +++ b/docs/light & dark.md @@ -0,0 +1,14 @@ +--- +title: Light & Dark +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 3 +--- + +# Light & Dark Settings +![Light and Dark](/assets/Obsidian Advanced Progress Bars - Settings - Light and Dark.png) + +These two buttons (`Light` & `Dark`) will change **ALL** the color settings to their respective defaults. +All other settings will remain unchanged.
+**Note:** once selected, all previous colors will be lost forever and can *not* be retrieved. \ No newline at end of file diff --git a/docs/override error warning.md b/docs/override error warning.md new file mode 100644 index 0000000..da6a740 --- /dev/null +++ b/docs/override error warning.md @@ -0,0 +1,24 @@ +--- +title: Override Error Warning +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 7 +--- + +## Override Error Warning +Typically, when your `Value` exceeds the `Total`, this error will appear to help you identify and correct any mistakes while editing the Value. + +![Error](/assets/Obsidian Advanced Progress Bars - Error.png) + +However, there may be instances where you would prefer the ability to exceed 100%, and this is where this setting proves useful. + +When you toggle `on` the `Override large value error`, **APB** will no longer display an error if the Value exceeds the Total. + +Additionally, a second setting will appear, allowing you to customize the color of the percentage text once it exceeds 100%. + +As usual, there are two defaults `Light` and `Dark` or select a custom color using the colorpicker. + +![Error](/assets/Obsidian Advanced Progress Bars - Error Override.png) + +As shown in the image above, the percentage text changes color and now displays values exceeding 100%. \ No newline at end of file diff --git a/docs/progress bar color.md b/docs/progress bar color.md new file mode 100644 index 0000000..1ad6aab --- /dev/null +++ b/docs/progress bar color.md @@ -0,0 +1,20 @@ +--- +title: Progress Bar Color +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 10 +--- + +## Progress Bar Color Settings +Here, you will find all the available color options for customizing the progress bar. + +### Completed Color +This color is what the progress bar will be when it has reached 100%. +You can see in the image above, that the bottom completed progress bar is using the default `Dark` option which is a light blue-grey color. + +### Bar Background Color +This is the color for the remaining portion of the progress bar. +In this example it is a mid blue-grey color. + +![Advanced Progress Bars](/assets/Obsidian Advanced Progress Bars - Bar Diagram.png) \ No newline at end of file diff --git a/docs/progress bar.md b/docs/progress bar.md new file mode 100644 index 0000000..24677a9 --- /dev/null +++ b/docs/progress bar.md @@ -0,0 +1,57 @@ +--- +title: Progress Bar +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 4 +--- + +## Progress Bar Settings +### Default Title +![Title](/assets/Obsidian Advanced Progress Bars - Settings - Title.png) + +You can use this to setup your default progress bar title. +By clicking the `Reset to Default` button this will change the title back to `Progress`. +If you change this, the `Title` will be automatically changed in the example code block at the top of the settings for easy copy and pasting later on. + +### Default Total +This setting is used to set the `total` you want for your default progress bar. +This is does not need to be set to `100` (as in percentage). For example, you could set it to `7` if you are tracking seven subtasks. + +![Smaller Total](/assets/Obsidian Advanced Progress Bars - Smaller Total.png) + +### Progress Percentage +![Slider](/assets/Obsidian Advanced Progress Bars - Settings - Slider.png) + +This slider is used to change the percentage of the demonstration progress bar found near the top of the settings. +It is meant as an aid so you can see how your progress bar will look with different settings. + +Additionally, it is also changes the `Value` in the `Example Code` found at the top of the settings. + +If you want to use the example code block's `Copy to Clipboard` feature or a hotkey to later paste into obsidian, then you would probably want this to be set to 0. + +It is recommended that you do this *after* you are happy with all the other settings and no longer need to see the demonstration progress bar. + +### Full Width +![Toggle](/assets/Obsidian Advanced Progress Bars - Settings - Toggle.png) + +If this is toggled `on`, then the entire progress bar will expand to fill the width of its container. + +If toggled `off` then a new `Width` setting will appear below this setting. + +The new `Width` setting will allow you to enter in a number to fix the width of the progress bar (in pixels). + +This is particularly useful when displaying a progress bar on a full-screen note, as a flexible width without a fixed limit can cause the progress bar to stretch excessively. + +### Height +![Slider](/assets/Obsidian Advanced Progress Bars - Settings - Slider.png) + +This slider allows you to set the height of the progress bar from a range of 1 to 15 pixels. + +Pressing the `Reset to Default` button changes this value back to 8 pixels tall. + +### Round End Caps +If this is toggled `on`, then the progress bar (and its background) will have rounded ends. +Toggling it `off` will change them to square ends. + +![End Caps](/assets/Obsidian Advanced Progress Bars - Settings - End Caps.png) \ No newline at end of file diff --git a/docs/section marks.md b/docs/section marks.md new file mode 100644 index 0000000..040ebd4 --- /dev/null +++ b/docs/section marks.md @@ -0,0 +1,47 @@ +--- +title: Section Marks +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 5 +--- + +## Section Mark Settings +### Section Marks +![Toggle](/assets/Obsidian Advanced Progress Bars - Settings - Toggle.png) + +If this is toggled `on`, the progress bar will automaticlaly have equally spaced vertical markers along its length. +The following table shows how many marks will be displayed depending on the `Number of Colors` setting (located further down on the settings page). + +| Number of Colors | Number of Marks | +| ---------------- | --------------- | +| 1 | 0 | +| 2 | 1 | +| 3 | 2 | +| 4 | 3 | +| 5 | 4 | + +> Note: if you have 1 color selected, you will by default, not see any markers. + +### Automatically Assigned Marks +If this is toggled `on`, the progress bar will automaticlaly have equally spaced vertical markers along its length - as described above. + +However, if you want to manually overide this behavior to choose the number of equally spaced marks along the progress bar then, toggle this setting `off`. + +If you do so, a new slider will apear underneath to allow you to set the number of marks you wish to be used. + +### Number of Marks +If you have the `Automatically Assigned Marks` toggle in the `off` position (as described above), you can use this slider to pick exactly how many vertical marks you want evenly distributed along your progress bar. + +> Note: this overrides the automatically assigned system + +### Section Mark Color +This setting defines the color of the vertical section markers. + +Use the colorpicker to select a custom color or alternatively, use one of the `Light` or `Dark` defaults by pressing the appropriate buttons. + +> Note: the color selected will automatically be set to 50% transparency, allowing the progress bar's color to blend and influence the final appearance. + +### Section Mark Width +This is a slider to set the width of each marker from a range of 1 to 5 pixels. +Pressing the `Reset to Default` button changes this value back to 3 pixels wide. \ No newline at end of file diff --git a/docs/tasks.md b/docs/tasks.md new file mode 100644 index 0000000..6e455b5 --- /dev/null +++ b/docs/tasks.md @@ -0,0 +1,133 @@ +--- +title: Tasks +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 11 +--- + +## Tasks Settings +Here, you will find all the available options for customizing the progress bar when using tags to link to tasks. + +### Enable Task Linking +When toggled on, progress bars can use tags to link to matching tags in your tasks. This results in your progress bar automatically tracking tags to display your current task completion. + +Normally your code block would look something like this:- +```` +```apb +My Title: 57/100 +``` +```` +To add a tag to your progress bar, you add a hastag to the end of your `Title`, followed by your tag name. +```` +```apb +My Title#orange: 57/100 +``` +```` +As you can see in the image below, the tag will be displayed as a badge to the left of your `Title`. +![Tasks](/assets/Obsidian Advanced Progress Bars - Tasks.png) + +> Note: If there is at least one matching tag in your tasks, APB will automatically find them, and change your `Value/Total` in the code block. You do not need to manually edit the code block once setup. + +So the previous code block example above, will now automatically be changed to somthing like this:- +```` +```apb +My Title#orange: 1/2 +``` +```` +In the example above, the tag is #orange (all lowercase) and is added to the end of your `Title` (but before the colon). + +### Add Tags to Tasks +Now simply add the same tag to the end of each top task you want to link to this progress bar. +```php +- [x] Task 1 #orange + - [ ] Subtask 1 + - [x] Subtask 2 + - [ ] Sub Subtask 1 +- [ ] Task 2 #banana +- [ ] Task 3 #orange +``` +In the example above, there are a total of 3 top tasks and 3 subtasks (1 of which is a sub-subtask). + +The `#orange` progress bar would see 2 linked top level tasks (task 1 and task 3) and it would see that one of those was completed, so your progress bar would therefore be set to 50% (1/2). + +> Note: your tags are case sensative so you need to exactly match your tags for APB to link them. You can use any case and even numbers if you wish. + +If you add a tag to your progress bar and it does not match any task tags, you will see an error saying (in this example) `#orange not found`. + +![tag not found](/assets/Obsidian Advanced Progress Bars - Tag Not Found.png) + +> Note: if you see this error, the progress bar's data may be incorrect and will not update as it is not correctly linked. + +### Other tags +If you add tags to your subtasks (or sub-subtasks, etc) they will be ignored by APB. + +### Track More than One Tag +In the `Add Tags to Tasks` example above, you will notice there are 3 top tasks, two of which are tagged with `#orange`. However there was also one top task that was tagged with `#banana`. + +This `#banana` tag was ignored by the progress bar which was looking for `#orange` tags. +You can however (if you desire) add a second progress bar, and give it the `#banana` tag so it will track all `#banana` top tasks. + +![multi tags](/assets/Obsidian Advanced Progress Bars - Multi Tags.png) + +In the image above, both `#orange` and `#banana` are being tracked automatically. + +And you can track as many tags as you wish by simply adding additonal progress bars with a new tag for each. + +### Tag Badge Colors +Once you toggle the task linking setting to `on`, two additional color settings will appear underneath. + +`Task Text Color` is used to set the color of the tag badge's text, whilst the `Task Background Color` is used to set the background color of the tag badge. + + +## Sub Tasks +In addition to the color settings mentioned above, you should also see a new toggle option called `Enable Sub-Task Linking`. + +When toggled `on` it should reveal two further color settings underneath it. + +These are used to change the text color of the sub tasks, with one being used after you have completed all sub tasks. + +As with all color settings, there are Light and Dark buttons to set default colors - or choose your custom color from the colorpicker. + +If you activate the sub task toggle, APB will keep a count of all subtasks of your top level tasks and display it in text form underneath your progress bar. + +```php +- [x] Task 1 #orange +- [ ] Task 2 #banana + - [x] Subtask 1 + - [ ] Sub Subtask 1 +- [ ] Task 3 #orange +- [ ] Task 4 #banana + - [ ] Subtask 1 +``` +So for the tasks example above, you will see a sub task count for `#banana` that will be 1/3 as there are a total of three sub tasks (or sub-subtasks), one of which is completed. + +![multi tags](/assets/Obsidian Advanced Progress Bars - Sub Tasks.png) + +As you can see in the image below, if you complete all sub tasks for the specified tag, your text will change color and add the word `COMPLETED` after it. + +![multi tags](/assets/Obsidian Advanced Progress Bars - Sub Tasks Completed.png) + +> Note: subtasks **do not** require tags themselves, they will be counted according to their top tasks tag. +If you do add tags to subtasks, they will be totally ignored by APB. + +### Subtask Code Block +For APB to track your subtasks, it adds additional data to the end of the `My Title#Tag` in your code block. +```` +```apb +My Title#banana~2/4: 0/2 +``` +```` +As you can see in the example above, there is a `~2/4` placed directly after the `#banana` tag. +This is simply the `Value/Total` for subtasks of your progress bars tag, and is automatically added by APB. + +> Note: For task linked progress bars - it is not recommended that you make any changes manually to the code block apart from the `Title` or `#tag` as it will be overwritten when APB refreshes the data. + +## Refreshing +If you have `Enable Task Linking` turned `on` the progress bars will update when you change between notes. +This can be used to "manually" make sure that notes are refreshed and up-to-date. + +Additionally, APB will refresh automatically after you make changes to either the liniked progress bar code block or the tasks themselves. +For performance and user experience reasons, it will only update 2 seconds after it detects a change. + +> Note: if you are not going to be using tags to keep track of your task progress, then it is **highly** advised to turn `off` the `Enable Task Linking` for a smoother and efficient experience. \ No newline at end of file diff --git a/docs/text.md b/docs/text.md new file mode 100644 index 0000000..a848211 --- /dev/null +++ b/docs/text.md @@ -0,0 +1,26 @@ +--- +title: Text +has_toc: false +back_to_top: true +back_to_top_text: "Back to top" +nav_order: 6 +--- + +## Text Settings +There are four pairs of settings which relate to `Title`, `Percentage`, `Fraction` (value/total) and `Completed Text`. + +![Text Diagram](/assets/Obsidian Advanced Progress Bars - Text Diagram.png) + +If you toggle each text item `on`, it will display that particular text on your progress bar (see image above). + +The `completed` text will be displayed over the top of the progress bar, and will only be shown when it reaches 100%. + +![Completed](/assets/Obsidian Advanced Progress Bars - Settings - Completed.png) + +(as always, you can see what it will look like by viewing the demo progress bar near the top of the settings.). + +![Color Picker](/assets/Obsidian Advanced Progress Bars - Settings - Color Picker.png) + +Using the accompanying color settings will allow you to pick your desired custom color for each of the four text items. + +Alternatively, you could use one of the `Light` or `Dark` defaults by pressing the appropriate buttons. \ No newline at end of file