Documentation

.gitignore

@@ -4,6 +4,7 @@
 # User-specific files
 *.suo
 *.user
+*.bak
 *.sln.docstates
 
 # Build results
@@ -206,5 +207,6 @@ ReactiveUI.Events/Nustache.*
 
 ext/monodroid/18
 
-
+# Exlcude compiled versions of the documentation
+docs/_build/**
 

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/README.md

@@ -0,0 +1,35 @@
+# ReactiveUI Documentation
+
+The source for ReactiveUI documentation is here under `sources/` and uses extended
+Markdown, as implemented by [MkDocs](http://mkdocs.org).
+
+These files are built and deployed to [docs.reactiveui.net](http://docs.reactiveui.net)
+whenever `master` is updated.
+
+## Contributing
+
+### Pre-requisites
+
+On Windows, you should use
+[Chocolatey](http://chocolatey.org/) to setup your local environment:
+
+    # cinst python2
+    # cinst pip
+
+On OS X, you should use [Homebrew](http://brew.sh/):
+
+    # brew install python
+
+Once you've done that, install [MkDocs](http://mkdocs.org) from the command line:
+
+    # pip install mkdocs
+
+### Build and Test
+
+Run this command from the root of the ReactiveUI repository:
+
+    # mkdocs serve
+
+And point your browser to `http://localhost:8000` to view the documentation running
+locally. As files are changed, MkDocs will rebuild the documentation in the
+background.

docs/legacy/basics/application-boostraper.md

@@ -0,0 +1,21 @@
+```cs
+/* COOLSTUFF: What is the AppBootstrapper?
+* 
+* The AppBootstrapper is like a ViewModel for the WPF Application class.
+* Since Application isn't very testable (just like Window / UserControl), 
+* we want to create a class we can test. Since our application only has
+* one "screen" (i.e. a place we present Routed Views), we can also use 
+* this as our IScreen.
+* 
+* An IScreen is a ViewModel that contains a Router - practically speaking,
+* it usually represents a Window (or the RootFrame of a WinRT app). We 
+* should technically create a MainWindowViewModel to represent the IScreen,
+* but there isn't much benefit to split those up unless you've got multiple
+* windows.
+* 
+* AppBootstrapper is a good place to implement a lot of the "global 
+* variable" type things in your application. It's also the place where
+* you should configure your IoC container. And finally, it's the place 
+* which decides which View to Navigate to when the application starts.
+*/
+```

docs/legacy/basics/data-binding.md

@@ -0,0 +1,73 @@
+is it still impossible to use RXUI binding inside ItemTemplate?
+
+paulcbetts [5:35 AM] 
+Yes
+
+ionoy [5:35 AM] 
+damn
+
+paulcbetts [5:35 AM] 
+Well, inside an implicit DataTemplate
+
+paulcbetts [5:36 AM]
+You have to create a UserControl
+
+paulcbetts [5:36 AM]
+The good news is, if you use `OneWayBind` to set the ItemsSource, we'll set up a DataTemplate for you
+
+ionoy [5:37 AM] 
+can you elaborate? if I have an Items collection and one way bind it to my list, how should I name this UserControl then? (for you to automatically set it as DataTemplate) (edited)
+
+paulcbetts [5:38 AM] 
+You can name it whatever you want, as long as:
+1. The UserControl implements `IViewFor<TheViewModelYourePuttingIntoThatList>`
+2. You register the View: `Locator.CurrentMutable.Register(() => new MyUserControl, typeof(IViewFor< TheViewModelYourePuttingIntoThatList>));`
+
+ionoy [5:38 AM] 
+oh, awesome
+
+paulcbetts [5:39 AM] 
+The end result is, in ReactiveUI you end up writing a bit more UserControls, but your XAML is cleaner
+
+ionoy [5:39 AM] 
+this is actually a very good solution
+
+paulcbetts [5:39 AM] 
+Because your ListBox can now be as simple as `<ListBox x:Name="MyList" />`
+
+ionoy [5:39 AM] 
+yep
+
+ionoy [5:49 AM] 
+hm, one downside is that my design time data isn't displayed nicely anymore...
+
+paulcbetts [5:59 AM] 
+Design time data is the best part of ReactiveUI
+
+paulcbetts [5:59 AM]
+So, the way you do design time data, is that you just *set the property* to whatever you want
+
+paulcbetts [5:59 AM]
+And at runtime, the RxUI binding will override it
+
+paulcbetts [6:00 AM]
+It works with ItemsControls too
+
+paulcbetts [6:01 AM]
+```<ListBox x:Name="Foo">
+<ListBox.Items>   <!-- At runtime, ItemsSource trumps Items -->
+<MyControl />
+<MyControl />
+<MyControl />
+</ListBox.Items>
+</ListBox>
+
+
+moswald [6:14 AM] 
+the only downside is that if you are setting your `ItemsSource` from within a call to `WhenActivated` , your design-time data ends up showing up for a frame or two
+
+moswald [6:14 AM]
+the solution is to manually clear your design-time data at the bottom of your constructor in those cases
+
+ionoy [6:56 AM] 
+@moswald: I set design time data via '{Binding Source={d:DesignInstance Type=models:DesignTimeData, IsDesignTimeCreatable=True}}', so it doesn't show when app is started

docs/legacy/basics/presenters.md

@@ -0,0 +1,24 @@
+paulcbetts [8:59 AM] 
+@ghuntley: At a high level, the single View is being pushed on and off the IScreen, yeah
+
+paulcbetts [9:00 AM]
+Not familiar with the concept of Presenters
+
+ghuntley [9:11 AM] 
+Customization of the behavior of views  when navigating between ViewModels. For example pushing on and off UINavigationViewController, switching between uitabbarcontroller options, displaying as splitviewcontroller on iPad but hamburger on iPhone.
+
+ghuntley [9:11 AM]
+http://4.bp.blogspot.com/-Vg7F4u_Unew/UaXgifRFsfI/AAAAAAAAA2o/GIVg5-VM6tM/s1600/redblue1.png (27KB)
+
+
+ghuntley [9:11 AM]
+http://4.bp.blogspot.com/-6UzllelBSj4/UaXgjuLbkcI/AAAAAAAAA2w/Cs23N8j8sIM/s1600/redblue2.png (7KB)
+
+
+paulcbetts [9:12 AM] 
+Ah, in that case you'd have to create your own `RoutedViewHost` which isn't too hard
+
+ghuntley [9:13 AM] 
+:heart:
+
+https://github.com/reactiveui/ReactiveUI/blob/master/ReactiveUI/Xaml/RoutedViewHost.cs

docs/legacy/basics/project-layout.md

@@ -0,0 +1,46 @@
+We suggest the following logical naming pattern when laying out your solution:
+
+<img>
+
+
+All application logic is stored within a core portable class library which is shared between and referenced in each specific platform application:
+
+.Core
+-----
+
+A portable class library that will be the heart of the application and where you will spend most of your time. Profile259 is the recommended profile which should be used, you will need to select it when you create the project.
+
+.Core.Tests
+-----------
+
+A standard class library that contains unit tests that confirm functionality of .Core.
+
+.Droid
+-------
+
+A monodroid (Xamarin.Android) application which contains Android user interface code for both phone and tablet. Please note .Android namespace prefix is reserved by Google for Android internals and must not be used.
+
+.iOS
+-----
+
+A monotouch (Xamarin.iOS) application which contains iOS user interface code for both iPhone and iPad.
+
+.Mac
+----
+
+A monomac (Xamarin.Mac) application which contains OSX user interface code.
+
+.WindowsPhone
+-------------
+
+A Windows Phone application which contains the user interface code.
+
+.WindowsStore
+-------------
+
+Windows 8 Store application with contains the user interface code.
+
+.Wpf
+----
+
+Windows Presentation Foundation applications with contains the user interface code.

docs/legacy/basics/view-location.md

@@ -0,0 +1,69 @@
+# View Location + IViewFor
+
+View Location is a feature of ReactiveUI that allows you to associate Views with
+ViewModels and set them up Automagically.
+
+### ViewModelViewHost
+
+The easiest way to use View Location is via the `ViewModelViewHost` control,
+which is a View (on Cocoa, a UIView/NSView, and on XAML-based platforms a
+Control) which has a single `ViewModel` property. When the ViewModel property is
+set, View Location looks up the associated View and loads it into the container.
+`ViewModelViewHost` is great for lists - so much so, that if you Bind to
+`ItemsSource` on XAML-based platforms and don't set a DataTemplate, one gets
+configured that just uses `ViewModelViewHost`.
+
+```xml
+<ListBox x:Name="ToasterList" />
+```
+
+```cs
+// Now ListBox automatically gets a DataTemplate
+this.OneWayBind(ViewModel, vm => vm.ToasterList, v => v.ToasterList.ItemsSource);
+```
+
+### Registering new Views
+
+To use View Location, you must first register types, via Splat's Service Location feature.
+
+```cs
+Locator.CurrentMutable.Register(() => new ToasterView(), typeof(IViewFor<ToasterViewModel>));
+```
+
+View Location internally uses a class called `ViewLocator` which can either be
+replaced, or the default one used. The `ResolveView` method will return the View
+associated with a given ViewModel object.
+
+
+### Registering multiple views for a single ViewModel
+In order to register multiple views for the same ViewModel the contract parameter must be used on registration.  Here I register 2 views with 2 contracts. Landscape and Portrait. There is no significance to the contract name. I just used these to be descriptive.
+
+```cs
+Locator.CurrentMutable.Register(() => new LandscapeLayoutView(), typeof(IViewFor<MainLayoutViewModel>), "Landscape");
+Locator.CurrentMutable.Register(() => new PortraitLayoutView(), typeof(IViewFor<MainLayoutViewModel>), "Portrait");
+
+```
+
+To change your view (note that the view must be displayed in a `ViewModelViewHost`),create a new `ViewContractObservable` for the `ViewModelViewHost`.
+
+For example, if I have a `ViewModelViewHost` named mainPanel declared in XAML, then I could setup changing its displayed view like this:
+
+```cs
+public partial class ShellView : Window, IViewFor<ShellViewModel>
+{
+  var mainLayoutChange = new BehaviorSubject<string>("Landscape"); //start with landscape
+
+  //ViewContractObservable takes an IObservable<string>
+  this.mainPanel.ViewContractObservable = mainLayoutChange;
+  ...
+  //to change between the views, fire the IObservable<string>
+  //OnNext with a valid contract identifier.
+  someSubsciption
+    .Where(_=> someCondition)
+    .Subscibe(_=> mainLayoutChange.OnNext("Portrait"));
+
+  someSubsciption
+    .Where(_=> someOtherCondition)
+    .Subscibe(_=> mainLayoutChange.OnNext("Landscape"));
+}
+```

docs/legacy/basics/view-model-design.md

@@ -0,0 +1,21 @@
+```cs
+/// <summary>
+/// It's usually a good idea to create an interface for every ViewModel and
+/// reference that instead of the implementation. This makes creating fake
+/// versions or design-time versions of ViewModels much easier.
+/// </summary>
+public interface ITeamLoginTitleViewModel
+{
+    [IgnoreDataMember]
+    ReactiveCommand<Object> LoginToThisTeam { get; }
+
+    [DataMember]
+    TeamWithUser Model { get; }
+}
+
+
+public class TeamLoginTitleViewModel : ReactiveObject, ITeamLoginTitleViewModel
+{
+
+}
+```

docs/legacy/best-practices/command-names.md

@@ -0,0 +1,14 @@
+# Don't
+Don't suffix `ReactiveCommand` properties' names with `Command`; instead, name the property using a verb that describes the command's action. For example:
+
+```cs
+
+public ReactiveCommand Synchronize { get; private set; }
+
+// and then in the ctor:
+
+Synchronize = ReactiveCommand.CreateAsyncObservable(
+_ => SynchronizeImpl(mergeInsteadOfRebase: !IsAhead));
+```
+
+When a `ReactiveCommand`'s implementation is too large or too complex for an anonymous delegate, name the implementation's method the same name as the command, but with `Impl` suffixed (for example, `SychronizeImpl` above).

docs/legacy/best-practices/commands.md

@@ -0,0 +1,39 @@
+Prefer binding user interactions to commands rather than methods.
+
+# Do
+
+```cs
+// In XAML
+<Button Command="{Binding Delete}" .../>
+
+public class RepositoryViewModel : ReactiveObject
+{
+    public RepositoryViewModel() 
+    {
+      Delete = ReactiveCommand.CreateAsyncObservable(x => DeleteImpl());
+      Delete.ThrownExceptions.Subscribe(ex => /*...*/);
+    }
+
+    public ReactiveAsyncCommand Delete { get; private set; }
+
+    public IObservable<Unit> DeleteImpl() {...}
+}
+```
+# Don't
+
+Use the Caliburn.Micro conventions for associating buttons and commands:
+
+```
+// In XAML
+    <Button x:Name="Delete" .../>
+
+    public class RepositoryViewModel : PropertyChangedBase
+    {
+      public void Delete() {...}	
+    }
+```
+
+# Why? 
+- ReactiveCommand exposes the `CanExecute` property of the command to enable applications to introduce additional behaviour.
+- It handles marshaling the result back to the UI thread.
+- It tracks in-flight items.

docs/legacy/best-practices/index.md

@@ -0,0 +1,3 @@
+The following recommendations are intended to help keep ReactiveUI code predictable, understandable, and fast.
+
+They are, however, only a set of practices to help maintain sanity when building RxUI client applications distilled from hard lessons learned. Use best judgment when determining whether to apply the recommendations here to a given piece of code.