Circled Documentation

Introduction

Circled 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' image_width=100 name_format="%first% %last%"]

The anatomy of Circled

1. Contact information.
2. The entry bio excerpt.

Image Credit: Photo by stockimages via freedigitalphotos.net.

Configuring the Optional Features

Enable Search

By default Circled 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 Circled 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 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 enable_category_select='TRUE' 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 enable_category_select='TRUE' show_empty_categories='TRUE' show_category_count='TRUE']

Pagination

By default Circled 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 of 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]

Layout Configuration

Layout

Circled by default will have a 2 column layout.

Circled supports a secondary layout format where the entries are listed in a single column. This is achieved by using the single shortcode option. Here’s an example.

[connections single='TRUE']

This layout is very useful if you wish to use a very large image width, bringing even more focus to the image.

Image Size

The default size diameter of the image is 100px. This can be adjusted with the image_width shortcode option. Here is an example shortcode showing the image diameter being set to 200px.

[connections image_width=200]

You can use any width that you would like, Connections will automagically create the required image sizes for you.

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 use 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 page.

The title will be displayed 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.

Contact Information

The contact info displays the entry’s social media networks an icon for its email address.

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: The preferred email address will be used. If a preferred email address was not assigned to the entry then the first available will be used.

NOTE: If the social media icons are disabled, they will also be disabled on the entry’s profile page.

Excerpt

The 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 which override the settings set in the admin.

• image_single
• image_single_width
• image_single_fallback

The image_single shortcode option can be use 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]

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’s 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_title
• show_org
• show_contact_name
• show_family
• show_addresses
• show_phone_numbers
• show_email
• show_im
• show_social_media
• show_dates
• show_links
• 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: Disabling the title will also disable the title from being shown in the results list.

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 the social media will also disable them from being shown in the results list.

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 13. The valid range is 0 – 19 with 0 being the whole world and 19 is the closest.
• map_frame_height – This option controls how tall the map is. The default value is 400px

Here’s and example shortcode which 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_circled. These template specific strings are:

• Select Category
• Show All Categories
• No Photo Available
• Biography
• Notes
• Contact
• View Profile

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='' (blank, no label)
• 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 use 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.

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']