=== Cross-references ===
Contributors: hervada
Tags: cross-references,links,posts,related,permalinks,slugs
Requires at least: 2.5
Tested up to: 2.6
Stable tag: 1.2

Insert cross-references between posts and pages easily and get a list of backward references on each post and page automatically.

== Description ==
With this plugin you can manually set a reference to another post or page in posts und pages and you get all backward references automatically listed for every post and page.

= Usage Basics =
Just place [cref post] at your post or page content to get both a forward and a backward link between these. The plugin shows automatically a list of related entries at the end of each post and page.

= Usage Details =
When writing a post or page, you can refer to other posts or pages by their slug or numerical ID. At the Settings/Cross-References page on your admin panel you can switch between referencing by ID and by slug.

- [cref <post>] sets a reference from the current post to <post>. Example: "As I said on my first post [cref hello-world], I won't write about my job." The current entry is shown at the blog as "As I said on my first post Hello World!, I won't write about my job.", with a html link from "Hello World" to the "Hello World!" post. At the "Hello World!" post the current post appears under "Related Posts".

- [cref <post> <alternative text>] same as [cref <post>] but the link has an alternative text instead of the post title. Example: "As I said on my [cref hello-world first post], I won't write about my job." This is shown as "As I said on my first post, I won't write about my job.", with a html link from "fist post" to the "Hello World!" post.

- [cref.from <post>] sets a backward reference from <post> to the current post. Example: "[cref.from my-vision]"
A forward reference is not shown at all, and both the current and the <post> post appear at each others related posts list.

  
= Related Posts List =
You get automatically a list of all the posts and pages that link to the current post or page at the end of each entry. 

For a greater control over the appearence and position of this list you can optionally customize your templates:
- Go to the Settings/Cross-References page on your admin panel and set up "Do not show related posts list"
- At your templates place `<?php the_crossreferences() ?>` wherever you want to place the related posts list.

Parameters: `the_crossreferences( $before, $between, $after, $id, $emptylist )`
It shows the related posts list for post $id, or for the current post if $id is not given.
- If there are some related posts: It shows $before, then all post titles with $between in between, then $after.
- If there are no related posts: It shows $emptylist.
For more information and examples about the parameters see the page "Other Notes".

= Tools =
This plugin adds a page at the admin panel under Settings / Cross-References where you can set the plugin options and run some tools:
- Switch between [cref post-slug] and [cref post-ID]. You can switch at any time: if your blog has already some references set, they will be updated.
- Configure the "related posts" lists, or hide it if you call `the_crossreferences()` in your templates.
- Rename a page slug (you can rename a post slug directly within the admin panel / manage posts, but this does not work for pages because of WordPress internals).
- Set how to show references when exporting your blog to XML. You can let them unchanged as [cref...] or show the post title, optionally with a html link to the referred blog post.
- Rebuild the plugin table, if the plugin was some time inactive, in order to fix possible errors at the related posts lists.
- Deinstall completely the plugin, deleting the plugin's table and options from your database. All existing [cref ...] references are optionally replaced with post titles, with or without html links.

= International =
This plugin works for any blog language, because you can customize its wording, and it works fine with multilanguage plugins such as qTranslate. Please let me know if you have some localization issues.

The plugin settings page is right now in 3 languages: English, German and Catalan.

If you want to translate the settings page to another language you can use the .pot file that is included in the .zip file. If you send me your translated .po file, I will include it in the plugin distribution.

== Installation ==
= First installation =
1. Download the .zip file and entpack it.
1. Upload the 'cross-references-plugin' folder as a whole to '/wp-content/plugins'.
1. Activate the plugin through the 'Plugins' menu in WordPress.
1. Optionally, go to the dashboard / Settings / Cross-references page in order to adjust some settings.

= Update from v. 1.2 or older =
You can use the WordPress Plugin Update or update manually:
1. Download the .zip file and entpack it.
1. Upload the whole 'cross-references-plugin' folder as a whole to '/wp-content/plugins'.
1. Deactivate the plugin through the 'Plugins' menu in WordPress.
1. At your server delete the file '/wp-content/plugins/cross-references.php'
1. Activate the plugin through the 'Plugins' menu in WordPress.
1. Optionally, go to the dashboard / Settings / Cross-references page in order to adjust some settings or run some tools. I recommend to do a table rebuild, which will ensure the cross-references table at your database has no errors.

== Frequently Asked Questions ==

= Are references automatically updated whenever the refered/referer post title changes? =

Yes, since the title of the post is read dynamically when it is shown.

= What happens if I delete a post to which there are references? =

All links will be removed from the referer posts, but their text (possibly the title of the removed post) will remain unchanged.

= What happens if I set a reference to a draft/pending/private post? =

No links will be shown on the referer posts (just possibly the title of the hidden post) until it is made public. The hidden post will also not appear at the back links list from other posts. The same happens if you set a reference to a published post and then you hide it.

= What happens if I change a post slug which is being referred to? =

If you reference posts by slug all references will be automatically updated when you change a post slug.

= What happens if I change a page slug which is being referred to? =

Because of the way WordPress handles page slugs, if you reference posts by slug all references to it would be broken. You need to rename page slugs with the tool "slug rename" at the plugin settings page (Admin panel / Settings / Cross-References).

= Is this plugin compatible with the multilanguage plugin qTranslate? =

Yes. At the plugin settings page just write for example:
<h1>[lang_es]Entradas Relacionadas: [/lang_es][lang_en]Related Posts: [/lang_en]</h1>

== Template Funtion ==

You can place this function at your templates, in order to get the related posts list for a particular post or page. You do not have to use this, because the plugin shows the list automatically, but this function gives you a greater control on the appearance and the position of the list. If you use this function, please set up "Do not show related posts list" at the admin panel / Settings / Cross-references. Otherwise the related posts list will appear twice.
 
`the_crossreferences($before,$between,$after,$id,$emptylist)`

`$before` - Optional. This string being printed once before the related posts list (only if there is 1 related post or more)
`$between` - Optional. This string being printed between 2 entries in the related posts list.
`$after` - Optional. This string being printed once after the related posts list (only if there is 1 related post or more)
`$emptylist` - Optional. This string being printed if there are no related posts.
`$id` - Optional. The post id number to which the related posts list are shown. Defaults to the current post or page.

Examples:
If you write `<?php the_crossreferences() ?>` you get an output such as:
	<ul><li>Post title 1</li><li>Post title 2</li><li>Post title 3</li></ul> (if there are 3 related posts)
	Nothing (if there are no related posts)

If you write 	`<?php the_crossreferences('See also:', '; ', '.') ?>` you get an output such as:
	See also: Post title 1; Post title 2; Post title 3. (if there are 3 related posts)
	Nothing (if there are no related posts)

If you write 	`<?php the_crossreferences('See also:', '; ', '.',,'There are currently no related posts.') ?>` you get an output such as:
	See also: Post title 1; Post title 2; Post title 3. (if there are 3 related posts)
	There are currently no related posts. (if there are no related posts)

If you write 	`<?php the_crossreferences('<h2>Related posts</h2><ul><li>') ?>` you get an output such as:
	<ul><h2>Related posts</h2><li>Post title 1</li><li>Post title 2</li></ul> (if there are 2 related posts)
	Nothing (if there are no related posts)

If you write 	`<h2>Related posts</h2><?php the_crossreferences() ?>` you get an output such as:
	<h2>Related posts</h2><ul><li>Post title 1</li><li>Post title 2</li></ul> (if there are 2 related posts)
	<h2>Related posts</h2> (if there are no related posts)

It is better to enclose the call to `the_crossreferences()` within a `if function_exists()` block, otherwise your template will raise an error if the plugin is inactive.
	`if (function_exists('the_crossreferences')) the_crossreferences();`
?>
`

== Change Log ==
1.3-RC2 7/23/2008
Fixed some problems if you set [cref ID] to a post revision ID.
Fixed: After importing blog entries with [cref ...] backward links coming from older entries were not shown.

1.3-RC1 7/22/2008
<ul>...</ul> added as default parameters for the_crossreferences().
Readme revised.

1.3-beta4 7/21/2008
Some code enhancements.

1.3-beta3 7/20/2008
Internationalization fixes (now it works fine with qTranslate).
New utility "slug rename" allows renaming page slugs.
Fixed: Rebuild caused post revisions to be indexed.

1.3-beta2 7/19/2008
Added support for multilanguage plugins such as qTranslate.
Table structure cleaned.
Some bugs fixed.

1.3-beta1 3/26/2008
Support for post slugs additionally to post ids for referring to posts. This can be changed on a blog with already existing references, the existing references being automatically updated.
Support for related post list automatically shown at the end of each post/page without editing any templates.
New plugin options page at the admin panel to adjust settings and run utilities.
XML export can be now configured to show up references unchanged (as [cref ...]), as html links or as mere titles.
New utility "rebuild" repairs all errors at the crossreferences table (needed for example if the plugin was some time inactive).
New utility "deinstall" removes all tables and options from this plugin from your database.

1.2 9/24/2007
No links are shown to or from draft/pending/private posts

1.1 9/15/2007
First public release