Feature/documentation

.github/Get-Started.md

@@ -0,0 +1,6 @@
+#How to get started
+
+- [Installation & Setup](Installation-&-setup.md)
+- [How to use in backoffice](How-to-use-in-backoffice.md)
+- [How to use in Razor](How-to-use-in-Razor.md)
+

.github/How-to-use-in-Razor.md

@@ -0,0 +1,54 @@
+## Examples
+
+As you'll see below, this OEmbed package doesn't do all that much for you outisde the backoffice. In true Umbraco style it tries very hard to not be opinionated when it comes to presentation.
+
+Here are a few examples of how you *could* embed the responses. Some properties are available on most OEmbed responses  [as per the specs](https://oembed.com/#section2) and can be accessed directly (like ``Type`` or ``Html``), while others are specific for each type. Others again might be entirely custom for the provider. Those "custom" properties are accessed via ``TryGetValue(...)``.
+
+###Video
+In this example we make sure to honor the aspect ratio of the video when presenting it, by sizing the container before outputting the HTML from the OEmbed response.
+
+Also notice the two ways of getting properties from the OEmbedResponse object
+
+```csharp
+@if (Model.PageVideo?.OEmbed is OEmbedResponse video)
+{
+    var ratio = video.Width.HasValue && video.Height.HasValue ?
+        (double)video.Height.Value / (double)video.Width.Value :
+        0d;
+
+    <div class="embed" data-ratio="@ratio">
+        <div class="embed__item embed__item--@(video.Type?.ToLower())" style="padding-bottom: @Math.Round(ratio * 100, 2).ToString(CultureInfo.InvariantCulture)%;">
+            @Html.Raw(video.Html)
+        </div>
+
+        @if (video.TryGetValue<string>("upload_date", out var uploadDateValue) &&
+             DateTime.TryParse(uploadDateValue, out var uploadDate))
+        {
+            <p>Upload from @video.ProviderName: @uploadDate</p>
+        }
+    </div>
+}
+```
+
+###'Any'
+Knowing the type of OEmbed data in the response is quite advantageous, as _not_ knowing it severely limits what you can do with the response data. As long as you remember to use ``TryGetValue(...)`` it should be safe enough, though.
+
+```csharp
+@if (Model.PageAny?.OEmbed is OEmbedResponse any)
+{
+    if (!string.IsNullOrWhiteSpace(Model.PageAny?.Url))
+    {
+        <div class="embed">
+            <div class="embed__item embed__item--@(any.Type?.ToLower())">
+                @Html.Raw(any.Html)
+            </div>
+
+            @if (any.TryGetValue("upload_date", out string uploadDateValue) &&
+        DateTime.TryParse(uploadDateValue, out var uploadDate))
+            {
+                <p>Upload from @any.ProviderName: @uploadDate</p>
+            }
+        </div>
+    }
+}
+```

.github/How-to-use-in-backoffice.md

@@ -0,0 +1,16 @@
+## Data Type Definition Example
+![Data Type Definition](images/datatypeconfiguration.jpg)
+
+### Type
+Defines validation for the selected media type. Note that the selected Type is used for **backoffice validation only** - there is still only one model/response to deal with everywhere else.
+
+OEmbed requests typically respond with whatever type of content it provides. While Video, Photo and Link may be (relatively) self explanatory, there are few more options in there.
+
+#### Rich
+The Rich type is for rich (HTML) content not fitting into any of the other Types/categories. The tweet in the screenshot below could be one example (even though in the screenshot it's actually used in an editor allowing Any type).
+
+#### Where's the Any type?
+Forgive the pun. There _is_ an "Any" type, but what does it mean? Well, the Any type simply means that there is no type validation in the editor. Anything goes.
+
+## Content Example
+![Content Example](images/UmbracoOEmbedContent.jpg)

.github/Installation-&-setup.md

@@ -0,0 +1,23 @@
+### Install with dotnet
+Gone are the days of installation via backoffice. Your only option is now to install via [Nuget](https://www.nuget.org/packages/Novicell.Umbraco.OEmbed/) - or dotnet as below:
+
+```
+> dotnet add package Novicell.Umbraco.OEmbed
+```
+
+### Setup
+For everything to kick in and be registered properly, you need to enable AutoDiscover when registering in your Startup class, like so:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddUmbraco(_env, _config)
+        .AddNovicellOEmbed(o => {
+            o.Autodiscover = true;
+        })
+        .AddBackOffice()             
+        .AddWebsite()
+        .AddComposers()
+        .Build();
+}
+```

README.md

@@ -4,8 +4,6 @@
 
 [![Pack and Release](https://github.com/Novicell/Novicell.Umbraco.OEmbed/actions/workflows/cd-pack-and-release.yml/badge.svg)](https://github.com/Novicell/Novicell.Umbraco.OEmbed/actions/workflows/cd-pack-and-release.yml)
 
-A property editor for Umbraco 9 that allows you to use OEmbed data for embedding video or images from external sources.
+A property editor for Umbraco 9 that allows you to use OEmbed data for embedding video, images and anything else that supports OEmbed - from external sources.
 
-Find the package on nuget - https://www.nuget.org/packages/Novicell.Umbraco.OEmbed/
-
-> dotnet add package Novicell.Umbraco.OEmbed --version 1.0.0-rc002
+[Take a look at the documentation here](/.github/Get-Started.md) for info and tips on installation as well as implementation.

src/Novicell.Umbraco.OEmbed.Website/Views/Home.cshtml

@@ -5,22 +5,22 @@
 @using ContentModels = Umbraco.Cms.Web.Common.PublishedModels
 @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.Home>
 @{
-	Layout = null;
+    Layout = null;
 }
 
 <style type="text/css">
-    div.page
-    {
+    div.page {
         max-width: 50%;
     }
 
     .media {
-        max-width:100%;
-    }
-    .media img {
-      width:100%;  
+        max-width: 100%;
     }
 
+        .media img {
+            width: 100%;
+        }
+
     .embed {
     }
 
@@ -30,37 +30,54 @@
         height: 0;
     }
 
-    .embed__item iframe,
-    .embed__item embed,
-    .embed__item object
-    {
-        position: absolute;
-        top: 0;
-        left: 0;
-        width: 100%;
-        height: 100%;
-    }
+        .embed__item iframe,
+        .embed__item embed,
+        .embed__item object {
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+        }
 </style>
 
 <div class="page">
 
-@if (Model.PageVideo?.OEmbed is OEmbedResponse video)
-{
-    var ratio = video.Width.HasValue && video.Height.HasValue ?
-        (double)video.Height.Value / (double)video.Width.Value :
-        0d;
+    @if (Model.PageVideo?.OEmbed is OEmbedResponse video)
+    {
+        var ratio = video.Width.HasValue && video.Height.HasValue ?
+            (double)video.Height.Value / (double)video.Width.Value :
+            0d;
 
-    <div class="embed" data-ratio="@ratio">
-        <div class="embed__item embed__item--@(video.Type?.ToLower())" style="padding-bottom: @Math.Round(ratio * 100, 2).ToString(CultureInfo.InvariantCulture)%;">
-            @Html.Raw(video.Html)
-        </div>
-        
-        @if (video.TryGetValue<string>("upload_date", out var uploadDateValue) &&
+        <div class="embed" data-ratio="@ratio">
+            <div class="embed__item embed__item--@(video.Type?.ToLower())" style="padding-bottom: @Math.Round(ratio * 100, 2).ToString(CultureInfo.InvariantCulture)%;">
+                @Html.Raw(video.Html)
+            </div>
+
+            @if (video.TryGetValue("upload_date", out string uploadDateValue) &&
              DateTime.TryParse(uploadDateValue, out var uploadDate))
+            {
+                <p>Upload from @video.ProviderName: @uploadDate</p>
+            }
+        </div>
+    }
+
+
+    @if (Model.PageAny?.OEmbed is OEmbedResponse any)
+    {
+        if (!string.IsNullOrWhiteSpace(Model.PageAny?.Url))
         {
-            <p>Upload from @video.ProviderName: @uploadDate</p>
-        }
-    </div>
-}
+            <div class="embed">
+                <div class="embed__item embed__item--@(any.Type?.ToLower())">
+                    @Html.Raw(any.Html)
+                </div>
 
+                @if (any.TryGetValue("upload_date", out string uploadDateValue) &&
+           DateTime.TryParse(uploadDateValue, out var uploadDate))
+                {
+                    <p>Upload from @any.ProviderName: @uploadDate</p>
+                }
+            </div>
+        }
+    }
 </div>

src/Novicell.Umbraco.OEmbed.Website/appsettings.json

@@ -18,7 +18,7 @@
   "Umbraco": {
     "CMS": {
       "ModelsBuilder": {
-        "ModelsMode": "SourceCodeAuto"
+        "ModelsMode": "SourceCodeManual"
       },
       "Hosting": {
         "Debug": false

src/Novicell.Umbraco.OEmbed.Website/uSync/v9/Content/home1.config

@@ -13,6 +13,28 @@
     <Template Key="6ef2aa7c-e22f-4cad-aae5-2346dba37d33">Home</Template>
   </Info>
   <Properties>
+    <pageAny>
+      <Value><![CDATA[{
+  "url": "https://twitter.com/jack/status/1247616214769086465",
+  "oembed": {
+    "type": "rich",
+    "version": "1.0",
+    "title": null,
+    "author_name": "jack",
+    "author_url": "https://twitter.com/jack",
+    "provider_name": "Twitter",
+    "provider_url": "https://twitter.com",
+    "thumbnail_url": null,
+    "thumbnail_height": null,
+    "thumbnail_width": null,
+    "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">I’m moving $1B of my Square equity (~28% of my wealth) to <a href=\"https://twitter.com/hashtag/startsmall?src=hash&amp;ref_src=twsrc%5Etfw\">#startsmall</a> LLC to fund global COVID-19 relief. After we disarm this pandemic, the focus will shift to girl’s health and education, and UBI. It will operate transparently, all flows tracked here: <a href=\"https://t.co/hVkUczDQmz\">https://t.co/hVkUczDQmz</a></p>&mdash; jack (@jack) <a href=\"https://twitter.com/jack/status/1247616214769086465?ref_src=twsrc%5Etfw\">April 7, 2020</a></blockquote>\n<script async src=\"https://platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>\n",
+    "url": "https://twitter.com/jack/status/1247616214769086465",
+    "height": null,
+    "width": 550,
+    "cache_age": null
+  }
+}]]></Value>
+    </pageAny>
     <pageVideo>
       <Value><![CDATA[{
   "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",

src/Novicell.Umbraco.OEmbed.Website/uSync/v9/ContentTypes/home.config

@@ -20,6 +20,28 @@
     </AllowedTemplates>
   </Info>
   <Structure />
-  <GenericProperties />
-  <Tabs />
+  <GenericProperties>
+    <GenericProperty>
+      <Key>cc37654d-d4c3-4315-823f-df79a5b763c6</Key>
+      <Name>Any</Name>
+      <Alias>pageAny</Alias>
+      <Definition>72de9d10-46b5-4eba-b112-e023bd17c4b2</Definition>
+      <Type>Novicell.OEmbed</Type>
+      <Mandatory>false</Mandatory>
+      <Validation></Validation>
+      <Description><![CDATA[]]></Description>
+      <SortOrder>1</SortOrder>
+      <Tab>Content</Tab>
+      <Variations>Nothing</Variations>
+      <MandatoryMessage />
+      <ValidationRegExpMessage />
+      <LabelOnTop>false</LabelOnTop>
+    </GenericProperty>
+  </GenericProperties>
+  <Tabs>
+    <Tab>
+      <Caption>Content</Caption>
+      <SortOrder>0</SortOrder>
+    </Tab>
+  </Tabs>
 </ContentType>

src/Novicell.Umbraco.OEmbed.Website/uSync/v9/DataTypes/HomeAnyNovicellOEmbed.config

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<DataType Key="72de9d10-46b5-4eba-b112-e023bd17c4b2" Alias="Home - Any - Novicell OEmbed" Level="1">
+  <Info>
+    <Name>Home - Any - Novicell OEmbed</Name>
+    <EditorAlias>Novicell.OEmbed</EditorAlias>
+    <DatabaseType>Ntext</DatabaseType>
+  </Info>
+  <Config><![CDATA[{
+  "Type": null
+}]]></Config>
+</DataType>