Version: 1.0.0 and higher (there may be separate notes about versions compatibility)

Installation

To add a WordPress Plugin using the built-in plugin installer:

  1. Go to "Plugins -> Add New".
  2. Click "Upload Plugin" button.
  3. Choose downloaded ZIP file and click "Install Now" button.
  4. Make sure that you click on "Activate the plugin", now you have installed maps plugin.
  5. Create new page with [webmap] shortcode. Also you may create additional pages with [webmap-submit] and [webmap-dashboard] shortcodes if you wish your logged in users to manage their listings and profile on the frontend dashboard page.

Special note: additional pages with [webmap-submit] and [webmap-dashboard] shortcodes must not have main maps page with [webmap] shortcode as parent.

WordPress Multisite installation

Upload the plugin on Network Admin plugins page, but don't activate it. It is not allowed to enable "Network Activate" for the plugin on Network plugins page, instead activate it on the plugins page of each sub-site. Also note, that each activation on each sub-site requires separate license.

How to update

First of all download the latest version of the plugin from Codecanyon. Simply unpack the archive with new version and upload all new files and folders to your existing plugin folder on the server, that is all, the system will automatically execute required operations. All files and folders must be uploaded using FTP-client (like FileZilla) or using file manager in your hosting control panel. It would be better to make backups of the database and all plugin files before update. All your configurations, settings and data will be saved after update, you will not lose anything. Files modifications must be made according to customization instructions, in such case they will be saved during update.


Getting started

So you get your instance of the plugin installed and ready for use. Now lets set up most important settings and options. Note that you may manage and change following settings in any time you want, but it is recommended to set up before your google maps site becomes public. Here is some recommendation on how to get familiar with the plugin in right way:

  1. first of all configure your Google Maps using special built in settings
  2. manage existing core fields and create additional content fields for your needs
  3. build your own maps categories tree and tags
  4. work with locations: define maps locations tree and look at locations levels
  5. create some test listings with map markers and explore how listings behave themselves at the frontend, which additional options and tools they have

Maps settings

First of all look at "Maps Admin -> Maps settings" page. There are some separate tabs with own groups of settings.

General settings tab

settingsThere are 2 available addons, if you do not need unnecessary functionality - do not enable them:

Frontend submission & dashboard addon - allow users to submit new listings at the frontend side of your site, also provides users dashboard functionality.

Ratings addon - ability to place ratings for listings, then manage these ratings by listings owners.

Frontend submission and dashboard

These are additional settings for frontend submission if appropriate addon was enabled.

Select frontend submission login mode -

  • login required - logged in users have an ability to manage their listings, invoices and profile on the frontend dashboard page.
  • necessary to fill in contact form - after successful submission WordPress creates new user profile. If user with entered email already exists in the system - it doesn't required to create new profile and listing will just be assigned with existed user. Later admin may manage and contact new user when needed. For new users registration email with newly generated password will be sent.
  • not necessary to fill in contact form - the same behaviour as for previous option, but it does not required to enter contact info. For empty contact form the system creates anonymous user. Registration email will be sent when user enters contact email.
  • do not even show contact form

Post status after frontend submit - define which status listing post will receive after successful submission: Pending Review, Draft or Published.

Post status after listing was modified - define which status listing post will receive after modification: Pending Review, Draft or Published.

Enable submit listing button - enable this option if you wish your users to submit new listings and map markers. Also the page with [webmap-submit] shortcode required.

Hide top admin bar at the frontend for regular users and do not allow them to see dashboard at all - when this option enabled - regular user will never see backend of your site. It is recommended to enable when you have the page with [webmap-dashboard] shortcode.

Allow users to manage own profile at the frontend dashboard - enable this option if you wish your users to manage own profile at the dashboard.

Enable listings tags input at the frontend - during listing creation/edition you may hide tags input.

Require Terms of Services on submission page? - select or create new WordPress page containing your TOS agreement and assign it using this setting.

Use custom login page for listings submission process - when login required before submission user have to login using default login form. You may use any 3rd party plugin to make custom login page and assign it with submission process using the dropdown above.

Use custom login page for login into dashboard - you may use any 3rd party plugin to make custom login page and assign it with login into dashboard using the dropdown above.

 

Listings settings tab

Listings will never expire - with this option listings will never expire.

Active period of listings (in days), Active period of listings (in months), Active period of listings (in years) - with these settings listings will expire within a specified time. Note, that listings remember all these settings at their time of creation and follow them even if settings will be changed in future. This means that if listing was created when "Listings will never expire" setting was enabled - it will never expire, even after this setting have been disabled. And visa versa, listing will expire within a specified time if it was created with enabled active period.

Allow regular users to change listings expiration dates - with this enabled setting listings owners may manually set expiration dates of listings, after that date the status of listing become expired. The change of expiration dates available only for listings with limited active period, not for eternal listings. Administrators may control expiration dates even if this option is disabled.

Allow listings to renew - after expiration listings may be renewed on dashboard.

Allow unlimited categories - there isn't any limit on assigned categories within each listing.

Number of categories allowed for each listing - the number of categories allowed to be assigned with listings. When during listing creation/edition user exceeded this number - the warning message will arise.

Number of locations allowed for each listing - an ability to set exact number of locations/markers allowed for each listing.

Enable map in listing window - enable map for listing window.

Show directions panel in listing window? - directions panel will be shown on listing window when map enabled for listing window.

Directions functionality - built-in onsite routing or redirect to build routes on Google Maps service (tablet and mobile devices may use own maps applications)

Enable contact form on listing page - whether to show contact listing owner form in a separate tab on current listing page.

Contact Form 7 shortcode - The plugin was fully integrated with Contact Form 7 plugin. Insert shortcode generated by CF 7 plugin and CF 7 form will be displayed instead of standard contact form. This will work only when CF 7 plugin enabled, otherwise standard contact form will be displayed.

Listings comments system - select what to use: plugin's system or native installed system.

Listings comments mode - when the option "As configured in WP settings" was selected - it depends on WordPress discussion settings such as "Allow people to post comments on new articles" and also individual listing setting "Allow comments".

Priority of opening of listing tabs - set up priority of tabs those are opened by default. If any listing does not have any of tabs - next tab in the order will be opened by default.

Enable statistics functionality - statistics charts visible on frontend users dashboard. At the backend only total number of clicks visible.

Listings logos & images

Enable logo in infowindow - switch on/off listings logo images in map marker infowindow.

Enable lightbox on images gallery - switch on/off lightbox effect for images gallery in listing window.

Enable automatic rotating slideshow on images gallery - switch on/off auto slider for images gallery in listing window.

The delay in rotation (in ms) - the delay between rotation of slides.

Enable default logo image - when logo image file was not uploaded the listing will show default image.

Default logo image - this image will appear when listing owner did not upload own logo.

100% width of images gallery on single listing page - this switcher controls how image gallery will appear in listing window. When 100% width was disabled - next setting will be used.

Images gallery width on listing window(in pixels) - this option needed only when 100% width of images gallery is switched off. Images gallery in listing window places at the left side within provided width, right side contains other information.

Images gallery main slide mode - this setting needed to fit main slide for images proportions you preferred on your site: "Cut off image to fit width and height of main slide" for popular rectangular images (in this case images may be scaled and cut off) or "Full image inside main slide" for tall and thin images (so images will be scaled to be fully placed inside main slide).

Images number (including logo) - maximum number of images allowed to upload for listings.

Videos number (including logo) - maximum number of YouTube videos allowed to embed for listings.

Description & Excerpt settings

Enable description field - main description field may be hidden from listing.

Enable summary field - summary/excerpt field may be hidden from listing.

Excerpt max length - insert the number of words you want to show in the listings excerpts.

Use cropped content as excerpt - when excerpt field wasn't filled in by user - cropped main content will be used.

Strip HTML from excerpt - check the box if you want to strip HTML from the excerpt content only.

Ratings settings

All these settings appears when ratings addon is active. There are 3 settings:

Only registered users may place ratings - this setting restricts unregistered users to rate listings, when this setting unchecked - anyone can rate any listing. Please note, that when user places new rating, the plugin creates new record with ID of registered member, for anonymous users - the plugin stores their IPs, also the plugin saves cookie in user's browser.

Show rating in map info window - renders 5-stars rating in map info window.

Allow users to flush ratings of own listings - when this option was checked - listing owner has an ability to flush current rating of his listing.

 

Search settings tab

Search shortcode settings

These are default settings for all [webmap-search] shortcodes.

Show "What search" section? - show/hide "What search" section in search block. This setting is actual for search shortcode and compact search form.

Show "Where search" section? - show/hide "Where search" section in search block. This setting is actual for search shortcode and compact search form.

Show keywords search? - show/hide keywords field in search block. This setting is actual only for search shortcode.

Show locations search? - show/hide locations dropboxes in search block. This setting is actual for search shortcode and compact search form.

Show address search? - show/hide address field in search block. This setting is actual for search shortcode and compact search form.

Show listings counts in locations search dropboxes? - whether to show number of listings assigned with current location in brackets.

Show categories search? - show/hide categories dropboxes in search block. This setting is actual for search shortcode and compact search form.

Show listings counts in categories search dropboxes? - whether to show number of listings assigned with current category in brackets.

Show locations radius search? - show/hide radius slider in search block. This setting is actual for search shortcode and compact search form. Radius search functionality requires cURL extension on the server.

Dimension in radius search - which dimension to use: miles or kilometers. This setting is actual for search shortcode and compact search form.

Minimum radius search - set the minimum value for radius slider.

Maximum radius search - set the maximum value for radius slider.

Default radius search - this value will be set by default.

 

Default Maps tab

Default maps settings

These are default settings for all [webmap] shortcodes. You may configure individual look and behaviour of each map using shortcode parameters.

Use AJAX loading - load map markers using AJAX. The map loads only needed map markers, those visible in the viewport of the map.

InfoWindow AJAX loading - load infowindow using AJAX.

Maximum number of listings on map - place -1 if you need unlimited..

Enable Draw Panel - very important: MySQL version must be 5.6.1 and higher or MySQL server variable "thread stack" must be 256K and higher. Ask your hoster about it if "Draw Area" does not work.

Show compact search form on the map? - whether to show compact search on index and excerpt maps.

Show read more button in InfoWindow? - whether to show read more button in map marker infowindow.

Show directions button in InfoWindow? - whether to show directions button in map marker infowindow. Click will redirect to build routes on Google Maps service (tablet and mobile devices may use own maps applications)

Start address - when map markers load by AJAX - it should have starting point and starting zoom. Enter start address or select latitude and longitude. Example: 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA.

Starting point latitude

Starting point longitude

Default Google Maps zoom level (for submission page) - this zoom level is used during new listing creation, the range is 1-19. 1 - the lowest zoom (whole world), 19 - the highest zoom (individual buildings, if available).

Google Maps style - ability to set custom Google Map style, by default there are 17 map styles, information about map styles stores in php array in "maps_styles.php" file.

Default map width (in pixels) - default map width.

Default map height (in pixels) - default map height.

Show cycle during radius search? - by this option you may hide red transparent cycle that appears on map during locations search in radius. Radius search functionality requires cURL extension on the server.

Enable clusters of map markers? - when checked - map markers will be grouped in clusters.

Enable Geolocation - enable automatic geolocation.

 

Markers & Addresses tab

Addresses settings

Default country/state for correct geocoding? - this value needed when you build local site, all your listings place in one local area - country or state. You do not want to set countries or states in the search, so this hidden string will be automatically added to the address for correct geocoding when you create/edit listings.

Order of address lines - Order address elements as you wish, commas and spaces help to build address line.

Enable address line 1 field - enabled/disable address line 1 field in locations metaboxes.

Enable address line 2 field - enabled/disable address line 2 field in locations metaboxes.

Enable zip code - enabled/disable zip code field in locations metaboxes.

Enable additional info field - enabled/disable additional info field in locations metaboxes.

Enable manual coordinates fields - enabled/disable manual coordinates fields in locations metaboxes.

Map markers & InfoWindow settings

Allow users to select markers - users will be able to select specific icon for each marker according to the type of map markers.

Type of Map Markers - 2 possible types: Font Awesome icons (recommended) - icons from the Font Awesome set will be used, PNG images - custom images from "w2gm/resources/images/map_icons/icons/" folder. Site administrator may upload additional icons in this folder via the Files manager of hosting control panel or via FTP.

Using Font Awesome icons it is possible to select default icon and color of map marker. When Allow users to select markers option enabled in maps settings - users will be able to select specific icon for each marker. On "Maps listings -> Maps categories" page it is allowed to select specific marker icon and color for each category.

category_icons

Other settings related to custom PNG images. Do not touch these settings if you do not know what they mean. Modification of these settings needed when you use own custom map markers icons with own sizes. If you are using custom markers images, note that they must be of same size.

map_marker_structure

 

Email notifications tab

Days before pre-expiration notification will be sent - one time email with pre-expiration notification text will be sent to the email box of listing owner.

Pre-expiration notification - 2 tags are used: [listing] - listing name and [days] - number of days from previous setting.

Expiration notification - 2 tags are used: [listing] - listing name and [link] - the link on the listing.

Registration of new user notification (this setting is from frontend submission addon) - 4 tags are used: [author] - listing author name, [listing] - listing name, [login] - user login, [password] - user password.

Notification to admin about new listing creation (this setting is from frontend submission addon) - 3 tags are used: [user] - listing author name, [listing] - listing name, [link] - the link on the listing.

 

Advanced settings tab

Google API

Google browser API key - get your Google API key here, following APIs must be enabled in the console: Google Maps JavaScript API, Google Static Maps API and Google Maps Directions API.

Google server API key - get your Google API key here, following APIs must be enabled in the console: Google Maps Geocoding API for radius search functionality.

JavaScript & CSS

Enable lightbox slideshow? - this adds functionality to watch listings images as full size animated slideshow. Also may be disabled in order to avoid conflicts with other javascript slideshow plugins.

Do not include jQuery UI CSS - some themes and 3rd party plugins include own jQuery UI CSS - this may cause conflicts in styles.

Miscellaneous

Enable autocomplete on addresses fields - disable if you are using predefined locations tree and do not want to see country, city, e.t.c. in the input autocomplete field.

Enable "Get my location" button on addresses fields - enable/disable geolocation button on addresses fields.

reCaptcha settings

reCaptcha is used on contact listing owner forms and frontend submission form. You may get your reCAPTCHA API Keys here

WPML Settings

This section appears when WPML plugin is active.

Enable frontend translations management (this setting is from frontend submission addon) - enable/disable management of translations on users frontend dashboard.

 

Customization tab

Color palettes

Compare palettes at the frontend - this setting enables at the frontend special interactive widget helping to compare color palettes. Do not forget to switch off this setting when comparison will be completed.

color_palette_widget

When you want to finish and hide this widget - click bottom link and you'll be redirected to the settings page, preferred color palette already will be selected and you just need to save changes. While you didn't disable comparison setting, this widget still be at the frontend.

 

 

 

 

 

 

 

Color palette - selecting any of palettes will automatically change some settings below, like links and buttons colors, backgrounds of search, categories, locations blocks, primary color, jQuery UI style and so on. Changes will not appear untill you click save button.

It would be better to experiment and test other customization settings directly on the site.


Maps categories

Site admin may create/edit/delete special categories items. Management of maps categories tree has exactly the same functionality as standard WordPress categories, but these are separate items and have special administration page "Maps listings -> Maps categories".

Using Font Awesome icons it is possible to select specific marker icon and color for each category.

category_icons


Maps locations

There are 3 ways to provide locations functionality on Google Maps site:

  1. Use predefined locations - this way users will be able to select for their listings only previously defined locations, autocomplete on addresses fields and "Get my location" button on addresses fields disabled, also search by address must be disabled on search form. So addresses fields will be used only to enter streets, buildings, postal codes, e.t.c.
  2. Use addresses fields - do not insert predefined locations. Users will work only with addresses fields, autocomplete function and "Get my location" button on addresses fields will help them. Addresses fields will contain whole information about country, state, city, region, streets, buildings, postal codes e.t.c. In this way default radius search value would be quite useful to get nearby locations in search results.
  3. All in one - usage of predefined locations and addresses fields. But in such case information in addresses fields may contain country, state, city, region, the same as selected predefined locations.

locations_search_options

Predefined locations

Site admin may create/edit/delete special predefined locations items. Management of maps locations tree has exactly the same functionality as standard WordPress categories, but these are separate items and have special administration page "Maps listings -> Maps locations"

After locations levels were successfully configured and locations tree completed - users may select any predefined location from select boxes group on create/edit listing page.

predefined_locations

Note, that there is an ability to select more than 1 location for each listing.

Locations levels

Just in some words, locations levels - these are names of nesting levels of maps locations tree. By default there are 3 locations levels: Country, State and City. Site admin has an ability to edit/remove or create new locations levels. But note, that in most of cases, whole chain of locations is required to set correct location point on Google maps. This means that when your site will be used locally, for example, for users of only one country or state/region - do not delete unnecessary locations levels and locations, they are required to set correct location point at the Google map during listings creation. You'll just exclude needed locations levels from address line - yes, there is such option for each locations level, it allows to build custom address line at the frontend:


Content fields & content fields groups

Additional content fields is one of the most important part of maps sites. They allow to add some piece of information to listings. Also content fields take part in the search of listings using [webmap-search] shortcode. On "Maps Admin -> Content fields" page you may order existing content fields by drag & drop rows in the table.

content_fields-links

Each content field belongs to the type that defines its behaviour and display. You may hide field name, select custom field icon, set field as required, manage visibility. Note that you may assign fields for specific categories.

Content fields types:

  • Content (core field type)
  • Excerpt (core field type)
  • Listing addresses (core field type)
  • Listing categories (core field type)
  • Listing tags (core field type)
  • Text string
  • Textarea
  • Number
  • Select list
  • Radio buttons
  • Checkboxes
  • Website URL
  • Email
  • Date-Time
  • Price
  • Opening hours

There are 5 core field types, during initial installation the system creates 5 content fields - one field of each core field type. Core fields have special destination. This is impossible to delete any of these fields in future either create new field of core type, they will be always displayed on listing administration page (it is possible to disable content and excerpt fields on Listings settings tab). You can't edit slugs of these fields, can't order by them, can't set specific categories list, can't use in search.

Here are common settings of fields types:

Field name - required and used on listings administration page and in the search block.

Field slug - this option required and isn't able to edit for core fields.

Hide name - when checked - the name of field will be hidden at frontend pages.

Field description - this will be like a hint for users who fill in details into field.

Icon image - select icon from Font Awesome font set.

Field type - it is possible to change field type, but only for non-core fields.

Is this field required? - most of types of fields can be set as required and some can not - listings categories, listings tags, listings addresses.

In map marker InfoWindow - show value of this field in map info window. Address field always on top.

In listing window - show value of this field in listing popup window.

Search by this field? - take part in the search of listings. Some field types have special configuration options.

On advanced search panel? - when disabled - this field will appear in regular search block, when enabled - this field will be hidden by default and appear only in advanced search block

 

Now detail about each content field type separately:

Content (core field type)

At the backend this is richtext editor field to store general content of listings. Can't be searched by its value. By default this field is hidden on index and excerpt pages and visible only on listings pages.

Excerpt (core field type)

The WordPress Excerpt is an optional summary or description of a listing; in short, a listing summary. Can't be searched by its value. By default this field is shown on index and excerpt pages and hidden only on listings pages. It is possible to set up max length of output, also possible to use cropped content as excerpt, when excerpt field is empty - cropped main content will be used (look at Listings settings tab).

Listings addresses (core field type)

This is a block of listing locations and addresses. Can't be required, has special search block. This block of fields is controlled by locations manager.

Listings categories (core field type)

This is a block of categories, those were assigned to listing. Can't be required, has special search block. This block of fields is controlled by categories manager.

Listings tags (core field type)

This is a block of tags, those were assigned to listing. Can't be required.

Text string

Uses to insert short text/string data, for instance, phone number. At the backend display as pure HTML input element. Can be required, can take part in search. Has own special configuration and search configuration options:

Max length - max number of characters allowed in this field.

PHP RegEx template - this interesting option allows to set the format of field. For example, such RegEx: \(?([1-9]\d{2})(\)?)(-|.|\s)?([1-9]\d{2})(-|.|\s)?(\d{4}) matches phone number format: (xxx) xxx-xxxx

Textarea

Uses to insert long text data and/or HTML data. Its values make take part in search (as separate search field, not keywords search field). Some configuration settings: "HTML editor enabled" to enable richtext editor, "Run shortcodes" - enable to process shortcodes inside this field, also have "Max length" setting.

Number

Uses to insert numeric data. At the backend displays as pure HTML input element. Can be required, can take part in search. Has own special configuration options:

Is integer or decimal - choose how to format the value of this field.

Decimal separator - possible values: dot or comma.

Thousands separator - possible values: no separator, dot, comma or space.

Min - you may set minimum bound of this field. Leave empty if you do not need to limit this field.

Max - you may set maximum bound of this field. Leave empty if you do not need to limit this field.

Special search configuration options:

Search mode - 4 modes available:

  • enter exact number in search field
  • provide an ability to search using min-max combination of select boxes
  • search range slider with steps from Min-Max options
  • search range slider with step 1, enter exact range

Min-Max options - when second search mode selected - just complete the list of options.

Select list

At the backend displays as selectbox HTML input element. Its values may take part in search. On configuration page admin may complete selection items, also on the search form these items will be rendered as a group of checkboxes HTML inputs or selectbox or radio buttons group - this depends on search configuration setting: "Search input mode".

Radio buttons

Fields of this type inherit all features and settings from "select list" field type. At the backend displays as radio buttons group of HTML input elements. On the search form these items will be rendered as a group of checkboxes HTML inputs or selectbox or radio buttons group - this depends on search configuration setting: "Search input mode".

Checkboxes

Fields of this type inherit all features and settings from "select list" field type. At the backend displays as checkboxes group of HTML input elements. At the frontend this field looks like HTML unordered list. On the search form these items will be rendered as a group of checkboxes HTML inputs or selectbox or radio buttons group - this depends on search configuration setting: "Search input mode".

Website URL

At the backend this is combination of 2 HTML inputs: the first input for a URL of link and the second for a text of link. Can't take part in search. At the frontend looks like a link. Has 5 configuration settings:

Open link in new window - when checked - the system adds target="blank" attribute to the link.

Add nofollow attribute - when checked - the system adds rel="nofollow" attribute to the link.

Enable link text field - possible to hide text link input and the text of link will be its URL in any case.

Default link text - this is default text for the link.

Use default link text when empty - when checked - empty inputs will be replaced by default link text. When unchecked - for empty inputs the URL will be displayed as link text.

Email

At the backend displays as pure HTML input element. Can't take part in search. At the frontend looks like mailto link.

Date-Time

search_calendar_widget

At the backend this field inherits the behaviour of jQuery UI datepicker widget. Has special configuration setting to include time-selection feature.

Also in the search block this field renders as 2 separate inputs to search by date range.

Price

Fields of this type has very much like behaviour as number field type, but it is always decimal and besides "Decimal separator" and "Thousands separator" settings it owns 2 additional configuration settings: "Currency symbol" and "Currency code". The same special search configuration options: "Search mode" and "Min-Max options list". "Search range slider with steps from Min-Max options" mode on the image below:

price_field_search_slider

Opening hours

The only configuration option is "Time convention" - 12-hours clock or 24-hours clock.

opening_hours

 

Category-specific content fields

As was told earlier, it is possible to set some fields (except core fields) to function only when exact specific categories were checked on listings administration page. The same functionality appears at the search block. This is important and powerful feature allows to build category-specific content fields.
For instance: there may be one ‘price’ field especially in ‘Classifieds/For sale’ category and all its subcategories, so this field will appear only in listings, those were assigned with those categories.

 

Content fields groups

content_fields_groups

This functionality allows to combine separate content fields into groups (including core fields). There is an ability to place content fields group on a separate tab in listing popup window, also ability to hide content fields group from anonymous users - they will only see the link to login page "You must be logged in to see this info".

 

 

 

 

 

 

 

 


Maps listings

Maps listings open in popup window by clicking on "Read more" button in map marker infowindow. Clicking "Directions" button will redirect to build routes on Google Maps service (tablet and mobile devices may use own maps applications).

map_infowindow

Listings creation and management

Listings administration page may contain standard fields and metaboxes such as: title field, richtext editor for listing description, slug and excerpt fields, comments metabox. Also, according to maps settings, this page contains special metaboxes: listing categories, listing locations, content fields, media metabox with forms for images uploading and YouTube videos embedding.

When you click "Update" or "Publish" button on the listing administration page - the system tries to save listing details, when all required conditions were kept (all required fields completed, matched their formats and location, categories, images, videos items do not exceed their limits) - the listing will be saved successfully, the listing status becomes "active" and the system sets expiration date (when the active period is not eternal). If something goes wrong - the post status becomes "draft" and warning message with the list of issues appears. Note, that title field is required.

Each maps listing has special metabox on its administration page:

listing_info_metabox"Listing Info" metabox have some information fields: listing status and expiration date.

Note: listing status IS NOT the same thing as post status, listing status may be "active" or "expired". Post status may be "published", "pending review" or "draft".

 

Listing row on "maps listings" page and "Listing Info" metabox place possible "renew listing" link.

administration_listing_row

Renew listing option

This option displays when "Listings will never expire" setting has not been enabled and current listing is under "expired" status. This feature processes maps listing renewal. After renew process was completed successfully the listing status becomes "active" and the system sets new expiration date.


Search block divided into 3 sections: "What search", "Where search" and "Advanced search block"

What search section

This section includes keywords search field. Also allows to use categories filter and search by content fields, not all content fields have an ability to search listings by their values. Keywords search field is absent on compact search form on the map.

Where search section

There are locations search filter and "Search by address or zip code" field in this section. "Search by address or zip code" field is the autocomplete field, this helps users to choose item from existed addresses or zip codes.

Advanced search block

This block is hidden by default and used only for search by content fields. You may choose to hide search content field under "Advanced search" link, in order to make search block a bit smaller when there are lots of search fields enabled.

 

Search form shortcode

[webmap-search] - additional shortcode that may be used on the page to work together with [webmap] shortcode. Require to use same uid="" parameter for both shortcodes. Example:
[webmap-search uid="u1"] [webmap uid="u1"]


Google Maps, Marker Icons and Google API keys

Markers Icons depends on the type selected in maps settings. Frontend page may render empty map when there aren't any listings with assigned locations and defined markers.

Here is simple example of how Google map looks with custom marker icons and special radius search layer:

google_map

When appropriate setting "Allow users to select markers" is checked (Custom markers on google map) - during listings creation/edition users may select custom marker icons. On "Maps listings -> Maps categories" page it is allowed to select specific marker icon and color for each category.

During listings creation/edition there is an option to set marker coordinates (latitude and longitude) manually or by drag & drop of existing marker by mouse.

location_enter

Clicking "Generate on google map" button processes targeting and compiling of addresses to render markers on the map.

Google API keys

Since 22 June 2016 Google requires mandatory Maps API keys for maps created on NEW websites/domains. Otherwise it may cause problems with Google Maps, Geocoding, addition/edition listings locations, autocomplete on addresses fields.

google_maps_error

You have to login to Google API console, create new project or select existing one and create 2 API keys: browser and server keys. Enter them in appropriate settings on Advanced settings tab of the plugin settings page Maps Admin -> Maps Settings

Create_project
Create_API_key

Take special attention to "Accept requests from these HTTP referrers (web sites)" (for browser key) and "Accept requests from these server IP addresses" (for server key) fields. If they will be wrongly filled in - it may cause problems with Google Maps and their functionality. You can try to leave them blank.

Also you have to enable following APIs in the console: Google Maps JavaScript API, Google Static Maps API, Google Places API Web Service, Google Maps Geocoding API and Google Maps Directions API.

Enabled_APIs

Sometimes it requires some time for keys activation. Also you could try to speed up the process (as some users did) in the following way: disable, delete, re-enable and re-create all your APIs and keys (or, at least, the ones that give you problems), and see if this fixes the issue for you. If you prefer, you could try with API keys from different account instead, but both keys from one account.


Frontend dashboard & submission

These features become available when "Frontend submission & dashboard addon" was enabled.

Create new page with [webmap-dashboard] shortcode if you wish your logged in users to manage their listings and profile on the frontend dashboard page.

"Submit new listing" button appears on front panel, clicking this button - users start the process of listing creation. Note, that the page with [webmap-submit] shortcode required.

Special note: additional pages with [webmap-submit] and [webmap-dashboard] shortcodes must not have main maps page with [webmap] shortcode as parent.

submission_form

When "Select frontend submission login mode" setting is set to "Login required" option - users will have to be logged in before submission. After successfull submission, according to "Post status after frontend submit" setting, listing post status will become: Pending Review, Draft or Published.

There are some settings for frontend submission addon.


Customization

The customization of the plugin requires some experience with HTML, CSS and even PHP to change the templates around to an arbitrary theme look. Plugin templates are designed to work relatively well with most themes, but if you do have the need to override these templates to match your theme please try to follow these conventions:

  • if you want to change the layout or styles of google maps section on your site do not modify existing CSS files, instead copy them and give exactly the same name to new file, just add "-custom" postfix to the end of name before file's extension. For example, w2gm/resources/css/frontend.css file must be named w2gm/resources/css/frontend-custom.css. Using such method will save your modifications during further updates
  • the same convention for any templates - .tpl files in "w2gm/templates/" folder. For example, custom "w2gm/templates/frontend/listing_single.tpl.php" template must be named "w2gm/templates/frontend/listing_single-custom.tpl.php"
  • other part of customization is that you may manage map markers icons

The inclusion of CSS files on frontend pages has following order:

  1. w2gm/resources/css/bootstrap.css - basic CSS rules
  2. w2gm/resources/css/frontend.css - main file, controls the layout of maps markup
  3. wp-content/uploads/w2gm-plugin.css, special CSS file for dynamic plugin options
  4. w2gm/resources/css/frontend-custom.css - (optional) custom main fronted file
  5. w2gm/addons/w2gm_ratings/resources/css/rater.css - CSS file from ratings addon
  6. w2gm/addons/w2gm_ratings/resources/css/rater-custom.css - (optional) custom CSS file for ratings addon
  7. w2gm/addons/w2gm_fsubmit/resources/css/submitlisting.css - CSS file from frontend submission addon
  8. w2gm/addons/w2gm_fsubmit/resources/css/submitlisting-custom.css - (optional) custom CSS file for frontend submission addon

The plugin has special customization settings to change some elements on frontend pages like links and buttons colors, backgrounds of search, primary color, jQuery UI style and so on.


How to modify texts and strings

If you use WordPress in English and simply want to modify texts and strings of the plugin follow these steps:

  1. on "Settings -> General page select needed site language
  2. now you are able to work with default "languages/W2GM-en_US.po" file and modify any texts and strings using poEdit
  3. Every time you save W2GM-en_US.po file, PoEdit automatically generates W2GM-en_US.mo file, which is the one WordPress uses and basically the only one you need to upload on the server

Always backup W2GM-en_US.po and W2GM-en_US.mo files in order to save your changes after plugin upgrade.


Translations & Multi-Language Support

Web 2.0 Google Maps plugin is fully adapted for translations - look at "languages/" folder with W2GM.pot and W2GM.po files. Use poEdit to translate W2GM.pot file. The process of translation is similar to modifying texts and strings:

  1. duplicate the W2GM.pot file and rename it to W2GM-lang_COUNTRY.po
  2. Example for the Portuguese Brazil lan: W2GM-pt_BR.po
    -- pt_BR means Portuguese Brazil, but many languages don't have a country variation...
    -- you'll have to fill in with your own language
  3. on "Settings -> General page select needed site language
  4. Every time you save translated W2GM-lang_COUNTRY.po file, PoEdit automatically generates W2GM-lang_COUNTRY.mo file, which is the one WordPress uses and basically the only one you need to upload on the server

Always backup *.po and *.mo files in order to save your changes after plugin upgrade. Or you may place these files into "wp-content/languages/plugins/" folder.

WPML

The plugin fully compatible with WPML plugin. It allows to easily translate maps listings, maps categories, tags, predefined locations. Also users may manage listings translations at the frontend of the site.

dashboard_wpml

Note: main map page must have translations in those languages you wish to operate. The same thing with dashboard and submission pages.

When user clicks "Add translation to ..." button add_translation - new copy of corresponding listing in selected language will be created. This will be exact copy of listing from the original language, maps categories, locations and content fields assigned with this listing will be copied either.

Note, that listing operations are strongly connected beetween translations, this means that when user or admin clicks to activate, renew or when the active period of listing expires - all related translations also will process these oprations. But content of translations is independent, also each translation may be deleted independently.

When WPML plugin is active - new setting appear on Advanced tab of maps settings page:

Enable frontend translations management - this allows to manage translation directly from frontend dashboard.


CSV Import

We place sample CSV file into "documentation/" folder in the plugin archive.

  1. On the second step of importing you'll collate CSV headers of columns with existing listings fields, this means there isn't fixed format for CSV files.
  2. The only required column in CSV file is the column for listings titles. Also information about author must be provided - in any column of CSV file or by setting default author in settings.
  3. In order to assign categories/tags with each listing - specify category/tag slugs in one CSV column and separate them with special delimiter. This delimiter must be any string character, but not the same as the delimiter for separation of CSV columns.
  4. You may set to auto-create new maps category/tag. In such case, when there isn't any existing category/tag with provided slug - new root category/tag will be created automatically and that string in the CSV column will be used as category/tag name.
  5. MultiValues - are such fields, those may have more than one value, for example, checkboxes content field. Separate them in one CSV column with special delimiter in the same way as for assigned categories.
  6. Also you may upload ZIP archive with images files for new listings. Specify names of images files in one CSV column and separate them with special delimiter in the same way as for assigned categories. Note, that images files must be in the root inside ZIP archive, not inside folder.
  7. By default listings authors will be specified in one of CSV columns, there must be existed user ID, user login or user email. Also you may switch to assign all new listings with one specific existed user.
  8. 2 possible ways to import addresses and locations for new listings: define already existed maps location ID or you may select up to 4 address parts in different CSV columns (e.g., building number in one column, street in another column, city in separate column, ......). Also you may set special column for names of existed map icons files: for example, there is such map marker icon file "w2gm/resources/images/map_icons/icons/_new/Boat.png", so you have to place "_new/Boat.png" into CSV column. Using Font Awesome icons just place the name of icon "w2gm-fa-automobile".
  9. When you do not have latitude/longitude information for Google Maps markers - Google geocoding service may be used to build markers points from addresses (cURL extension required), but you can only import maximum of 2500 addresses per day, this is the max query limit of the Google geocoding service, unless you have a Google Maps API business license.
  10. There is an option to configure all imported listings as claimable, this option is shown when frontend submission addon was enabled and also claim functionality was switched on.
  11. When the size of your CSV file is very large - this may slow down the server and break the process of import, you may try to split the file into smaller CSV files.
  12. Recommended to make whole backup of the database before import.