Before you get started with cMap, you need to make sure you have Connections installed and setup. If you have not done this already, please take a moment to read and follow the QuickStart.
After you have installed cMap, the last step is to activate it. Here’s how:
Navigate to the Connections : Template admin page.
Find the cMap template under the Available Templates section.
Click the Activate button.
The anatomy of cMap
Searchable Category Drop Down
Keyword Search
Logo
Contact Information
Bio Content Tray
Notes Content Tray
Map Content Tray
Configuration
cMap uses the Template Customizer feature introduced in Connections 8.4. To enter the the Template Customizer follow these simple steps:
Navigate to the Connections : Template admin page.
Find the cMap template. If you have activated it, it will be at the top of the page. If you have not activated it, it will be in the Available Template section.
Click the Customize button.
After you enter the Template Customizer you will have over 100 interactive point and click options available which will allow you to tweak the template to better accommodate your needs and style it to better match your theme.
The Template Customizer will open on the Display panel by default. There are many panels which are used to organize the options. Here is the list of panels with a brief description of the options available within each:
Global Options :: Options such as those relating to the character index. Changing these options will affect all templates.
Search :: Choose whether or not to display keyword search control.
Category Select :: Choose whether or not to display the category drop down and whether or not the category counts or empty categories should be shown.
Pagination :: Chose whether or not to enable pagination control, where to display it and change the number of entries displayed per page.
Display :: Allows you to choose which element/fields to display.
Style :: Provides options to control the card color, text color and whether or not to display the gradient and/or drop shadow.
Image :: Choose which image to display, set its size and crop mode and more.
Bio Tray Image :: Choose which image to display, set its size and crop mode and more.
Map :: Whether or not to display the map.
Strings :: Customize many of the template specific strings.
Advanced :: Many advanced options such as name and address format.
Tip
The results card view and the profile detail view can be configured independently. To configure the profile detail view, click any entry name. After you have completed, click the “Go Back” link to get back to the result list card view.
Advanced
In addition to the ability to be customized by the Template Customizer, cMap provides a large array of shortcode options. The available shortcode options are, for the most part, exactly the same as those that are available in the Template Customizer. These allow you to use the Template Customizer to change the template options globally and the shortcode options allow you to override those global options per shortcode instance.
Tip
Here are a couple quick tips on working with shortcodes, useful not only for the Connections shortcodes, but for all plugins that use them.
First, always switch the post editor to the Text tab.
Second, never copy paste them from a website. It is always best to manually type them out.
That should solve and help prevent many issues when working with shortcodes.
Note
All shortcode options will affect both the results list card view and the profile detail view.
Background Color and Gradient
The background gradient and background color can be turned off and the color changed.
Here are some examples:
Change the background color from grey to a light blue with gradient.
[connections background_color="#CAE1FF"]
[connections background_color="#CAE1FF"]
Keep the light blue background color without the gradient.
The background_color option accepts any valid CSS color.
Disable Search
If you wish to not display the keyword search use the enable_search shortcode option.
[connections enable_search=false]
[connections enable_search=false]
Category Dropdown
To remove the searchable category drop down use the enable_category_select shortcode option.
[connections enable_category_select=false]
[connections enable_category_select=false]
Any categories which are “empty” will not be displayed in the category drop down. Empty means no entries have been assigned to that category. If you like to show empty categories, the show_empty_categories shortcode option can be used.
[connections show_empty_categories=true]
[connections show_empty_categories=true]
You can also choose to show the number of entries assigned to a category in the drop down by using the show_category_count shortcode option.
NOTE: The entries in the moderation queue will not be included in the count.
The category drop down will automatically show all categories. You can use enable_category_by_root_parent option to limit which categories are shown in the drop down by limiting the drop down to specific root parent categories [see definition of root parent category]. This is very useful if you want to create multiple directories. For example on a chamber of commerce site you could show a directory business members on one page and on another page a directory chamber officers with all entries managed by a single installation of Connections.
See this FAQ for an example of how to use this option.
DEFINITION:root parent category – This is a category that is not a child of another category.
NOTE: This option must be use with the category shortcode option.
Pagination
To disable the pagination feature use the enable_pagination shortcode option.
[connections enable_pagination=false]
[connections enable_pagination=false]
When pagination is enabled, the page control will be displayed after of the result list by default. You can change the position to have it shown before the result list or in both positions.
To have it show before the result list use:
[connections pagination_position=before]
[connections pagination_position=before]
To show it in both positions use:
[connections pagination_position=both]
[connections pagination_position=both]
If you would like to change how many entries are shown per page the page_limit shortcode option can be added to the shortcode. To change the results per page to 10 this is the shortcode you would use.
[connections page_limit=10]
[connections page_limit=10]
Entry Details
By default all of the entry’s details that were entered will be displayed. Each field type can be configured to not be displayed. Here is the list of shortcode options that control whether or not a data type should be displayed:
show_title
show_org
show_dept
show_contact_name
show_family
show_addresses
show_phone_numbers
show_email
show_im
show_social_media
show_dates
show_links
show_last_updated
show_categories
show_return_to_top
enable_bio
enable_bio_head
enable_note
enable_note_head
enable_map
Here’s a sample shortcode which would disable the display of addresses, phone numbers and link:
NOTE: The show_family will only have an effect if the entry type is a family.
Formatting the Name
The name shown will be the full name of the entry including the prefix, middle name and suffix. This can be configured by using the name_format shortcode option.
The name_format option accepts only a few specific tokens. A token is a word wrapped with the % symbol, for example, %first% is a token.
The valid tokens are:
%prefix%
%first%
%middle
%last%
%suffix%
The default for name_format is %prefix% %first% %middle% %last% %suffix%. If you would like to display just the first and last name, you would use this shortcode:
[connections name_format='%first% %last%']
[connections name_format='%first% %last%']
NOTE: The name format will also be used on the entry’s profile detail page.
Changing the Label Text
The best way to change the strings in cMap is to use the Template Customizer. Here are the steps you can follow to change the template specific strings in cMap using the Template Customizer:
Navigate to the Connections : Template admin page.
Click the Customize button for cMap.
The page will reload with the Customizer on the left and a preview on the right.
Click the back arrow in the upper left of the Customizer.
Click the Strings panel.
Change the strings as desired.
Click an entry name in the preview. The preview will reload displaying the entry detail profile page.
Make the same changes again. This is required because the results list view and the profile detail view can be configured separately for greater flexibility.
Click the Save and Publish button and then exit the Customizer.
Alternatively, you can change the template specific strings in the cMap template by using the Say What? plugin as outlined in this QuickTip. Following the instructions given in the QuickTip will change the strings wherever they are used throughout all of Connections and within the cMap template.
The text domain for the address, phone and email labels will be connections.
There are several template specific strings in which you would use the textdomain, cnt_cmap. These template specific strings are:
Select Category
Show All Categories
No Image Available
Show Map
Close Map
Biography
Show Bio
Close Bio
Notes
Show Notes
Close Notes
Contact
Categories:
Optionally and in addition to using the Template Customizer or the Say What? plugin the strings can be overridden by using shortcode options. Here’s the complete list and their default value:
str_select='Select Category'
str_select_all='Show All Categories'
str_image='No Image Available'
str_map_show='Show Map'
str_map_hide='Close Map'
str_bio_head='Biography'
str_bio_show='Show Bio'
str_bio_hide='Close Bio'
str_note_head='Notes'
str_note_show='Show Notes'
str_note_hide='Close Notes'
str_contact='Contact'
str_category_label='Categories: '
str_home_addr='Home'
str_work_addr='Work'
str_school_addr='School'
str_other_addr='Other'
str_home_phone='Home Phone'
str_home_fax='Home Fax'
str_cell_phone='Cell Phone'
str_work_phone='Work Phone'
str_work_fax='Work Fax'
str_personal_email='Home Email'
str_work_email='Work Email'
Examples
// Example 1: Change the 'Home Phone' label to 'Phone'[connections str_home_phone='Phone']// Example 2: Change the 'Personal Email' label to 'Email'[connections str_personal_email='Email']/*
* Example 3: You can add as many strings as needed.
*
* Change the 'Personal Email' label to 'Email'
* AND
* Change the 'Home Phone' label to 'Phone'
*/[connections str_personal_email='Email' str_home_phone='Phone']
// Example 1: Change the 'Home Phone' label to 'Phone'
[connections str_home_phone='Phone']
// Example 2: Change the 'Personal Email' label to 'Email'
[connections str_personal_email='Email']
/*
* Example 3: You can add as many strings as needed.
*
* Change the 'Personal Email' label to 'Email'
* AND
* Change the 'Home Phone' label to 'Phone'
*/
[connections str_personal_email='Email' str_home_phone='Phone']
Miscellaneous Formatting
Here’s a list of miscellaneous formatting shortcode options that can be set and their default value:
Rather than explain each of these above options individually we’ll go over the addr_format shortcode option since all are used the same way.
The addr_format option accepts only a few specific tokens. A token is a word wrapped with the % symbol, for example, %label% is a token.
The valid tokens for the addr_format option are:
%label%
%line1%
%line2%
%line3%
%city%
%state%
%zipcode%
%country%
NOTE: The %label% will be the address type.
When processing the display of the address, Connections will scan for each token and replace it with the corresponding address segment. Each token should only be used once even though you could use each token more than once, but that is not recommended.
Here is the default layout of the tokens that create the format of the address:
The block layout is achieved using CSS which can easily be overridden to make the address segments display inline. How to override the CSS is a separate topic.
Examples
This will display the address minus the label and country fields.
Rather than explain each of these above options individually we’ll go over the address_types shortcode option since all are used the same way.
The address field has the Type option when adding an address. The default choices are: Home, Work, School and Other. It is possible to limit the output to any combination of these address types regardless if an address is entered for an address type or not by utilizing the address_types shortcode option.
Examples:
Show only the home address type.
[connections address_types='home']
[connections address_types='home']
Show only the work address type.
[connections address_types='work']
[connections address_types='work']
Show both the home and school address types.
[connections address_types='home, school']
[connections address_types='home, school']
The examples demonstrate the address_types shortcode option.
FAQs
Why am I receiving “Oops! Something went wrong.” error?
If you are receiving the error message instead of a Google Map then you need to set your Google Maps API Browser and Server keys. To learn how, please refer to the Get Google Maps API Keys tutorial.
Can I switch templates without having to reenter my entries again?
Absolutely! You can switch templates as often as you wish, your entries will be intact. Think of templates for Connections like themes for WordPress. The primary purpose of a WordPress theme is to change the visual style of your site. The primary purpose of Connections’ templates, just like WordPress themes, is to change the visual style of your directory. Just as you can switch themes in WordPress and not loose your pages and posts because they are saved in the WordPress database, you can switch templates in Connections.
As soon as I select a ‘category’ search is performed with the keyword ‘Search’ by default.
This is likely being caused by the theme including a “buggy”, in my opinion, HTML5 shim script. The purpose of these shim scripts is to enable HTML5 features in browsers that do not support them. They work pretty well … but, there seems to be a bug in this shim script.
When you click on a category, the “Search” placeholder string in the search box is being sent as a search keyword term. So you’re actually searching for “Search” within the category being selected. Obviously not what we want to do.
The fix will be to remove the “Search” placeholder text. To do this easily, we can use another plugin.
Changing the search string can be done with the Say What? plugin.
It’ll add a new Text Changes menu item under the Tools admin page.
Click Add New, enter the string exactly as shown in Connections, Search.
Next enter connections (notice the lack of capitalization, that’s important!) as the domain and then enter your new text. In this case leave it blank.
There’s a few reason the map would not work. Let go thru them…
1. The theme does not have the wp_footer() template tag in its foot. If the theme does not have this, it will break many plugins that require it.
2. There could be a fatal javascript error in another plugin or in the theme that is causing other plugin’s javascripts to not run. You can check this by loading your site into Chrome, hitting the F12 key and then clicking the Console tab. If there are errors listed here, they could be why the map is not working.
3. The theme or another plugin is also queueing the Google Maps API. When it is loaded more than once, it will often times fail to function correctly. If that is the case, try unchecking the Google Maps API option on the Connections : Settings admin page under the Advanced tab in the Compatibility section.
There are primarily two reasons this issue occurs:
One, when copy pasting the shortcode into a page or post while using the rich text editor (the Visual tab) HTML tags will also be pasted. The solution is to paste the shortcode into the HTML editor (the HTML tab) or use the “Paste as Plain Text” button in the Visual editor.
To fix this, go to the page or post where you pasted the Connections shortcode, switch to the HTML editor and remove any HTML tags that surround the shortcode, for example <pre></pre> and <code></code>.
Two, many commercial themes support shortcodes named [raw] or [noformat]. If your theme does, wrap the Connections shortcode within one of them. Here are examples of how to use the [raw] and [noformat] shortcodes.
If the [[raw]] or [norformat] shortcodes do not work, please visit the Support Forum for assistance. A copy of your theme may be required in order to debug the issue.
UPDATE: 03-15-2013
As of version 0.7.6.1 of Connections there is a setting can be enabled that attempts to fix the issue with themes that implement the [[raw]] shortcode. Please go to the Connections : Settings admin page, Advanced tab. Under the Compatibility section, please check the Templates option and click the Save Changes button.
The package could not be installed. The theme is missing the style.css stylesheet.
I get the following error, what does it mean?
The package could not be installed. The theme is missing the style.css stylesheet.
If you are trying to install a Connections template as a theme you will receive this error. Connections templates must be installed as a plugin. Please following the template installation instructions found here:
How do I embed a YouTube or Vimeo video in the Bio or Notes field?
To embed videos in to the bio and notes field you must use the WordPress shortcode. The examples show only YouTube and Vimeo, but any of the sites that the shortcode supports can be used.
Can I use cMap on two different pages showing different categories in the drop down?
Sort of, you can limit the list to specific root parent categories. What is meant by root parent is that the category is not a child of another category. This can be done by using the category shortcode option and a cMap enable shortcode option, enable_category_by_root_parent. Here is an example that will only show the root parent categories 2, 5, 12 and their children categories in the drop down.
The manner in which this plugin alters the outgoing links seem to make the links for both the bio and notes none functional. Currently the only solution is to deactivate this plugin.
NOTE: This FAQ was written based on External Links 4.2
Formidable Pro ship with an older version of Chosen which breaks Connections use of it. The only solution is to replace the version that ships with Formidable Pro with the newer version that ship with Connections.
Copy the files from this folder:
../wp-content/plugins/connections/vendor/chosen/
to this folder:
../wp-content/plugins/formidable/pro/js/
NOTE: This FAQ was written based on Formidable Forms 1.07.09
When both cMap and WP Flexible Map are installed on the same site the directory page using the cMap template will no longer function. The issue is usually caused by the Google Maps API being loaded on the page twice. cMap will load it only on its page in the page footer. Mapping plugins should do the same, but some, like WP Flexible Map, load it on every page regardless if there is a map or not. This of course causes the Google Maps API to be loaded on the cMap page twice which can break the API.
The solution is to use a mapping plugin which will load the Google Maps API only on its pages. One such plugin recommended by a user is Robo Maps.
NOTE: This FAQ was written based on WP Flexible Map 1.9.2
Both Connections and Comprehensive Google Map Plugin requires the use of the Google Maps API. The Comprehensive Google Map Plugin has a function which looks for other instances where the Google Maps API has been registered and if it finds one, it unregisters it. This will completely break templates [and any other plugin, actually] which require the Google Maps API because the Google Maps API is registered as a dependency. If the dependency does not exists, WordPress will not load any other script which depends on the missing dependency. There is a solution…
Install the Code Snippets plugin.
Add a new snippet using this:
[connections enable_category_select=false]
[connections enable_category_select=false]
Save and Activate the new snippet.
Now, both Connections, its template and the Comprehensive Google Map Plugin should play nicely together.
The only other option is to use another plugin. A user suggested Leaflet Maps Marker as an alternative to Comprehensive Google Map Plugin.
NOTE: This FAQ was written based on Comprehensive Google Map Plugin 9.0.20
This plugin loads an older version of jQuery even though the bundled version of jQuery may already be loaded which can cause other JavaScripts and jQuery libraries to fail to run. What this means to Connections is that if the template supports expandable content trays for maps bio and notes they will fail to work.
NOTE: This FAQ was written based on Marquee XML RSS Feed Scroll 3.0
This plugin re-writes the links created for the Note and Bio tray links on the cMap and Market templates causing them to no longer function. The only fix it to disable this plugin.
NOTE: This FAQ was written based on External Links 4.0.6
There seems to be a JavaScript conflict wit this plugin that causes the drop down to auto-scroll to the bottom of the list. When using the mouse scroll wheel it’ll make it not possible to select items in the middle of a long list of categories. There only seems to be two solutions. Drag the scroll bar to scroll through the list of categories or deactivate the plugin and find an alternative solution.
When this plugin is active it alters the query strings that WordPress attaches to the JavaScript and CSS files. This will break the loading of the Google Maps API by removing the “sensor” parameter. When this is removed, the Google Maps will not work. How can you check for this error? You can check the browser’s developer tools console log. Each browser is different on where the console log can be found but in most cases it can be brought up by hitting the F12 key and switch to the console log section. The error you’re looking for is:
The Google Maps API server rejected your request. The “sensor” parameter specified in the request must be set to either “true” or “false”.
UPDATE: This issue can be resolved by un-checking the option Generate Random Version Number in Better Security Tweaks
UPDATE 2: When performing a search in IE or Chrome, Firefox seems to be unaffected, the results will be shown. However, if you perform a second search from within the previous search results, you will receive a 404 error. At this time there is no solution other than to deactivate Better WP Security.
NOTE: This FAQ was written based on Better WP Security 2.18
This plugin re-writes the links created for the Note and Bio tray links on the cMap and Market templates causing them to no longer function. The only fix it to disable this plugin.
NOTE: This FAQ was written based on Auto Thickbox Plus .3.
UPDATE: Version .6 and newer resolves this conflict.
If the template you are using has an embedded Google map and only an empty box is showing, the cause might be a conflict with Events Made Easy.
This plugin still uses the Google Maps API 2 which is loaded in the head of every page instead of just the pages it is needed on.
Connections uses Google Maps API 3 which is only loaded on the page foot where it is being used.
When the request for the map is sent to Google, it is using the Google Maps API 2 because it was loaded first in the page head by Events Made Easy. The map request from Connections is sent in the Google Maps API3 format which causes a JavaScript error and the map fails to load.
Unfortunately there is no fix for this conflict. The developer for Events Made Easy would need to alter it so it only loads its JavaScripts on the pages where the plugin needs them.
NOTE: This FAQ was written based on Events Made Easy 1.0.1
The author of the theme uses a different jQuery plugin to customize select boxes, to which they have set to affect all select boxes globally within the theme. In my opinion, not a smart way of doing it because it’ll affect any plugin that happens to output a select box. There are two fixes, both of which may not be ideal. The first, you could disable the the jQuery plugin the theme uses. The downside, no select boxes in the theme will be enhanced other than the one in template. The second solution would be to disable the jQuery plugin in the template. The downside here would be threefold, you would loose the inline search for categories, the select box will be blank until clicked and the categories will loose their hierarchical appearance. I, obviously recommend disabling the theme’s jQuery plugin but I’ll give you the instructions for both.
To disable the theme’s jQuery plugin:
NOTE: Before following these step, check the theme’s settings to see if there is an option to turn this off.
1. Open the theme-scripts.js file found here: ../wp-content/themes/classipress/includes/js
2. On line 14 add /* to before the $.
3. On line 17 add */ to after the });.
4. Save the file.
5. Upload it back to the originating folder overwriting the original file.
To Disable the cMap jQuery plugin:
1. Open the template.js file found here: ../wp-content/connections_templates/template-name
2. On line 79 add // to before the $.
3. Save the file.
4. Upload it back to the originating folder overwriting the original file.
NOTE: This FAQ was written based on ClassiPress 3.1.9
Here are a couple quick tips on working with shortcodes, useful not only for the Connections shortcodes, but for all plugins that use them.