Merge pull request #61 from catppuccin/feature/add-custom-folder-for-user-defined-modules

Feature/add custom folder for user defined modules

.gitignore

@@ -0,0 +1 @@
+custom

README.md

@@ -26,7 +26,8 @@
    3. [Status](#status)
    4. [Customizing modules](#customizing-modules)
    5. [Battery module](#battery-module)
-5. [Configuration Examples](#configuration-examples)
+5. [Custom module](#custom-module)
+6. [Configuration Examples](#configuration-examples)
    1. [Config 1](#config-1)
    2. [Config 2](#config-2)
    3. [Config 3](#config-3)
@@ -210,7 +211,7 @@ Values:
 
 #### Set the module list
 ```sh
-set -g @catppuccin_status_modules" "application session"
+set -g @catppuccin_status_modules "application session"
 ```
 Provide a list of modules and the order in which you want them to appear in the status. 
 
@@ -229,17 +230,17 @@ Every module (except the module "session") supports the following overrides:
 
 #### Override the specific module icon
 ```sh
-set -g @catppuccin_[module_name]_icon" "icon"
+set -g @catppuccin_[module_name]_icon "icon"
 ```
 
 #### Override the specific module color
 ```sh
-set -g @catppuccin_[module_name]_color" "color"
+set -g @catppuccin_[module_name]_color "color"
 ```
 
 #### Override the specific module text
 ```sh
-set -g @catppuccin_[module_name]_text" "text"
+set -g @catppuccin_[module_name]_text "text"
 ```
 
 ### Battery module
@@ -260,9 +261,16 @@ set -g @plugin 'tmux-plugins/tmux-battery'
 
 Add the battery module to the status modules list.
 ```sh
-set -g @catppuccin_status_modules" "... battery ..."
+set -g @catppuccin_status_modules "... battery ..."
 ```
 
+## Custom module
+
+It is possible to add a new custom module or overrite any of the existing modules.
+
+Look into custom/README.md for more details.
+
+Any file added to the custom folder will be preserved when updating catppuccin.
 
 ## Configuration Examples
 

catppuccin.tmux

@@ -161,8 +161,11 @@ build_status_module() {
 load_modules() {
   local loaded_modules
 
-  local modules_path=$1
-  local modules_list=$2
+  local modules_list=$1
+  
+  local modules_custom_path=$PLUGIN_DIR/custom
+  local modules_status_path=$PLUGIN_DIR/status
+  local modules_window_path=$PLUGIN_DIR/window
 
   local modules_array
   read -a modules_array <<< "$modules_list"
@@ -171,13 +174,34 @@ load_modules() {
   local module_name
   for module_name in ${modules_array[@]}
   do
-    local module_path=$modules_path/$module_name.sh
+    local module_path=$modules_custom_path/$module_name.sh
     source $module_path
 
     if [[ 0 -eq $? ]]
     then
       loaded_modules="$loaded_modules$( show_$module_name $module_index )"
       module_index=$module_index+1
+      continue
+    fi
+
+    local module_path=$modules_status_path/$module_name.sh
+    source $module_path
+
+    if [[ 0 -eq $? ]]
+    then
+      loaded_modules="$loaded_modules$( show_$module_name $module_index )"
+      module_index=$module_index+1
+      continue
+    fi
+
+    local module_path=$modules_window_path/$module_name.sh
+    source $module_path
+
+    if [[ 0 -eq $? ]]
+    then
+      loaded_modules="$loaded_modules$( show_$module_name $module_index )"
+      module_index=$module_index+1
+      continue
     fi
 
   done
@@ -225,8 +249,8 @@ main() {
   local window_number_position="$(get_tmux_option "@catppuccin_window_number_position" "left")" # right, left
   local window_status_enable="$(get_tmux_option "@catppuccin_window_status_enable" "no")" # right, left
 
-  local window_format=$( load_modules "$PLUGIN_DIR/window" "window_default_format")
-  local window_current_format=$( load_modules "$PLUGIN_DIR/window" "window_current_format")
+  local window_format=$( load_modules "window_default_format")
+  local window_current_format=$( load_modules "window_current_format")
 
   setw window-status-format "${window_format}"
   setw window-status-current-format "${window_current_format}"
@@ -238,7 +262,7 @@ main() {
   local status_fill="$(get_tmux_option "@catppuccin_status_fill" "icon")"
 
   local status_modules="$(get_tmux_option "@catppuccin_status_modules" "application session")"
-  local loaded_modules=$( load_modules "$PLUGIN_DIR/status" "$status_modules")
+  local loaded_modules=$( load_modules "$status_modules")
 
   set status-left ""
   set status-right "${loaded_modules}"

custom/README.md

@@ -0,0 +1,31 @@
+# User defined modules
+
+## Description 
+
+This folder is used to store user defined modules.
+You can use this folder to add a new module or override any existing module.
+To override an existing module, make sure you use the same name for your module as the module you want to override.
+You can also override the window module for current and default window.
+
+## Create a new module
+
+Use the [Module template](#module-template) (or example.sh) as a starting point when creating a new module.
+Save the new module under this folder using the module name as the file name and .sh as the extension.
+Update the status module list with your module.
+```sh
+set -g @catppuccin_status_modules "... <module_name> ..."
+
+```
+
+## Module template
+
+show_<module_name>() { # save this module in a file with the name <module_name>.sh
+  local index=$1 # this variable is used by the module loader in order to know the position of this module 
+  local icon="$(get_tmux_option "@catppuccin_<module_name>_icon" "<Use an icon from [nerdfonts](https://www.nerdfonts.com/cheat-sheet)>")"
+  local color="$(get_tmux_option "@catppuccin_<module_name>_color" "<Use one of the default theme colors (ex: $thm_orange), or provide a color code (ex: #ef9f76)>")"
+  local text="$(get_tmux_option "@catppuccin_<module_name>_text" "<Provide the text that you want to be displayed>")"
+
+  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+
+  echo $module 
+}

custom/example.sh

@@ -0,0 +1,10 @@
+show_example() {
+  local index=$1 
+  local icon="$(get_tmux_option "@catppuccin_test_icon" "󰙨")"
+  local color="$(get_tmux_option "@catppuccin_test_color" "$thm_blue")"
+  local text="$(get_tmux_option "@catppuccin_test_text" "It works!")"
+
+  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+
+  echo $module 
+}