==README for Advanced Anchors add-on for miniBB==
Release date: February 10, 2016
Most recent update: April 23, 2021
miniBB version: 3.5 and higher
Author: Paul Puzyrev (minibb.com)

This add-on is used to provide direct and precise links to exact POSTS on the forum. In the default version, links to such posts provided under '#' sign appearing above or near each message, and then the whole hyperlink to such message will consist of the full Topic's URL + '#msgID' anchor at the end of it, supposing the browser to redirect to such a message directly, if this URL is pasted somewhere. It absolutely works for the very first messages in each Topic, but as soon the Topic grows and is splitted by pages, there could happen that some linked messages could be moved from page A to page B - for example, in the case of deleting some messages, or moving them to another Topic. Then the direct links, which are using certain page numbers, will lead to nowhere and could look quite confusing, not allowing to find the certain linked message.

Also, in the case of mod-rewritten URLs, if URL-parsing function is changed for some reason (new convertion rules added), miniBB will try to redirect to the most proper URL, and it will anyway lead to the 301-redirection mechanism.

This add-on uses a script called "message locator" and named 'msg.php', which is distributed amongst the default free miniBB package starting from version 3.5. Linking to this script anywhere on the forum or external web pages, will *always* provide valid links to certain messages. This script will try to locate a message in both live or optionally archived forum tables; also it uses the most proper HTTP protocol headers, providing either 301 (for found messages) either 410 report codes, which are very useful for search engines like Google.

An extra addition to this forum allows to install a special BB-code, which will produce specifically named anchors; they could be used in large starting topic texts to refer directly to the exact portions of such texts. Message locator supports direct moving to such anchors as well - read instructions below for proper usage. This feature is mostly useful for professional writers, building the most properly hyperlinked paragraphs.

***************************************

INSTALLATION INSTRUCTIONS

* Modify the file bb_codes.php file adding the codes provided under bb_codes.encode.txt and bb_codes.decode.txt. 

The code under bb_codes.encode.txt, marked as "/* Advanced anchors - msg links */" should be pasted in the function enCodeBB before the line which says

`$msg=preg_replace($pattern, $replacement, $msg);`

whereas the code marked as "/* Advanced anchors - named anchors - admin section */" should be preferrably pasted in the admin section of codes, surrounded by `if($admin==1 or $GLOBALS['isMod']==1){` and `}` tags - because it's could be too risky to give the "anchoring" freedom to any random member of the board. However, this code also could be pasted and enabled for all members, in this case paste it before the aforementioned line of code.

The code under bb_codes.decode.txt should be pasted in the beginning of the function deCodeBB before the URL-decoding patterns, and possibly right after this line:

`$replacement[]="[nourl]\\1[/nourl]";`

***************************************

UPDATING OLDER MESSAGES

NB: Executing this script is for experienced coders only.

If you'd like to update some older messages of your forum, which could contain direct links to certain posts, try to execute msg_convert.php script, putting it in the root folder of your forums. 

! Open it for editing before running, and change some options.

The most important setting there to change is $convertMode. It's set to FALSE by default; in this case, at the first time when you execute this script, it will just output all messages, which possibly contain message texts containing regexp patterns, set in $quotePatterns (you need to change at least URL to your forums there). Check what happens, and specifically check if messages will be properly updated; it's visible if you click on certain links in the output page: link over the post ID will lead to the message, which currently contains this link; link over the "Test" will lead to the conversion page (in test mode, nothing will be actually converted and just shown on the screen, how it looks). Setting `$convertMode=TRUE;` will update all messages in the database. Afterall, if you execute this script again, it should give 0 results - it means, all of your older messages were updated properly.

The script will also display expected page numbers, where the currently determined anchored links will lead to. If it's not the first page, then it will be marked in bold for more easier verifying (on the "Test" page). At the end of the page, you could check for an "Expected benefit ratio", showing of how big is the amount of messages, which are under risk of not properly located, if hyperlinked directly. Regarding this amount, you could get an idea, if this add-on will be useful for you at the current stage of your forum.

***************************************

USAGE

* Linking to any available message on the forum: catch the link under '#' near each message, it will lead to something like:

http://www.minibb.com/forums/msg.php?id=5569

Use this link anywhere, including BB-code tags. `5569` is the certainly known, unique, never repeated message ID, which also could be seen in desktop browsers, just mouse-overing this link.

``````````

* Creating a certainly named anchor: just use the following when posting your message:

[name=million_ways]...some text or just an empty place here...[/name]

This will be transformed to:

<a name="million_ways" id="million_ways">...some text or just an empty space here...</a>

``````````

* Linking to a certainly named anchor: use the proper BB-code, like:

[name=6412:million_ways]...some text or just an empty place here...[/name]

where the numeric value in the 'name' tag stands for a message ID (determined like described above); and the second value in this tag stands for an unique ID/name of the portion of text.

This code will be transformed to:

<a href="{forums_url}/msg.php?id=6412&amp;name=million_ways">...some text or just an empty space here...</a>

***************************************

NOTES

Linking to a named anchor could be referred just using the original Topic's URL and adding '#anchor_name' to the end of it. This is a preferred method, if you have named anchors appearing in the very first messages of a Topic, which will never go to another pagination. 

The same is valid for any first messages in a Topic; in this case, just use the Topic's URL and adding '#msg{ID}' to the end of it, where ID stands for a numerical message ID.

***************************************

THAT's ALL SO FAR.

You could uninstall the plugin, undoing changes made from the steps above. However please note: if you convert database messages having older links going to msg.php, this is most likely has no way back. Always keep 'msg.php' in your forums root folder, even if you undo all changes and remove all BB codes and switch back to the original anchoring which miniBB provides by default.

Enjoy using the add-on! Please, post bugs and suggestions on our forums:
http://www.minibb.com/forums/
