MyHeadlines Administration Guide

Assumptions. 1

Menu Item: Administration. 1

Menu Item: Administration > Import. 84

Menu Item: Administration > Maintenance. 90

Menu Item: Administration > Configure > Parameters. 104

Menu Item: Administration > Configure > Appearance. 144

Menu Item: Administration > Configure > Templates. 166

Menu Item: Administration > Configure > Sections. 224

Menu Item: Administration > User Subscriptions. 239

Menu Item: Administration > Backend. 245

Assumptions

I am going to assume you have installed the MyHeadlines module according to the install.txt file that was included with the package, and followed the Getting Started procedures. You should have a populated Category tree with some headlines in it.

Menu Item: Administration

The first screen of the Administrators interface contains 3 important functional areas: Administrator’s View of the Category Tree, Sub Menu Items for the Administrator, and the Administration Action Buttons.

1. Please log in to your MyHeadlines module as the administrator. This will enable the “Administration” menu item.

2. Click on the “Administration” link in the menu.

The Administration main screen has a larger number of active elements. On the left you see the Main menu, and sub-menus. On the right at the top is the current Category Tree, followed by an array of buttons that act on the Category Tree.

Category Tree

Please take a moment to navigate[1] the Administrator’s Category Tree to see the scope of the contents included within the bundled import files. Feel free to “play” with the various options or read on. Each option is detailed below.

Drill (click) into the “Top News” category (or any category you chose)

As an administrator you have security clearance for all of the maintenance options of the Category Tree. You may copy branches (categories) from one location to another, delete whole branches or individual sources. You can rename, modify, inspect and set mandatory site subscriptions for every user. There are currently four types of data stored in the Category Tree: Categories, Good Sources, Bad Sources, and User Submitted Sources:

· Categories are self explanatory

· Good Sources are feeds that have provided valid results

· Bad Sources are feeds that either did not respond or provided invalid data (identifier is the “ERROR – “ prefix)

· User Submitted sources are feeds one of your users has submitted to you so that you may add it to the Category Tree (identifier is the “New – “ prefix)

User submitted sources and Bad sources are only visible in the Administrator’s Category Tree. This is both a security feature and a usability feature: Security can be breached by malicious sources whose RSS output my in fact be a crude Trojan attack vector (cross site scripting attacks). It is important to ensure that a user may not submit a new source and immediately view the results, the admin takes the responsibility for this task and the admin preview screen is much different than the user’s. If a source goes “bad” then it is removed from the user tree so that users are not frustrated by trying to subscribe to a questionable feed.

This interface expects the administrator to know what s/he is doing. It does not ask: “Are you sure?” Click delete and it deletes.

Category Tree Action Table

Type	Active Element	Comment	Details
Category	Category Name	The expands or collapses the branch
Category	Copy	This copies the item to a new location	Copy
Category	Delete	This deletes the item
Category	Rename	This allows the admin to rename a category	Rename
Good	Source Name	This allows the admin to preview results and edit the source parameters	Verify Source
Good	Copy	This copies the item to a new location	Copy
Good	Delete	This deletes the item form the category tree
Good	Mandatory	This will make the source a mandatory (Default) subscription for every user	Mandatory
Good	Add to Section	This will add the source to one of the Custom Section pages
Good	Info	This will show some useful internal information	Info
Bad	Verify	This allows the admin to preview results and edit the source parameters	Verify Source
Bad	Delete	This deletes the item form the category tree
Bad	Info	This will show some useful internal information	Info
User	Verify	This allows the admin to preview results and edit the source parameters	Verify Source
User	Delete	This deletes the item form the category tree
User	Info	This will show some useful internal information	Info

Copy

1) Select the destination Category from the pull down list.

2) Click Copy or Cancel to complete the transaction

Rename

1) Enter the new name for the Category

2) Click Copy or Cancel

Verify Source

1) Ensure the RSS output is being parsed properly by testing the source

2) Modify any source parameters required to correct the source, this can also include re-categorizing the source

3) Preview your changes by clicking “Preview”

4) Finalize your previewed changes (you must preview after any change) by choosing from the finalizing buttons “Passed”, “Delete”, or “Cancel”

5) If you are building a scraped feed please refer to the Template Based Scraping document

Mandatory

1) Click the Mandatory link for the source to make it a site default. Mandatory for all users.

2) Select the position for the source from the drop down menu

3) Click “Subscribe” to complete the transaction

4) If you want to remove a Mandatory Subscription look here: Menu Item: Administration > User Subscriptions

Info

1) Click the info link to view source information. The key data element on this screen is the ID.

Administration Action Buttons

New Category New Headline New Mandatory Stock Symbol

New Category

1) Click the New Category button to add a branch to the tree

2) Enter the new category name

3) Select the Parent Category for the new branch form the pull down

New Headline

1) Click the New Headline button to add a new source to the Category Tree

2) Fill in the Source information

3) Preview the source and adjust and preview and adjust and preview until satisfied

4) Click on “Save”

5) If you are building a scraped feed please refer to the Template Based Scraping document

New Mandatory Stock Symbol

This feature seems out of place here, but I don’t have a better location right now. In any case this will allow you to set a mandatory stock symbol for all users in the Stock Ticker. I user it to put up the NASDAQ, DJIA, and CDN$, and each user can add to it if they want.

1) Click New Mandatory Stock Symbol

2) Fill in the fields and click Save

Menu Item: Administration > Import

The import function is a simple method of distributing new feed information in a manner that allows a MyHeadlines admin to expand the category tree and the sources within. Most new releases of MyHeadlines include expanded import files so I recommend re-importing each file you are currently using to ensure you have up to date information.

1) Click on the Import submenu link

2) There are two options from here: Import and Remove. The pull down box contains a list of import files[2] to choose from. Click import to import the selected file. If you want to remove all the sources imported from an import file, this task is usually due to a change in Terms of Use from any given provider, Click the associated “Remove” button.

Menu Item: Administration > Maintenance

MyHeadlines like any other complex system will over time generate a certain amount of useless data. Sources go bad, user suggest new sources, anonymous user information is collected but never purged, headline cache grows beyond your account quotas, etc. The features in this section help you manage this bloat.

1) Click on the Maintenance submenu

2) There are two areas to the maintenance screen: the top half is Headline maintenance for user submissions and bad feeds, the bottom half is general MyHeadlines garbage collection.

Headline Maintenance

1) Click on the user submitted or bad headline to Verify Source

Garbage Collection

Force Cache Refresh for ALL Sources

Clicking this button will expire all sources in the Category Tree. It is useful if you are debugging an issue and you want a source to be fetched but don’t want to wait for it to expire

Flush ALL Headlines from the Cache

This is a quick and dirty method of reducing the size of your database. The Cache table grows quite a bit over time. It will level off over time, but increases for each new subscription. My site has over 240 unique sources with subscribers, I hold cached headlines for 14 days, and my cache table is just under 40 MB, and contains approx 60,000 cached headlines.

(refer to the Top Ten screen to view how many headlines you have cached)

Remove All Anonymous User Data

This is a quick hack to help clean up the cookie records, and trash all Anon data. It is needed due to the increasing number of users NOT accepting cookies. Every time an anon user loads MyHeadlines a cookie is sent and the value of the cookie is added to the DB. If the user does not accept the cookie a new one will be sent again, and again, and again on each subsequent page load. On High traffic sites the user accounts DB grow fairly quickly due to onetime users who are just passing through. This is a cheap hack that should really be replaced with a proper fix, but I won’t revisit the Account system for a while. It’s a standard situation where features are more important that redoing bad sections that “work”.

Menu Item: Administration > Configure > Parameters

This section details how to modify the performance characteristics of MyHeadines.

1) Click on the Configure submenu

2) Click on the Parameters submenu

default_lang

Place the filename of the language file you'd like to use in this box. The MyHeadlines Language files can be found in "/html/modules/MyHeadlines/lang"

date_format

This is the template for converting the date stamp. More information on the acceptable variables can be found here:

PHP Docs: Date Function

rss_timeout

This is the timeout in seconds before giving up on refreshing the content from any given source or stock symbol.

consecutive_failures_before_bad

This is the number of retries before a source is marked as bad in the database. The retries are not executed immediately, but instead at the regular source timeout interval. As soon as a success is registered this counter is reset and the next failure will appear as the first.

NOTE: a "bad" source is not visible to the user for subscriptions, it is held in wait for an admin to verify the status.

rss_cache_expire

This is the number of days to keep headlines in the database. The longer your keep them the bigger your database will be, and the deeper the search. It's a trade off, better searches for larger databases.

max_updates_per_cron_cycle

This one is an advanced feature. If you have setup a cron job, according to the Administration >Configure >Backend >Cache Control, this feature will allow you to limit the amount of time the cron job spends refreshing the cache. The job will stop after updating this number of unique headline sources. This is useful if you want to spread the refreshing of sources “evenly” across a time period. If you have 120 sources with subscribers, you refresh every 10 minutes, and max_updates_per_cron_cycle is set to 20, it will take 1 hour to refresh all sources. The benefit here is that the sources will expire in a staggered fashion from this point on, instead of all at once. Basically this is a cheap attempt at a load balancing algorithm.

stck_timeout

This is the timeout in minutes between cache updates for stock quotes. This is hard coded to reset to 20 minutes if you try to enter a shorter timeout of less than 20 minutes. A longer timeout will remain unchanged. Play nice when using other services on the web.

rss_proxy_enabled

Turn on/off proxy support. Are you behind a proxy server? Set this to 1, if not leave it as 0.

allow_anonymous

This is a flag to indicate that anonymous users may or may not access this system. ALWAYS SET THIS TO 1. If you have an external account system from your CMS you may change this to 0 to limit access to registered users, but I recomend using the CMS account system to restrict access.

If you are using the Stand Alone version you could be locking ALL users out of this code since everyone is anonymous.

BE VERY CAREFULL!!!

max_user_time

This parameter limits the time spent trying to update expired sources IF it is determined that this is a user (or anonymous user). Your site will try to update expired stock ticker and / or headline sources until this timeout is reached. The timeout is in seconds, and I like 7 seconds. This has no impact on Backend functions, and does not impact the rss_timeout parameter. The ideal situation is to increase the rss_timeout value to the order of 60 seconds, and limit the user interface to something much shorter.

google_registration_key

Enter your Google API registration key here. This will enable SOAP backend connection to Google. Set this to 0 if you want to disable. In order to use Google Web APIs you first must register with Google to receive an authentication key. You can do this online at http://www.google.com/apis/.

rss_proxy_host

This is the IP address or host name of your proxy server (this variable is visible when "rss_proxy_enable" = 1)

rss_proxy_port

This is the Port number for proxy connections on the rss_proxy_host (this variable is visible when "rss_proxy_enable" = 1)

rss_proxy_user

Does your proxy server require authentication? If no, leave this as 0 if it does require authentication enter the user name here. (this variable is visible when "rss_proxy_enable" = 1)

rss_proxy_pass

Does your proxy server require authentication? If no, leave this as 0 if it does require authentication enter the user password here. (this variable is visible when "rss_proxy_enable" = 1)

Menu Item: Administration > Configure > Appearance

These configuration parameters affect the look and feel of the MyHeadlines module.

1) Click on the Configure submenu

2) Click on the Appearance submenu

rss_max_items

This is the number of items to show in the side boxes. The cache holds older items in the database until they expire (see rss_cache_expire), but only the most recent items up to rss_max_items are displayed.

rss_show_summary

This will show the summary information that may be included with stored headline.

1=show 0=don’t show

rss_override_logo_width

If your theme does not align any more due to the size of the logos displayed within the MyHeadlines side blocks then turn on the override feature to scale all logos to be the same width (see rss_logo_width).

1 = override, 0 = do not override

rss_logo_width

This is the static width for all logo images, in pixels. Set this to a value that fits within your theme side blocks.

num_search_results_per_page

This is the maximum number of search results to display per page. If there is a possibility that there are more results available then a “more” button will be shown.

show_shameless_plug

This one hijacks sites with no logo image defined and shows the "Powered by: MyHeadlines" banner. If you're sick of my cheesy image, and wish it would just go away...

1 = Show Image, 0 = Hide Image.

front_page

You can now change the text of the entry screen. You have access to the raw HTML and can do as you please. Want to add your site logo? Put up detailed instructions? A special tribute to the geek who wrote this fancy MyHeadlines module? As you please.

Menu Item: Administration > Configure > Templates

These configuration parameters affect the layout and branding of the MyHeadlines module.

1) Click on the Configure submenu

2) Click on the Templates submenu

tag_line

This is the credit tag found in the bottom right of most of the action screens. (just below the “Done” button) If you wish to hide the authorship of themodule you may remove this brand, or replace it with your own tag.

front_page

This is a duplicate location of the front_page parameter. Make some sense to include it here too.

dispBlockWithImage

The template for the block that includes the site logo (“WithImage”). The template system follows the same syntax as the scraper system: The raw HTML code is used to render the block and the variables denoted by matching pairs of “{“ and “}” brackets are replaced with the internal MyHeadlines data. This template will replace the following variables with the described data:

Variable:	Replaced By:
{site_name}	The name of the source from which the headlines have been gathered
{image}	The logo from the source of these headlines. This particular block (dispBlockWithImage) is intended to include the site logos, so it is a good idea to include this variable in this template
{content}	This a macro place holder for ALL of the headlines to be displayed for this source. This variable has its own templates for formatting the layout of the headlines.
{url}	This is the URL of the RSS/RDF/XML file for this source.
{next_update}	This is the time stamp representing the count down until the source is updated again.
{more_link}	This is a complete anchor tag that deep links into MyHeadlines to show all of the headlines for the source. (“More…”)
{promote}	This is a complete anchor and image (bullhorn) that deep links into the MyHeadlines Promote features for Blogging about the headlines

dispBlockNoImage

The template for the block that DOES NOT include the site logo (“NoImage”). This template will replace the following variables with the described data:

Variable:

Replaced By: