Megawidget Default Behavior Modification - Hazard Services

Purpose:

This jobsheet walks through changing the default selection of impact statements for FL.W hazards from "Closest in Stage/Flow Window" to "All Below Upper Stage/Flow". To accomplish this, the metadata file for FL.W is edited, and specifically the default behavior of the embedded megawidget for impacts "Search Type".

Tasks:

JOBSHEET ORGANIZATION: This jobsheet includes two sections:

• Section 1: Highlights a discovery process which explains how to identify the appropriate Python fields to change
• Section 2: Directly lays out the steps needed to make the change.

Focal Points who are simply interested in making the needed change and not practicing exploration can skip to the second section.

 

SECTION 1 (of 2): How to Identify the Code for Changing Impact Statement Search Strategy

1. Click on a river flood (FL-type) hazard in the Hazard Services console to launch its associated Hazard Information Dialogue (HID)
   1. You may need to generate a river flood hazard or switch to a time when one exists before proceeding. To create a river flood hazard: 
      1. Open the Hydro Perspective
         1. FOCAL POINT WORKSHOP: Set your CAVE clock to the time provided on the notecard attached to your screen. Then go to MapData --> Point Data Control. Be sure to uncheck the box for Show NonFcstPoints. Then, click Map. 
      2. Double click on any visible gauge to select it (a red box should surround it when selected).
      3. Right click and hold on any river gage and select "Create Hazard" (NOTE: Hazard Services must be open for this option to be available)
      4. A popup will appear for the Flood Recommender. Click "Run"
      5. The HID will appear, at which point you can change the "type" to any FL-related hazard. 
2. Click on the "Impact Statement" tab in the Details section of the HID
3. Click on the triangle next to "Impacts Search Parameters" near the top of the tab to expand that megawidget group
4. Scroll down until you see the "Search Type" drop-down megawidget
   1. NOTE: It's useful to make note of the text used to label a megawidget, in this case "Search Type:", for identifying the appropriate megawidget to edit later
5. Observe the default state of the drop-down, which may say "Closest in Stage/Flow Window" or some other value
   1. We will be interested in making the "All Below Upper Stage/Flow" the default selection.  If that is already the default state then this jobsheet will be unnecessary, but you may follow along to continue learning how it would be changed.
6. Click on the "Search Type" drop-down field to see its options.
   1. One of the options will be "All Below Upper Stage/Flow", our desired default
7. Before moving on, take into account the following clues for determining WHERE we'll need to look to find and edit this behavior
   1. HID: We're looking at behavior in the Hazard Information Dialogue, therefore (from the metadata training) we know that we'll be looking for a metadata file to edit since metadata files dictate the HID layout
   2. FL-type hazard: The loaded hazard type (FL.W, FL.A, or FL.Y) tells us more specifically WHICH metadata file to look at. For example, if we have an FL.W open, we expect that Metadata_FL_W.py should be a good starting point. (However, also recall that Common Metadata may house relevant configurations for many metadata files)
   3. "Search Type" label: The label of the drop-down megawidget in question can be very useful in a localization file search for quickly rounding up, and positively identifying, the important lines of code for this component.
8. Close the HID for the hazard. We are now ready to look for the relevant code
9. Switch to the Localization Perspective by clicking on the "Open Perspective" icon at the top-right of your CAVE window, and choosing "Localization"
10. Try searching for the megawidget using its label, as follows:
    1. From the Search menu at the top of the Localization Perspective, select Search by Content
    2. In the "Containing Text" field, enter "Search Type" (without quotes), which was the label of our megawidget
    3. From the drop-down under "Application:", select Hazard Services to limit the search scope to those files
    4. Press "Search" to begin the search
11. Review the search results in the "Search" tab at right. In particular, notice:
    1. Two directories within Hazard Services had hits: Hazard Meta Data, and Utilities. We know because we are trying to customize the HID that the Meta Data hit is most relevant
    2. Within Hazard Meta Data, there's only one matching file: CommonMetaData.py... and likely only one version (BASE) of this file, unless your site has already created override versions
    3. Within CommonMetaData.py, we see several lines of code where the term "Search Type" matched. Two should stand out:
       1. The commented "# Search Type Dropdown (specific to 'crest' or 'impacts')", which sounds a lot like the right neighborhood for our megawidget definition
       2. "label": "Search Type:", which looks like the exact code responsible for configuring our megawidget with the label we observed
12. Double-click on search result item under CommonMetaData which reads "label":"Search Type:" to open the file at exactly the line where the match was found
    1. CONTEXT: Notice again that we've opened "CommonMetaData.py" rather than a hazard-specific file like MetaData_FL_W.py... Focal Points should expect the CommonMetaData file to be routinely used by hazard-specific metadata to house communal functions and megawidgets, as it does here. That's why, even though we we were looking at the HID for an FL-type hazard, the code for this megawidget was not found in MetaData_FL_W.py or a similar hazard-specific metadata file.
13. Study what you see to determine if we've found what we're looking for. Notice the following:
    1. We've found "Search Type" as one value in a Python dictionary { }, specifically next to the key "label"... this is what we expect for a megawidget labeled "Search Type" in the HID
    2. This dictionary is tucked inside a function called "getSearchType". This function, like most, returns a value, seen following the "return" statement. In this case, the returned value is the dictionary { } in which "Search Type" and other megawidget parameters are specified. It is typical in Hazard Services for each megawidget to be defined in its own function, like the "getSearchType" function we see here.
    3. In this return dictionary, we notice a few other key:value pairs of interest:
       1. "fieldType" is set to "ComboBox", which in megawidget nomenclature refers to a drop-down field just like we're expecting
       2. there are "choices" and "values" keys, which in this case have similarly named variables assigned to them as values. These set the available drop-down choices, and the default selected value, respectively. We'll want to know what these variables hold.
    4. In the function, notice some logic, shown below, where the "choices" variable are assigned contingent on this function having received an argument of "impacts", as is the case in our "Impact Statement" tab

              if parm == "impacts":
                   choices = ["All Below Upper Stage/Flow",
                              "Closest in Stage/Flow Window",
                              "Highest in Stage/Flow Window"
                              ]
              return {
                      "fieldType": "ComboBox",
                      "fieldName": parm + "SearchType",
                      "label": "Search Type:",
                      "choices": choices,
                      "values": self.crestsAndImpactsUtil.getSearchTypeDefaultValue(parm),
                      "spacing": 5,
                      "expandHorizontally": False
       

    5. Notice that the choices correspond exactly to the drop-down options, however the "values" key (bolded line), which defines the default value in the "Search Type" megawidget, calls a method named "getSearchTypeDefaultValue" from a class called "crestsAndImpactsUtil". Since we're interested in modifying the default value of this megawidget, we will also need to find where this class is located. 
    6. Again, let's use the "Search" option in the toolbar to look for "getSearchTypeDefaultValue" in the "search by content" box. 
    7. You will find that the search returns two locations: one in CommonMetaData.py where we have pointed this out in step 5, and one in a file called "CrestsAndImpactsUtil.py" located in the Utilities folder of Hazard Services. 
    8. If you expand the drop down options in the Search menu, you can see the locations of getSearchTypeDefaultValues in the CrestsAndImpactsUtil.py BASE file. Double click on the line showing where getSearchTypeDefaultValues is defined (i.e. "def getSearchTypeDefaultValues") to be taken directly to that line in the file. 
    9. Here you will see that all this method does is return the defined default value for any megawidget that calls it, which is what was seen in the HID.
    10. All of the above clues indicate that we're looking at the correct code for modifying the "Search Type" megawidget.
    11. Moreover, we can see now that we must change the "values" variable by changing the returned value from the getSearchTypeDefaultValue method in CrestsAndImpactsUtil.py to implement our new desired default state for this megawdiget. This is accomplished through a class override in Section 2 (below).
14. Exploration complete! Proceed to Section 2 below to actually make the change. But here's a recap of how we got to this point:
    1. We gathered clues about the megawidget we wished to modify, specifically that it was labeled "Search Type", and also made note of its choices and default state
    2. We also mentally noted that, since this megawidget is displayed in a Hazard Information Dialog, a MetaData file is likely responsible behind the scenes
    3. We used the localization search tool to rapidly find potentially matching configuration files, using our megawidget label ("Search Type") as the search term, and found CommonMetaData.py
    4. We reviewed the "getSearchType" function to see if the megawidget it defined was a match for the label, choices, and default selection we saw. 
    5. We noted that this megawidget called another method for its default value, and again we used our handy search tool to find where this method was located, which was in another file called CrestsAndImpactsUtil.py 
       1. Note: The class defined in CrestsAndImpactsUtil.py is imported into CommonMetaData.py at the top of the file so it can be accessed. Take a look for yourself! 

 

SECTION 2 (of 2): Changing the Megawidget Default Selection Value

1. In the Localization Perspective, navigate to the Utilities sub-directory under the Hazard Services folder.
2. Double click on CrestAndImpactsUtil.py to show the available versions
3. Create a user override version if none exists (user override is best practice for testing changes):
   1. If there is only a BASE version: right click on BASE and select Create Override File, then select User
   2. If there is another version (e.g. SITE) you wish to use: right click on that file and select Copy To, then select User
4. Double click on the User version of CrestAndImpactsUtil.py to open it for editing (if not already opened)
5. (No action in this step) Notice, if this is a new override file, that the Localization Perspective auto-populated the same class statement as the reference file as an important first step in your override. In this case, your new file should look like example below:

   class CrestAndImpactsUtil(object):
       pass
   

   1. The "pass" line is simply a needed placeholder in new, empty class overrides, which does nothing
6. IMPORTANT: Before making any edits to the user version, CLOSE THE SEARCH TAB in the Localization Perspective
   1. Keeping Search open while making edits can produce nonstop alertviz errors. It must be closed to prevent those.
7. Open a reference copy of the existing CrestsAndImpactsUtil.py file, which will be used for comparing to and copying existing code for overrides.
   1. The BASE file will usually be a good reference, but any pre-existing overrides may also be useful to open (MORE INFO: If the methods below have already been overriden in non-BASE files, then the modified methods should be sourced from those overrides to preserve any customizations)
8. In the reference file you opened, scroll or search to find the "getSearchTypeDefaultValue" method which begins with the line below:

   def getSearchTypeDefaultValue(self, parm): 

9. INFO: This method defines and returns the default value of the drop-down megawidget for setting the impacts or crest value search types, whose behavior we want to edit
10. Once found, select the entire getSearchTypeDefaultValue method by clicking and dragging from (and including) the "def getSearchTypeDefaultValue(self, parm):" line which begins the function, all the way to (and including) the last line of the function which has the return statement.
11. Copy the selected contents by right-clicking and selecting "Copy" from the pop-up menu, or by hitting CTRL-C on your keyboard
12. Switch back to the USER override you were working on
13. Paste the getSearchTypeDefaultValue method into your USER override on a blank line after the "class..." and "pass" lines, by right-clicking and selecting "Paste" from the pop-up menu, or by hitting CTRL-V on your keyboard
14. In the USER copy of the getSearchTypeDefaultValue method you just pasted in:
    1. Change the return value so it appears exactly as below:

       return "All Below Upper Stage/Flow"

    2. INFO: This will set the default megawidget value to "All Below Upper Stage/Flow".
15. You're finished with the needed edits! Proofread for Python syntax mistakes in any areas you edited.
16. When finished, save the file by hitting Ctrl+S, or selecting Save from the File menu
    1. If a "File Version Conflict" is encountered, click OK to accept merge
    2. In the two-panel "Merge" tab that opens, make no changes, once again save the file by hitting Ctrl+s, then close the "Merge" tab
    3. When a "File Changed" message appears,  click Yes.
    4. This behavior will only be encountered each time a new override file that did not exist before is created and saved
17. Review, test, and (if desired) promote the file to the appropriate localization level (SEE JOBSHEET FOR PROMOTION)
18. Task Complete!

To  see changes implemented:

• No restarts needed
• HOWEVER: existing hazards already have their impacts selections "in memory" and will not reflect this change... to see the new new HID behavior, a new hazard must be created

New behavior to expect:

• The customization in this jobsheet will cause only the single closest impact to be selected, by default, in the "Impacts" tab of river flood hazards
• NOTE: Anywhere that the method "getSearchTypeDefaultValue" is called, this new behavior will be reflected, not just in the FL.W hazard type.