YAMLs Level-I

YAMLs, the Basics

With recent advancements in YAML technology, they’ve become faster, stronger, more adequate than before, and most importantly they’ve become accessible to all on support without the need for core access, and fancy deploy methods. 

YAMLs themselves have become no less complicated, or potentially damaging to a client’s site in the wrong hands. In fact, formatting, troubleshooting, and error reversion have become much more difficult, so REACH OUT FOR REVIEW FROM AN EXPERIENCE SUPPORT MEMBER BEFORE PUSHING ANY LIVE CHANGES TO A SITE. 

** = Reach out to higher-trained support if changes not discussed in this article are needed. 

WHAT IS A YAML? (QUICK VERSION)

For the long version, please brush up on What is a YAML? (long version)

What are forms/fields/props

There are 3 YAML types that you may have noticed in MCP: Forms/Fields/Props. 

• Fields: This file defines search fields and settings for the forms file. It directly creates a search field in the Super Search menu. This is only visible to Agents.
• Forms: This file structures the search pages based on pre-defined items in the fields form. This is visible to Leads, and Agents. 
• Props: This file stands ‘alone’ to define and relabel items that show up on the property listing pages, and loosely where. This is visible to Leads and Agents.

Preface: What We Don't Do

Declining baselines - are the gradual change that happens over time when comparing a behavior solely by the last time it was measured. This is what happens when you give in to "small" requests that are typically against Support's SOP. Small changes unnoticed over a long period amount to large changes that continue to go unnoticed.

    As you're likely aware, clients typically want the worst thing for them, and like a child throwing a tantrum in a candy store, they'll demand to dip their disgusting hands into the days_on_market jar. Parents must follow the parenting SOP, otherwise, we risk the argument "Well I've had days_on_market, so why can't I now have open_house?", and so on… until declining baselines have muddled the line between reasonable requests, and unreasonable ones. 

While these don't have much to do in the first level, you'll be the first in line to accept the requests, so keep an eye out: (* see long version for detailed 'whys' )

1. Status - The site is built around these, trust the system. 
2. Open house data - (can be done, but is against SOP. See DOC: WHY WE DON'T OPEN HOUSE) 
3. Days on Market - or other similar date fields, because saved searches hate them.
4. Half baths - because programming math is hard.
5. "ALL AVAILABLE FIELDS FROM MY MLS" - ask for examples, use your sense, and see #6
6. Fields typically not for leads - we're a Lead Generation Platform, and these fields are for leads
7. Relabel Choice lists - Sometimes necessary, but problematic. 
8. Limit Choice Lists - cutting a list down is inadvisable for several reasons, but not uncommon.
9. More Than 30-40 Price options - +/- 10, because again, math is hard. 

Things you need to know first:

Indentation/formatting

• (Indent == 4 spaces == TAB) Intention is the whitespace before the field, it's used to indicate hierarchy.  You're familiar with how picky programs are with this if you've ever done an LSC. 

Examples:

The pipe symbol "|" represents one tab of indentation in a supported text editor. 

Since each tab equals 4 spaces, this makes a marked difference in efficiency, see the difference below with ␣ as spaces. This is how direct-edit in mcp works, and why it's not recommended.  

• Case/Punctuation: Specific fields require certain casings and wrapping.
  • Field names are always lower_case_separated_by_an_underscore (this is called "snake_case")
  • Labels appear exactly "as is" on the site. They don't require quotation. 
  • Choices must be cased/spelled exactly as they appear in the IDX, and text must be enclosed in double quotes "" 

File Structure

• Forms have several sections varying from site to site, but generally, you can expect it to follow the same flow as below
  • Homepage Search Templates
    1. Homepage template
       
       1. primary section (location/type)
       2. secondary section (less important stuff)
    2. Search Homepage template
    3. Rentals Homepage Template (optional)
  • Advanced Search Tab Templates
    1. Advanced
       
       1. primary section (location/type)
       2. secondary section (less important stuff)
    2. Condos
    3. Rentals (optional)
    4. Sold
    5. Mls Search
    6. Foreclosures Search
    7. Address Search
    8. Market Report Search

• Fields are simply a list of names, definitions, and formatting, one after another, in no particular order. 
  • For example 
    
• Props are another list, but of labels, and order-of-appearance. Hierarchy is sorted by type, top/bottom page, and id
  • style
    • top
      • field_name: Label
    • bottom
      • field_name: Label

Useful Tools:

Editing an item to advanced searches usually means editing ALL OF THESE Which is why we recommend using a tool such as VSCode, which offers several tools to help format, replace-all, multi-line-edit, and error checking. 

• VScode for MACs https://code.visualstudio.com/download

A YAML validator is another nice tool to just check indentation and for any other weirdness. It won't check the spelling, or relevance of id names to the Real Geeks program though, so look out. 

• YamlLint Yaml Valiadator: https://www.yamllint.com/

FINALLY the Good Stuff.

What can I start with?

To start off, we should work exclusively with items that have already been defined in fields, which we know provide a result in the super search. 

• (‘simplest’ method to get there: <website.com>/admin/content/contentpage/add > Property Display Search Options > Create Search)

This First Level of Changes Include:

1. Adding a search form (forms)
2. Changing the default option (fields)
3. Changing the Label for a field
4. Changing which fields appear, and what they say in the Property Details Page
5. Using an all_key
6. Add flags/widgets to change how a field appears

Anything not included should be escalated until you’ve been walked through level-II changes. **

1. Add a Form

To Add a form to a search: 

1. Easy-Peasy-Lemon-Squeezy, to add an existing field to the client's search confirm that this field exists in one or both of the Defaults YAMLs **
2. match appropriate indentation, and widgets
3. then just write it in: - id: field_name
   

• Remember that these changes need to go everywhere sensible, a homepage search change likely needs to be on all homepage templates. Find all instances using cmd+f. 
• in VScode you can use highlight> cmd+d to select and edit all instances of a word. 
  • WARNING: arrow key navigation only when multi-line editing. 
•  

2. Adding a Label

Changing what a field says on a site is just as simple. (NOTE: only effects site, not super search)

To add a Label to a form, there are two options.

1. Forms: adding a label here only adds the label to one instance of the field. 
2. Fields: adding a label here adds it to all instances of the field in forms. 

To Change a Label,

1.  move down a line
2. match the indentation of  - id:
3. add "label: " + the replacement
   1. label: Exact Case/Spelling

3. Adding All_Keys

All_Keys are labels for the "all" options in multiselect fields such as "No Preference", "Select an Option", "Any", "All", etc...

To add an all key to a multiselect form with "all" present:

1. move down a line from - id,
2. match the indentation:
3. add all_key: No Preference
   
   1. This can be anything such as Select, Any, All Cities, etc...

4. Adding a Default

Depending on the number of changes needed, there are two options.

1. Forms: adding a label here only adds the label to one instance of the field. 
2. Fields: adding a label here adds it to all instances of the field in forms. 

To add a default to a field:

1. move down a line from - id,
2. match the indentation:
3. add "default: " + the exact spelling of the choice from Mongo/Debug
   1. default: Exact Choice
   2. default: True/False/Yas/Nah

Numbers can also have defaults: (See "Flags: min_max_field" for which fields can use this)

1. default: 5 
2. default_min: 5 (requires min_max formatting, which we won't go into adding in this article)
3. default_max: 10 (requires min_max formatting, which we won't go into adding in this article)

NOTE: 'All' values are programmatic, and not a list choice, do not use default for any variation of "all"

5. Adding Flags/Widgets

Flags are small tags that determine specific behaviors in a field. There are many more than are discussed in this article, but these have fewer intricacies. **

To add a flag to a field: 

1. move down a line from - id,
2. match the indentation:
3. type flags: [+flag_name, +flag_name]
   1. notice that the list is encapsulated by square brackets [], and that separate flags are separated by commas

• +min_max_field: Indicates that a field is set up for min/max. Check if present before setting a default_min/max or label_min/max. **
• +checked: (Checkbox only) Sets a checkbox's default state. 
• +locked: (Checkbox only) Locks a checkbox's state. Usually used in conjunction with +checked
• NOTE: The (-) setting is used specifically to override a fields setting from forms that can't/shouldn't otherwise be changed, or only needs to appear in one instance. **

Widgets choose which type of input selector the field uses

• none: will usually just display a single-select pulldown, otherwise will default to section default. 
• multiselectdropdown: creates a pulldown of checkbox selectable options. 
• multiselect: creates a large box of selectable choices. (primarily in the main (Location) section of searches since this large field catches the eye first.)
• checkbox: Used to create checkboxes for types, but use-case is tightly controlled by rg2 programming, so we won't go into it here. ** 
• 
  WARNING: Don't use in multiselect widget in 'secondary' as it will shift everything over an entire section  

To Add a Widget to a Field:

1. move down a line from - id,
2. match the indentation:
3. type widget: multiselectdropdown
   1. These aren't complicated, just check that it works, and makes sense in the context of use.

6. Adding to Props

Props are surprisingly easy if everything is already mapped for you **. 
many things are structured by scripts in RG2, so can't be arranged. 

Props are structured by type > top > bottom repeating for all available property types. 

• type being the property type such as res, con, lnd, etc...
• top being the listing details directly underneath the property images
• bottom being the listing details which appear beneath the property description. 

To add a label to an existing prop_field **: 

1. Find the label that requires changing, and select all with cmd+d
2.  after the colon, type one space, and the exact label you intend to use.
   1. ␣␣␣␣-␣lot_size:␣Lot␣Size

NOTE: To remove a label, reverse this process, and leave the field name, just blank after the colon. The map search uses these fields. 

More on the Subject:

To hand this task off gracefully, we've broken this process into 5 experiential tiers. The real fun stuff will, for now, remain in private docs to be dripped out on the basis of experience. Reach out to @escalations when you think you've outgrown this doc.  **

• ** = Reach out to higher-trained support if changes not discussed in this article are needed.  
• ␣ = Invisible Whitespace or indentation