Introduction
By default this shortcode will display the list of all public entries and the private entries if the user is logged into WordPress using the activated template for the “All” template type.
[connections]
Shortcode Options
One of the great strengths of Connections is the ability to customize the results to be displayed with a large array of shortcode options.
The shortcode has the following options:
- category
- category_in
- exclude_category
- filters
- last_name
- group_name
- title
- organization
- department
- district
- county
- city
- state
- zip_code
- country
- force_home
- home_id
- geo_location
- id
- list_type
- lock
- meta_query
- order_by
- repeat_alphaindex
- show_alphahead
- show_alphaindex
- template
Multiple short attributes are added to the same shortcode. Do not add the shortcode to the page multiple times with different attributes. Here’s an example of using multiple attributes with the shortcode:
[connections category=7 order_by='id|RANDOM']
category
The category
option allows you to show entries within a specific category or multiple categories and all their children categories. To show the entries in multiple categories and their children, list the categories by id separated by commas enclosed in single quotes.
The category ID can be found on the Connections : Category admin page, as shown in this screen capture.
The default is to show all available categories and their children categories.
Examples:
/* * Example 1 * Show a single category. */ [connections category='12'] /* * Example 2 * Show multiple categories. */ [connections category='1,3,9']
Important
category_in
The category_in
option allows you to show only the entries assigned to the supplied categories, by ID.
The category ID can be found on the Connections : Category admin page as shown in this screen capture.
Example:
/* * To show only the entries that have been assigned to the listed category IDs. */ [connections category_in='1,3,9']
Important
exclude_category
The exclude_category
option allows you to exclude specific categories from the entry list.
The Category ID can be found on the Connections : Category admin page, as shown in this screenshot.
/* * Example 1 * Exclude a single category by id from the results. */ [connections exclude_category='12'] /* * Example 2 * Exclude entries in multiple specific categories. */ [connections exclude_category='12,3,1,9']
Important
filters
The filter shortcode options can be used one at a time or in combinations. The filter shortcode options are case sensitive.
- last_name
- family_name
- title
- organization
- department
- district
- county
- city
- state
- zip_code
- country
Examples:
/* * Example 1 * Output a list where the last name is "Smith". */ [connections last_name='Smith'] /* * Example 2 * Output a list where the organization is "ACME" AND where the department is "Accounting". */ [connections organization='ACME' department='Accounting']
Tip
Important
force_home
The various permalinks for an entry are created contextually. This means if the shortcode is used on a page, all links for that instance of the shortcode will resolve to that page. However, if the shortcode is used on WordPress Post or in the theme’s sidebar, any area that is not a page, the links will resolve to the page set as the Directory Homepage on the Connections : Settings admin page under the Display tab.
Depending on how you’re using Connections you may want to force an instance of the shortcode when used on a page other than the Directory Homepage to the Directory Homepage. In this case, you would use the force_home
shortcode option.
Example:
[connections force_home='TRUE']
Tip
home_id
shortcode option instead.home_id
The various permalinks for an entry are created contextually. This means if the shortcode is used on a page, all links for that instance of the shortcode will resolve to that page. However, if the shortcode is used on WordPress Post or in the theme’s sidebar; any area that is not a page, the links will resolve to the page set as the Directory Homepage on the Connections : Settings admin page under the Display tab.
Example:
/* * The Directory Homepage ID is 33 but you need the premalinks need to resolve * to a separate page ID for this shortcode instance and that page ID is 68 */ [connections home_id=68]
Tip
geo_location
The geolocation shortcode options can be utilized to display Entries within a radius of latitude and longitude values.
The geolocation shortcode options are made up of the following four shortcode options:
- latitude
- longitude
- radius
- unit
Examples:
/* * Example 1 * Display Entries within 10 mile of Mt Evans in Clear Creek County, Colorado. */ [connections latitude=39.5883 longitude=-105.6439] /* * Example 2 * Display Entries within 10 miles of Salt Lake, Hawaii. */ [connections latitude=21.355 longitude=-157.9078] /* * Example 3 * Display Entries within 30 kilometersof Lancaster, OH. */ [connections latitude=39.719769 longitude=-82.598259 radius=30 unit='km']
Tip
latitide
and logitude
shortcode options are required. The radius
will default to 10
and the unit
will default to mi
(miles); both are optional.Tip
unit
shortcode option to km
.id
The id
option allows you to show the details for a single entry or multiple specific entries. To display a single entry, locate its ID on the Connections : Manage page in the admin and add the id
attribute with the entry’s ID in single quotes to the Connections shortcode. If you would like to display multiple specific entries, list all the entries displayed by their ID separated by commas within single quotes. This will list the specified entries in the default sort order. The default sort order can be changed by using the order_by
shortcode attribute.
The entry ID can be found in the admin by first clicking on Manage under Connections and then clicking the Show Details link under the entry. It will be labeled Entry ID: and will be found at the top right of the entry field.
Examples:
/* * Example 1 * Display a single entry. */ [connections id=349] /* * Example 2 * Display a list of specific entries. */ [connections id="2,349,36,46"]
list_type
The list_type
option allows you to show all entries, or individuals, or organizations, or families. You can show multiple entry types by listing the types you wish to display separated by commas. Setting the list_type
option will display the active template assigned to the Entry type set in the template manager. If multiple entry types are specified, the template for the entry type listed first will be used to display the entry list.
Examples:
/* * Example 1 * Display all Entry types. */ [connections] /* * Example 2 * Display only Entries set as an individual. */ [connections list_type='individual'] /* * Example 3 * Display only Entries set as an organization. */ [connections list_type='organization'] /* * Example 4 * Display only Entries set as families. */ [connections list_type='family'] /* * Example 5 * Display only Entries set as individual and family. */ [connections list_type='individual,family']
lock
Query string variables registered by Connections influence the results of the shortcode. In instances where you might use the shortcode on the page multiple times, you may not want each instance of the shortcode to process the query string variables. If that is the case, you will set this option to true.
[connections lock='TRUE']
meta_query
The meta_query
shortcode option allows you to filter the Entry results list by using Custom Metadata Fields Name and Value fields.
Examples:
/* * Example 1 * Return Entries with the meta key `color` AND a meta value of `red`. */ [connections meta_query='{"meta_key":"color","meta_value":"red"}'] /* * Example 2 * Return Entries with the meta key `Membership Type` AND a meta value of `Gold`. */ [connections meta_query='{"meta_query":{"0":{"key":"Membership Type","value":"Gold","compare":"="}}}'] /* * Example 3 * Return Entries with the meta key `Wall of Honor` AND a meta value that is not empty. */ [connections meta_query='{"meta_query":{"0":{"key":"Wall of Honor","value":"","compare":"!="}}}'] /* * Example 4 * Return Entries with a meta key `color` of with a meta value of either "red" OR "orange" AND * have a meta meta key of `featured` and a meta value of `1`. */ [connections meta_query='{"meta_query":{"relation":"AND","0":{"key":"color","value":("red","orange"),"compare":"IN"},"1":{"key":"featured","value":"1","compare":"="}}}']
Important
order_by
By default, Connections will sort by last name [organization name, family name], first name in descending alphabetical order. The order_by
attribute can be used to apply a custom sort order. Here are the available sort fields and order flags that can be used.
Sort Fields:
- id
- date_added
- date_modified
- first_name
- last_name
- title
- organization
- department
- city
- state
- zipcode
- country
- birthday
- anniversary
Order Flags:
- SORT_ASC
- SORT_DESC
- SPECIFIED
- RANDOM
Multiple sort fields can be used by separating them by commas. You can also add the order flag to each sort field to list the results in ascending or descending order. The sort flag is entered right after the order field separated by a ‘pipe’ | . This character is usually placed above the ENTER key and typed by hitting SHIFT + BACKSLASH keys.
Examples:
/* * Example 1 * Sort by state in ascending order and then zip code in descending order. */ [connections order_by='state|SORT_ASC,zipcode|SORT_DESC'] /* * Example 2 * Sort by entry ID but list them exactly in the order as entered in the id attribute. */ [connections id='5,401,10,36' order_by='id|SPECIFIED'] /* * Example 3 * Sort all results randomly. */ [connections order_by='id|RANDOM'] /* * Example 4 * List the supplied entry IDs but order them randomly. */ [connections id='5,401,10,36' order_by='id|RANDOM']
Important
Important
repeat_alphaindex
The repeat_alphaindex
shortcode attribute functions similar to the show_alphaindex
shortcode attribute except that it places the alpha index at the beginning of each character group.
Example:
[connections show_alphaindex='true' repeat_alphaindex='true']
Tip
show_alphaindex
shortcode attribute is set to true.show_alphahead
The show_alphahead
option inserts the current character, by last name, at the beginning of each character section.
Example:
/* * Example 1 * Show the current character at the head of section. */ [connections show_alphahead='true']
Important
show_alphaindex
By default, the entry list is sorted by last name, organization name, family name, and first name in descending alphabetic order. Clicking “M” in the alpha index will filter the directory by the letter “M”.
Example:
/* * Example 1 * Show the alpha index at the head of the list. */ [connections show_alphaindex='true']
Important
Important
show_alphaindex
, so it will only show the letters that are available to jump to within the current page entry list.template
The default template set on the Connections : Templates admin can be overridden by setting the template
option.
Examples:
/* * Example 1 * Output the list using the Profile template. */ [connections template='profile'] /* * Example 2 * Ouput Entry ID 2 using the `card-single` template. */ [connections id=2 template='card-single']