[BHP1-1264] Add VMS Documentation

arch/03_vms_guide.org

@@ -0,0 +1,311 @@
+#+TITLE: Hitchhiker's Guide to the Variable Management System (VMS) \includegraphics[]{./images/vms-guide/Screenshot 2025-04-18 123426.png}\par  \includegraphics[width=1.0\textwidth]{./images/vms-guide/Screenshot 2025-04-18 124034.png}\par
+#+OPTIONS: toc:t author:nil date:nil
+#+LATEX_HEADER: \usepackage{float}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \usepackage{hyperref}
+#+LATEX_HEADER: \hypersetup{
+#+LATEX_HEADER:     colorlinks=true,
+#+LATEX_HEADER:     linkcolor=blue,
+#+LATEX_HEADER:     urlcolor=blue,
+#+LATEX_HEADER:     citecolor=blue
+#+LATEX_HEADER: }
+#+LATEX_HEADER:\usepackage{titlesec}
+#+LATEX_HEADER:\newcommand{\sectionbreak}{\clearpage}
+#+LATEX_HEADER:\newcommand{\subsectionbreak}{\clearpage}
+
+* Finding VMS elements in the Application
+
+The VMS holds the structure of our application. The data is a tree like structure that determines how the application is rendered. This section aims to help you understand how the data in the VMS translates to how it is shown in the application.
+
+** Modules/Submodules/Groups/Group Variables
+
+In the VMS Use the side bar to navigate down these paths:
+
+#+begin_verse
+Applications \to Modules \to Submodules \to Group \to Group Variables \to Variables
+#+end_verse
+
+Example:
+
+#+begin_verse
+BehavePlus \to Surface \to Fire Behavior(output) \to Surface Fire \to Heading Rate of Spread \to Heading Rate of Spread
+#+end_verse
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: VMS: Home page
+[[./images/vms-guide/Screenshot 2025-04-15 122636.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: Outputs page after a Surface Only worksheet has been created.
+[[./images/vms-guide/Screenshot 2025-04-14 144743.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: Inputs page after a Surface Only worksheet has been created. NOTE Groups can have sub groups.
+[[./images/vms-guide/Screenshot 2025-04-14 163337.png]]
+
+** Variables
+
+The Variables can be associated with multiple group variables but group variables can only be associated to a single variable. The Variable entity will hold information about Domains/Dimension/units
+
+*** Variable Entities
+
+1. Navigate to the "Variables" tab
+
+*** Variable Associated with a Group Variable
+
+1. Navigate to the Application \to Module \to Group
+2. "Expand" the "Variables" accordion
+3. Find the variable you are interested in and click "Edit". This will take you to the "Variables" page and populate the form with the variable's info.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Finding the variable associated with a group variable
+[[./images/vms-guide/Screenshot 2025-04-14 151243.png]]
+
+** List and List Options
+
+Certain Group Variables have a list associated with it (usually inputs). In the application lists show up as either radio selections or drop down selections.
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: List options as radio selections.
+[[./images/vms-guide/Screenshot 2025-04-14 150013.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: List options as multi select drop down.
+[[./images/vms-guide/Screenshot 2025-04-14 150755.png]]
+
+In the VMS you can find the list associated to a group variable by:
+
+1. Navigating to the Module \to Submodule \to Group
+2. Click "Expand" on the "Variables" accordion. Then click "Edit" on the Variable listed. This will Navigate you to the "Variables" page and populate the form with the variable's information.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Group page
+[[./images/vms-guide/Screenshot 2025-04-14 151243.png]]
+
+3. Look for the "List" field and note the list selected.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Variables page
+[[./images/vms-guide/Screenshot 2025-04-14 164610.png]]
+
+1. Navigate to the "List" tab and scroll down or (Ctrl +f) to find the list mentioned above.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: List page
+[[./images/vms-guide/Screenshot 2025-04-14 164814.png]]
+
+5. Click "Edit". This will populate the form at the bottom of the page.
+
+** Filter and Color Tags
+
+*** Filter and Color Tags Entities
+Filter and Color tags in the application can be found in input group variables that allow users to select multiple inputs.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: Filter Tag and Color Tag example.
+[[./images/vms-guide/Screenshot 2025-04-14 163724.png]]
+
+You can find existing tags in the VMS by:
+1. Navigate to the "Tags" tab
+
+#+ATTR_LATEX: :placement [H] :width 0.50\textwidth
+#+CAPTION: VMS: Tags page
+[[./images/vms-guide/Screenshot 2025-04-15 145117.png]]
+
+*** Filter and Color Tags associated with a Group Variable
+You can find the tag sets associated with a group variable by:
+
+1. Find the list associated to the group variable, see [[*List and List Options][List and List Options]] section.
+2. Click "Edit" on the list
+3. Once the form on the list page has been populated you can find the associated tag sets.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: List page
+[[./images/vms-guide/Screenshot 2025-04-15 162354.png]]
+
+** Variable Domains
+*** Variable Domain Entities
+
+The Variable Domain entities is used primarily to associate a group of variables to some default units and decimal precision. Domain entities are grouped into Domain sets, primarily used for creating collapsing accordions in the application.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: Custom Unit Preferences table.
+[[./images/vms-guide/Screenshot 2025-04-16 152012.png]]
+
+1. Navigate to the "Variable Domains" tab
+2. Click "Edit" on the "Domain Set". This will populate the form on the right with a list of domains that belong to this set.
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Variable Domains.
+[[./images/vms-guide/Screenshot 2025-04-16 152830.png]]
+
+*** Variable Domains Associated with a Group Variable
+
+1. Find the Variable associated with your group variable of interest. see [[*Variable Associated with a Group Variable][Variable Associated with a Group Variable]] section
+2. You can find the domain associated to the variable under the "Domain" field
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: The Domain associated with this variable.
+[[./images/vms-guide/Screenshot 2025-04-16 160738.png]]
+
+** Units and Precision
+
+Default Units and Precision live in the Domain Entities.
+
+1. Find the Domain associated with your group variable see [[*Variable Domains Associated with a Group Variable][Variable Domains Associated with a Group Variable]] section.
+2. Navigate to the "Domains" page and lookup the domain.
+3. Click "Edit" on the "Domain Set" and "Edit" on the "Domain" entity to populate the forms.
+4. Default units is shown under "Native Unit"
+5. Default precision is shown under "Decimals"
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: The Domain associated with this variable.
+[[./images/vms-guide/Screenshot 2025-04-16 16125122.png]]
+
+** Conditionals
+
+Conditionals serve one of two purposes. First and most common is to determine if a submodule or group should be displayed in the application. The second purpose is to attach them to actions. When attached to actions the conditional determines if that action should be fired (i.e. setting an input group variable to a default value if a certain output group variable is selected).
+
+*** Submodule/Group Conditionals
+
+To find a conditional that controls if a submodule or group are hidden:
+1. Navigate to the submodule or group entity page and expand the "Conditionals" accordion
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Conditionals to only show the Spot(input) submodule if either these output variables are selected. NOTE: Clicking "Edit" on the conditional will populate the form on the right. This is useful for seeing all the parent entities of this group (i.e. The conditional above belongs to the Surface (Module) \to Spot Output (Submodule) \to Maximum Spotting Distance (group).
+[[./images/vms-guide/Screenshot 2025-04-21 115338.png]]
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: "Wind Driven Surface Fire" is selected as an output.
+[[./images/vms-guide/Screenshot 2025-04-21 115625.png]]
+
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: Since "Wind-Driven Surface Fire" is selected as an output, the Spot(Input) submodule passes the conditional and is displayed.
+[[./images/vms-guide/Screenshot 2025-04-21 115646.png]]
+
+*** Action Conditionals
+
+To find a conditional attached to an action:
+1. Navigate to the Group Variable entity page and expand the "Actions" accordion
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: VMS: Group Variables can have multiple actions.
+[[./images/vms-guide/Screenshot 2025-04-21 122253.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: VMS: Each action has one or more conditionals. The name of the action should describe what is necessary to trigger the action but to more closely look at the conditionals, click "Edit" on the action you are interested in.
+[[./images/vms-guide/Screenshot 2025-04-21 122436.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: "Midflame Wind Speed" is selected as an output
+[[./images/vms-guide/Screenshot 2025-04-21 123238.png]]
+
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: Application: Action is triggered to disable "Midflame (Eye Level)" as an option in the inputs page.
+[[./images/vms-guide/Screenshot 2025-04-21 123312.png]]
+
+* Updating Text
+
+Most texts for entities displayed in the application can be updated by changing the translation field for that entity..These entities will have 2 translation fields. One field is used in the worksheet wizard (pages before computation) and the second is used for the results page. Usually the result translations are a short form of the worksheet translations. Here are some of the common entities you might want to update. The application will default to the worksheet translation if a result translation is not present.
+
+** Submodule/Group/Group-Variables
+
+1. For these entities navigate to the entity page, see [[*Modules/Submodules/Groups/Group Variables][Modules/Submodules/Groups/Group Variables]] section.
+2. Update the "Translation" field.
+
+#+ATTR_LATEX: :placement [H] :width 0.50\textwidth
+#+CAPTION: VMS: Group page after navigating BehavePlus \to Surface \to Fire Behavior(output) \to Surface Fire
+[[./images/vms-guide/Screenshot 2025-04-14 145649.png]]
+
+
+
+** List Options
+
+#+ATTR_LATEX: :placement [H] :width 0.50\textwidth
+#+CAPTION: Application: Worksheet translations appear in the wizard.
+[[./images/vms-guide/Screenshot 2025-04-15 165647.png]]
+
+#+ATTR_LATEX: :placement [H] :width 0.50\textwidth
+#+CAPTION: Application: Result translations appear in the results matrices and tables.
+[[./images/vms-guide/Screenshot 2025-04-15 165841.png]]
+
+1. Find the list associated to the group variable, see [[*List and List Options][List and List Options]] section.
+2. Click "Edit" on the list.
+3. Find the list option you are interested in updating and click "Edit".
+4. Update the "Translation" field and the "Name" field.
+5. Navigate to the list associated with the group variable. see [[*List and List Options][List and List Options]]
+6. Click "Edit" on the list option you want to update.
+
+#+ATTR_LATEX: :placement [H] :width 0.75\textwidth
+#+CAPTION: VMS: List Page
+[[./images/vms-guide/Screenshot 2025-04-15 164954.png]]
+
+** Tags
+
+1. Navigate to the tag set associated with your group variable of interest. See [[*Filter and Color Tags associated with a Group Variable][Filter and Color Tags associated with a Group Variable]]
+2. Click "Edit" on the tag set. This will populate the table on the right.
+3. Click "Edit" on the tag option you'd like to update.
+4. Update the "Translation" field and the "Name" field.
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Updating translations on tags page.
+[[./images/vms-guide/Screenshot 2025-04-15 171421.png]]
+
+* Updating Default Unit Preferences
+
+** Units
+
+1. Find the Domain associated with the variable you are interested in. See [[*Variable Domains Associated with a Group Variable][Variable Domains Associated with a Group Variable]] section.
+2. Click "Edit" on the Domain set
+3. Click "Edit" on the Domain found in step 1.
+4. Update the "Native Unit" field
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Updating translations on tags page.
+[[./images/vms-guide/Screenshot 2025-04-16 1612512.png]]
+
+** Precision
+
+1. Follow the steps from [[*Units][above]] to find the Domain entity.
+1. Update the "Decimals" field
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Updating translations on tags page.
+[[./images/vms-guide/Screenshot 2025-04-16 161251.png]]
+
+* Updating Units Dropdown Selections
+
+In the Application's inputs page a user can change units via a drop down menu. By default a variable is linked to a "Dimension" (i.e. length) and will have all options available to select. However there are cases when this list should be limited to a subset. If this is desired do the following:
+
+1. Find the Domain associated with the variable you are interested in. See [[*Variable Domains Associated with a Group Variable][Variable Domains Associated with a Group Variable]] section.
+2. Click "Edit" on the Domain set
+3. Click "Edit" on the Domain found in step 1.
+4. Under "Filtered Units" select a subset of your desired units
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Domains Page Updating Units drop down to a subset of units.
+[[./images/vms-guide/Screenshot 2025-04-16 163044.png]]
+
+* Re-Ordering
+
+Certain entities can be re-ordered via the VMS. To do this:
+
+1. Find the parent entity of the entity you are trying to reorder (i.e. Need to reorder groups? find the submodule entity page. Need to reorder a list options? Find the List entity page.). See  [[*Finding VMS elements in the Application][Finding VMS elements in the Application]]
+2. Once you're on that page there should be a table that have a list of entities for you to reorder. Click on the "up" and "down" buttons to reorder
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: Reordering Direction Mode output selections.
+[[./images/vms-guide/Screenshot 2025-04-18 122848.png]]
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Reordering Direction Mode output selections: Navigate to BehavePlus \to Surface \to Fire Behavior(output) \to Direction Mode
+[[./images/vms-guide/Screenshot 2025-04-18 121904.png]]
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: Application: Reordering fuel model codes.
+[[./images/vms-guide/Screenshot 2025-04-18 122936.png]]
+
+#+ATTR_LATEX: :placement [H]
+#+CAPTION: VMS: Reordering fuel model codes. Find list "SurfaceFuelModels" and click "Edit".
+[[./images/vms-guide/Screenshot 2025-04-18 122529.png]]

projects/behave_cms/src/cljs/behave_cms/tags/views.cljs

@@ -2,6 +2,7 @@
   (:require [re-frame.core                     :as rf]
             [behave-cms.components.common      :refer [simple-table]]
             [behave-cms.components.entity-form :refer [entity-form]]
+            [behave-cms.components.translations :refer [all-translations]]
             [behave-cms.events]
             [behave-cms.subs]
             [string-utils.interface :refer [->kebab]]))
@@ -16,7 +17,8 @@
 
 (defn- tag-editor [tag-set-eid tag-eid]
   (let [tag-set (rf/subscribe [:entity tag-set-eid])
-        tags    (rf/subscribe [:pull-children :tag-set/tags tag-set-eid])]
+        tags    (rf/subscribe [:pull-children :tag-set/tags tag-set-eid])
+        tag-entity (rf/subscribe [:entity tag-eid])]
     [:<>
      [:h3 (if tag-eid "Edit Tag" "Add Tag")]
      [entity-form {:entity       :tag
@@ -31,16 +33,18 @@
                                    :type      :color
                                    :disabled? (:tag-set/color? @tag-set)
                                    :field-key :tag/color}]
-                   :on-create    (fn [data]
-                                   (let [translation (upsert-translation (:tag/translation-key data) (:tag/name data))]
+                   :on-create (fn [data]
+                                (let [translation (upsert-translation (:tag/translation-key data) (:tag/name data))]
                                      (rf/dispatch [:api/create-entity translation])
                                      (merge data {:tag/order (count @tags)})))
-                   :on-update    (fn [data]
+                   :on-update (fn [data]
                                    (if (:tag/name data)
                                      (let [translation (upsert-translation (:tag/translation-key data) (:tag/name data))]
                                        (rf/dispatch [:api/create-entity translation])
                                        data)
-                                     data))}]]))
+                                     data))}]
+     [:h4 "Worksheet Translation"]
+     [all-translations (:tag/translation-key @tag-entity)]]))
 
 (defn- tags-table [tag-set-eid]
   (when tag-set-eid