Ooui-tws-port/README.md

113 lines
4.7 KiB
Markdown
Raw Normal View History

2018-01-17 21:56:39 +00:00
# Ooui Web Framework <img src="https://raw.githubusercontent.com/praeclarum/Ooui/master/Documentation/Icon.png" height="32"> [![Build Status](https://www.bitrise.io/app/86585e168136767d/status.svg?token=G9Svvnv_NvG40gcqu48RNQ)](https://www.bitrise.io/app/86585e168136767d)
2017-11-29 03:52:24 +00:00
| Version | Package | Description |
| ------- | ------- | ----------- |
2018-02-07 23:42:45 +00:00
| [![NuGet Package](https://img.shields.io/nuget/v/Ooui.svg)](https://www.nuget.org/packages/Ooui) | [Ooui](https://www.nuget.org/packages/Ooui) | Core library with HTML elements and a server |
| [![NuGet Package](https://img.shields.io/nuget/v/Ooui.AspNetCore.svg)](https://www.nuget.org/packages/Ooui.AspNetCore) | [Ooui.AspNetCore](https://www.nuget.org/packages/Ooui.AspNetCore) | Integration with ASP.NET Core |
2017-11-29 03:52:24 +00:00
| [![NuGet Package](https://img.shields.io/nuget/v/Ooui.Forms.svg)](https://www.nuget.org/packages/Ooui.Forms) | [Ooui.Forms](https://www.nuget.org/packages/Ooui.Forms) | Xamarin.Forms backend using Ooui |
2017-06-14 02:39:36 +00:00
2018-02-07 23:42:45 +00:00
Ooui (pronounced *weee!*) is a small cross-platform UI library for .NET that uses web technologies.
2017-06-13 19:33:06 +00:00
It presents a classic object-oriented UI API that controls a dumb browser. With Ooui, you get the full power of your favorite .NET programming language *plus* the ability to interact with your app using any device.
2017-06-13 19:02:57 +00:00
2017-06-17 00:59:35 +00:00
## Try it Online
2017-11-16 05:51:02 +00:00
Head on over to [http://ooui.mecha.parts](http://ooui.mecha.parts) to tryout the samples.
2017-06-17 00:59:35 +00:00
## Try the Samples Locally
2017-06-16 23:02:38 +00:00
```bash
git clone git@github.com:praeclarum/Ooui.git
cd Ooui
2017-06-14 01:10:37 +00:00
dotnet restore
msbuild
dotnet run --project Samples/Samples.csproj --no-build
2017-06-14 01:10:37 +00:00
```
2018-02-01 22:17:29 +00:00
*(There is currently an issue with Xamarin.Forms and building from the dotnet cli, so for now we use the msbuild command and then set the --no-build flag on dotnet run but this will eventually change when the issue is resolved.)*
This will open the default starting page for the Samples. Now point your browser at [http://localhost:8080/shared-button](http://localhost:8080/shared-button)
2017-06-16 23:02:38 +00:00
2018-02-07 23:42:45 +00:00
You should see a button that tracks the number of times it was clicked. The source code for that button is shown in the example below.
2017-06-16 23:02:38 +00:00
2017-06-14 01:10:37 +00:00
2018-02-07 23:42:45 +00:00
## Example App
2017-06-14 01:10:37 +00:00
2017-06-16 23:02:38 +00:00
Here is the complete source code to a fully collaborative button clicking app.
2017-06-13 19:02:57 +00:00
```csharp
2017-06-16 23:02:38 +00:00
using System;
2017-06-13 19:02:57 +00:00
using Ooui;
2017-06-16 23:02:38 +00:00
class Program
{
static void Main(string[] args)
{
// Create the UI
var button = new Button("Click me!");
// Add some logic to it
var count = 0;
button.Click += (s, e) => {
2017-06-16 23:02:38 +00:00
count++;
button.Text = $"Clicked {count} times";
};
// Publishing makes an object available at a given URL
// The user should be directed to http://localhost:8080/shared-button
2017-06-16 23:02:38 +00:00
UI.Publish ("/shared-button", button);
// Don't exit the app until someone hits return
Console.ReadLine ();
}
}
```
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
Make sure to add a reference to Ooui before you start running!
2017-06-13 19:02:57 +00:00
2017-06-16 23:02:38 +00:00
```bash
dotnet add package Ooui
2018-02-07 23:42:45 +00:00
dotnet run
2017-06-13 19:02:57 +00:00
```
2018-02-07 23:42:45 +00:00
With just that code, a web server that serves the HTML and web socket logic necessary for an interactive button will start.
2017-06-13 19:33:06 +00:00
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
## The Many Ways to Ooui
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
Ooui has been broken up into several packages to increase the variety of ways that it can be used. Here are some combinations to help you decide which way is best for you.
2017-06-13 19:02:57 +00:00
<table>
2018-02-07 23:42:45 +00:00
<thead><tr><th>Ooui</th><th>Ooui.AspNetCore</th><th>Ooui.Forms</th><th></th></tr></thead>
2017-06-13 19:02:57 +00:00
<tr>
2018-02-08 00:31:01 +00:00
<td>&check;</td><td></td><td></td><td><a href="https://github.com/praeclarum/Ooui/wiki/Write-the-UI-using-the-web-DOM-and-use-the-built-in-web-server">Write the UI using the web DOM and use the built-in web server</a></td>
2017-06-13 19:02:57 +00:00
</tr>
<tr>
2018-02-07 23:42:45 +00:00
<td>&check;</td><td>&check;</td><td></td><td>Write the UI using the web DOM and serve it with ASP.NET Core</td>
2017-06-13 19:02:57 +00:00
</tr>
<tr>
2018-02-07 23:42:45 +00:00
<td>&check;</td><td>&check;</td><td>&check;</td><td>Write the UI using Xamarin.Forms and serve it with ASP.NET Core</td>
2017-06-13 19:02:57 +00:00
</tr>
<tr>
2018-02-07 23:42:45 +00:00
<td>&check;</td><td></td><td>&check;</td><td>Write the UI using Xamarin.Forms and use the built-in web server</td>
2017-06-13 19:02:57 +00:00
</tr>
2018-02-07 23:42:45 +00:00
</table>
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
## How it works
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
When the user requests a page, the page will connect to the server using a web socket. This socket is used to keep the server's in-memory model of the UI (the one you work with as a programmer) in sync with the actual UI shown to the user in their browser. This is done using a simple messaging protocol with JSON packets.
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
When the user clicks or otherwise interacts with the UI, those events are sent back over the web socket so that your code can deal with them.
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
## Contributing
2017-06-13 19:02:57 +00:00
2018-02-07 23:42:45 +00:00
Ooui is open source and I love merging PRs. Please fork away, and please obey the .editorconfig file. :-) Try to file issues for things that you want to work on *before* you start the work so that there's no duplicated effort. If you just want to help out, check out the issues and dive in!