Installation
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.
Installing the cMap template is just like installing any other plugin. Please follow the detailed template installation instructions.
In order for maps to load on your site you will have to setup Google Maps API keys. Here’s how to setup your Google Maps API keys.
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:
- 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
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
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"] |
Keep the light blue background color without the gradient.
[connections background_color="#CAE1FF" background_gradient=FALSE] |
Keep the default grey background without the gradient.
[connections background_gradient=FALSE] |
Remove the background color and gradient.
[connections background_color="transparent" background_gradient=FALSE] |
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] |
Category Dropdown
To remove the searchable category drop down use the enable_category_select
shortcode option.
[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] |
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.
[connections show_empty_categories=true show_category_count=true] |
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] |
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] |
To show it in both positions use:
[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] |
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:
[connections show_addresses=false show_phone_numbers=false show_links=false] |
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%'] |
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'] |
Miscellaneous Formatting
Here’s a list of miscellaneous formatting shortcode options that can be set and their default value:
name_format='%prefix% %first% %middle% %last% %suffix%'
contact_name_format='%label%%separator% %first% %last%'
addr_format='%label% %line1% %line2% %line3% %city%, %state% %zipcode% %country%'
phone_format='%label%%separator% %number%'
email_format='%label%%separator% %address%'
link_format='%label%%separator% %title%'
date_format='%label%%separator% %date%'
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:
%label% %line1% %line2% %line3% %city%, %state% %zipcode% %country%
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.
[connections addr_format='%line1% %line2% %line3% %city%, %state% %zipcode%'] |
This will display the address with the state and city switched, which is common in many parts of the world.
[connections addr_format='%label% %line1% %line2% %line3% %state%, %city% %zipcode% %country%'] |
Miscellaneous Field Types
Several of the fields can have their output limited based on type. Here are the list of shortcode options and their default values:
address_types='home, work, school, other'
phone_types='homephone, homefax, workphone, workfax, cellphone'
email_types='personal, work'
date_types='baptism, certification, employment, membership, graduate_high_school, graduate_college, ordination'
link_types='website, blog'
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'] |
Show only the work address type.
[connections address_types='work'] |
Show both the home and school address types.
[connections address_types='home, school'] |
The examples demonstrate the address_types shortcode option.
FAQs
Can I display cMap in columns?
The cMap template was not designed to be displayed in a columnar layout, and there are display inconsistencies with the sliding content trays. However, if you are not using those features or are not concerned with the content shifting due to the sliding content tray, you can use the following CSS to force the template into a multiple-column layout. Add this custom CSS to the theme’s custom CSS area found in the Customizer.
#cn-cmap .cn-list-body { align-items: stretch; display: flex; flex-direction: row; flex-wrap: wrap; justify-content: space-around; overflow: hidden; width: 100%; } #cn-cmap .cn-list-item { margin: 0 5px; height: 100%; width: calc( 33% - 10px ); } #cn-cmap .cn-list-item .cn-entry { height: 100%; } #cn-cmap .cn-list-body { display: grid; direction: rtl; /* Change 3 to the number of desired columns. */ grid-template-columns: repeat( 3, minmax( 0, 1fr ) ); grid-auto-rows: 1fr; grid-column-gap: 10px; grid-row-gap: 10px; min-height: 0; min-width: 0; width: 100%; } #cn-cmap .cn-list-item { display: flex; min-width: 0; } #cn-cmap .cn-list-item .cn-entry { margin: 0 !important; width: 100%; overflow: hidden; }
Permalink | Comments Closed
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.
Permalink | Comments Closed
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.
Permalink | Comments Closed
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.
That should fix it.
Permalink | Comments Closed
Why doesn’t the map work?
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.
Permalink | Comments Closed
Why does the template layout look wrong?
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.
[raw][connections][/raw] |
[noformat][connections][/noformat] |
Why? The theme is removing and then re-applying the wpautop filter which is interfering with all shortcodes. Here’s a link to a comment that explains the issue in more detail: http://wpforce.com/prevent-wpautop-filter-shortcode/#comment-1328. And here’s another link with more info: http://theandystratton.com/2011/shortcode-autoformatting-html-with-paragraphs-and-line-breaks
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
Permalink | Comments Closed
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:
http://connections-pro.com/documentation/install/templates/
Permalink | Comments Closed
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.
/* * Example 1 * Embed a YouTube video */ [embed]http://www.youtube.com/watch?v=Zs-8-cWFbOU[/embed] |
/* * Example 2 * Embed a Vimeo video */ [embed]http://vimeo.com/26963550[/embed] |
If you would like to embed a video that pops using a lightbox effect, use the WP Video Lightbox plugin instead of the shortcode.
Permalink | Comments Closed
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.
[connections category='2,12,5' enable_category_by_root_parent=true] |
Permalink | Comments Closed
Plugin Conflicts
External Links
http://wordpress.org/plugins/sem-external-links/
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
Permalink | Comments Closed
Formidable Forms
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
Permalink | Comments Closed
WP Flexible Map
https://wordpress.org/plugins/wp-flexible-map/
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
Permalink | Comments Closed
Comprehensive Google Map Plugin
http://wordpress.org/extend/plugins/comprehensive-google-map-plugin/
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:
add_filter( 'wp_head', 'cn_market_register_google_maps_api', 999 ); function cn_market_register_google_maps_api() { global $connections; if ( ! is_ssl() ) wp_register_script( 'cn-google-maps-api', 'http://maps.googleapis.com/maps/api/js?sensor=false', array( 'jquery' ), CN_CURRENT_VERSION, $connections->options->getJavaScriptFooter() ); if ( is_ssl() ) wp_register_script( 'cn-google-maps-api', 'https://maps.googleapis.com/maps/api/js?sensor=false', array( 'jquery' ), CN_CURRENT_VERSION, $connections->options->getJavaScriptFooter() ); } |
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
Permalink | Comments Closed
Marquee XML RSS Feed Scroll
http://wordpress.org/extend/plugins/marquee-xml-rss-feed-scroll/
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
Permalink | Comments Closed
External Links
http://wordpress.org/extend/plugins/sem-external-links/
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
Permalink | Comments Closed
Photonic
http://wordpress.org/extend/plugins/photonic/
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.
NOTE: This FAQ was written based on Photonic 1.22
Permalink | Comments Closed
Better WP Security
http://wordpress.org/extend/plugins/better-wp-security/
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
Permalink | Comments Closed
Auto Thickbox Plus
http://wordpress.org/extend/plugins/auto-thickbox-plus/
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.
Permalink | Comments Closed
Events Made Easy
http://wordpress.org/extend/plugins/events-made-easy/
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
Permalink | Comments Closed
Theme Conflicts
ClassiPress
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
Permalink | Comments Closed