The Link List module organizes your links to other websites. With the Link List module, you can add/edit/delete links, display links on any webpage. Link List is XFN friendly as well. For more information about XFN, please visit their website: http://gmpg.org/xfn/.

This module is being released under the MIT License. Please read the License Information.

Please report your bugs to either my hello! blogger ( http://haroblogger.com ).

Notes about using the recently updated feature: This feature will only work with links which have an RSS URL. There are many reasons for this. The foremost reason would be that without actually spidering every single site on your linklist and analyzing each page, there's really no way to know if a site has been updated. Honestly, that kind of analysis is beyond this mere module. Another option of course, is to use the same technique displayed in blogrolling or weblogs.com, which would be insane since it would kill your server with pings. (provided all those people in the world pinged you!) Yet another option is to parse the weblogs.com or blogrolling changes.xml. This was done in the past, and I have yet to come up with a good way to do it. If I recall correctly, blogrolling tried to do this with weblogs.com changes.xml file, and eventually, they just started their own ping server.

So in order to keep updated with your links, you should be sure to run the {exp:linklist:checkupdated} tag at a regular interval. Remember that the tag only checks EACH link once an hour. (Usually this is acceptable to do, anything more often might put you on a blacklist.) So if you have 100 links, and by default, the checkupdated tag checks 5 sites at a time, (you can increase or lower this by using the limit parameter) then it will take approximately 20 hits to the checkupdated tag in order to process all your links. I say 20 hits, because it will roll to the next batch whenever you run it again. If you were to run the checkupdated tag every hour, then it would take 20 hours.

Honestly, I recommend running no more than 5 links at a time (default) if you run the script as part of a template. If you are able to set up a cron event or scheduled task, then I recommend placing the tag there, and schedule it as often as you can run it. I'd almost recommend setting the limit higher than 5. You can play around with this value and determine what is best for you.

HOW TO INSTALL

1. Upload/copy your files

The files you need are already located in their own directories that they need to be in. simply copy the lang.linklist.php file into the /system/language/english folder, and the mod.linklist.php and mcp.linklist.php files into the /system/modules/linklist/ folder. You can also simply unzip them into your system folder as well, though I do recommend using caution with this.

2. Install the module

In your Control Panel, go to Modules and then you should see the Linklist module listed as "Not Installed". All you need to do is click on Install, and then you should be on your way!

By clicking on the module name, "Link List" you will be able to add/edit/delete links and link lists.

HOW TO UPGRADE

1. Upload/copy your files

Upload your files, overwriting the existing files on your server.

2. Run the upgrade script

After copying your files to the server, simply go into Modules, then select Linklist. The Linklist should present itself by telling you you are running an older version, and click to upgrade. Go ahead and click to upgrade. Then that's it! The script will autodetect what version you're currently running and upgrade itself appropriately.

HOW TO USE

The Link List is basically broken up into 2 different parts.

You have the main Link Lists and you have individual links that are a part of each Link List.

When you create a new Link List ( Add New Link List ), you enter the name of your list and a description (or title).

You should now see the Link List and you can click on the Edit Links to add/edit/delete Links to that list.

Keywords

I feel this feature has a right to have it's own section, so I'll explain how keywords (or tags, as some of you may call them) work.

When you edit a link, you will notice a field called "Keywords". These keywords should be separated by commas, and may contain spaces. An example would be: "expression engine, pmachine, blog, reference" (without the quotes). These keywords are used by the linklist to display only links associated by keyword. (should you choose to.)

Using keywords, you will be able to group your links together in a fashion very similar to del.ico.us. Basically keywords are a way to organize and share your links. (see below -- {exp:linklist:keywords})

Linklist results can be influenced by either specifying the keywords in the parameter of the {exp:linklist:entries} tag OR by the URL of the page (dynamic="on"). Please read the parameter functions for more details.

{exp:linklist:entries} tag
{exp:linklist:checkupdated} tag
{exp:linklist:keywords} tag
Troubleshooting
Tips and Tricks

{exp:linklist:entries} Usage

parameters
variables
variable pairs
Conditionals

Within your Expression Engine Templates you may use the {exp:linklist:entries} tag. This tag is the core of this module. Here is an example showing you in action:

Parameters

linklist="linklist"
member_id="1"
orderby="url_title"
sort="ASC"
status="open"
limit=10
offset=10
dynamic="on"
keywords="keyword1|keyword2"
paginate="bottom"

linklist="linklist"

Back to Parameters

Choose which linklist you will be displaying links from. If you omit this parameter, all linklists will be displayed in order. You can also opt to display only certain linklists using pipe character:

Choosing not will display any linklists that are NOT in the list you provide:

member_id="1"

Back to Parameters

Chooses what user's linklist to retrieve. If you omit this parameter, the linklist will assume all users. This can be very useful when you want to display linklists only for certain users.

Like the linklist parameter, you can use the pipe character as well as the not.

orderby="url_title"

Back to Parameters

This will order the list of links in the order you specify. If you do not specify this parameter, the default sort is by Linklist ID, then the URL name. eg., this will sort the list in the order of the links being added, then by the title:


You may additionally specify the list to show the links in random order:

sort="ASC"

Back to Parameters

This determines what sort order the orderby will be in. If you do not specify this parameter, it defaults to ascending (ASC).

status="open"

Back to Parameters

Each individual link has a status associated to it, "open", "closed", and "pending". This parameter allows you to specify what status to show. You may also use the pipe character to specify more than one option:

limit="10"

Back to Parameters

This will limit the results to the number you specify. Please note this option limits the number of links returned for that one result set, and does not limit by linklist. i.e. if you specified 2 linklists that had 10 links each, and specified a limit of 10, it will show only the first ten links from the first linklist, and not show any from the 2nd linklist.

However, let's say that you wish to show 5 links from those 2 linklists. It's perfectly acceptable to have multiple linklist tags per template:

offset="10"

Back to Parameters

Used in conjunction with the limit parameter, with offset, you can offset the start record by a certain number of links. So if you specified, limit=10 offset=10, this will start on the 10th link and show 10 links. This is especially useful in a scenario when you want to display your links in multiple columns.

Example:

dynamic="on"

Back to Parameters

Dynamic tells the linklist to either gather information from your URL or not to gather information from the URL. By default, dynamic is set to "on", meaning it will use segments in your URL to dynamically display your linklist. Linklist looks in particular for segment 3. i.e. if you're URL is: http://www.yourdomain.com/index.php/weblog/index/keyword then segment 3 is "keyword". The third segment is used for queries associated with keywords. If you do not want the linklist to change it's results because of the URL, then specify dynamic="off" and it will not be influenced at all.

By default segment 3 of the URL will be used as the primary "keyword". This enables you specify a URL that will show for instance all the links with the keyword "expression engine". You're URL in this case would be http://www.yourdomain.com/index.php/weblog/template/expression_engine. (please note that underscores are equivalents to spaces in the URL.)

keywords="keyword1|keyword2"

Back to Parameters

The keywords param allows you to specify exactly what links to display via keywords. If you wanted to display all links with the keywords "expression engine" and "pmachine", then the parameter would be: keywords="expression engine|pmachine". In this case, you may use the space and not use an underscore, as in the URL. This is permitted, although either way will work.

paginate="bottom"

Back to Parameters

By default, paginate is set to bottom. if you omit this parameter and include the {paginate}..{/paginate} variable pair, the pagination links will appear towards the bottom. You can also set this to paginate="top" to include the pagination links above your links to display. View the paginate variable pair for an example.

Variables

{normal_linkcode}
{xfn_linkcode}
{xfncode}
{count_linkcode}
{countxfn_linkcode}
{counturl}
{linklist_name}
{linklist_title}
{linklist:url}
{url_rss}
{url_favicon}
{linklist:url_title}
{url_desc}
{relative_updated}
{updated_hours}
{last_updated format="%m/%d/%y"}
{prepend_str}
{append_str}

{normal_linkcode}

Back to variables

Displays your link with the anchor code tag already in place. eg.:

{xfn_linkcode}

Back to variables

Identical to the {normal_linkcode} variables, except this will display the xfn code in the "rel" parameter. eg.:

{xfncode}

Back to variables

If for some reason you wish to display only the xfncode itself, you can use this variable to do so. This will display:

{count_linkcode}

Back to variables

Identical to the {normal_linkcode} variable, except this will show the URL that will increment the clickthru counter for the link. eg.:

{countxfn_linkcode}

Back to variables

Identical to the {xfn_linkcode} variable, except this will show the URL that will increment the clickthru counter for the link. eg.:

{counturl}

Back to variables

This will show the URL that will increment the clickthru counter for the link. eg.:

{linklist_name}

Back to variables

Displays the "short" name of the current Linklist. This would be commonly used within the {list_heading} variable pair. eg:

{linklist_title}

Back to variables

Identical to the linklist_name variable, however this will show the "long" name of the linklist. eg:

{linklist:url}

Back to variables

This will display the actual URL of the link. eg:

{url_rss}

Back to variables

This will display the actual URL of the RSS (if any). eg.:

{url_favicon}

Back to variables

This will display the actual URL of the favicon for a website (if any). eg:

{linklist:url_title}

Back to variables

Displays the Title of the link. eg:

{url_desc}

Back to variables

Displays the description of the link (if any). eg.:

{relative_updated}

Back to variables

Displays the last date updated in Relative Time. i.e. 12 hours, 33 minutes.

{updated_hours}

Back to variables

Displays in hours the last time a site was updated.

{last_updated format="%m/%d/%y"}

Back to variables

Displays the date the site was last updated according to the format.

{prepend_str}

Back to variables

Displays the Prepend String you specified within the LinkList Preferences. Use this when you are manually building your URL. Note that the {prepend_str} variable will only show when a site has been recently updated.

{append_str}

Back to variables

Displays the Append String you specified within the LinkList Preferences. Use this when you are manually building your URL. Note that the {append_str} variable will only show when a site has been recently updated.

Variable Pairs

{list_heading}...{/list_heading}

Back to variable pairs

You can specify the code to execute one time per linklist using this variable pairs. It's very much like the {date_heading} parameter used in the {exp:weblog:entries} tag. You can specify within the variable pair any code that you want to show everytime it goes to the new linklist.

{keywords backspace="6"}...{/keywords}

Back to variable pairs

When used within the {exp:linklist:entries} tag, this variable pair will enable you to show all the keywords that are associated with that certain link. This works similar to the categories variable pair in the weblogs tag.

You can also specify a backspace with a value meaning that on the last iteration, it will remove that many characters at the end. i.e. if you use backspace="6", then it will remove the last 6 characters.

Variables for this tag:

{keyword}

{keyword} will display the keyword for the link.
{path="weblog/keywords"} will display the URL to point to, according to the template you specify (weblog/keywords in this case) and append the keyword to the URL. eg. http://www.yourdomain.com/index.php/weblog/keywords/expression_engine.

{path="weblog/template"}

This will display the URL to point to with the keyword attached to it. i.e. {path="weblog/keywords"} results in: http://www.yourdomain.com/index.php/weblog/keywords/thekeyword.

Here is an example of the usage:

{paginate}...{/paginate}

Back to variable pairs

If you want to paginate your linklist, you can do so using the paginate feature. This feature works identical to the paginate method for weblog entries and comments.

Pagination defaults to bottom. If you include the {paginate} tags, then they will be placed at the bottom or top. To specify the location, simply use the paramter paginate="top" or paginate="bottom".

Example usage:

Conditionals

Regular Conditionals
Updated Hours
Recently Updated

{if == ""}...do something...{/if}

Back to conditionals

You can typically use any variable used above to develop show or hide certain things. Here are a few examples to get you going.

{if updated_hours < "12"}...do something...{/if}

Back to conditionals

This is to show an example of using Updated Hours to "bypass" your default "recently updated" value in your Linklist preferences. Regardless of what you may have in there, (default to 12) you can always bypass it by using this conditional.
The example above will show any link you have as Updated if the site has been updated within 24 hours, regardless of what your linklist preferences might be set to. This can get handy if you want to change certain links to show updated at different times.

{if recently_updated}...do something...{/if}

Back to conditionals

This is an example of using Recently Updated as a way to show more than just the prepend string or append string.
As you can see from the example, the last updated date will only show if the link has been recently updated. This can get handy again if you want to highlight those sites that have been updated recently.

{exp:linklist:checkupdated}

This tag is mainly used as a "background" function. Basically what this tag will do is go out to the web and spider the RSS URL's of your links, and determine if the site has been updated or not. Most likely this tag will be added to the header of every template, or could be set to a template that you call at a specified interval.

BASIC USAGE:

This tag will only check a batch of sites within a 1 hour period. When initially run, this tag will try to get all sites updated dates, so I recommend putting this tag into a test or temporary template and refresh that page until all your links have been updated with the last updated date. By default, this tag will only check 5 sites at a time. You can change this by using the limit parameter. If you wish to specify only a certain linklist or linklists to be updated at a time you can also specify that using the linklist parameter.

Example Usage:

{exp:linklist:checkupdated} Parameters

limit="5"

Back to Parameters

This parameter will limit the number of sites you will check to see for updates. While 5 may be a low number of sites to spider, please consider that this tag will be executed on the top of every page. I recommend tweaking this setting to your liking. Please remember that it will only check the latest 5 (or whatever specified number) sites within 1 hour. By default, limit is set to 5.
Tips: You may consider putting this into a special template and setting a Cron or Scheduled task to hit this page every so often. This would essentially be best, as it would not slow down access to your website when you have visitors.

silent="true"

Back to Parameters

This param if set to false, will display exactly what it is doing. It will display the starting check of each link, and supply a benchmark time of how long it took for each RSS URL. By default, silent="true", meaning, there will be no display at all. (Use this only when you are debugging)

linklist="linklist"

Back to Parameters

If you prefer only to see if certain linklists are updated, then you can specify the linklist that you want to have this module spider. You can also specify multiple linklists with the pipe character.

{exp:linklist:keywords}

This tag is used to display the keywords for a linklist. This tag uses the same tags as the {exp:linklist:entries} tag. You can specify displaying of keywords by single linklist, all linklists, some linklists, and so on. If you so choose, you may also display them as weighted keywords, meaning the more links you have associated to a certain keyword, the larger the size of the font.

BASIC USAGE:

That will display a series of keywords with links to the template "weblog/keywords".

{exp:linklist:keywords} Parameters

min_size="10"

Back to Keywords

min_size will make the minimum {font_size} to whatever you specify. You may wish to use this to control the sizes of your weighted keywords.

max_size="50"

Back to Keywords

max_size will make the maximum {font_size} to whatever you specify. You may wish to use this to control the sizes of your weighted keywords.

related="on"

Back to Keywords

This parameter allows you to display only the related Keywords to the current viewing keyword. i.e. if you reached a page at: http://www.yourdomain.com/index.php/weblog/keywords/expression_engine, this parameter tells the exp:linklist:keywords tag to look for related keywords to "expression engine", provided dynamic="on". You can also override the URL by specifying the keywords to relate to via the keywords="" parameter. Here is an example, this will only display keywords that are related to "expression engine" and "pmachine":

{exp:linklist:keywords} Variables

{keyword}

Back to Keywords

{keyword} displays the keyword used in the links for that linklist.

{path="weblog/template"}

Back to Keywords

This will display the URL to point to with the keyword attached to it. i.e. {path="weblog/keywords"} results in: http://www.yourdomain.com/index.php/weblog/keywords/thekeyword.

{font_size}

Back to Keywords

Will return a font size equivalent to the weight of the keyword. i.e. the more links associated to a certain keyword, the bigger the font size.

Troubleshooting

Problem: I'm having a problem importing my OPML file. I can import by using the URL, but if I upload a file, I keep getting an error that the file is not a valid file type.

Solution: As of ExpressionEngine version 1.3, files are checked against an array of mime types. You need to edit your mimes.php file located in your system/libs folder. Check your file type and make sure that it's listed as an acceptable file type in your list. If you are using the typical file format, the file is probably an OPML file. so you'll need to add this line to your mimes.php file: 'opml'=>'application/opml' Here is what it should look like:

Problem: I have the linklist in a sidebar on my main page, and it works great! But when you navigate to any other page, (such as the comments page) nothing shows up at all. What gives?

Solution: Remember that the linklist by default uses the third segment (segment_3) for keyword/tag searching. Typically then it display related links to that keyword. However if you are navigating to a comments page, (just as an example) odds are, the url would look like: http://www.yoursite.com/index.php/weblog/comments/title_permalink. In which case, the "title_permalink" segment is seen as a keyword/tag and it will attempt to display any link you have that has that keyword. (odds are good it's probably none) To disable this functionality, use the "dynamic=off" parameter to fix this issue:

Tips and Tricks

I've had a few questions and basic ponderings of how to make some incredibly customized outputs using this linklist. To see some really cool techniques, check out LisaJill's site and you'll see some pretty cool stuff that she's done with it.

I'll be showing some examples in the following area to show you how some things can be displayed.