The Regions Module allows you users to filter listings based on location. You also get the ability to define the regions they 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.
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
To correctly configure Regions Module, you must do the follow activities:
- Create and associate your regions in a hierarchy
- Add regions to a side list (if you want the side list used)
- Change the field labels to match your hierarchy naming convention
- Decide where your fields will show up (Search Page, List View, Detail View)
- 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.
Installing Regions module automatically adds 4 new fields to your configuration under Directory Admin->Manage Form Fields. They are as follows:
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.
IMPORTANT: You should NOT try to add fields to manage a region hierarchy here manually by adding fields. When you add levels to the hierarchy, you will automatically get fields added to the field list. Any region-type fields you add manually will be completely ignored by Regions Module. Define your hierarchy FIRST, and then change the labels of the fields generated by Regions to match how you defined it.
NOTE: If you accidentally delete a Regions field, don’t panic. You can get it back by visiting the Regions tab under Directory Admin->Manage Regions. At the top, click to expand the Regions pane and click on “Restore Regions Fields”. Shown below:
The regions administration screen looks like this from Directory Admin->Manage Options, click on the Regions tab:
The settings are as follows:
Show Sidelist: This activates the sidelist option (see below), where any regions present on the sidelist are displayed as links next to listings. This makes it easy for users to “quick filter” listings by a particular region, instead of selecting one manually at the top of the listings screen. When this option is unchecked, no side list will appear on the View Listings or Directory screens in Business Directory.
In addition to the settings above, there is also a link for Manage Regions. The Manage Regions screen can also be accessed by the menu here:
The Manage Regions area also has a collapsed pane that will allow you some “restore” operations if you get things in a bad state. When you click on the right of the Regions pane, you get this expanded area below:
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, Africa (a continent) has several counties (with single dashes) below it:
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.
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.
Add Child: Clicking this will automatically change the Parent region of the Add Region widget to the left to the selected region and await for you to enter the new region name. You must click “Add New Region” to complete the addition of the child to the hierarchy.
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 Manage Regions area of the admin dashboard of Directory Admin.