Introduction
Gridder adds over 70 options to the Connections shortcode that customize its display and function. These can be used in combination with the standard core shortcode options.
Multiple shortcode options are added to the same shortcode, do not add the shortcode to the page multiple times with different options. Here’s an example of using multiple shortcode options with the Connections shortcode:
[connections enable_search='TRUE' background_color="#0e8a8a" color="fff" overlay="none" image_width=120 image_height=120 image_opacity=.4] |
The anatomy of Gridder
- The overlay contains the name and title of the entry.
- The panel which contains the entry contact info, bio excerpt, and view profile link.
- The panel contact info which contains the phone, email, and social media icons.
- The entry bio excerpt.
Image Credit: Photo by stockimages via freedigitalphotos.net.
Configuring the Optional Features
Important
Enable Search
By default, Gridder does not display the keyword search. If you require this feature, it can easily be enabled with the enable_search shortcode option.
[connections enable_search='TRUE'] |
Enable Category Search
By default, Gridder does not display the category search. If you require this feature, it can easily be enabled with the enable_category_select shortcode option.
[connections enable_category_select='TRUE'] |
Any categories which are “empty” will not be displayed in the category dropdown. 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 enable_category_select='TRUE' show_empty_categories='TRUE'] |
You can also choose to show the number of entries assigned to a category in the dropdown by using the show_category_count shortcode option.
[connections enable_category_select='TRUE' show_empty_categories='TRUE' show_category_count='TRUE'] |
NOTE: The entries in the moderation queue will be included in the count.
Pagination
By default, Gridder does not paginate the result list. If you require this feature, it can be enabled with the enable_pagination shortcode option.
[connections enable_pagination='TRUE'] |
When pagination is enabled, the page control will be displayed after the result list. 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 enable_pagination='TRUE' pagination_position="before"] |
To show it in both positions use:
[connections enable_pagination='TRUE' pagination_position="both"] |
After enabling pagination, the result list will show 20 entries per page. 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 enable_pagination='TRUE' page_limit=10] |
Configuring the Grid
Grid Size
The default size of each grid tile is 300x300px. The grid size is determined by the thumbnail image size which can be controlled with the image_width and image_height shortcode options. To change the grid tile size to 200x250px, you would use the following shortcode.
[connections image_width=200 image_height=250] |
You can use any width that you would like, Connections will automagically create the required image sizes for you.
Image Opacity
The image opacity can be adjusted by using the image_opacity shortcode option. The default is that the image will be completely opaque. A valid value is a number between 0 and 1. For example to set the image opacity to 50% you would use .5.
Here is an example shortcode that shows settings the image opacity to 40%.
[connections image_opacity=.4] |
Name Overlay
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 used on the overlay will also be used on the entry’s profile page.
The name overlay displays the entry’s and title if one was entered. If you would like to not show the entry’s title the show_title shortcode option can be used like so:
[connections show_title='FALSE'] |
NOTE: If the title is disabled, it will also be disabled on the entry’s profile page.
The name overlay over the image will be shown by default. This can be changed so it is shown only on a mouseover or it can be set to be not shown by using the overlay shortcode option.
To show the name overlay on mouseover:
[connections overlay="hover"] |
To hide the name overlay:
[connections overlay="none"] |
NOTE: When the name overlay is hidden the entry name will be shown in the panel.
Name Overlay and Panel Color
The default name overlay and panel color is #f3f3f3 this can be changed by using the background_color shortcode option. The value used for background_color must be a valid color in hexadecimal.
Here’s an example shortcode that changes this to a red color.
[connections background_color="FF0000"] |
NOTE: When changing the background color, you very likely want to change the text color too, see the next section Name Overlay and Panel Text Color.
Name Overlay and Panel Text Color
The default name overlay and panel text color is #000 this can be changed by using the color shortcode option. The value used for color must be a valid color in hexadecimal.
Here’s an example shortcode that changes the text in the name overlay and panel to white.
[connections color="FFF"] |
Configuring the Panel
Panel Contact Information
The panel contact info displays the entry’s phone number, email address, and social media networks.
The preferred phone number and email address will be displayed. If a preferred phone number and/or email address were not assigned to the entry, then the first available will be displayed.
The social media icons will be shown for each network that was added to the entry. If you do not wish to show the social network icons, you can use the show_social_media shortcode option. Here’s an example:
[connections show_social_media='FALSE'] |
NOTE: If the social media icons are disabled on the panel, they will also be disabled on the entry’s profile page.
Panel Excerpt
The panel excerpt is created from the entry’s bio. By default it will display up to the first 55 words of the bio and the append ....
Both the excerpt length and the ... can be configured using the excerpt_length and excerpt_more shortcode options.
To increase the excerpt length to 100 words, you would use this shortcode:
[connections excerpt_length=100] |
If you would like change the ... you can use this shortcode:
[connections excerpt_more=""] |
If you would like to disable the excerpt and use the full contents of the bio, set the excerpt_length to 0.
[connections excerpt_length=0] |
View Profile
The View Profile link will be shown by default. To disable it use the show_profile_link shortcode option.
[connections show_profile_link='FALSE'] |
Configuring the Profile Page
Photo
The profile photo size can be set on the Connections settings admin page under the Image tab. The image settings you need to adjust are under the Large image settings section.
The are several shortcode options that are available that override the settings set in the admin.
image_singleimage_single_widthimage_single_heightimage_single_fallback
The image_single shortcode option can be used to set the image to be displayed. By default, it is the entry photo. The valid options are logo and none. To Change it to the logo you would use:
[connections image_single="logo"] |
The image_single_width and image_single_height options can be used to override the settings set in the admin. Valid values are in pixels, for example:
[connections image_single="logo" image_single_width=300 image_single_height=100] |
In the event that no photo has been uploaded for the entry a placeholder block will be shown. To disable this feature, you would use the image_single_fallback by setting it to none.
[connections image_single_fallback="none"] |
Profile Details
By default, all of the entry details that were entered will be displayed. Each data type can be configured not to be displayed. Here is the list of shortcode options that control whether or not a data type should be displayed:
show_titleshow_orgshow_contact_nameshow_familyshow_addressesshow_phone_numbersshow_emailshow_imshow_social_mediashow_datesshow_linksenable_bioenable_bio_headenable_noteenable_note_headenable_map
Here’s a sample shortcode that would disable the display of addresses, phone numbers, and links:
[connections show_addresses='FALSE' show_phone_numbers='FALSE' show_links='FALSE'] |
NOTE: Disabling the title will also disable the title from being shown on the panel.
NOTE: The show_org option will disable the display of both the organization and department fields.
NOTE: The show_family will only have an effect if the entry type is a family.
NOTE: Disabling social media will also disable them from being shown on the panel.
Map Options
By default, the map will be shown. The pin location on the map will be the first address entered for the entry. The map can be disabled by using the enable_map shortcode option. Here is a sample shortcode:
[connections enable_map='FALSE'] |
The map has two options that can be used to configure it, and they are:
map_zoom— This option controls the initial zoom of the map. It defaults to 13. The valid range is 0 – 19 with 0 being the whole world and 19 being the closest.map_frame_height– This option controls how tall the map is. The default value is 400px
Here’s an example shortcode that adjusts the zoom and map height.
[connections map_zoom=16 map_frame_height=600] |
Changing the Label Text
The best way to change the strings in the template is to use 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.
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 text domain, cnt_gridder. These template-specific strings are:
- Select Category
- Show All Categories
- No Photo Available
- View Profile
- Biography
- Notes
- Contact
Optionally and in addition to using 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_single='No Photo Available'str_bio_head='Biography'str_note_head='Notes'str_contact='Contact'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
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%
Your first question might be, but the address items are stacked in the traditional block layout, not on a single line, how is that being done? Right, 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%"] |
FAQs
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.
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.
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.
Why does the template layout look wrong?
There are primarily two reasons this issue occurs:
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 re-applying the wpautop filter, 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 [noformat] shortcodes do not work; please visit the Support Forum for assistance. A copy of your theme may be required to debug the issue.
UPDATE: 03-15-2013
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/
How do I use the str_***** shortcode options?
Every string in a template can be customized to suit your specific needs. This can be done by setting template-enabled shortcode options. These string shortcode options all begin with “str_”. Every template differs on what strings are available to be customized; please refer to the template’s documentation [currently under construction] to learn more. But here are a couple of examples that will work across most templates.
/* * 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 string customization shortcode options 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']
How do I use the addr_format shortcode option?
Explaining how the addr_format shortcode option works is difficult, so I will provide some examples.
First, some background.
The addr_format option accepts only a few specific tokens.
Tokens are the % symbols, and the word between, for example, %label%, is a token.
The valid tokens for the addr_format option are:
%label%[NOTE: unless this is overridden, the label will be the address type.]%line1%%line2%%line3%%city%%state%%zipcode%%country%
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’s the default layout of the tokens that create the format of the address:%label% %line1% %line2% %line3% %city%, %state% %zipcode% %country%
Your first question might be, but the address items are stacked in the traditional block layout, not on a single line; how is that being accomplished? The block layout is achieved using CSS, which can easily be overridden to display the address segments inline. How to override the CSS is a separate topic.
On to the 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, common in eastern Europe. [connections addr_format='%label% %line1% %line2% %line3% %state%, %city% %zipcode% %country%']
How do I change the number of entries per page?
By default, the template will show 20 entries per page. You can change the number of entries per page by setting a template-enabled shortcode option, page_limit. Here is an example:
[connections page_limit=10]
How can I hide empty categories?
You can hide empty categories by setting a template-enable shortcode option, show_empty_categories. Here’s an example:
[connections show_empty_categories='false']