FreshRSS/rssguard
1
0
Fork 0
mirror of https://github.com/martinrotter/rssguard.git synced 2024-12-29 09:31:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs, work on adblock

Browse Source
This commit is contained in:
Martin Rotter 2021-05-07 11:21:27 +02:00
parent 544c52015e
commit 764ab8d083
7 changed files with 104 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
resources/docs/Documentation.md
View File

@ -98,7 +98,7 @@ If you're not sure which version to use, **use the WebEngine-based RSS Guard**.
## RSS Guard 3 vs. RSS Guard 4
RSS Guard 4 is **NOT** backwards compatible with previous editions of the application!!! It stores settings in slightly different [folder](#portable-user-data) to not overwrite user data from previous versions.
RSS Guard 4.x contains numerous enhancements and many of them are hidden under the hood and they make application easier to maintain, easier to improve and easier to use.
RSS Guard 4 contains numerous enhancements and many of them are hidden under the hood and they make application easier to maintain, easier to improve and easier to use.
# Features
RSS Guard is simple (yet powerful) feed reader. It is able to fetch the most known feed formats, including RSS/RDF/ATOM/JSON. RSS Guard is developed on top of the [Qt library](http://qt-project.org) and it supports these operating systems:
@ -119,20 +119,17 @@ RSS Guard is simple (yet powerful) feed reader. It is able to fetch the most kno
* Feedly.
* core:
* support for all feed formats (RSS/RDF/ATOM/JSON),
* full support of podcasts (RSS/ATOM/JSON),
* support for podcasts (RSS/ATOM/JSON),
* import/export of feeds to/from OPML 2.0,
* possibility of using custom 3rd-party feed [synchronization services](Feed-formats.md),
* feed metadata fetching including icons,
* support for [scraping websites](#websites-scraping) which do not offer RSS/ATOM feeds and other related advanced features,
* simple internal Chromium-based web viewer (or alternative version with simpler and much more lightweight internal viewer),
* scriptable [message filtering](#message-filtering),
* downloader with own tab and support for up to 6 parallel downloads,
* application-wide and account-specific network proxies support,
* ability to cleanup internal message database with various options,
* enhanced feed auto-updating with separate time intervals,
* "portable" mode support with clever auto-detection,
* feed categorization,
* feed authentication (BASIC),
* [external tools](#external-tools) - you can run your program with article URL,
* handles tons of messages & feeds,
* ability to backup/restore database or settings,
@ -182,9 +179,9 @@ MariaDB (MySQL) backend is there for users, who want to store their data in a ce
For database-related configuration see `Settings -> Data storage` dialog.
## Google Reader API
Starting with RSS Guard 3.9.0, there is a new plugin which offers synchronization with services using Google Reader API. Plugin was so far tested with FreshRSS, Reedah, The Old Reader and Bazqux. All Google Reader API enabled services should work.
There is a plugin which offers synchronization with services using Google Reader API. Plugin was so far tested with FreshRSS, Reedah, The Old Reader and Bazqux. All Google Reader API enabled services should work.
Note that Inoreader has its own separate plugin, because it uses OAuth as authentication method, therefore it is cleaner to have separate plugin.
Note that Inoreader has its own separate plugin, because it uses OAuth as authentication method.
Google Reader API integration in RSS Guard offers a way to set custom service endpoint even if you select service which is not self-hosted such as Bazqux, providing all users with greater flexibility and freedom.
@ -197,9 +194,9 @@ For example The Old Reader does not seem to offer tags/labels functionality, the
## Websites scraping
> **Only proceed if you consider yourself to be a power user and you know what you are doing!**
RSS Guard 3.9.0+ offers extra advanced features which are inspired by [Liferea](https://lzone.de/liferea/).
RSS Guard offers extra advanced features which are inspired by [Liferea](https://lzone.de/liferea/).
You can select source type of each feed. If you select `URL`, then RSS Guard simply downloads feed file from given location and behave like everyone would expect.
You can select source type of each feed. If you select `URL`, then RSS Guard simply downloads feed file from given location and behaves like everyone would expect.
However, if you choose `Script` option, then you cannot provide URL of your feed and you rely on custom script to generate feed file and provide its contents to **standard output**. Resulting data written to standard output should be valid feed file, for example RSS or ATOM XML file.
@ -211,7 +208,7 @@ Any errors in your script must be written to **error output**.
Note that you must provide full execution line to your custom script, including interpreter binary path and name and all that must be written in special format `<interpreter>#<argument1>#<argument2>#....`. The `#` character is there to separate interpreter and individual arguments. I had to select some character as separator because simply using space ` ` is not that easy as it might sound, because sometimes space could be a part of an argument sometimes argument separator etc.
Used script must return `0` as process exit code if everything went well, or non-zero exit code if some error happened.
Used script must return [`0`](https://www.cplusplus.com/reference/cstdlib/EXIT_SUCCESS) as process exit code if everything went well, or non-zero exit code if some error happened.
Interpreter must be provided in all cases, arguments do not have to be. For example `bash#` is valid execution line, as well as `bash#-c#cat feed.atom`. Note the difference in interpreter's binary name suffix. Also be very carefully about arguments quoting. Some examples of valid and tested execution lines are:
@ -229,7 +226,7 @@ RSS Guard offers [placeholder](#data-placeholder) `%data%` which is automaticall
Also, working directory of process executing the script is set to RSS Guard's user data folder.
There are some examples of website scrapers [here](https://github.com/martinrotter/rssguard/tree/master/resources/scripts/scrapers), most of the are written in Python 3, thus their execution line is `python#script.py`.
There are some examples of website scrapers [here](https://github.com/martinrotter/rssguard/tree/master/resources/scripts/scrapers), most of thme are written in Python 3, thus their execution line is similar to `python#script.py`. Make sure to examine the script for more information on how to use it.
After your source feed data are downloaded either via URL or custom script, you can optionally post-process the data with one more custom script, which will take **raw source data as input** and must produce processed valid feed data to **standard output** while printing all error messages to **error output**.
@ -237,11 +234,7 @@ Format of post-process script execution line is the same as above.
<img src="images/scrape-post.png" width="50%">
Typical post-processing filter might do things like advanced CSS formatting, localization of contents to another language or filtering of feed file entries or removing ads:
| Command | Explanation |
|---------|-------------|
| `bash#-c#xmllint --format -` | Pretty-print input XML feed data. |
Typical post-processing filter might do things like advanced CSS formatting, localization of contents to another language, downloading of full articles, some kind of filtering or removing ads:
It's completely up to you if you decide to only use script as `Source` of the script or separate your custom functionality between `Source` script and `Post-process` script. Sometimes you might need different `Source` scripts for different online sources and the same `Post-process` script and vice versa.
@ -255,11 +248,11 @@ RSS Guard includes Gmail plugin, which allows users to receive and send e-mail m
* Plugin is able to suggest recipient's e-mail. Suggestable addresses are read from e-mail messages which are already stored in RSS Guard's database. Therefore you have to have some e-mails fetched in order to have this feature working.
## Feedly
RSS Guard 3.9.0+ offers [Feedly](https://feedly.com) plugin. Note that there are some specifics when using the plugin.
RSS Guard offers [Feedly](https://feedly.com) plugin. Note that there are some specifics when using the plugin.
Some official builds of RSS Guard might include official Feedly support and will provide almost unlimited API quotas and ability to just login with your username and password.
Official builds (including development builds) of RSS Guard include official Feedly support and provide almost unlimited API quotas and ability to just login with your username and password.
Sadly, some builds of RSS Guard do not have embedded production Feedly API keys and thus no official support from Feedly, therefore you must use something called `developer access token` to be able to use the plugin. See below image and notice the `Get token` button which will lead you to Feedly authentication page where you can generate the token.
Sadly, some builds of RSS Guard do not have embedded production Feedly API keys and thus no official support from Feedly, therefore you must use something called `developer access token` to be able to use the plugin. See the below image and notice the `Get token` button which will lead you to Feedly authentication page where you can generate the token.
<img src="images/feedly-details.png">
@ -287,9 +280,9 @@ RSS Guard allows you to define a set of custom tools which you can subsequently
## AdBlock
[Web-based variant](#web-based-and-lite-app-variants) of RSS Guard offers ad-blocking functionality via [Adblocker](https://github.com/cliqz-oss/adblocker). Adblocker offers similar performance to [uBlock Origin](https://github.com/gorhill/uBlock).
You need to have have [Node.js](https://nodejs.org) installed to have ad-blocking in RSS Guard working. Also, the implementation requires additional [npm](https://www.npmjs.com) modules to be installed, specifically: `@cliqz/adblocker`, `concat-stream`, `psl`, `node-fetch`.
You need to have have [Node.js](https://nodejs.org) with [NPM](https://www.npmjs.com) (which is usually included in Node.js installer) installed to have ad-blocking in RSS Guard working. Also, the implementation requires additional [npm](https://www.npmjs.com) modules to be installed. You see that list of needed modules near the top of [this](https://github.com/martinrotter/rssguard/blob/master/resources/scripts/adblock/adblock-server.js) file.
The way ad-blocking internally works is that RSS Guard starts local HTTP browser which provides API determine which elements of website should (or should not) be blocked. RSS Guard then asks the server about each file to be downloaded.
The way ad-blocking internally works is that RSS Guard starts local HTTP browser which provides ad-blocking API, which is subsequently called by RSS Guard. There is some caching done in between, which speeds up some ad-blocking decisions.
## GUI tweaking
RSS Guard's GUI is very customizable. You can, for example, hide many GUI elements. There are even people who use RSS Guard on mobile devices powered by Linux like PinePhone or Librem devices.

4
resources/docs/Labels.md
View File

@ -1,7 +1,7 @@
# Labels
RSS Guard supports labels/tags. Arbitrary number of tags can be assigned to each and every messages.
RSS Guard supports labels (tags). Arbitrary number of tags can be assigned to each and every messages.
Also, note that tags are synchronizeable for account plugins which support it, currently Inoreader and TT-RSS. While labels are synchronized with these services, they sometimes cannot directly created via RSS Guard and you have to create them via web interface of the respective service and then perform `Sync in` which will download created labels too.
Also, note that tags are synchronizeable for account plugins which support it, currently Inoreader, Google Reader and TT-RSS. While labels are synchronized with these services, they sometimes cannot be directly created via RSS Guard and you have to create them via web interface of the respective service and then perform `Synchronize folders & other items` which will download newly created labels too.
You can easily add labels via `Labels` root item.

28
src/librssguard/network-web/adblock/adblockdialog.cpp
View File

@ -5,6 +5,7 @@
#include "network-web/adblock/adblockmanager.h"
#include "definitions/definitions.h"
#include "exceptions/applicationexception.h"
#include "gui/guiutilities.h"
#include "miscellaneous/application.h"
#include "miscellaneous/iconfactory.h"
@ -24,13 +25,10 @@ AdBlockDialog::AdBlockDialog(QWidget* parent)
qApp->icons()->miscIcon(ADBLOCK_ICON_ACTIVE),
tr("AdBlock configuration"));
QPushButton* btn_options = m_ui.m_buttonBox->addButton(tr("Options"),
QDialogButtonBox::ButtonRole::HelpRole);
auto* menu = new QMenu(btn_options);
menu->addAction(tr("Learn about writing rules..."), this, &AdBlockDialog::learnAboutAdblock);
btn_options->setMenu(menu);
connect(m_ui.m_btnHelp, &QPushButton::clicked, this, [=]() {
qApp->web()->openUrlInExternalBrowser(QSL(ADBLOCK_HOWTO));
});
connect(m_ui.m_btnTest, &QPushButton::clicked, this, &AdBlockDialog::testConfiguration);
connect(m_ui.m_cbEnable, &QCheckBox::toggled, this, &AdBlockDialog::enableAdBlock);
connect(m_ui.m_buttonBox, &QDialogButtonBox::rejected, this, &AdBlockDialog::saveAndClose);
@ -54,8 +52,20 @@ void AdBlockDialog::enableAdBlock(bool enable) {
}
}
void AdBlockDialog::learnAboutAdblock() {
qApp->web()->openUrlInExternalBrowser(QSL(ADBLOCK_HOWTO));
void AdBlockDialog::testConfiguration() {
try {
m_manager->testConfiguration();
m_ui.m_lblTestResult->setStatus(WidgetWithStatus::StatusType::Ok, tr("You are good to go."), tr("OK!"));
}
catch (const ApplicationException& ex) {
qCriticalNN << LOGSEC_ADBLOCK
<< "Test of configuration failed:"
<< QUOTE_W_SPACE_DOT(ex.message());
m_ui.m_lblTestResult->setStatus(WidgetWithStatus::StatusType::Error,
tr("There is error, check application log for more details and "
"head to online documentation."), tr("ERROR!"));
}
}
void AdBlockDialog::load() {

2
src/librssguard/network-web/adblock/adblockdialog.h
View File

@ -18,7 +18,7 @@ class AdBlockDialog : public QDialog {
private slots:
void saveAndClose();
void enableAdBlock(bool enable);
void learnAboutAdblock();
void testConfiguration();
private:
void load();

68
src/librssguard/network-web/adblock/adblockdialog.ui
View File

@ -9,12 +9,12 @@
<rect>
<x>0</x>
<y>0</y>
<width>438</width>
<width>453</width>
<height>424</height>
</rect>
</property>
<layout class="QVBoxLayout" name="verticalLayout">
<item>
<layout class="QFormLayout" name="formLayout">
<item row="0" column="0" colspan="2">
<widget class="QCheckBox" name="m_cbEnable">
<property name="text">
<string>Enable AdBlock</string>
@ -24,10 +24,41 @@
</property>
</widget>
</item>
<item>
<item row="1" column="0" colspan="2">
<layout class="QHBoxLayout" name="horizontalLayout">
<item>
<widget class="QPushButton" name="m_btnHelp">
<property name="text">
<string>&amp;Help</string>
</property>
</widget>
</item>
<item>
<widget class="QPushButton" name="m_btnTest">
<property name="text">
<string>&amp;Test configuration</string>
</property>
</widget>
</item>
<item>
<spacer name="horizontalSpacer">
<property name="orientation">
<enum>Qt::Horizontal</enum>
</property>
<property name="sizeHint" stdset="0">
<size>
<width>40</width>
<height>20</height>
</size>
</property>
</spacer>
</item>
</layout>
</item>
<item row="3" column="0" colspan="2">
<widget class="QTabWidget" name="m_tcSubscriptions">
<property name="currentIndex">
<number>0</number>
<number>1</number>
</property>
<widget class="QWidget" name="m_tabPredefinedLists">
<attribute name="title">
@ -39,6 +70,9 @@
<property name="text">
<string>Add your direct links to filter lists here (one URL per line)</string>
</property>
<property name="buddy">
<cstring>m_txtPredefined</cstring>
</property>
</widget>
</item>
<item>
@ -56,6 +90,9 @@
<property name="text">
<string>Add your custom filters here (one filter per line)</string>
</property>
<property name="buddy">
<cstring>m_txtCustom</cstring>
</property>
</widget>
</item>
<item>
@ -65,7 +102,7 @@
</widget>
</widget>
</item>
<item>
<item row="4" column="0" colspan="2">
<widget class="QDialogButtonBox" name="m_buttonBox">
<property name="orientation">
<enum>Qt::Horizontal</enum>
@ -75,8 +112,27 @@
</property>
</widget>
</item>
<item row="2" column="0" colspan="2">
<widget class="LabelWithStatus" name="m_lblTestResult" native="true"/>
</item>
</layout>
</widget>
<customwidgets>
<customwidget>
<class>LabelWithStatus</class>
<extends>QWidget</extends>
<header>labelwithstatus.h</header>
<container>1</container>
</customwidget>
</customwidgets>
<tabstops>
<tabstop>m_cbEnable</tabstop>
<tabstop>m_btnHelp</tabstop>
<tabstop>m_btnTest</tabstop>
<tabstop>m_tcSubscriptions</tabstop>
<tabstop>m_txtPredefined</tabstop>
<tabstop>m_txtCustom</tabstop>
</tabstops>
<resources/>
<connections/>
</ui>

4
src/librssguard/network-web/adblock/adblockmanager.cpp
View File

@ -105,6 +105,10 @@ bool AdBlockManager::canRunOnScheme(const QString& scheme) const {
return !(scheme == QSL("file") || scheme == QSL("qrc") || scheme == QSL("data") || scheme == QSL("abp"));
}
void AdBlockManager::testConfiguration() {
// Just try to run testing JS program to see if all dependecies are installed.
}
QString AdBlockManager::elementHidingRulesForDomain(const QUrl& url) const {
if (m_serverProcess->state() == QProcess::ProcessState::Running) {
try {

2
src/librssguard/network-web/adblock/adblockmanager.h
View File

@ -37,6 +37,8 @@ class AdBlockManager : public QObject {
bool canRunOnScheme(const QString& scheme) const;
AdBlockIcon* adBlockIcon() const;
void testConfiguration();
// General methods for adblocking.
BlockingResult block(const AdblockRequestInfo& request) const;
QString elementHidingRulesForDomain(const QUrl& url) const;