DOCUMENTATION UPDATE

izelnakri · Sep 15, 2016 · b9d3ab4 · b9d3ab4
1 parent 1feba56
commit b9d3ab4
Show file tree

Hide file tree

Showing 9 changed files with 115 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -2,13 +2,98 @@
 
 PaperTrail lets you record every change in your database in a seperate database table called ```versions```. Library generates a new version record with associated data every time you run ```PaperTrail.insert/1```, ```PaperTrail.update/1``` or ```PaperTrail.destroy/1``` functions. Simply these functions wrap your Repo insert, update or destroy actions in a database transaction, so if your database action fails you won't get a new version.
 
-```elixir
+## Example
 
+```elixir
+  changeset = Post.changeset(%Post{}, %{
+    title: "Word on the street is Elixir got its own database versioning library",
+    content: "You should try it now!"
+  })
+
+  PaperTrail.insert(changeset)
+  # => on success:
+  # {:ok,
+  #  %{model: %Post{__meta__: #Ecto.Schema.Metadata<:loaded, "posts">,
+  #     title: "Word on the street is Elixir got its own database versioning library",
+  #     content: "You should try it now!", id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #     updated_at: #Ecto.DateTime<2016-09-15 21:42:38>},
+  #    version: %PaperTrail.Version{__meta__: #Ecto.Schema.Metadata<:loaded, "versions">,
+  #     event: "create", id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #     item_changes: %{title: "Word on the street is Elixir got its own database versioning library",
+  #       content: "You should try it now!", id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #       updated_at: #Ecto.DateTime<2016-09-15 21:42:38>},
+  #     item_id: 1, item_type: "Post", meta: nil}}}
+
+  # => on error:
+  # {:error, :model,
+  #  Ecto.Changeset<action: :insert,
+  #  changes: %{title: "Word on the street is Elixir got its own database versioning library", content: "You should try it now!"},
+  #  errors: [content: {"is too short", []}], data: #Post<>,
+  #  valid?: false>, %{}}
+
+  post = Repo.get!(Post, 1)
+  edit_changeset = Post.changeset(post, %{
+    title: "Elixir matures fast",
+    content: "Future is already here, you deserve to be awesome!"
+  })
+
+  PaperTrail.update(edit_changeset)
+  # => on success:
+  # {:ok,
+  #  %{model: %Post{__meta__: #Ecto.Schema.Metadata<:loaded, "posts">,
+  #     title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!",
+  #     id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #     updated_at: #Ecto.DateTime<2016-09-15 22:00:59>},
+  #    version: %PaperTrail.Version{__meta__: #Ecto.Schema.Metadata<:loaded, "versions">,
+  #     event: "update", id: 2, inserted_at: #Ecto.DateTime<2016-09-15 22:00:59>,
+  #     item_changes: %{title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!"},
+  #     item_id: 1, item_type: "Post",
+  #     meta: nil}}}
+
+  # => on error:
+  # {:error, :model,
+  #  Ecto.Changeset<action: :update,
+  #  changes: %{title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!"},
+  #  errors: [title: {"is too short", []}], data: #Post<>,
+  #  valid?: false>, %{}}
+
+  PaperTrail.get_version(post)
+  #  %PaperTrail.Version{__meta__: #Ecto.Schema.Metadata<:loaded, "versions">,
+  #   event: "update", id: 2, inserted_at: #Ecto.DateTime<2016-09-15 22:00:59>,
+  #   item_changes: %{title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!"},
+  #   item_id: 1, item_type: "Post", meta: nil}}}
+
+  updated_post = Repo.get!(Post, 1)
+
+  PaperTrail.delete(updated_post)
+  # => on success:
+  # {:ok,
+  #  %{model: %Testo.Post{__meta__: #Ecto.Schema.Metadata<:deleted, "posts">,
+  #     title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!",
+  #     id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #     updated_at: #Ecto.DateTime<2016-09-15 22:00:59>},
+  #    version: %PaperTrail.Version{__meta__: #Ecto.Schema.Metadata<:loaded, "versions">,
+  #     event: "destroy", id: 3, inserted_at: #Ecto.DateTime<2016-09-15 22:22:12>,
+  #     item_changes: %{title: "Elixir matures fast", content: "Future is already here, you deserve to be awesome!",
+  #       id: 1, inserted_at: #Ecto.DateTime<2016-09-15 21:42:38>,
+  #       updated_at: #Ecto.DateTime<2016-09-15 22:00:59>},
+  #     item_id: 1, item_type: "Post", meta: nil}}}
+
+  Repo.aggregate(Post, :count, :id) # => 0
+  Repo.aggregate(PaperTrail.Version, :count, :id) # => 3
+
+  last(PaperTrail.Version, :id) |> Repo.one
+  #  %PaperTrail.Version{__meta__: #Ecto.Schema.Metadata<:loaded, "versions">,
+  #   event: "destroy", id: 3, inserted_at: #Ecto.DateTime<2016-09-15 22:22:12>,
+  #   item_changes: %{"title" => "Elixir matures fast", content: "Future is already here, you deserve to be awesome!", "id" => 1,
+  #     "inserted_at" => "2016-09-15T21:42:38",
+  #     "updated_at" => "2016-09-15T22:00:59"},
+  #   item_id: 1, item_type: "Post", meta: nil}
 ```
 
 PaperTrail is inspired by the ruby gem ```paper_trail```. However, unlike the ```paper_trail``` gem this library actually results in less data duplication, faster and more explicit programming model to version your record changes.
 
-The library source code is minimal and tested. It is highly suggested that you check it out, there is nothing magical really.
+The library source code is minimal and tested. It is highly suggested that you check it out, it isn't rocket science.
 
 ## Installation
 
@@ -32,24 +117,28 @@ The library source code is minimal and tested. It is highly suggested that you c
 
 Your application is now ready to collect some history!
 
+## How to use paper_trail with phoenix?
+
+A guide needs to be written for this. Although it isn't that hard to implement for the brave.
+One caveat: your application Repo has to be ```Repo``` instead of ```YourApplicationName.Repo```
 
 TODO AREA:
 
+** remove wrong Elixir compiler errors
+
 ** explain the columns
 
 ## Storing version meta data
 
 give originator example
 
-
 Your versions don't need a model lifecycle callbacks like before_create or before_update for any extra meta data, all your meta data could be stored in one object and that object could be passed as the second optional parameter to PaperTrail.create
 
 ## Suggestions
 
-order matter,
+PaperTrail.Version(s) order matter,
 don't delete your versions merge them
 
-
 ## Examples
 
 PaperTrail.create/1, PaperTrail.update/1, PaperTrail.destroy/1

diff --git a/doc/404.html b/doc/404.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>404 – paper_trail v0.1.4</title>
+    <title>404 – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/404.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 

diff --git a/doc/Mix.Tasks.Papertrail.Install.html b/doc/Mix.Tasks.Papertrail.Install.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>Mix.Tasks.Papertrail.Install – paper_trail v0.1.4</title>
+    <title>Mix.Tasks.Papertrail.Install – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/Mix.Tasks.Papertrail.Install.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -60,7 +60,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">paper_trail v0.1.4</small>
+        <small class="visible-xs">paper_trail v0.1.5</small>
         Mix.Tasks.Papertrail.Install
 
 

diff --git a/doc/PaperTrail.Migration.html b/doc/PaperTrail.Migration.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>PaperTrail.Migration – paper_trail v0.1.4</title>
+    <title>PaperTrail.Migration – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/PaperTrail.Migration.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -60,7 +60,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">paper_trail v0.1.4</small>
+        <small class="visible-xs">paper_trail v0.1.5</small>
         PaperTrail.Migration
 
 

diff --git a/doc/PaperTrail.Version.html b/doc/PaperTrail.Version.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>PaperTrail.Version – paper_trail v0.1.4</title>
+    <title>PaperTrail.Version – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/PaperTrail.Version.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -60,7 +60,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">paper_trail v0.1.4</small>
+        <small class="visible-xs">paper_trail v0.1.5</small>
         PaperTrail.Version
 
 

diff --git a/doc/PaperTrail.VersionQueries.html b/doc/PaperTrail.VersionQueries.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>PaperTrail.VersionQueries – paper_trail v0.1.4</title>
+    <title>PaperTrail.VersionQueries – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/PaperTrail.VersionQueries.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -60,7 +60,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">paper_trail v0.1.4</small>
+        <small class="visible-xs">paper_trail v0.1.5</small>
         PaperTrail.VersionQueries
 
 

diff --git a/doc/PaperTrail.html b/doc/PaperTrail.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>PaperTrail – paper_trail v0.1.4</title>
+    <title>PaperTrail – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/PaperTrail.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -60,7 +60,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">paper_trail v0.1.4</small>
+        <small class="visible-xs">paper_trail v0.1.5</small>
         PaperTrail
 
 

diff --git a/doc/api-reference.html b/doc/api-reference.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.12.0">
-    <title>API Reference – paper_trail v0.1.4</title>
+    <title>API Reference – paper_trail v0.1.5</title>
     <link rel="stylesheet" href="dist/app-88251e7c81.css" />
 
       <link rel="canonical" href="https://hexdocs.pm/paper_trail/api-reference.html" />
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         paper_trail
       </h1>
       <h2 class="sidebar-projectVersion">
-        v0.1.4
+        v0.1.5
       </h2>
     </div>
 
@@ -59,7 +59,7 @@ <h2 class="sidebar-projectVersion">
     <div id="content" class="content-inner">
 
   <h1>
-    <small class="visible-xs">paper_trail v0.1.4</small>
+    <small class="visible-xs">paper_trail v0.1.5</small>
     API Reference
   </h1>
 

diff --git a/doc/index.html b/doc/index.html
@@ -2,7 +2,7 @@
 <html>
   <head>
     <meta charset="utf-8">
-    <title>paper_trail v0.1.4 – Documentation</title>
+    <title>paper_trail v0.1.5 – Documentation</title>
     <meta http-equiv="refresh" content="0; url=api-reference.html">
     <meta name="robots" content="noindex">
     <meta name="generator" content="ExDoc v0.12.0">