Thanks for choosing the meoReader. The following documentation will tell you more about how to use the plugin, what each option, button or action link is for and how easy it actually is to use the meoReader.
In case you're more of a visual person there is also a 12 minute walk through video that should get you started pretty good.
And please also check out the more detailed changelog about new features and bug fixes at Meomundo.com.
When considering to use the meoReader, or actually any other self-hosted RSS feed reading application for that matter, keep something in mind: The meoReader is not the Google Reader!
It's gonna be your server that might become a bottleneck when you're subscribing to too many feeds. Not so much in terms of disk or database space but when you're trying to update all these feeds.
You might run into PHP execution time problems (which is limited by your php.ini settings), especially when you don't have Javascript enabled in your browser. In PHP it's simply not possible to have multiple threads. But as a workaround you can use Javascript/Ajax to split the task of updating all feeds at once into updating one feed after another. But it will still take more time than simply checking your Google Reader (where everything has nicely been timed, cached and pre-processed for you).
And even though there are standards for how RSS feeds should be build, there are a thousand things that can go wrong when generating and then providing such a feed. Some will be unintentionally and others will be by choice! Yes, feed provides come up with all kinds of reasons why they think they have to break the standard.
The thing is, it doesn't even matter why a feed appears to be broken. At best it's only going to be harder but in the worst case simply impossible to handle that feed!
So please make sure the feed you want to subscribe to but cannot isn't broken in itself. And if it is, please contact the feed provider first. It should be in his/her own interest to offer feeds that can processed by other applications without causing any trouble - which kind of is the reason RSS was invented...
The meoReader plugin basically uses the following four sections that in total make up the WordPress embedded RSS feed reader.
Typically, when you've installed and set up the plugin you would go the subscriptions page and create some categories and then manually add some RSS feeds or import some data sets.
Then a typical day-to-day workflow could look like this:
And every now and then you should export your data to keep a backup of your current subscriptions (categories and feeds). This can be done on the subscriptions page.
Before you start make sure you have downloaded the plugin ZIP file (which will be named something like "meoReader-1.0.0.zip") and have saved it to your local computer.
Then log into your WordPress backend as an administrator and select "Plugins / Add New" from the main menu. Now click the "upload" link at the top of the page, choose the plugin ZIP file from your local machine and click the "Install Now" button.
Depending on your internet connection this might take a moment. But when you see the message "Successfully installed the plugin meoReader" click the "Activate Plugin" link - and that's it.
The plugin is now installed and you can see that a new main item, "meoReader", has been added to menu.
This plugin will be updated every now and then. Bugs will be fixed and new, requested features might be implemented.
No matter if you update the plugin manually or by using the auto-update service you should always follow these three steps:
WordPress only runs certain update operations (file operations and database structure updates, for example) only when re-activating a plugin. So these 3 little steps are crucial!
To update the meoReader plugin you log into your CodeCanyon account and download the latest ZIP archive which you have to unpack to some location on your local computer.
Log into your WordPress backend as an administrator, go the plugins menu and deactivate the meoReader.
Then start an FTP client of your choice and upload the complete /meoReader/ folder that you just extracted to your server, into the directory /wp-content/plugins/
Now activate the meoReader again in the WordPress backend and you should be done.
You can check if everything went okay by going to the menu plugins/installed plugins. You should see that the version number has changed!
The meoReader also offers automatic updating. So if you log into the WordPress backend as an administrator you will see a notification if there is a newer version of this plugin available. Simply go to the plugin menu then and you will see a message, "There is a new version of meoReader available", at the bottom of the plugin row.
There are also two links available: "View Version Details" - which will open a little popup with further information about the new version - and "update now".
Click "update now" and after confirming the action the new version will be automatically downloaded and installed.
Depending on the server connections this might take a bit. WordPress is giving you little progress messages which in my experience can be a little bit misleading. So please be patient and wait until the message "Plugin re-activated" appears. Then, and only then is the update complete!
If you leave this page too early the installation might break and even damage the plugin.
But even if that has happened, it's not the end of the world. But you would have to install the update manually then since you have to overwrite possibly incomplete files.
The plugin settings can be found as sub menu item of the "meoReader" menu (/meoReader/Settings/.
The number of entries that will be shown in the reader as well as the archive on a single page.
If there are more entries than that you will find links to pages of older and newer entries (prev/next navigation) at the bottom of the page, below the entry block.
It is not a good idea to store entries forever if you want to keep your database clean, fast and responsive. With this setting you can specify the number of days you do want to keep them (always counting backwards from today). Entries that are older than that will automatically be deleted on a regular basis. Also, when you update feeds or add new ones, incoming entries that are too old (according to this setting) will not even be saved to begin with.
This is a tricky one. When adding or refreshing a feed, its URL will be loaded in order to get the latest version of the RSS feed. And loading an external source takes time. It's quite possible that the server that's being contacted takes too long to generate an answer or that this server is even down (permanently or temporarily).
If you have more than one feed you're subscribing to you don't want to wait forever for a server sending a response, as this might sum up to a pretty long time. Instead, you would want to wait only a certain amount of time (set the number of seconds you're willing to wait here) and then move on to reading or refreshing the next feed.
But there is another limitation and it is due to your server settings: the PHP execution time. If a script (or a PHP application as a whole) takes more than that time (also in seconds), PHP will simply stop (or "die") and produce a hard error.
So the timeout value you set here always has to be at least one below this PHP maximum execution time. There is footnote for this option that will show you your current server setting! If it turns out that this is not enough (meaning, you cannot load feeds within that timeframe) you either have to change your PHP.ini file yourself or contact your hosting company so they can do that for you.
If you want to read your RSS feeds sitting in a public place like a Cafe or park you should be aware that the local networks there might not be the most secure ones. It's also possible that other people might simply see you typing your password when you log into WordPress.
Therefore it is recommended to select a single user from the list here -which you might have to create beforehand- that at best is only a "subscriber" but in any case should not have any admin rights! If you log into the backend as this user you can refresh your feeds, read your entries, even move them to the archive and back, but cannot manage your subscriptions. This restriction makes it at least a little bit more secure surfing in public networks.
If this option is checked all new entries will automatically be published as WordPress blog posts. Make sure you have the original author or publisher's permission to do that. And also be aware that there is certain risk when auto-publishing third-party code/content. It might break your design or worse, contain mal code.
Each auto-published post will get a unique ID that's being stored in the post meta data. This way no duplicate posts should be created even, for example, when you're deleting a feed and after a while add it again.
Google has a service called "Takeout" that lets you download all kinds of data from your Google account. And if you go to the Google Reader section (https://www.google.com/takeout/) you can download a ZIP archive that will contain your subscription data.
This ZIP file can be imported into the meoReader where your categories and feed subscriptions will then be added.
But since you might only import that data once (or at least not too many time, I guess) you can hide this import form on the subscriptions page by unchecking this setting. And of course by checking the checkbox again you can always bring it back whenever you want to.
Importing data from a ZIP file requires PHP to have a ZIP module enabled. If that is not the case you will not be able to import your Google Reader data. Instead you will see a message telling you to enable this module. You might have to ask your host to do that for you.
By using this redirect service you can anonymize your referrer for outgoing links in the Reader. Meaning, the sites you're about to go to can still identify you, respectively your IP address or certain browser settings but will not know where you're coming from.
For even more anonymous surfing you would have to go through a proxy server or a VPN tunnel of some kind.
Say you've subscribed to the RSS feed of an audio podcast. If take a look at the content of an entry (or episode) you will see the link to the "attached" media file at the bottom of the content area. If you check this setting and run what would be considered a "modern" browser an instance of the HTML5 audio player, audio.js, will be shown so you can listen to this media file right here, in your browser.
Audio.js is a free third-party application by Anthony Kolber and is released under the MIT License.
Though this player is said to be working with all modern browsers I've had some trouble when loading it in IE. So if you're also using IE and experience the same difficulties you might uncheck this option!
Also, when you click the play button of the player you have to be a little bit pacient. The way I set it up no audio file is being preloaded and therefore it takes a few seconds until there is enough initial audio until the player will start.
If checked, output like tiles and contents of each entry will be checked and certain potentially unsecure code will be removed. This will now be handled by the HTMLPurifier library.
Needles to say that this a security feature that makes sense but also take it's time, especially when you have lots of entries per page. And in some cases content will be stripped out that should have stayed in - but that's pretty rare.
If you want to run the feed updates automatically, e.g. by creating a cronjob on your server, this is the URL you should target. make sure the ?token={someToken} URL parameter is added! Otherwise it won't work.
There are certain risks of running such an auto-update. For example, if all goes wrong (and none of the error handlers can catch it) the cron.php script might run in an endless loop! And since you're most likely not there to stop it in time, it can block quite some server resources (CPU and RAM).
You should also be aware of when to schedule the cronjob. My advice: Running it every 6 or even 12 hours is usually enough. Plus you want to choose a time with your lowest website traffic (so it won't slow your server down), e.g. 5am/5pm.
When you are done editing the plugin settings remember to click the "Save Changes" button. You will then get a message if the settings could be changed or not (in case there was a technical error).
You can find the "Subscriptions" page as sub item of the "meoReader" menu in the WordPress backend. Here you can manage your subscriptions, respectively your RSS feeds and organize them in categories.
Categories are optional but pretty handy so you can group RSS feeds that typically share a common topic or a common source. Basically you can add as many categories as you like and also rename and delete them according to your needs. There is one category though that is a little bit different:
When you install the meoReader plugin a category called "Unsorted" will be created. This is going to be the default category that might be renamed (as long as the name is not taken by another one) but cannot be deleted! Each feed that is not assigned to any other (valid) category will be listed here. You can still see what the default category is even after you have renamed it since it will always have a violet border, unlike the others.
To add a category use the form at the bottom of the page, below the categories block. Simply enter the name into the input field and hit the "Add Category" button, right next to it. If the name is not taken by an existing category the new category will be created.
To delete a category click the link on the right side of a category's bar. You will then be asked to confirm your request, just to be sure you haven't clicked this action by mistake.
When you delete a category the feeds that are currently assigned to it will not be lost! They will be moved to the default category instead.
There are two ways to rename a category: You can either click the "rename" action link on the right side of a category's bar or simply double-click the category name. In both cases, a text input field will appear and you can edit the name. In order to actually rename the category after you've changed the name, simply hit the RETURN key. If you decide you don't want to rename it any more, simply hit the ESCAPE key and the action will be discarded.
If the new name is already being used by another category you will get an error message that will tell you so. It is not possible to use the same name twice. And also, category names are not case-sensitive when it comes to checking the uniqueness!
The meoReader handles RSS as well as atom feeds. And though technically these are two different standards, when it comes to terminology they might use interchangeably throughout the documentation. So "RSS feed" usually means "atom feed" as well and vice versa.
A feed's title and the action links are aligned in the same row, so to speak. The background color of this row will turn into a dark grey so can always be sure you are about click the right action link for the right feed.
To add an RSS feed use the form at the top of the subscriptions page. Enter the URL into the text input field, select a category this feed should be assigned to from the drop-down list right next to it, and then click the "Add Feed" button.
If the URL is valid and the feed can be reached it will be loaded immediately. Some meta data like the feed title and the URL of the website this feed belongs to will then be extracted and the feed will be added to your database. Also, the entries of that feed will be added - as long as they're not older than what you have specified in the plugin settings.
To delete a feed along with all its entries(!), simply click the "delete" action link on the far right of the feeds name.
When you click a delete link you will be asked to confirm your action just to be sure you haven't clicked that link by mistake.
When you suspect that a feed is not loading correctly or you just want to know how the meoReader dissects a feed you can click the "check" link on the far right of the feed name.
You will see if and how each entry is being detected, along with its meta data, and if an entry has already been added to the database or not (in which case you will see a message if that's because of your "older than" setting).
Feeds are always assigned to one (and only one) category, even if it's only the default category. If you want to move a feed to another category, click the "move" action link on the far right of the feeds name. You will then be asked to select the new category which you have to choose from the drop-down list. You can still discard the action at this point or actually move the feed by clicking the corresponding button.
Below your subscriptions block is a link that, when clicked, will generate and lets you download an XML file containing all your categories and feeds you subscribe to. Though the XML format is a proprietary one it is pretty simple to understand. Anyway, this XML file can be imported back into (or any other installation of) the meoReader plugin.
The export function might be handy in case you want to move that data or, even more important, to make backups every now and then!
Here you can select a meoReader export (XML) file and import that data again. When you import data sets into the meoReader existing data will not be deleted! So when you want to make a "hard update" you have to manually delete these items before you start importing "new" one.
Google has a service called "Takeout" that lets you download all kinds of data from your Google account. And if you go to the Google Reader section (https://www.google.com/takeout/?pli=1#custom:reader) you can download a ZIP archive file that will contain your subscription data.
This ZIP file can be imported into the meoReader where your categories and feed subscriptions will then be added.
You can also import and export a list of feeds and their categories by using data in the OPML format.
"The reader" is the page that shows you a list of entries, sorted by date (from new to old) that can be found in the WordPress backend under the main menu item "meoReader". While the "subscriptions" page is for managing and organizing your feeds the reader is the place for actually reading the content.
The reader page is basically made out of two sections. At the top of the page is a toolbar where a bunch of action buttons are located that will influence what entries will be listed below.
The second section is "the entries list" that allows you to read the content. Entries are listed one in a row and will show you (from left to right) the [A] icon to move an entry to the archive, the feed name this entry belongs to, the entry title, and the date of the entry (according to the RSS feed!)
Unread entry rows have a white background and their text is written in bold letters while items that have been read will have a grey background color and normal weighted text.
To read the content of an entry, single-click the entry row wherever you want and the full content will then be shown. And the moment you click an unread entry it will also change its status to "read".
If you want to read another entry just click that new entry row. This will close the current content and open the new one so that the reader page won't grow to an unacceptable length.
Sometimes, entries can have links to certain kinds of media files attached. In case of a podcasting RSS this might be the link to one or more audio files, for example. These media file links will be listed beneath an entry's content, in a dark grey box. When you hover such a link with your mouse, a tooltip will appear and show you the full URL of this file.
Some media types will also be hinted by showing related icons in front of the filename, like a little speaker icon when it's an audio file.
The content of an entry might contain things like "iframes" or certain kinds of embedded objects. Normally, loading these things would cause the rest of the page to stop loading until these external contents have been fully loaded first. And depending on the number of entries you have set up to be shown on one page (e.g. 30) this would result in you having to wait way too long just so you can see the list of entries.
To prevent this annoying behavior from happening elements like iframes will be filtered out of the content. But they are not lost, of course. If the content of an entry contains such elements you will see placeholders with a neon-yellowish background color. When you explicitly want to load the content a placeholder holds back you simply have to left-click them.
This approach might not be ideal but it turned out to be the best compromise when it comes to loading numerous entries to build the reader list.
Entries will be located either in the reader or in the archive, never in both places at the same time. The archive is the place to store entries you like to keep. Hopefully because they are interesting to read but also to keep them even when they are older than what you have specified in the plugin settings. Archive entries - opposed to reader entries - will not be deleted if they are older than that!
To move an entry from the reader to the archive click the [A] icon at the very left in an entry's row. It then will disappear from the reader list but show up in the archive list.
To get the latest entries of all the feeds you subscribe to, click the "Refresh" button in the toolbar at the top of the page. This might take a while depending on how many feeds you subscribe to!
When you start the updating/refreshing process a box pops up that shows you what feed is currently being refreshed and how many feeds have already being updated (e.g. 3 of 32). When all feeds have been refreshed the reader will automatically update the entry list.
If some feeds could not be reached or updated for whatever reason you will be shown a list of those feeds. You then might check the feed URLs by yourself and see if this was only a temporary problem or, for example, if the feed URL has changed (in which case you would have to delete the old feed and add the new feed URL on the subscriptions page).
If you have created categories other than the default one you can select a single category from a drop-down list in the toolbar. If you do that, only entries of those feeds that are assigned to that category will be shown.
You can also select "All Categories" which then will show you (who would have thought) all entries, no matter what.
When you click this button in the toolbar, all entries will be marked as read and the entry list will be updated when it's done. This can be very handy if you have read the entries that seemed interesting to you and you don't want to check the other items again the next time you refresh the feeds.
When you click the little [R] icon left next to a feed name you can toggle a single item's status from read to unread and vice versa.
By clicking the "Today" button in the toolbar at the top of the Reader page only today's entries will be displayed.
The button then changes from "Today" to "All Time". So when you hit it again all entries of all time will be displayed again.
At the top of the reader, in the toolbar, there is also a search box that allows you to search all entries, from the reader as well as the archive, or more precisely, their titles and their contents.
If search results could be found a list of those entries will be shown, just like you're used to in the reader or the archive. You can click entries to show the content and close it by clicking again (or another item).
| Key | Action |
|---|---|
| NUM PAD [+] or SPACE |
Select and open the next entry. |
| NUM PAD [-] | Select and open the previous entry. |
| j | Select the next entry. |
| k | Select the previous entry |
| o | Open/Close entry (expand/collapse) the content of the current entry. |
| r | Toggle unread/read state of the current entry. |
| R | Mark all items as read. |
| a | Move the current entry to the archive or from the archive back to the Reader. |
| t | Either only show TODAY's entries or all entries of ALL TIME. |
| u | Refresh/Update feeds. |
| ESCAPE | Abort refresh/update process. |
The archive lets you store entries you want to keep for whatever reason and that will not be deleted, no matter if they are older than what you have set on the plugin's setting page.
Reading entries here is just like on the reader page. You once click an entry to show and then read its content. You click again or another entry and the current content will close (and the new one might open up).
Even though you most probably will not have as many entries in the archive as you will in the reader, the concept of placeholders also applies here: In case the content of an entry contains iframes or certain embedded objects, placeholders will be shown instead. This prevents the page from having to wait until all those external contents will be loaded before you can even see the archive page. To show (and therefore load) that elements you have to left-click the placeholders.
Another difference to the reader is that you don't have a complete toolbar here. Operations like refreshing feeds etc. have to be done in the reader. You can still search all(!) entries though.
If you want to remove an entry from the archive (and therefore move it back to the reader) you have to click the [A] icon on the very left of an entry's row. It will then no longer be shown in the archive. Instead it will appear in the reader.
[A] The content might be older than what you have specified in the plugin settings (under "Settings / meoReader"). Entries that are "too old" will be deleted, respectively not saved to the database in the first place.
[B] The feed itself is not valid (according the RSS standard) or even broken, or the feed URL does not point to an XML file - though the website might still return "something readable". If you suspect something might not be working properly please go to the subscriptions page and click the "check" link for this RSS feed. You will then see how the meoReader interprets the feed and it will show you potential problems.
If no error is being reported when checking a feed and the problem still remains, feel free to contact me.
But if it turns out that the feed is broken, invalid or something alike, please contact the feed provider and ask him/her (politely) to fix it.
You can leave your feedback, or questions, or make suggestions in the comments on the plugin page or on meomundo.com