Pingback Documentation
- Installation
- Creating a pingserver template
- Enabling entries to receive pingback pings
- The Module’s Control Panel
- Displaying pingbacks on your website
- Sending pingback pings
Installation
- Unzip the file.
- Upload the file ext.pingback_ext.php to the extensions-folder inside your EE system directory.
- Upload the folder pingback and the contained files to the modules-folder inside your EE system directory.
- Upload the files lang.pingback.php to the language/english-folder inside your EE system directory.
- In your Control Panel navigate to CP Home › Admin › Utilities › Extensions Manager, find the Pingback Extension and click Enable?
- In your Control Panel navigate to CP Home › Modules, find the Pingback Module and click Install.
Creating a pingserver template
To enable other sites to pingback you, your pages must announce a pingserver URL. Since some other systems I tested seemingly don’t like URLs with query strings I dumped the approach to use an EE Action ID for this. Instead a template is used to construct the URL.
So in order to receive pingback pings you need to create a template of the type ‘Web Page’. You can place it in any template group and choose whatever name you like as long as the template is publicly accessible. Let’s assume we choose ‘site/pingserver’.
The template will only contain on single tag:
{exp:pingback:pingserver}
Save the template and remember its path.
Enabling entries to receive pingback pings
In order to receive pingback pings your single-entry templates must either be served with an X-Pingback HTTP header or contain a <link> element that points to the pingserver, or both. There are two tags to achieve this: {exp:pingback:http_header} and {exp:pingback:link_rel}.
They share the same parameters and are handled identically. The important difference is where to place them.
First off, due to ExpressionEngine’s inherent flexibilty in respect to placing content there can be a lot of possible scenarios in which it is almost pointless to try to infer the relevant entry_id just from the URL. Hence both tags have to be enclosed in a pair of {exp:weblog:entries}-tags in order to pass the entry_id. Their parameters must of course pull the same entry as the tag that shows the single entry in question, but since we only need the ID you may disable all other aspects.
HTTP header
{exp:pingback:http_header}
This tag will add an X-Pingback HTTP-header to your page. You should use this tag as most pingback enabled software will look for it first.
Parameters:
template=""
Mandatory. The templategroup/template of the pingserver-template you created in the previous step.
entry_id="{entry_id}"
Mandatory. This passes the relevant Entry ID.
Example:
{exp:weblog:entries weblog="blog" limit="1" disable="categories|member_data|trackbacks|pagination|custom_fields"}{exp:pingback:http_header template="site/pingserver" entry_id="{entry_id}"}{/exp:weblog:entries}
This tag MUST be placed in the very beginning of your page output. No other output must happen before it, not even whitespace or linebreaks. Otherwise a HTTP-header cannot be properly created.
Link element
{exp:pingback:link_rel}
According to the specification you may additionally place a <link> element on your pages as an alternative to the HTTP-header.
Parameters:
template=""
Mandatory. The templategroup/template of the pingserver-template you created in the previous step.
entry_id="{entry_id}"
Mandatory. This passes the relevant Entry ID.
Example:
{exp:weblog:entries weblog="blog" limit="1" disable="categories|member_data|trackbacks|pagination|custom_fields"}{exp:pingback:link_rel template="site/pingserver" entry_id="{entry_id}"}{/exp:weblog:entries}
The <link> element belongs into the <head></head> section of your document.
The Module’s Control Panel
All settings and incoming pingbacks are managed in the Module’s Control Panel, so go to to CP Home › Modules, find the Pingback Module and click on its name.
There are three tabs here: Pingbacks, Weblog Preferences and General Preferences.
General Preferences
There are just three settings here.
Connection method
The way your server will make outgoing network connections. Either is fine as long as your server supports it. If it does, a green “Success!” will display to the right. If it doesn’t there’ll be an error message. In that case try the other setting or make sure your server allows outgoing connections.
Size of excerpt for received pingbacks
Once you receive a pingback ping, your server will fetch the originating page and check if a link to your site actually exists there. If it does it will grab the text in the context of that link and save this excerpt. Here you can configure the length of that text. This can be up to 300 characters long but values between 50 and 100 usually make sense.
Show logs after publishing an entry?
When posting an entry (and sending of pingback pings for the weblog in question is activated) the extension will check if any URLs mentioned in your post are enabled to receive pingback pings. If you set this setting to ‘yes’, after saving your post you will get a report showing the results of this process.
Weblog Preferences
After selecting the Weblog Preferences tab you are first presented with a list of all your weblogs. Here you can see at a glance for which weblogs pingback-functionality has been enabled. Click on the weblog you want to configure to get to its settings.
The first three settings deal with receiving pingback-pings.
Allow receiving pingbacks for this weblog?
Receiving of pingback pings for this weblog can be switched on or off here. In order to enable your weblog to receive pingbacks, additional steps are necessary.
Moderate incoming pingbacks for this weblog?
If you enable moderation incoming pingbacks will initially have their status set to closed.
Enter email-addresses to be notified on pingback receipt
You may enter one or more email addresses here that are to be notified once a pingback is received. If you enter multiple addresses, seperate them with commas.
The remaining settings deal with sending pingback pings when publishing entries.
Send pingbacks from this weblog?
Sending pingback pings from this weblog can be switched on or off here.
Choose field(s) which shall be searched for links to ping
The pingback extension will try to ping any URLs linked in your posts. Since you may have several custom fields that serve different purposes than containing the text of your entry you have to specifiy the fields that shall be searched for URLs to ping.
Permalink URL for this weblog
This field will be prepopulated with the Comment Page URL from your weblog’s Path Settings if that is set. Check whether this is correct and adjust it if needed.
What are you using for your links?
Choose if whether you use Entry IDs or URL titles in your permalinks.
Domains to exclude from pinging
You may enter URLs or fragments of URLs that shall be exluded from pinging. If you don’t want to pingback yourself for example you should enter your own domain here.
Managing incoming pingbacks
Finally under the ‘Pingbacks’ tab you see a list of all pingback pings you received.
Managing the pingbacks is pretty straightforward.
- The dropdowns above the list let you filter the entries by several aspects.
- If you enabled pingback moderation for a weblog, new pingbacks will show up with the status ‘Closed’ here.
- Use the checkboxes to the right in conjunction with the dropdown to the bottom right to either delete unwanted entries or toggle their status.
- The ‘Edit’-link for each entry allows you to edit the title and the excerpt in case it contains anything undesired.
Displaying pingbacks on your website
The Pingback Entries Tag enables you to display the pingbacks associated with your entries.
This is mostly analogical to showing comments/trackbacks so the same general principles apply:
- The Pingback Entries Tag is intended for use in one of your “single entry” pages. That is, a page that shows a single, specific weblog entry. Therefore, the page must be linked to from within your Weblog entries using the URL Title Path variable or the Entry ID Path variable, so that the pingbacks can be associated to a specific entry.
- The tag is not supposed to be nested inside of a standard
{exp:weblog:entries}tag.
{exp:pingback:entries}
Parameters:
dynamic="off"
Optional. Use only if you want to override the default behaviour.
The Pingback Entries Tag sets some parameters dynamically, based on what is in the URL. There are times, however, where you do not want the parameters affected by what the URL contains. To override the dynamic nature of the pingback tag, use dynamic=“off”.
This is often useful if you want to list pingbacks in a “sidebar” on your site and have them always be the same ones regardless of which page on your site you visit (main page, archives, comments, etc.). Using this, you can create a “recent pingbacks” list. By setting dynamic=“off” you will ensure that the list is not affected by anything passed in the URL.
entry_id="24"
Optional. Use only if you want to override the default behaviour.
You can hard code the pingback entries tag to show pingbacks for a specific weblog entry by its entry ID.
NOTE: This parameter takes precedence over any entry specified dynamically in the URL, so when using this parameter you will want to make sure it is clear to the user which entry the displayed pingbacks belong to.
orderby="date"
Optional.
You can order the pingbacks either by date or by title.
sort="desc"
sort="asc"
Optional.
The sort order can be “asc” (ascending order or “oldest item first” for dates) or “desc” (descending order or “newest item first” for dates). If you do not use a sort order the default is ASC for titles and DESC for dates.
excerpt="[...]"
Optional.
A string of text that is appendend to the beginning and end of the pingback’s excerpt-text when set.
Variables:
{pingback_title}
The title of page that sent you the pingback ping.
{excerpt}
The excerpt that was fetched from the page that sent you the pingback ping.
{source}
The URL of the page that that sent you the pingback ping.
{pingdate format="%Y-%m-%d %H:%i:%s"}
The time the pingback ping was received. Formatting options are the same as with any date-variables in EE.
{switch}
See here for example.
{pingback_id}
The ID number of the pingback.
{pingback_count}
The “count” out of the current pingbacks being displayed. If five pingbacks are being displayed, then for the fourth pingbacks the {pingback_count} variable would have a value of “4”.
Example:
{exp:pingback:entries orderby="date" sort="desc" excerpt="[...]"}
{if {pingback_count} == 1}<h2>Pingbacks</h2>{/if}
<p>{pingback_count}. {if pingback_title}
<a href="{source}">{pingback_title}</a>
{if:else}
<a href="{source}">{exp:char_limit total="20"}{source}{/exp:char_limit}</a>
{/if} on {pingdate format="%Y-%m-%d %H:%i:%s"}:<br />
{if excerpt}{excerpt}{/if}</p>
{/exp:pingback:entries}
Finally there is a tag that can be used to display the number of pingbacks an entry has received. This is comparable to the {trackback_total} or {comment_total} variables.
The tag is supposed to be nested inside {exp:weblog:entries}-tags. It is a single tag with no closing element.
{exp:weblog:entries limit="1"}
{exp:pingback:received entry_id="{entry_id}"}
{/exp:weblog:entries}
Sending pingback pings
Sending pingbacks is fully automatic. There’s no action to be taken by the user. If you have configured your weblog to send pingback pings and the designated fields contain any links, the extension will contact the linked pages and if they support pingback will send the ping.
Some notes:
- Pings will only be sent if the entry has the status “Open”.
- If you update an entry at a later date the same URL will not be pinged twice, but newly added URLs will be pinged.
- If the entry date lies in the future the pings will go into an internal queue and will not be executed until the entry date is reached. The queue will be checked periodically when someone is logged into the CP. So the future pings might take place a little while after the entry actually went live.
- If you have the Show logs after publishing an entry? option enabled, you will see a protocol of the pinging attempts. If it’s a future entry you’ll see a list of links enqueued to be pinged later. You can access the log anytime by going to CP Home › Edit Weblog Entries and clicking the View-link.
