Regions Module

The Regions Module allows you users to filter listings based on location. You also get the ability to define the regions people can use to submit their listings, search, and edit. There is also a quick-region-set sidelist where the user can click on a region and automatically see listings filtered for that region.

Regions can be defined in a hierarchical fashion, for example: Continent → Country → State → County → City. You do not need to define all those levels if you don’t want to. By default, we pre-configure the Regions module with all Continents, the Countries of the world and the States of the United States. Additional regions and levels can be added easily to customize for your locale.

NOTE: The module does not come with states outside of those provided for the United States, and it doesn't come with cities, counties, etc. These must be populated manually. Instructions for doing this are provided below in the Adding cities to Regions in Bulk section of this page.

Installation

The files you download are in a ZIP that is a full plugin. The installation instructions are inside of it, and here as well:

Upload the ZIP as a plugin via the MANUAL process*. From the WordPress admin panel

• Go to Plugins → Add New
• Click on the “Upload” link, and then click on Browse Now to locate the ZIP file you just downloaded.
• Click OK once you find it on your local computer
• Click the Install Now button to start the process.
• After the installation completes, click the “Activate Plugin” link to turn on the module

*NOTE: If you are using a Mac, the file may be automatically unzipped when you download it. You can change the default setting in Safari to only download the ZIP file and not unpack it. To do this: 1. Open Safari, 2. Click Preferences, 3. Under the General tab, uncheck the option Open “safe” files after downloading.

Regions Setup

To correctly configure Regions Module, you must do the follow activities:

1. Create and associate your regions in a hierarchy
2. Add regions to a side list (if you want the side list used)
3. Change the field labels to match your hierarchy naming convention
4. Decide where your fields will show up (Search Page, List View, Detail View)
5. Change the order of display of fields

That’s it. The first step is the longest. We start you out with the Countries and Continents of the world as well as all states for the USA. The rest you will need to add or associate yourself.

The hierarchy definition does not need to match Continent → County → State → City. You can have any association you like, such as Middle Earth → Hobbiton → The Shire → Bilbo’s House if you like. The important part is to understand which are parent regions and which are child regions. We give you the most common use of Regions module pre-configured, but you are free to change that (including the labels of the fields) however you like.

Regions Fields

Installing Regions module automatically adds 4 new fields to your configuration under Directory → Manage Form Fields.They are as follows:

• City
• State
• Country
• Continent

By default, the Continent is set to NOT display in any form (listing, detail or search), and Country, City and State are. You can configure this however you like in the Manage Form Fields section of Business Directory, including their output order. For example, if you only want to show City and State for US listings, you might have something that looks like this:

Any fields that are not in the listing, excerpt or search from this screen are not displayed in the Region Selector or in the Sidelist. That’s helpful if you want to display States, but not the Country, in the Sidelist. The above configuration will do exactly that–show only States and Cities on the sidelist.

Administration

The regions administration screen looks like this from Directory → Settings → Premium Modules → Regions:

General Settings:

Regions Slug: This is used in the URL when users are filtering for a particular region, like /wpbdm-region/new-york/albany, which happens in some searches or the Regions browser page.  This must be a unique slug, a default one is provided but you can change it as long as it doesn't conflict with others.

Hide Region Selector?: Turning on this option disables the Region selector that is shown in various places, such as the main directory or the search page.  The Region selector looks like this (closed):

Or (open):

Show Region Selector Open by Default: Turning this option on leaves the selector open (image above) when the user first visits the page.  Default is closed/off.

Hide Empty Regions: Turning on this option allows you to hide regions that don't have any listings in them.  This helps collapse the size of your Regions sidelist considerably if you have a lot of regions uploaded, but it also can be confusing if your users want to find listings in a particular region and it's not available.

Show Post Counts: Turning on this option will display a count of the listings in that region when it's shown on the sidelist or in a drop-down menu, like “Albany (3)”.  Default is off.

Add Regions to Quick Search Bar?:  Turning this on will add the Region field to the Quick Search bar available fields to use.  It behaves similarly to the ZIP search option we show here:

You must still click the link at the top of this tab (“Change the configuration here”) and select it to activate it as a “searched field”.

Sidelist Settings:

The next section is for the Sidelist of Regions.  The Sidelist is the area next to the main directory that shows locations and listing counts.  The sidelist looks like this:

The settings that control this are as follows:

Show Sidelist: Turning on this option makes the Sidelist visible.  Otherwise, no sidelist for regions will be displayed.

Show “Clear Filter” option: Turning on this option will display a “Clear Filter” link at the top of the sidelist when you have a region selected, shown below.  Default is off.  The link will only appear when your mouse is hovering over the region sidelist.

Keep Sidelist expanded on current Region: Turning on this option means that selecting a Region will collapse all other regions EXCEPT the current selected one in the hierarchy.  Useful to highlight the selected region.

Automatically expand sidelist on page load?: Turning on this option means that the sidelist will fully expand when the page is loaded (all sub-regions will expand in the tree).  Makes it “prettier” when the user loads the directory.

In addition to the settings above, at the bottom of the tab, there are some buttons to help you manage the regions settings and fields, in case something goes wrong.

You can use these buttons to restore the default regions, the region form fields (if you accidentally delete them), or restore the default settings of the Regions Module.

Managing the Region Hierarchy

The Manage Regions screen is where all region configuration happens. Regions are configured as a hierarchy. You can make the hierarchy anything you like, we pre-configure it with the most common scenario, but you are free to use as much or as little as you like. The default is setup as follows:

Continent → Country → State

You can add counties, cities, villages, boroughs, whatever you like. The important thing to understand is which regions are parents and which are children, and to make the association accordingly. Each level of the hierarchy is displayed with a dash in front of it. So top level regions have no dash, first level (country) regions have a single dash, second level (state) regions have two dashes, and so on.

As you add or delete regions, the Regions Module will automatically change the Form Fields to add or remove the level of the hierarchy you create. These fields will have default names associated to them, but you can change them to whatever you like. The names of the fields are not important to Regions Module.

The Manage Regions screen primarily uses a list of regions to work with (notice the top level region, North America (a continent) has a country (with single dashes) below it, and state (with two dashes) and a city (with three dashes):

At the top of this list, you have various filters you can use to hide/show regions that you are interested in. Clicking Enabled will display all active regions (those that can be shown in the Region Selector, Search screen or Submit Listing screen), Disabled will show all inactive ones. On Sidelist will show all regions that have been added to the Sidelist, and Not on Sidelist does the opposite. Clicking All will return you to the master list of regions at any time.

To the left of the region list, you will find the Add Regions widget, where you can quickly add one or many regions at a time (under Add Multiple Regions). You can also specify the parent region of the region you are configuring:

To add a new region, simply type the name of the Region in the Name field, specify the parent region of it, and then click Add New Region. If you do not specify a parent, that region will become a top-level region. By default, top-level regions are Continents.  You can configure your regions any way you like, continents do NOT have to be the top level–this is just how the default data set comes.

When you are working with regions, the operations you can perform on them are found when you hover the mouse over a particular region, like so:

The commands are as follows:

Show Sub Regions: Clicking this link will automatically filter the region list to show ONLY regions that are children of the region you clicked on. For example, if you clicked on Show Sub Regions for Africa, you would see the message shown below:

And a list of regions that are countries under Africa, such as Algeria, Angola, Benin and Botswana, among others.

Edit: This will allow you to change the region name, slug and description on a separate screen.

Quick Edit: Similar to edit, but allows for in-line editing of the region info above.

Delete: Removes the region from the hierarchy. WARNING: Any child regions will ALSO be deleted as well, so be careful of this operation.

Show/Hide: This will show or hide the region on the sidelist. See the section about Sidelists below for more information. If you attempt to add a region to the sidelist and it’s parent(s) are not on the sidelist, clicking “Show” will automatically add the parent regions as well. Similarly, hiding a parent region from the sidelist will also hide all of its children as well.

Enable/Disable: This will make a region active or inactive. Only active regions will show up in the Region Selector, the Advanced Search screen, and the Submit a Listing screen. A region must also be active to show on the side list.

How to Filter Listings By Regions

When you visit the Directory or View Listings pages, at the top, you will see the Region Selector (which by default will say “Displaying listings from All Regions” until you select something).

To the right of the region indicator is a drop-down button:

Clicking on it will open up the region selector:

When you start out, the first drop down will be the only one displayed. Clicking a region in it will create the control to select the next level (in this case, selecting “USA” caused the “State” drop down to appear. Selecting “Washington” caused the City drop down to appear.

When you have fully selected the desired region you wish to filter on, click “Set Filter” to set the region for filtering. Now, only listings from that region will be shown in View Listings and Directory, until you change it. In the above example, clicking “Set Filter” will cause only listings from Seattle, WA, USA to show up in the directory.

If you make a mistake or simply wish to see all listings, click “Clear Filter” and the drop downs will reset, allowing for a new selection.

The Sidelist and Quick Filters

The sidelist allows you to have “quick filters” setup for regions you know will be of interest to your users. The side list appears like this in your directory on the View Listings and the Directory page, to the right of your listings and just below the button panel/region selector area:

When you click on a region in the sidelist, this will quickly set the region to match the one in the sidelist. Sidelist regions can also have sub-regions showing as well, such as this for USA (before and after pics):

By clicking on the button, that will open the sub region list (States) for USA, allowing for further location filter refinement.

If you want a region on the sidelist, you must add it under the Directory → Manage Regions area.

Adding cities to Regions in Bulk

The cities or other smaller regions will need to be added manually in the plugin, but you can do them several at a time.

Quick Video Instructions

Written Instructions:

To do this, go to Directory → Manage Regions, then click on the tab that says Add Multiple Regions:

Once you are there, you can see how easy it is to copy/paste lists of cities for each state in the box, and associate those cities to the state you want:

When you are done putting in the information, click the Add Multiple Regions button and those cities will be added.

You can do a Google search for the phrase “text list of cities in Florida” (for example) to get a good list you can copy/paste. We recommend putting the list in a text editor like Notepad to remove any formatting that may be on the page where you have copied the information from. Here is an example page I found in Google:

and what it looked like in Notepad when pasted there (this important steps removes formatting from the text):

Note: We have also identified this potential source of information on cities/locales that you might wish to use instead: https://developers.google.com/adwords/api/docs/appendix/geotargeting?csw=1

Enabling newly added cities

Once you have added the list of cities, they will need to be enabled, and if you want them on the sidelist, that setting will need to be changed also. To do this, from Directory → Manage Regions, search for the state you added cities for, then click on “show sub-regions”:

Once those are displayed, you can then use the bulk actions to enable the cities.
Be sure to select all sub-regions first, as shown below:

Then choose the bulk action “Enable” and click Apply:

IMPORTANT NOTE: There may be several pages where you need to follow this process, depending on the number of cities you've added. Be sure to go to the next page and follow this procedure to be sure that all cities are enabled (in this case, there are 9 pages)

Follow the same steps if you'd like to add the cities to the sidelist, but choose “Show on Sidelist” from the Bulk Actions dropdown menu.

Note for users of both the Regions Module and the ZIP Search Module:

You can choose to enable the Regions Module on the Quick Search menu, which adds the Located at <City, State> search field OR you can choose to enable the ZIP Search Module on the Quick Search menu, which adds a ZIP code field to the Quick Search.

Here is what the ZIP Search Module looks like when it is enabled on the Quick Search Menu:

Here is what the Regions Module looks like when it is enabled on the Quick Search Menu:

If you have enabled both modules in the Quick Search bar,  then the Regions Module will take precedence. Only one of those options can be added to the Quick Search bar, so you must make a choice between the two modules here.