More documentation.

bndwgn · Dec 18, 2020 · 9519d70 · 9519d70
1 parent a748116
commit 9519d70
Show file tree

Hide file tree

Showing 14 changed files with 14,941 additions and 33 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ node_modules
 phpunit.xml
 psalm.xml
 vendor
+dist
diff --git a/composer.json b/composer.json
@@ -24,6 +24,7 @@
         "vimeo/psalm": "^3.11"
     },
     "autoload": {
+        "exclude-from-classmap": ["/docs/", "/tests/"],
         "psr-4": {
             "Bndwgn\\Bandwagon\\": "src",
             "Bndwgn\\Bandwagon\\Database\\Factories\\": "database/factories"

diff --git a/config/bandwagon.php b/config/bandwagon.php
@@ -39,7 +39,7 @@
     | Cleanup
     |--------------------------------------------------------------------------
     |
-    | These keys are for use with cleaning up old Bandwagon Events. They are
+    | These keys are for use with cleaning up old Bandwagon Events. Events are
     | stored in the database and will continue to grow with time, depending on
     | your needs you may want to clear ones that will not be part of a query. 
     | Any events that are older than the `oldest` config setting will never be 
@@ -51,6 +51,14 @@
         'olderthan' => env('BANDWAGON_CLEANUP_OLDER_THAN', 86400),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Routes
+    |--------------------------------------------------------------------------
+    |
+    | These two values are for the api endpoint that exposes bandwagon
+    | events to the client.
+    */
     'domain' => env('BANDWAGON_DOMAIN', null),
     'path' => env('TELESCOPE_PATH', 'bandwagon'),
 ];
diff --git a/docs/deploy.sh b/docs/deploy.sh
@@ -0,0 +1,24 @@
+
+# abort on errors
+set -e
+
+# build
+npm run build
+
+# navigate into the build output directory
+cd src/.vuepress/dist
+
+# if you are deploying to a custom domain
+echo 'www.laravelbandwagon.com' > CNAME
+
+git init
+git add -A
+git commit -m 'deploy'
+
+# if you are deploying to https://<USERNAME>.github.io
+# git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master
+
+# if you are deploying to https://<USERNAME>.github.io/<REPO>
+git push -f [email protected]:bndwgn/laravel-bandwagon.git master:gh-pages
+
+cd -
diff --git a/docs/src/.vuepress/config.js b/docs/src/.vuepress/config.js
@@ -12,7 +12,7 @@ module.exports = {
   /**
    * Ref: https://vuepress.vuejs.org/guide/deploy.html#github-pages
    */
-  base: 'laravel-bandwagon',
+  base: '/laravel-bandwagon',
 
   /**
    * Extra tags to be injected to the page HTML `<head>`
@@ -42,12 +42,12 @@ module.exports = {
         link: '/guide/',
       },
       {
-        text: 'Config',
-        link: '/config/'
+        text: 'Author',
+        link: 'https://github.com/chasenyc'
       },
       {
-        text: 'VuePress',
-        link: 'https://v1.vuepress.vuejs.org'
+        text: 'Source',
+        link: 'https://github.com/bndwgn/laravel-bandwagon'
       }
     ],
     sidebar: {
@@ -58,6 +58,9 @@ module.exports = {
           children: [
             '',
             'getting-started',
+            'configuration',
+            'cleaning-up',
+            'firing-events'
           ]
         }
       ],

diff --git a/docs/src/.vuepress/dist b/docs/src/.vuepress/dist
diff --git a/docs/src/guide/cleaning-up.md b/docs/src/guide/cleaning-up.md
@@ -0,0 +1,21 @@
+# Cleaning up old events
+
+Every time an event is created using the the `Bandwagon::createEvent()` command a record is stored in the database in a table called `bandwagon_events`. Depending on how many events are being fired you will most likely want to cleanup this table from time to time. Additionally the `bandwagon.php` config key `oldest` dictates the oldest event to display to users, thus rendering any events older than `oldest` useless for this packages purposes.
+
+## Console command
+
+Out of the box you are provided with the following console command:
+```sh
+php artisan bandwagon:cleanup
+```
+This command will remove all events older than what is specified in the `bandwagon.php` config. You can see the specific key here:
+```php
+// config/bandwagon.php
+
+'cleanup' => [
+    'enabled' => env('BANDWAGON_CLEANUP_ENABLED', true),
+    'olderthan' => env('BANDWAGON_CLEANUP_OLDER_THAN', 86400),
+],
+```
+This will find any events older than `time() - config('bandwagon.cleanup.olderthan')`
+and delete them from the database to keep a maintainable size to this table. Feel free to adjust it as you would like but keep in mind it is best practice to make this value equal to or higher than the `oldest` key found in `bandwagon.php`.
diff --git a/docs/src/guide/configuration.md b/docs/src/guide/configuration.md
@@ -0,0 +1,42 @@
+# Configuration
+
+## Key values
+
+There are a few simple configurations you can change through `config/bandwagon.php` that will all impact what and how messages are displayed to the end user:
+
+```php 
+'poll' => env('BANDWAGON_POLL', 30)`
+``` 
+
+`poll` refers to how often (in seconds) the package will poll for new messages.
+
+```php
+'display' => env('BANDWAGON_DISPLAY', 8000)
+``` 
+`display` refers to how long (in seconds) the message will stay on the user's screen.
+
+```php
+'oldest' => env('BANDWAGON_OLDEST', 86400)
+``` 
+`oldest` refers to how old of an event to display to the user. This value is in seconds and defaults to 1 day. What that means is when a user goes to a page where we are displaying bandwagon events, when they first come to the page there will be a poll to get the most recent event that has occured in under one day, if one is found it will be displayed.
+
+## Cleanup
+
+For cleaning up old events there are a few keys that are used:
+```php
+'cleanup' => [
+    'enabled' => env('BANDWAGON_CLEANUP_ENABLED', true),
+    'olderthan' => env('BANDWAGON_CLEANUP_OLDER_THAN', 86400),
+],
+```
+These keys are for use with cleaning up old Bandwagon Events. Events are stored in the database and will continue to grow with time, depending on your needs you may want to clear ones that will not be part of a query.  Any events that are older than the `oldest` config setting will never be used or displayed to a user. It is recommended that you keep your 
+`olderthan` config the same or larger than the `oldest` key.
+
+## Routes
+
+These two values are for the api endpoint that exposes bandwagon events to the client.
+```php
+'domain' => env('BANDWAGON_DOMAIN', null),
+'path' => env('TELESCOPE_PATH', 'bandwagon'),
+```
+`path` refers to the path prefix for the endpoint. `domain` refers to domain value passed to `Route::group`.
diff --git a/docs/src/guide/firing-events.md b/docs/src/guide/firing-events.md
@@ -0,0 +1,73 @@
+# Firing events
+
+## Publishing a new event
+
+To use the example of sharing a purchase with people who are on the purchase page of your application you would just add the following:
+```php
+Bandwagon::createEvent(
+    "Someone in ${$user->state}",
+    "Purchased ${$product->displayName}",
+    $request->ip()
+); 
+```
+There are three parameters that are taken in by the `Bandwagon::createEvent(String $title, String $subtitle, String $ip)` function:
+
+| Property | Required | Description |
+| -----------| ------ | ----------- |
+| title | true | This is the text that appears on the first line of the message displayed to users. By default this text is slightly more prominent due to css making the font-weight slightly higher and the color slightly darker |
+| subtitle | true | This is the second line of text in the message displayed to users, it is more subtle than the first line by default |
+| ip | false | This is the ip address of the user who's action caused this event.
+
+### Title
+The title will be the first line of text in the notification that users will see. By default the first line is darker and a heavier font-weight than the subtitle. This can be customized through altering the css classes passed to the component. A good example of a title line might be "Someone in New York, NY". This is the social proof aspect that is being emphasized, another human being purchased, viewing or used your product.
+
+### Subtitle
+The subtitle is slightly less prominent and can also be altered through css, this field is required, if for any reason you would like to not include a second line you can always just pass an empty string. This line is suggested to be the action used by the consumer such as "purchased the annual plan" but can obviously be used in whatever way is desired. 
+
+### IP Address
+This field is not required, the purpose of this field is to allow for messages initiated by a user to be filtered out from display to that same user. For example, if there are three users, A, B and C, all three users are on the purchase page of a website, if user B were to make a purchase we would want to display that "Someone in New York, NY made a purchase 1 second ago" to user's A and C but we would not want to display this to user B, who made the purchase. If you would like for user B to see this message as well, you can omit the last parameter from `Bandwagon::createEvent()`.
+
+## Laravel Event
+The `Bandwagon::createEvent()` is a very simple wrapper that behind the scenes just fires a new Laravel Event.
+
+### `Bndwgn\Bandwagon\Events\BandwagonEventCreated`
+The `BandwagonEventCreated` event has three public properties on it: 
+```php
+/**
+ * The title for the message displayed to users 
+ */
+public $title
+
+/**
+ * The subtitle for the message displayed to users 
+ */
+public $subtitle
+
+/**
+ * The ip address of the user who generated the event,
+ * this is nullable and should only be used if you want
+ * to filter this event from being seen by the initiator
+ * of this event. 
+ */
+public $ip
+```
+
+## Database
+
+These events will then be stored in the database to a table named `bandwagon_events`. These events are stored by an event listener(`Bndwgn\Bandwagon\Listeners\RecordBandwagonEvent`). The databse schema is as follows:
+
+```php
+Schema::create('bandwagon_events', function (Blueprint $table) {
+    $table->bigIncrements('id');
+    $table->string('title');
+    $table->string('subtitle');
+    $table->string('ip', 50);
+    $table->integer('event_at')->unsigned();
+    $table->timestamps();
+
+    $table->index('ip');
+    $table->index('event_at');
+});
+```
+
+This table has a corresponding model that is used under the hood `Bndwgn\Bandwagon\Models\BandwagonEvent`.
diff --git a/docs/src/guide/getting-started.md b/docs/src/guide/getting-started.md
@@ -15,27 +15,6 @@ To publish the config file to `config/bandwagon.php` run:
 php artisan vendor:publish --provider="Bndwgn\Bandwagon\BandwagonServiceProvider"
 ```
 
-## Configuring the package
-
-There are a few simple configurations you can change through `config/bandwagon.php`:
-
-```php 
-'poll' => env('BANDWAGON_POLL', 30)`
-``` 
-
-`poll` refers to how often (in seconds) the package will poll for new messages 
-
-```php
-'display' => env('BANDWAGON_DISPLAY', 8000)
-``` 
-`display` refers to how long (in seconds) the message will display on the user's screen
-
-```php
-'oldest' => env('BANDWAGON_OLDEST', 8000)
-``` 
-`oldest` refers to how old of an event to display to the user
-
-
 ## Rendering the component
 
 To render the component just add the component to any or all desired pages like so:

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -5,8 +5,8 @@ tagline: Social proof package for Laravel
 actionText: Quick Start →
 actionLink: /guide/
 features:
-- title: Feature 1 Title
-  details: Feature 1 Description
+- title: Plug and Play
+  details: Minimal
 - title: Feature 2 Title
   details: Feature 2 Description
 - title: Feature 3 Title

diff --git a/public/app.js b/public/app.js
diff --git a/src/Events/BandwagonEventCreated.php b/src/Events/BandwagonEventCreated.php
@@ -10,8 +10,22 @@ class BandwagonEventCreated
     use Dispatchable;
     use SerializesModels;
 
+    /**
+     * The title for the message displayed to users 
+     */
     public $title;
+
+    /**
+     * The subtitle for the message displayed to users 
+     */
     public $subtitle;
+
+    /**
+     * The ip address of the user who generated the event,
+     * this is nullable and should only be used if you want
+     * to filter this event from being seen by the initiator
+     * of this event. 
+     */
     public $ip;
 
     /**
@@ -24,7 +38,6 @@ class BandwagonEventCreated
      */
     public function __construct(String $title, String $subtitle, String $ip = '')
     {
-        error_log('event_fired');
         $this->title = $title;
         $this->subtitle = $subtitle;
         $this->ip = $ip;

diff --git a/src/Listeners/RecordBandwagonEvent.php b/src/Listeners/RecordBandwagonEvent.php
@@ -9,7 +9,6 @@ class RecordBandwagonEvent
 {
     public function handle(BandwagonEventCreated $event)
     {
-        error_log('event_heeard');
         BandwagonEvent::create([
             'title' => $event->title,
             'subtitle' => $event->subtitle,
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,3 +9,4 @@ node_modules @@
     phpunit.xml
     psalm.xml
     vendor
+    dist