Commit aaa585f1 authored by Mikael Lindemann's avatar Mikael Lindemann
Browse files

Expanded readme with images.

parent fa499cf7
......@@ -59,7 +59,7 @@
<contributor>
</contributor>
</contributors>
<readme><![CDATA[]]></readme>
<readme><![CDATA[This adds a contact (phone) number custom property editor that allows to select a country code from a list of countries and shows a green checkbox if the number is known to be of correct length for the country.]]></readme>
</info>
<DocumentTypes />
<Templates />
......
# UmbracoContactNumber
Editor with stored value:
![Read-only mode (default).](images/property-editor-read.png "Read-only mode (default).")
## Build steps
When *Edit* is clicked, the view expands:
### How to build the NuGet package
![Editor with valid phone number length for selected country code.](images/property-editor-edit-dk-success.png "Editor with valid phone number length for selected country code.")
When clicking the country, a dropdown is shown:
![Country dropdown expanded.](images/property-editor-edit-dk-success-dropdown.png "Country dropdown expanded.")
If the number does not have one of the known correct lengths for the country, or if no number lengths are known for the country, the green checkbox is not shown:
![Turkish phone number. Validity of phone number length is unknown.](images/property-editor-edit-tr.png "Turkish phone number. Validity of phone number length is unknown.")
# Build steps
## How to build the NuGet package
This is automated by properties in the .csproj file by setting the following property to true:
```xml
......@@ -29,7 +43,9 @@ Furthermore, to fill out the NuGet package information such as owner, name, and
<RepositoryUrl>https://gitlab.dev.appstract.dk/internal/umbracocontactnumber</RepositoryUrl>
<PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
<Description>
This adds a contact (phone) number custom property editor that allows to select a country code from a list of countries and shows a green checkbox if the number is known to be of correct length for the country.
This adds a contact (phone) number custom property editor that allows to select a country code
from a list of countries and shows a green checkbox if the number is known to be of correct
length for the country.
</Description>
<PackageReleaseNotes>Initial release with hardcoded country database.</PackageReleaseNotes>
<Copyright>Copyright 2020</Copyright>
......@@ -58,7 +74,7 @@ To include the custom property editor in the NuGet package, the following items
</Project>
```
### How to build the Umbraco package
## How to build the Umbraco package
An MSBuild target that builds the Umbraco package has been defined to run after the build completes.
The targets file is imported as follows:
......@@ -98,7 +114,7 @@ Furthermore the manifest has some metadata that describes the package itself in
It is also possible to create Umbraco data on install. In this case we create a default data type instance of the custom property editor by adding an element to the `<DataTypes>` element. Since the custom property editor has no configuration for now, it's just consisting of a name, an id, a GUID, and a database type.
#### MSBuild target definitions walkthrough
### MSBuild target definitions walkthrough
Source: `UmbracoPackage.targets`.
The first property group defines an intermediate folder where the contents of the Umbraco package:
......@@ -117,7 +133,7 @@ This is useful if multiple projects create different Umbraco Packages.
If not overridden, it defaults to `$(BaseIntermediateOutputPath)\umbracopackage_staging\` which usually resolves to `obj\umbracopackage_staging\`.
##### UmbracoPackage
#### UmbracoPackage
The first target `UmbracoPackage` is set up to run after a build, and only if the input files have changed with respect to the resulting Umbraco package file.
It has the following steps:
......@@ -128,12 +144,23 @@ It has the following steps:
4. Change the version in the `package.xml` to follow the MSBuild Version property. Note that only the `package.xml` in `$(UmbracoPackageIntermediateOutputPath)` is changed, not the source file.
5. Zip `$(UmbracoPackageIntermediateOutputPath)` into a package, and place it in `$(BaseOutputPath)\$(Configuration)\$(AssemblyName).$(Version).zip`, overwriting any existing file. `$(BaseOutputPath)\$(Configuration)\$(AssemblyName).$(Version).zip` usually resolves to `bin\Release\Appstract.UmbracoContactNumber.1.0.0.zip`. This folder is also where the NuGet package is stored.
##### UmbracoPackageClean
#### UmbracoPackageClean
The second target `UmbracoPackageClean` is set up to run after cleaning the project. It removes the contents of `$(UmbracoPackageIntermediateOutputPath)` as well as the containing folder.
#### Roadmap
### Roadmap
If we make many of these packages in the future, it might be worthwhile spending some time on creating an actual Umbraco Package task, that takes the files and metadata as input, and creates the packages.xml from scratch, rather than relying on it being well-formed.
MSBuild tasks can be written in .NET and distributed as NuGet packages, such that this can be easily imported into other projects.
The downside to doing this, is that Umbraco can change the format without notice - so it would be great if they distributed such an opportunity alongside Umbraco itself.
\ No newline at end of file
The downside to doing this, is that Umbraco can change the format without notice - so it would be great if they distributed such an opportunity alongside Umbraco itself.
# Known Issues
* Editor does not correctly report validity.
* If the number field has been filled, but is now manually emptied, the editor will show a red warning saying that the property value is invalid.
* If the property has been marked as required, the editor still allows a deleted value, as it fills out `$scope.model.value` with a default of
```json
{
"CountryCodeAndPhoneCode": "#",
"ContactNumber": ""
}
```
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment