Documentation Update

TimeWarpEngineering · May 17, 2019 · 341ef4b · 341ef4b
1 parent 0570df9
commit 341ef4b
Show file tree

Hide file tree

Showing 11 changed files with 193 additions and 80 deletions.
diff --git a/Build/blazor-state.yml b/Build/blazor-state.yml
@@ -9,7 +9,9 @@ trigger:
   - source/BlazorState.Js/*
 
 # no PR builds
-pr: none
+pr:
+- master
+- releases/*
 
 queue:
   name: TimeWarpEnterprises

diff --git a/Documentation/Api/Overview.md b/Documentation/Api/Overview.md
@@ -0,0 +1,3 @@
+# Blazor-State API
+Currently only the public API is included in the DocFx generated documents.  
+Hopefully soon there will be easy way to include all.
diff --git a/Documentation/DevOps/DevOps.md b/Documentation/DevOps/DevOps.md
@@ -3,28 +3,8 @@
 Production Artifacts:
 
 * Blazor-State Nuget Package on Nuget.org
-* TimeWarp Templates Nuget Package on Nuget.org
 * Documentation Site
-* Sample Site
 
 Development Artifacts:
 
-* Blazor-State Nuget Package on Myget.
-* TimeWarp Templates Nuget Package on Myget.org
-
-Changes to tools may want to trigger new versions of outputs but currently they don't.
-
-2019-01-03 15:44:40 Creating a Yaml for each output.
-
-
-```
-- task: DotNetCoreInstaller@0
-  displayName: Use .NET Core SDK 2.1.500 
-  inputs:
-    version: 2.1.500
-```
-
-Do I need DotNetCoreInstaller given the build agent is my machine it has 
-to have the version I am using installed already.
-I am going to remove it
-
+* Blazor-State Nuget Package on Azure DevOps.
diff --git a/Documentation/Overview.md b/Documentation/Overview.md
@@ -1,29 +1,95 @@
-# TimeWarp Enterprises
+# Blazor-State
+[![Build Status](https://timewarpenterprises.visualstudio.com/Blazor-State/_apis/build/status/Blazor-State-CI-Master-Yaml)](https://timewarpenterprises.visualstudio.com/Blazor-State/_build/latest?definitionId=7)
+[![nuget](https://img.shields.io/nuget/v/Blazor-State.svg)](https://www.nuget.org/packages/Blazor-State/)
+[![nuget](https://img.shields.io/nuget/dt/AnyClone.svg)](https://www.nuget.org/packages/Blazor-State/)
 
-## Nuget Packages
+Blazor-State is a State Management architecture utilizing the MediatR pipeline.
 
-* Blazor-State
-* TimeWarp Blazor Template
-* TimeWarp Console Template
+If you are familiar with
+[MediatR](https://github.com/jbogard/MediatR),
+ [Redux](https://redux.js.org/),
+or the [Command Pattern](https://en.wikipedia.org/wiki/Command_pattern)
+you will feel right at home.
+All of the behaviors are written as plug-ins/middle-ware and attached to the MediatR pipeline.
 
-## Sites
+Please see our **[GitHub Site](https://github.com/TimeWarpEngineering/blazor-state)** for source and filing of issues.
 
-Documentation Site:
+## Installation
 
-* https://timewarpengineering.github.io/blazor-state/index.html
+Blazor-State is available as a [Nuget Package](https://www.nuget.org/packages/Blazor-State/)
 
-Sample Sites:
+```console
+dotnet add package Blazor-State
+```
 
-* https://blazor-state.azurewebsites.net/
+## Getting Started
 
-## Azure DevOps
+After you have completed the [getting started for blazor](https://docs.microsoft.com/en-us/aspnet/core/blazor/get-started)
+the easiest way to get started with blazor-state is to follow
+create new application based on the [timewarp-blazor template](../Templates/TimeWarpBlazorTemplate/TemplateOverview.md)
+Which gives you a base line for both client, server, and testing.
 
-https://timewarpenterprises.visualstudio.com/Blazor-State
+If you would like a basic step by step then follow this [tutorial](xref:BlazorStateSample:README.md).
 
-## Nuget
+## Architecture
 
-https://www.nuget.org/profiles/TimeWarp.Enterprises
+Blazor-State Implements a single `Store` with a collection of `State`s.
+The MediatR pipeline allows for easy integration
+by registering an interface with the DI container.
 
-## GitHub
+```csharp
+services.AddScoped(typeof(IPipelineBehavior<,>), typeof(CloneStateBehavior<,>));
+services.AddScoped(typeof(IPipelineBehavior<,>), typeof(DevToolsBehavior<,>));
+aServices.AddScoped(typeof(IPipelineBehavior<,>), typeof(RenderSubscriptionsBehavior<,>));
+```
 
-https://github.com/TimeWarpEngineering
+The three interfaces available to extend the Pipeline are `IPipelineBehavior`, `IRequestPreProcessor`,
+and `IRequestPostProcessor`;
+
+All of the behaviors in Blazor-State are implemented via one of these interfaces.
+You can integrate into the pipeline as well by implementing and registering one of these interfaces.
+
+### JavaScript Interop
+
+Blazor-State uses the same "Command Pattern" for JavaScript interoperability.
+The JavaScript creates a request and dispatches it to Blazor where it is added to the pipeline.
+Handlers on the Blazor side can callback to the JavaScript side if needed.
+
+### Behaviors
+
+#### CloneStateBehavior
+
+"Don't mutate state" always return a new state.
+The `CloneStateBehavior` behavior handles that for you by creating a clone of the `State`
+prior to processing the `Request`
+and updating `State` upon completion.  (Single responsibility principle)
+
+#### RenderSubscriptionsBehavior
+
+When a component accesses state we place a subscription.
+The `RenderSubscriptionsBehavior` will iterate over these subscriptions and re-render those components.
+So you don't have to worry about where to call `StateHasChanged`.
+
+#### ReduxDevToolsBehavior
+
+One of the nice features of redux is the 
+[developer tools](https://github.com/zalmoxisus/redux-devtools-extension).
+They allow for the monitoring of State transitions, time travel and more.
+This behavior implements the integration of these developer tools.
+
+[!include[Terminology](Partials/terminology.md)]
+
+### PureFunctions vs NonPureFunctions:
+Blazor-State does not distinguish these.
+As they are processed via the pipeline the same.
+Thus, async calls to fetch data, send emails, or just update local state
+are implemented in the same manner. Although the developer **should** be aware that Handlers have side effects and
+if the developer chose they could mark the Requests as such. For example **IActionWithSideEffect**
+
+[!include[Contributing](Partials/acknowledgements.md)]
+
+## UnLicense
+
+[The Unlicense](https://choosealicense.com/licenses/unlicense/)
+
+[!include[Contributing](Partials/contributing.md)]
diff --git a/Documentation/Partials/Acknowledgements.md b/Documentation/Partials/Acknowledgements.md
@@ -0,0 +1,22 @@
+
+## Acknowledgements
+
+Jimmy Bogard ([MediatR](https://github.com/jbogard/MediatR)).
+Jimmy is an amazing developer and a knowledge sharer.  
+Through his course at [11x Engieering](https://11xengineering.com/),
+his many blog posts on Los Techies and now [JimmyBogard.com](https://jimmybogard.com/).
+I have learned great amounts.
+
+Peter Morris ([Blazor-Fluxor](https://github.com/mrpmorris/blazor-fluxor)). Pete and I
+have been friends for many years and he is an amazing developer and person who has taught me much.
+Not surprisingly Pete and I think much alike.
+We independently started working on our State Management
+components. Although I started first :P (By like a few days)
+Pete's component attempts to solve most of the same problems.
+Blazor-State draws on the strengths of a proven pipeline in MediatR where as Fluxor
+implements its own middle-ware.  
+If Blazor-State does not meet your needs be sure to checkout Fluxor.
+
+Tor Hovland ([Blazor-Redux](https://github.com/torhovland/blazor-redux)).
+I have only know Tor for a short time via the Blazor Gitter channel but he is already stimulating ideas.
+If you use F# and need state management functionality checkout his library.
diff --git a/Documentation/Partials/Contributing.md b/Documentation/Partials/Contributing.md
@@ -0,0 +1,11 @@
+---
+uid: blazor-state.contributing.md
+title: Contributing
+---
+
+## Contributing
+
+Time is of the essence.  Before developing a Pull Request I recommend opening an issue for discussion.
+
+Please feel free to make suggestions and help out with the DocFx documentation.
+Refer to [Markdown](https://daringfireball.net/projects/markdown/) for how to write markdown files.
diff --git a/Documentation/Partials/Terminology.md b/Documentation/Partials/Terminology.md
@@ -0,0 +1,44 @@
+## Terminology
+
+The pattern used by Blazor-State and MediatR has been around for many years and goes by different names.
+Given we are using MediatR will use the names associated with it but list other terminology here for clarification.
+
+### Signals/Actions/**Requests**/Commands/
+
+In Redux they call them "Action".  
+In UML they are "Signal".  
+In Command Pattern they are "Command"  
+In MediatR they are `Request`
+In Blazor-State we call them `Actions` when they are handled on the Client and `Requests` if they handled on the Server.
+
+### Reducer/**Handler**/Executor
+
+This is the code that processes the `Request/Action` and returns the `Response`.
+
+In Redux they call them "Reducer".
+(State in, State out, doesn't reduce anything yet they still call them that)  
+In Command Pattern we call them "Executor".  
+In MediatR they are `Handler`.  
+In Blazor-State we call them `Handler`.
+
+### Feature
+
+A Feature is the collection of the code needed to implement a
+particular [Vertical Slice](https://jimmybogard.com/vertical-slice-architecture/)
+of the application.  
+
+On the server side we use the same architecture,
+(see sample in Hosted Server), where the Features contain
+`Controller`, `Handler`, `Request`, `Response`, etc...
+Each endpoint has its own controller
+which maps the HTTP Request to the `Request` Object and then sends
+on to the mediator pipeline.
+The `Handler` acts on the `Request` and returns a `Response`.
+
+Server side follows the `Request` in `Response` out pattern.
+
+A Feature Folder on the client side will contain an `Action` and the `Handler`
+and any corresponding files needed for this feature.
+The "Response" of client side feature is its `State`.
+
+Client side follows the `State` in new `State` out pattern.
diff --git a/Documentation/Sample.md b/Documentation/Sample.md
@@ -9,7 +9,7 @@ This sample shows how to add Blazor-State to a `Blazor (ASP.NET Core hosted)` ap
 
 ## Prerequisites
 
-1. Install the latest [].NET Core 3.0 Preview SDK release](https://dotnet.microsoft.com/download/dotnet-core/3.0).
+1. Install the latest [.NET Core 3.0 Preview SDK release](https://dotnet.microsoft.com/download/dotnet-core/3.0).
 2. Install the Blazor templates by running the following command in a command shell:
 
 ```console

diff --git a/Documentation/docfx.json b/Documentation/docfx.json
@@ -26,7 +26,6 @@
       {
         "src":"../",
         "files":[
-          "samples/**.md",
           "*.md"
         ]
       }

diff --git a/Documentation/toc.yml b/Documentation/toc.yml
@@ -1,20 +1,5 @@
-#- name: Home
-#  href: Overview.md
-- name: Blazor-State
-  href: Blazor-State/
-- name: Project Templates
-  href: Templates/
-- name: TimeWarp Development Process
-  href: Process/
-  dropdown: true
-  items:
-  - name: Backlog
-    href: Backlog/
-    homepage: Backlog/Overview.md
-  - name: DevOps
-    href: DevOps/
-  - name: Tools
-    href: Tools/
-- name: DeveloperNotebook
-  href: DeveloperNotebook/
-
+# auto-generated
+- name: Overview
+  href: Overview.md
+- name: Tutorial
+  href: Sample.md
diff --git a/README.md b/README.md
@@ -1,43 +1,44 @@
-Master: 
-[![Build Status](https://timewarpenterprises.visualstudio.com/Blazor-State/_apis/build/status/Blazor-State-CI-Master-Yaml)](https://timewarpenterprises.visualstudio.com/Blazor-State/_build/latest?definitionId=7)
-
-Dev:
-[![Build Status](https://timewarpenterprises.visualstudio.com/Blazor-State/_apis/build/status/Blazor-State-CI-Dev-Yaml)](https://timewarpenterprises.visualstudio.com/Blazor-State/_build/latest?definitionId=6)
-
 # Blazor-State
 
-State Management architecture utilizing the MediatR pipeline with plugin behaviors.
+[![Build Status](https://timewarpenterprises.visualstudio.com/Blazor-State/_apis/build/status/Blazor-State-CI-Master-Yaml)](https://timewarpenterprises.visualstudio.com/Blazor-State/_build/latest?definitionId=7)
+[![nuget](https://img.shields.io/nuget/v/Blazor-State.svg)](https://www.nuget.org/packages/Blazor-State/)
+[![nuget](https://img.shields.io/nuget/dt/AnyClone.svg)](https://www.nuget.org/packages/Blazor-State/)
 
-# Documentation
+Blazor-State is a State Management architecture utilizing the MediatR pipeline.
+
+## Documentation
 
 See the GitHub pages site for [Documentation](https://timewarpengineering.github.io/blazor-state/)
 
-# Install
+## Installation
 
 Blazor-State is available as a [Nuget Package](https://www.nuget.org/packages/Blazor-State/)
 
-For step by step see the [sample](https://timewarpengineering.github.io/blazor-state/samples/BlazorStateSample/README.html)
+```console
+dotnet add package Blazor-State
+```
 
 ## Acknowledgements
-Jimmy Bogard (MediatR). Jimmy is an amazing developer and a knowledge sharer.  
-Through his course at https://11xengineering.com/ , 
-his many blog posts on Los Techies and now https://jimmybogard.com/. 
+
+Jimmy Bogard ([MediatR](https://github.com/jbogard/MediatR)).
+Jimmy is an amazing developer and a knowledge sharer.  
+Through his course at [11x Engieering](https://11xengineering.com/),
+his many blog posts on Los Techies and now [JimmyBogard.com](https://jimmybogard.com/).
 I have learned great amounts.
 
-Peter Morris ([Blazor-Fluxor](https://github.com/mrpmorris/blazor-fluxor)). Pete and I 
+Peter Morris ([Blazor-Fluxor](https://github.com/mrpmorris/blazor-fluxor)). Pete and I
 have been friends for many years and he is an amazing developer and person who has taught me much.
-Not surprisingly Pete and I think much alike. 
-We independently started working on our Redux replacement
+Not surprisingly Pete and I think much alike.
+We independently started working on our State Management
 components. Although I started first :P (By like a few days)
 Pete's component attempts to solve most of the same problems.
-Blazor-State draws on the strengths of a proven pipeline in MediatR where as Fluxor 
+Blazor-State draws on the strengths of a proven pipeline in MediatR where as Fluxor
 implements its own middle-ware.  
 If Blazor-State does not meet your needs be sure to checkout Fluxor.
 
 Tor Hovland ([Blazor-Redux](https://github.com/torhovland/blazor-redux)).
-I have only know Tor for a short time via the gitter on Blazor but he is already stimulating ideas.
-If you use F# and need redux like functionality checkout his library.
-
+I have only know Tor for a short time via the Blazor Gitter channel but he is already stimulating ideas.
+If you use F# and need state management functionality checkout his library.
 
 ## Unlicense