// $Id: b2links.readme.txt,v 1.11 2003/04/29 22:03:48 zed1 Exp $
//
// B2Links
// Copyright (C) 2002 Mike Little -- mike@zed1.com
//
// This is an add-on to b2 weblog / news publishing tool
// b2 is copyright (c)2001, 2002 by Michel Valdrighi - m@tidakada.com
//
// **********************************************************************
// Copyright (C) 2002 Mike Little
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
//
// Mike Little (mike@zed1.com)
// *****************************************************************

B2Links is an add-on to b2 weblogging software.
 * It plugs in to the admin screens.
 * It adds to menu commands: Link Categories and Link Manager
 * It allows you to define multiple categories under which to store your links.
 * You can then define links with a url, name, optional image, href
   target and category.
 * You can then list your links in your template with a simple function call.
 * You can list them by category id or category name
 * You can specify text or html to be output before and after each link.
 * You can specifiy the sort order of the links displayed.
 * You can add a 'star' rating to your links.
 * There is special category type, auto-toggle which will allow only on link in
   the category to display at once.
 * Each link is owned by the user who created it. You can only edit or delete 
   links created by you or someone with a lower b2 administration level than you.


Files:
b2links.readme.txt          - this file
b2links.sql                 - sql to create the necessary database tables
b2links.update-0.5.sql      - sql to update the pre 0.5 tables
b2links.update-0.7.sql      - sql to update the pre 0.7 tables
b2links.update-1.0.sql      - sql to update the pre 1.0 tables
b2linkcategories.php        - admin plugin to manage link categories
b2linkmanager.php           - admin plugin to manage links
b2links.php                 - template functions
b2links.install.php         - alternate installation method
b2links.config.php          - configuration file
b2links.bookmark.txt        - mozilla bookmarklet
b2links.all.php             - Sample page to show all links
b2links-images\rating-0.gif - ratings images
b2links-images\rating-1.gif
b2links-images\rating-2.gif
b2links-images\rating-3.gif
b2links-images\rating-4.gif
b2links-images\rating-5.gif
b2links-images\rating-6.gif
b2links-images\rating-7.gif
b2links-images\rating-8.gif
b2links-images\rating-9.gif
b2links-images\star.gif
license.txt                 - GNU General Public License Version 2

You can download it from http://zed1.com/b2links/b2links-1.1.zip or http://zed1.com/b2links/b2links-1.1.tar.gz

There is an html version of this readme file at
http://zed1.com/b2links/b2links.html with screenshots and more detailed info.

Installation:

1. Execute the SQL from the file b2links.sql. This will create the two
   tables and add a default category and an example link. Alternatively, upload
   the file b2links.install.php to your B2 installation directory and 
   load it into your browser.

2. Edit the b2-include/b2menutop.txt file to add in the two new commands.

5	b2linkcategories.php	Link Categories
5	b2linkmanager.php	Link Manager

   Note: there should be a tab character after the 5 and after the filename.

3. Add the files b2linkcategories.php, b2linkmanager.php, b2links.config.php, 
   and b2links.php into your b2 install directory.

4. Edit b2links.config.php to your requirements. There are comments in the file
   to explain each configuration variable.

5. Login and click on the Link Categories menu command. Here you can
   create or edit link categories.
   - Name is the name of the category.
   - Auto-toggle: if you check this box, this category will only allow one link
     in this category to be visible at a time. If you edit an existing link or
     create a new one with the visible flag set on; all the other links in this
     category will be turned off. You can use this feature for a current mood
     category or current CD.

6. Click on the Link Manager command to edit links:
   - The url is the href part of the link tag. This is optional; if you wanted 
     to, for example, use it for mood icons.
   - The name will either be the linked word(s) or the alt and title tag for
     the image.
   - Image will be used as the src for an image tag. Use either an absolute 
     address or one relative to your template.
   - Target is the target of the link. _blank to open in a new browser window,
     and _top to open in the same window.
   - Category is the category under which to store this link.
   - Description is the description to be used as the title tag for the link
     (if it exists) and the text displayed after the link when no image is 
     defined.
   - Visible flag is used to turn off an individual link. Perhaps when a site 
     goes down temporarily but you don't want to delete your link. See also 
     auto-toggle categories above.
   - Rating is used to display a number, a number of characters, an image, or a 
     number of images after the link.

7. In your template include_once("b2links.php")
   - You can then <?php echo get_linkcatname(1); ?> or any category id. This will
     output the name of the category (perhaps for a heading)
   - Then <?php get_links(1); ?> to output all the links in category 1. You can
     also specify text to be output before and after the link, and the order of 
     the links.
   - You can also <?php get_linksbyname('General'); ?> to output all the links in
     the category called General.
   - Other functions are get_linksbyname_withrating(), get_links_withrating(), 
     and get_linkcatname().
   - See the comments above each function for full details.

9. Bookmarklet: I have a partially working bookmarklet to add to your browser
   toolbar. 
   - Clicking on this while viewing a site will cause the 'add a link' form to
     pop up in a new window with the site url and title pre-filled. 
   - This currently *only* works if you are already logged in to b2. The 
     bookmarklet *only* works in Mozilla.

Updating:

1. If you are updating from a pre 0.5 version, you will need to execute the sql
   in b2links.update-0.5.sql
2. If you are updating from a pre 0.7 version, you will need to execute the sql
   in b2links.update-0.7.sql
3. If you are updating from a pre 1.0 version, you will need to execute the sql
   in b2links.update-1.0.sql

Changes:

    1.1 - Added sample 'list all links' file.
          Added links_popup_script() function.
          Added the ability to return links in random order.
          Bug fixes: Can't create new category without auto-toggle.
                     b2links.install.php does not compile with smartquotes turned on.
                     Added missing title to b2linkcategories.php
    1.0 - Added mysql_connect() call to install script.
          Added separate configuration file.
          Added cookie to remember 'show' filter when managing links.
          Add ratings system.
          Added auto-toggle category flag.
          Added descending to sort order.
    0.9.1 - Added b2links.install.php DB installation script
    0.9 - URLs are optional. Delete asks for confirmation. You can now turn
          off the descriptions, even if you have no image or images turned off.
    0.8 - Added orderby parameter to output functions.
          In the link manager you can now sort your list of links.
          User level visibility now controlled by a variable at the top of
          b2linkmanager.php
    0.7 - Added link owners. Added truncation of long urls.
    0.6 - Added ability to not show images. Partially functional 
          'add link' bookmarklet. Documented template functions.
    0.5 - Added description and visibility flag.
    0.4 - Add stripslashes() calls in a couple of places.
    0.3 - fixed bad mysql call
    0.2 - fixed bad sql script
    0.1 - initial release


Thats about it really. This is reasonably stable software, however is has not 
been extensively tested. Use with caution.


--
Mike Little
mike@zed1.com
