Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Unified Diff: README.md

Issue 5987679581765632: Issue 1288 - Add basic usage instructions to the README (Closed)
Patch Set: Created Sept. 2, 2014, 7:23 a.m.
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: README.md
===================================================================
--- a/README.md
+++ b/README.md
@@ -44,6 +44,140 @@
`msbuild` command line tool, e.g. run `msbuild /m build\ia32\libadblockplus.sln`
from the Visual Studio Developer Command Prompt to create a 32 bit debug build.
+Usage
+-----
+
+You can use libadblockplus to build an ad blocker. Or, strictly speaking, a web
+content filter. Just like Adblock Plus, it can detect resources that should be
+blocked based on their URL and context information, and generate CSS selectors
+to hide DOM elements.
+
+The basic usage is explained below, see the
+[API documentation](https://adblockplus.org/docs/libadblockplus) for more
+information. See the [filter documentation](https://adblockplus.org/en/filters)
+to learn more about Adblock Plus filters.
+
+### Initialising the engine
+
+All the types and functions in libadblockplus are in the `AdblockPlus`
+namespace. For brevity's sake, we'll assume the following `using` declaration:
+
+ using namespace AdblockPlus;
+
+Most of the functionality of libadblockplus is available via the
+[`FilterEngine`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_filter_engine.html)
+class. Since libadblockplus uses the Adblock Plus core code under the hood, you
+first need to create a
+[`JsEngine`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_js_engine.html)
+instance and pass some information about your
+application to it.
+
+ AppInfo appInfo;
+ appInfo.name = "awesomewebfilter";
+ appInfo.version = "0.1";
+ appInfo.locale = "en-US";
+ JsEngine jsEngine(appInfo);
+
+`JsEngine` needs to store files, make web requests and write log messages. This
+works out of the box because it is using
Wladimir Palant 2014/09/02 13:27:34 "This somewhat works" :) Or just insert "normally
Felix Dahlke 2014/09/02 13:30:01 Done.
+[`DefaultFileSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_default_file_system.html),
+[`DefaultWebRequest`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_default_web_request.html)
+and
+[`DefaultLogSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_default_log_system.html)
+by default.
+
+Depending on your application and platform, you might want to supply your own
+implementations for these - see
+[`FilterEngine::SetFileSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_js_engine.html#a979e9bde78499dab9f5e3aacc5155f40),
+[`FilterEngine::SetWebRequest`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_js_engine.html#a290a03b86137a56d7b2f457f03c77504)
+and
+[`FilterEngine::SetLogSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_js_engine.html#ab60b10be1d4500bce4b17c1e9dbaf4c8)
+respectively.
+
+With the `JsEngine` instance created, you can create a `FilterEngine` instance:
+
+ FilterEngine filterEngine(jsEngine);
+
+When initialised, `FilterEngine` will automatically select a suitable ad
+blocking subscription based on `AppInfo::locale` and download the filters for
+it.
+
+### Managing subscriptions
+
+libadblockplus takes care of storing and updating subscriptions.
+
+You can add more:
+
+ SubscriptionPtr subscription =
+ filterEngine.GetSubscription("https://example.org/filters.txt");
+ subscription->AddToList();
+
+Retrieving an existing subscription works the same way, use
+[`Subscription::IsListed`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_subscription.html#a42da64bdc0cb7ee65a27a001db0307c8)
+to check if the subscription has been added or not.
+
+ SubscriptionPtr subscription =
+ filterEngine.GetSubscription("https://example.org/filters.txt");
+ if (subscription->IsListed())
+ ....
+
+Removing a subscription is not rocket science either:
+
+ subscription->RemoveFromList();
+
+You can also get a list of all subscriptions that were added:
+
+ std::vector<SubscriptionPtr> subscriptions =
+ filterEngine.GetListedSubscriptions();
+
+### Managing custom filters
+
+Working with custom filters is very similar to working with subscriptions:
+
+ FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png");
+ filter->AddToList();
+ filter->RemoveFromList();
+
+Note that applications should only do this to manage a user's custom filters. In
+general, filter lists should be hosted somewhere and added as a subscription.
+
+### Matching blocking filters
+
+As mentioned above, one of the two main tasks of libadblockplus is to check if
+a URL matches any of the active blocking filters.
+
+To demonstrate this, we'll add a custom filter:
+
+ FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png");
+ filter->AddToList();
+
+Now we'll call matches on an URL that should be blocked:
+
+ FilterPtr match =
+ filterEngine.Matches("http://example.com/ad.png", "DOCUMENT", "");
+
+Since we've added a matching filter, `match` will point to the same filter
+object as `filter`.
+
+Note that we've ignored the third parameter of
+[`FilterEngine::Matches`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_filter_engine.html#a184211d324bfb6e23c5e09fae2d12f91)
+here to keep things simple. Real applications should pass the frame structure
+in here - this is necessary because many filters and exception rules are domain
+specific.
+
+### Generating CSS from element hiding filters
+
+Aside from blocking requests, ad blockers typically also hide elements. This is
+done via a second type of filter that is completely ignored when matching URLs:
+[element hiding rules](https://adblockplus.org/en/filters#elemhide).
+
+You can retrieve a list of all CSS selectors for elements that should be hidden
+using
+[`FilterEngine::GetElementHidingSelectors`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_filter_engine.html#a91c44dac13c7655230be49440f45a168).
+
+What libadblockplus clients typically do with this is to generate a CSS style
+sheet that is injected into each page.
+
Shell
-----
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld