update documentation and website

2013-10-17 15:34:05 +02:00
parent 4222e873c7
commit d9c4b4c51f
4 changed files with 109 additions and 336 deletions
@@ -1,21 +1,15 @@
 ; This file is for unifying the coding style for different editors and IDEs
 ; editorconfig.org
 ; defaults by Tobias Klika
 ; 2013
 root = true
 ; default settings for all files
 [*]
-end_of_line = crlf ; this is git standard, so it won't convert it anymore
+end_of_line = crlf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = space
 indent_size = 2
 [*.md]
 trim_trailing_whitespace = false
@@ -0,0 +1,64 @@
 ### 2.0.0 (2013-10-17)
 - Add Reader API _(does not use the official Article View API, which is private. The PocketReader is based on a custom PCL port of NReadability and SgmlReader)_
 ### 1.5.1 (2013-09-30) 
 - `RetrieveFilter.All` didn't work
 - improve search speed
 ### 1.5.0 (2013-09-28) 
 - add statistics API
 - add registration API
 ### 1.4.0 (2013-09-21) 
 - rename `Retrieve` to `Get`
 - update IntelliSense documentation
 - add `GetTags` method
 ### 1.3.0 (2013-09-19) 
 - get Item by ID 
 - tag modification bugfixes
 ### 1.2.1 (2013-09-18) 
 - correct parameter conversion for DateTime and Boolean
 ### 1.2.0 (2013-09-17) 
 - simplified retrieve methods
 ### 1.1.0 (2013-09-17) 
 - fix modification requests
 ### 1.0.0 (2013-09-15) 
 - convert to PCL 
 - implement async
 ### 0.3.2 (2013-08-16) 
 - tag modification fixed
 - full retrieval of items for Retrieve method
 ### 0.3.1 (2013-07-07) 
 - authentication fixes
 ### 0.3.0 (2013-07-02) 
 - update authentication process 
 ### 0.2.0 (2013-06-27) 
 - add, modify item
 - modify tags
 ### 0.1.0 (2013-06-26) 
 - authentication 
 - retrieve functionality
@@ -33,7 +33,7 @@
      <p class="app-description">
        PocketSharp is a C#.NET class library, that integrates the Pocket API v3
        <br><br>
-        Current version: <b>1.5.1</b><br>
+        Current version: <b>2.0.0</b><br>
        <a href="https://www.nuget.org/packages/PocketSharp/">@ nuget</a>
      </p>
      <div class="app-nuget">
@@ -48,10 +48,11 @@
    <div class="app-main">
      <nav class="app-nav">
        <a href="#" data-id="gettingstarted" class="is-active">Getting Started</a>
        <a href="#" data-id="account">Account</a>
        <a href="#" data-id="get">Get</a>
        <a href="#" data-id="add">Add</a>
        <a href="#" data-id="reader">Reader</a>
        <a href="#" data-id="modify">Modify</a>
        <a href="#" data-id="account">Account</a>
      </nav>
      <article class="article">
@@ -125,6 +126,7 @@ using PocketSharp.Models;</code></pre>
          <h2>Release History</h2>
        <ul>
          <li><b>2.0.0</b> (2013-10-17) Add Reader API</li>
          <li><b>1.5.1</b> (2013-09-30) <code>RetrieveFilter.All</code> didn't work; improve search speed</li>
          <li><b>1.5.0</b> (2013-09-28) add statistics and registration API</li>
          <li><b>1.4.0</b> (2013-09-21) rename <code>Retrieve</code> to <code>Get</code> + update IntelliSense documentation + add <code>GetTags</code> method</li>
@@ -314,6 +316,43 @@ Accepts four parameters, with <code>uri</code> being required.
     </div>
     <div data-part="reader">
      <h2>Article Reader API</h2>
      <p>PocketSharp 2.0 implements a new <strong>Reader API</strong>.</p>
 <p>This API does _not _use the official (and private) Article View API by Pocket. It is based on a custom PCL port of NReadability and SgmlReader, which are included in the solution.</p>
 <h3>What's it all about?</h3>
 <p>The Reader API extracts the main content of a website and returns the extracted content as HTML and it's associated title (which should already be available in the <code>PocketItem</code>).</p>
 <p>This content can be encapsulated in a <code>&lt;body&gt;</code>-Tag and displayed as a readable website with a custom CSS (it's up to you!).</p>
 <h3>Implementation</h3>
 <p>As with all PocketSharp implementations you have to require the main namespace and it's model namespace:</p>
 <p><pre class="language-clike"><code>
 using PocketSharp;
 using PocketSharp.Models;</code></pre></p>
 <p>The <code>PocketReader</code> is a seperated class with it's own <code>HttpClient</code>. Create an instance of it:</p>
 <p><pre class="language-clike"><code>
 PocketReader reader = new PocketReader();</code></pre></p>
 <p><code>PocketReader</code> needs a <code>PocketItem</code> as a parameter to correctly identify its <code>ID</code> and <code>Uri</code>. With this requirement you can successfully query for an articles content.<br>
 Don't forget exception handling in case a website is down or not accessible.</p>
 <p><pre class="language-clike"><code>
 PocketArticle article;
 try
 {
  article = await reader.Read(myPocketItem);
  // PocketArticle: {
  //   int PocketItemID
  //   string Content
  //   string Title
  //   string NextPageUrl
  // }
 }
 catch (PocketException exc)
 {
  // handle exception
 }
 </code></pre></p>
    </di>
      </article>
    </div>
@@ -13,14 +13,9 @@
 Install-Package PocketSharp
 ```
-## Components
+## Documentation
- [Get](#get) - Retrieve and search for items
+See [wiki](https://github.com/ceee/PocketSharp/wiki) or [website]((http://pocketsharp.frontendplay.com/)).
 - [Modify](#modify) - Modify items and its tags
 - [Add](#add) - Add new items
 - [Authentication](#account-authentication) - Authenticate users
 - [Registration](#account-registration) - Register new users
 - [Statistics](#statistics) - Retrieve account statistics
 ## Supported platforms
@@ -33,327 +28,8 @@ PocketSharp is a **Portable Class Library** (since 1.0.0), therefore it's compat
 You can find examples for Silverlight 5, WP8 and WPF in the `PocketSharp.Examples` ([@github](https://github.com/ceee/PocketSharp/tree/master/PocketSharp.Examples)) folder.
 ## Async Support
 All public methods, which communicate with the Pocket servers are asynchronous. So they should be called with the preceding `await` keyword, and the encapsulated method marked with `async`.
 _In PocketSharp versions < 1.0.0 all methods lacked async support and were blocking._
 ## What's next
 Next is Reading API support (with NReadability implementation). Release: Mid October.
 ## Usage Example
 Request a [Consumer Key on Pocket.](http://getpocket.com/developer/apps/)
 Include the PocketSharp namespace and it's associated models (you will need them later):
 ```csharp
 using PocketSharp;
 using PocketSharp.Models;
 ```
 Initialize PocketClient with:
 ```csharp
 PocketClient _client = new PocketClient("[YOUR_CONSUMER_KEY]", "[YOUR_ACCESS_CODE]");
 ```
 Do a simple request - e.g. a search for `CSS`:
 ```csharp
 var items = await _client.Search("css");
 items.ForEach(
 	item => Debug.WriteLine(item.ID + " | " + item.Title)
 );
 ```
 Which will output:
    330361896 | CSS Front-end Frameworks with comparison : By usabli.ca
    345541438 | Editr - HTML, CSS, JavaScript playground
    251743431 | CSS Architecture
    343693149 | CSS3 Transitions - Thank God We Have A Specification!
 	...
 ## Create an instance
 Constructor:
 ```csharp
 PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)
 ```
 `consumerKey`: The API key
 <br>
 `accessCode`: Provide an access code if the user is already authenticated
 <br>
 `callbackUri`: The callback URL is called by Pocket after authentication
 Example:
 ```csharp
 PocketClient _client = new PocketClient(
 	consumerKey: "123498237423498723498723",
 	callbackUri: new Uri("http://ceecore.com"),
 	accessCode: "097809-oi987-izi8-jk98-oiuu89"
 );
 ```
 You can change the _Access Code_ after initialization:
 ```csharp
 _client.AccessCode = "[YOU_ACCESS_CODE]";
 ```
 **Before authentication** you will need to provide the `callbackUri` for authentication requests.
 <br>
 **After authentication** you will need to provide the `accessCode`.
 ## Account Authentication
 In order to communicate with a Pocket User, you will need a consumer key (which is generated by [creating a new application on Pocket](http://getpocket.com/developer/apps/)) and an **Access Code**.
 The authentication is a 3-step process:
 #### 1) Generate authentication URI
 Receive the **request code** and **authentication URI** from the library by calling `string GetRequestCode()`:
 ```csharp
 string requestCode = await _client.GetRequestCode();
 // 0f453f2d-1605-8584-28fd-39af8e
 Uri authenticationUri = _client.GenerateAuthenticationUri();
 // https://getpocket.com/auth/authorize?request_token=0f453f2d-1605-8584-28fd-39af8e&redirect_uri=http%253a%252f%252fceecore.com
 ```
 The _request code_ is stored internally, but you can also provide it as param in `GenerateAuthenticationUri(string requestCode = null)`.
 #### 2) Redirect to Pocket
 Next you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application (see image). After the user granted or denied, he/she is redirected to the `callbackUri`.
 ![authentication screen](https://raw.github.com/ceee/PocketSharp/master/PocketSharp/authentication-screen.png)
 #### 3) Get Access Code
 Call `Task<string> GetAccessCode(string requestCode = null)`
 ```csharp
 string accessCode = await _client.GetAccessCode();
 // fa8bfc16-69b3-4d22-7db7-84a58d
 ```
 Again, the received _access code_ is stored internally.
 Note that `GetAccessCode` can only be called with an existing _request code_. If you need to re-authenticate a user, start again with Step 1).
 #### Important
 **Be sure to permanently store the _Access Code_ for your user.**
 <br>
 Without it you would always have to redo the authentication process.
 ## Account Registration
 The `RegisterAccount` method exists in Pocket API v3, but is currently undocumented.
 <br>The user cannot authenticate directly after registration, as the account has to be activated via an opt-in link, which is sent to the e-mail address.
 ```csharp
 bool isSuccess = await _client.RegisterAccount("myUsername", "me@mymail.com", "mypassword");
 ```
 After registration you have to remind the user to check his/her mail account.
 ## Get
 Get list of all items:
 ```csharp
 List<PocketItem> items = await _client.Get();
 // equivalent to: await _client.Get(RetrieveFilter.All)
 ```
 Get a list with specific parameters (explanation in the [Pocket Docs](http://getpocket.com/developer/docs/v3/retrieve)):
 ```csharp
 List<PocketItem> items = await _client.Get(
  State? state = null,
  bool? favorite = null,
  string tag = null,
  ContentType? contentType = null,
  Sort? sort = null,
  string search = null,
  string domain = null,
  DateTime? since = null,
  int? count = null,
  int? offset = null 
 );
 ```
 It's best to use parameters as _named parameters_, to avoid typing `null` values:
 ```csharp
 List<PocketItem> items = await _client.Get(count: 10, offset: 20, sort: Sort.oldest);
 ```
 Get item by ID:
 ```csharp
 PocketItem item = await _client.Get(1298198);
 ```
 Find items by a tag:
 ```csharp
 List<PocketItem> items = await _client.SearchByTag("tutorial");
 ```
 Find items by a search string.
 <br>PocketSharp uses an internal search, which is significantly faster than the Search API by Pocket.
 ```csharp
 List<PocketItem> items = await _client.Search("css");
 ```
 Find items by a search string by already available items:
 ```csharp
 List<PocketItem> items = await _client.Search(myPocketItemList, "css");
 ```
 Get all tags:
 ```csharp
 List<PocketTag> items = await _client.GetTags();
 ```
 Get a filtered list:
 ```csharp
 List<PocketItem> items = await _client.Get(RetrieveFilter.Favorite);
 // returns favorites only
 ```
 The RetrieveFilter Enum is specified as follows:
 ```csharp
 enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }
 ```
 ## Add
 Adds a new item to your pocket list.
 Accepts four parameters, with `uri` being required.
 ```csharp
 Task<PocketItem> Add(Uri uri, string[] tags = null, string title = null, string tweetID = null)
 ```
 Example:
 ```csharp
 PocketItem newItem = await _client.Add(
 	new Uri("http://www.neowin.net/news/full-build-2013-conference-sessions-listing-revealed"),
 	new string[] { "microsoft", "neowin", "build" }
 );
 ```
 The title can be included for cases where an item does not have a title, which is typical for image or PDF URLs. If Pocket detects a title from the content of the page, this parameter will be ignored.
 If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id (with the tweetID). This allows Pocket to show the original tweet alongside the article.
 ## Modify
 All Modify methods accept either the itemID (as int) or a `PocketItem` as parameter.
 Archive the specified item:
 ```csharp
 bool isSuccess = await _client.Archive(myPocketItem);
 ```
 Un-archive the specified item:
 ```csharp
 bool isSuccess = await _client.Unarchive(myPocketItem);
 ```
 Favorites the specified item:
 ```csharp
 bool isSuccess = await _client.Favorite(myPocketItem);
 ```
 Un-favorites the specified item:
 ```csharp
 bool isSuccess = await _client.Unfavorite(myPocketItem);
 ```
 Deletes the specified item:
 ```csharp
 bool isSuccess = await _client.Delete(myPocketItem);
 ```
 #### Modify tags
 Add tags to the specified item:
 ```csharp
 bool isSuccess = await _client.AddTags(myPocketItem, new string[] { "css", "2013" });
 ```
 Remove tags from the specified item:
 ```csharp
 bool isSuccess = await _client.RemoveTags(myPocketItem, new string[] { "css", "2013" });
 ```
 Remove all tags from the specified item:
 ```csharp
 bool isSuccess = await _client.RemoveTags(myPocketItem);
 ```
 Replaces all existing tags with new ones for the specified item:
 ```csharp
 bool isSuccess = await _client.ReplaceTags(myPocketItem, new string[] { "css", "2013" });
 ```
 Renames a tag for the specified item:
 ```csharp
 bool isSuccess = await _client.RenameTag(myPocketItem, "oldTagName", "newTagName");
 ```
 ## Statistics
 The Pocket API supports retrieval of a simple statistics object.
 ```csharp
 PocketStatistics statistics = await client.Statistics();
 // PocketStatistics: [CountAll], [CountRead], [CountUnread]
 ```
 ---
 ## Release History
 - **1.5.1** (2013-09-30) `RetrieveFilter.All` didn't work; improve search speed
 - **1.5.0** (2013-09-28) add statistics and registration API
 - **1.4.0** (2013-09-21) rename `Retrieve` to `Get` + update IntelliSense documentation + add `GetTags` method
 - **1.3.0** (2013-09-19) get Item by ID + tag modification bugfixes
 - **1.2.1** (2013-09-18) correct parameter conversion for DateTime and Boolean
 - **1.2.0** (2013-09-17) simplified retrieve methods
 - **1.1.0** (2013-09-17) fix modification requests
 - **1.0.0** (2013-09-15) convert to PCL & implement async
 - **0.3.2** (2013-08-16) tag modification fixed and full retrieval of items for Retrieve method
 - **0.3.1** (2013-07-07) authentication fixes
 - **0.3.0** (2013-07-02) update authentication process 
 - **0.2.0** (2013-06-27) add, modify item & modify tags
 - **0.1.0** (2013-06-26) authentication & retrieve functionality
 ## Dependencies
 - [Microsoft.Bcl.Async](https://www.nuget.org/packages/Microsoft.Bcl.Async/)