diff --git a/15/umbraco-cms/.gitbook.yaml b/15/umbraco-cms/.gitbook.yaml index 9ba9b5b9bc6..4ce3e0d7c69 100644 --- a/15/umbraco-cms/.gitbook.yaml +++ b/15/umbraco-cms/.gitbook.yaml @@ -105,3 +105,4 @@ redirects: tutorials/creating-a-backoffice-tour: tutorials/overview.md extending/packages/types-of-packages: extending/packages/README.md reference/configuration/nucachesettings: reference/configuration/cache-settings.md + fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/listview: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/collection.md diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index 2dac08d1f64..76e79e55288 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -30,6 +30,8 @@ * [Property Editors](fundamentals/backoffice/property-editors/README.md) * [Built-in Property Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/README.md) * [Image Cropper](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/image-cropper.md) + * [Block Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md) + * [Block Grid](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md) ## Implementation @@ -83,6 +85,7 @@ * [Web routing](reference/configuration/webroutingsettings.md) * [Querying & Models](reference/querying/README.md) * [ITagQuery](reference/querying/itagquery.md) + * [UmbracoContext helper](reference/querying/umbraco-context.md) * [Routing & Controllers](reference/routing/README.md) * [Routing in Umbraco](reference/routing/request-pipeline/README.md) * [IContentFinder](reference/routing/request-pipeline/icontentfinder.md) diff --git a/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md b/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md index 3d711aad480..10e1061c981 100644 --- a/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md +++ b/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md @@ -14,7 +14,7 @@ Umbraco CMS currently ships with two Block Editors: the Block List and the Block ## Customizing Block Editors -### [Build custom views for blocks](build-custom-view-for-blocks.md) +### [Creating custom views for blocks](../../../../../tutorials/creating-custom-views-for-blocklist.md) Learn how to create custom views for the blocks used in your Block Grid or Block List property editors. diff --git a/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/collection.md b/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/collection.md new file mode 100644 index 00000000000..a4efa4edaab --- /dev/null +++ b/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/collection.md @@ -0,0 +1,110 @@ +# Collection + +`Alias: Umbraco.ListView` + +`Returns: IEnumerable` + +**Collection** displays a collection of categories when it is enabled on a Document Type with children. + +![Collection example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview.png) + +## Enable collection + +If enabled, editors will be able to see multiple children from a collection on a content node that has children. When not enabled, no collection will be shown and all children will be shown in the Content Tree. + +![Enable Collection example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/enable-listview.png) + +## Settings + +![Collection settings example](/14/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/images/list-view-settings.png) + + +### Page Size + +Defines how many child content nodes you want to see per page. This will limit how many content items you will see in your collection. If you set it to 5, then only 5 content items will be shown in the collection. + +### Order By + +Will sort your collection by the selection you choose in the dropdown. By default it selects "Last edited" and you get the following three columns: + +* **Last edited** - When the content node was last edited and saved. +* **Name** - Name of the content node(s). +* **Created by** - This is the user who the content node was created by. + +You can add more sorting to this collection by adding more datatypes to the columns in the "Columns Displayed" section. + +### Order Direction + +You can select order of the content nodes displayed, "Acsending" or "Descending". The order is affected by the "Order By" selection. + +### Columns Displayed + +It is possible to add more columns to the collection, via adding the properties through the dropdown. These properties are based on the Data Types which are used by the Document Type. It will show up in the dropdown by its alias and not the name on the property. + +![Collection property example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-property.png) ![Collection property example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-property-dropdown.png) + +Once you have selected a column you want to display, define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how they should look. This is done by the move icon on the left side of the alias. + +The template section is where you define what kind of value you want to display. The value of the column is in the `value` variable. + +### Layouts + +Collection comes with two layouts by default. A list and a grid view. These views can be disabled if you are not interested in any of them. + +{% hint style="info" %} +A minimum of one layout needs to be enabled for Collection to work. +{% endhint %} + +You can also make your own layout and add it to the settings. For example, if you wanted to change the width or length of the grid, you will be able to do so. + +### Bulk Action Permissions + +Select what kind of action is available on the collection. + +* **Allow bulk publish** - content only +* **Allow bulk unpublish** - content only +* **Allow bulk copy** - content only +* **Allow bulk move** +* **Allow bulk delete** + +### Workspace View icon + +Changes the icon in the backoffice of the collection. By default it will look like the image below. + +![Collection icon example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/list-icon.png) + +### Workspace View name + +You can change the name of the collection itself. Default if empty: 'Child Items'. + +### Show Content Workspace View First + +Enable this to show the Content Workspace View by default instead of the collection's. + +## Content Example + +### Generic field value + +This example uses a generic field on a child item and displays it in the collection. ![Collection content example email](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-content-example-email-settings.png) + +The `{{ value }}` will take the value of the Email property and display it in the collection, as shown on the image below. + +![Collection content example email](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-content-example-email.png) + +### Member name + +First, a Member Picker property needs to be present on the content item. In this example, the `child item` has gotten a Member Picker Data Type with the alias of `isAuthor`. + +![Collection member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/member-picker.png) + +The child item has a member and the value that should be displayed is the name of the picked value. The next step is to reconfigure the template value in the collection setting. + +![Collection member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/member-picker-settings.png) + +This will take the value picked up by the member picker. ![Collection member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/picked-member.png) + +And display it in the collection. Shown in the example below: ![Collection member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/list-member-picked.png) + +### Other examples + +![Collection other examples](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/others.png) ![Collection other examples](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/others-result.png) diff --git a/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/listview.md b/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/listview.md deleted file mode 100644 index 83d2db4be72..00000000000 --- a/15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/listview.md +++ /dev/null @@ -1,110 +0,0 @@ -# List View - -`Alias: Umbraco.Listview` - -`Returns: IEnumerable` - -**List View** display a list of categories when it is enabled on a Document Type that has children. - -![List view example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview.png) - -## Enable list view - -If enabled, editors will be able to see multiple children from a list on a content node that has children. When not enabled, no list will be shown and all children will be shown in the Content Tree. - -![Enable List view example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/enable-listview.png) - -## Settings - -![List view settings example](/14/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/images/list-view-settings.png) - - -### Page Size - -Defines how many child content nodes you want to see per page. This will limit how many content items you will see in your list. If you set it to 5, then only 5 content items will be shown in the list. - -### Order By - -Will sort your list by the selection you choose in the dropdown. By default it selects "Last edited" and you get the following three columns: - -* **Last edited** - When the content node was last edited and saved. -* **Name** - Name of the content node(s). -* **Created by** - This is the user who the content node was created by. - -You can add more sorting to this list by adding more datatypes to the columns in the "Columns Displayed" section. - -### Order Direction - -You can select order of the content nodes displayed, "Acsending" or "Descending". The order is affected by the "Order By" selection. - -### Columns Displayed - -It is possible to add more columns to the list, via adding the properties through the dropdown. These properties are based on the Data Types which are used by the Document Type. It will show up in the dropdown by its alias and not the name on the property. - -![List view property example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-property.png) ![List view property example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-property-dropdown.png) - -Once you have selected a column that you want to display, the next thing you want to do is define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how the headers should look. This is done by the move icon on the left side of the alias. - -The template section is where you define what kind of value you want to display. The value of the column is in the `value` variable. - -### Layouts - -The list view comes with two layouts by default. A list and a grid view. These views can be disabled if you are not interested in any of them. - -{% hint style="info" %} -A minimum of one layout needs to be enabled for the list view to work. -{% endhint %} - -You can also make your own layout and add it to the settings. For example, if you wanted to change the width or length of the grid, you will be able to do so. - -### Bulk Action Permissions - -Select what kind of action is available on the list view. - -* **Allow bulk publish** - content only -* **Allow bulk unpublish** - content only -* **Allow bulk copy** - content only -* **Allow bulk move** -* **Allow bulk delete** - -### Content app icon - -Changes the icon in the backoffice of the listview. By default it will look like the image below. - -![List icon example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/list-icon.png) - -### Content app name - -You can change the name of the listview itself. Default if empty: 'Child Items'. - -### Show Content App First - -Enable this to show the content app by default instead of the list view - -## Content Example - -### Generic field value - -This example uses a generic field on a child item and displays it in the list. ![List view content example email](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-content-example-email-settings.png) - -The `{{ value }}` will take the value of the Email property and display it in the list, as shown on the image below. - -![List view content example email](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/listview-content-example-email.png) - -### Member name - -First, a Member Picker property needs to be present on the content item. In this example, the `child item` has gotten a Member Picker Data Type with the alias of `isAuthor`. - -![List view member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/member-picker.png) - -Now that the child item has a member and the value that should be displayed is the name of the picked value, the next step is to reconfigure the template value in the listview setting. - -![List view member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/member-picker-settings.png) - -This will take the value picked up by the member picker. ![List view member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/picked-member.png) - -And display it in the listview. Shown in the example below: ![List view member picker](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/list-member-picked.png) - -### Other examples - -![List view other examples](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/others.png) ![List view other examples](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/others-result.png) diff --git a/15/umbraco-cms/legacy-documentation/README.md b/15/umbraco-cms/legacy-documentation/README.md new file mode 100644 index 00000000000..cfbf35ba351 --- /dev/null +++ b/15/umbraco-cms/legacy-documentation/README.md @@ -0,0 +1,21 @@ +--- +description: Resources and links for older versions of Umbrco CMS. +--- + +# Legacy Documentation + +This documentation platform covers only supported versions of the Umbraco CMS, excluding version 8. If you use an unsupported version, you need to go elsewhere. + +[Learn more about how long each major version of Umbraco is supported.](https://umbraco.com/products/knowledge-center/long-term-support-and-end-of-life/) + +## [Legacy versions on GitHub](https://github.com/umbraco/UmbracoDocs/tree/umbraco-eol-versions) + +When a major version of Umbraco CMS goes End of Life (EOL), the documentation for this version will be unpublished 3 months later. + +The documentation for all EOL versions will continue to be available on the [UmbracoDocs GitHub repository](https://github.com/umbraco/UmbracoDocs/tree/umbraco-eol-versions). + +## Our Umbraco + +The documentation for Umbraco 7 and 8 lives on [our.umbraco.com](https://our.umbraco.com/documentation/). + +
Umbraco 7 Documentationhttps://our.umbraco.com/documentation/
Umbraco 8 Documentationhttps://our.umbraco.com/documentation/
diff --git a/15/umbraco-cms/reference/configuration/globalsettings.md b/15/umbraco-cms/reference/configuration/globalsettings.md index b1758aa2a6e..84f5f2d9306 100644 --- a/15/umbraco-cms/reference/configuration/globalsettings.md +++ b/15/umbraco-cms/reference/configuration/globalsettings.md @@ -65,76 +65,124 @@ In the root level section, that is those without a seperate sub section like SMT ### Reserved urls +Key: `ReservedUrls` +Type: `string` (default: `~/.well-known,`) + A comma-seperated list of files to be left alone by Umbraco, these files will be served, and the Umbraco request pipeline will not be triggered. ### Reserved paths +Key: `ReservedPaths` +Type: `string` (default: `~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,`) + A comma-separated list of all the folders in your directory to be left alone by Umbraco. If you have folders with custom files, add them to this setting to make sure Umbraco leaves them alone. {% hint style="warning" %} Adding additional values to the Reserves URLs and Reserved Paths will overwrite default/current values. This causes performance issues as well. {% endhint %} ### Timeout +Key: `TimeOut` +Type: `string` (default: `00:20:00`) + Configure the session timeout to determine how much time without a request being made can pass before the user is required to log in again. The session timeout format needs to be set as `HH:MM:SS`. Any activity within the backoffice will reset the timer. {% hint style="info" %} Long session timeouts raise data exposure and unauthorized access risks. Thus, it's vital to establish a reasonable timeout to mitigate security risks. {% endhint %} ### Default UI language +Key: `DefaultUILanguage` +Type: `string` (default: `en-US`) + The default language to use in the backoffice if a user isn't explicitly assigned one. ### Hide top level nodes from path +Key: `HideTopLevelNodeFromPath` +Type: `bool` (default: `true`) + If you are running multiple sites, you don't want the top level node in your URL and can disable it with this setting. ### Use https +Key: `UseHttps` +Type: `bool` (default: `false`) + Makes sure that all of the requests in the backoffice are called over HTTPS instead of HTTP when set to true. ### Version check period +Key: `VersionCheckPeriod` +Type: `int` (default: `7`) + When this value is set above 0, the backoffice will check for a new version of Umbraco every 'x' number of days where 'x' is the value defined for this setting. Set this value to 0 to never check for a new version. ### Icons path +Key: `IconsPath` +Type: `string` (default: `umbraco/assets/icons`) + By adding this value you can specify a new/different folder for storing your icon resources. It's important to be aware of NetCore's limitations regarding serving static file content. By default, static content will only be served from the `wwwroot` folder. ### Umbraco CSS path +Key: `UmbracoCssPath` +Type: `string` (default: `~/css`) + By adding this you can specify a new/different folder for storing your CSS files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see [Extending filesystem](../../extending/filesystemproviders/) ### Umbraco scripts path +Key: `UmbracoScriptsPath` +Type: `string` (default: `~/scripts`) + By adding this you can specify a new/different folder for storing your script/js files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see [Extending filesystem](../../extending/filesystemproviders/) ### Umbraco media path +Key: `UmbracoMediaPath` +Type: `string` (default: `~/media`) + By adding this you can specify a new/different folder for storing your media files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see [Extending filesystem](../../extending/filesystemproviders/) ### Umbraco media physical root path +Key: `UmbracoMediaPhysicalRootPath` +Type: `string` (default: `~/media`) + By adding this you can specify a new/different folder for storing your media files elsewhere on the server. Unlike `UmbracoMediaPath`, this does not change the relative path that media is served from (e.g. /media) but allows for files to be stored **outside** of the wwwroot folder. Both relative paths (../../Shared/Media) and absolute server paths (X:/Shared/Media) are supported. For more info see [Extending filesystem](../../extending/filesystemproviders/) ### Install missing database +Key: `InstallMissingDatabase` +Type: `bool` (default: `false`) + This is not a setting that commonly needs to be configured. If enabled Umbraco will try to automatically install the database when it's missing. This is primarily used in conjuction with unattended installs. ### Disable election for single server +Key: `DisableElectionForSingleServer` +Type: `bool` (default: `false`) + This is not a setting that commonly needs to be configured. This value is primarily used on Umbraco Cloud for a small startup performance optimization. When this is true, the website instance will automatically be configured to not support load balancing and the website instance will be configured to be the 'primary' server for scheduling so no [primary election](../../fundamentals/setup/server-setup/load-balancing/file-system-replication.md) occurs. This will save 1 database call during startup. ### Database factory version +Key: `DatabaseFactoryServerVersion` +Type: `bool` (default: `false`) + This is not a setting that commonly needs to be configured. This setting is used to specify which sql server version that the database is running, this setting is only required if you use SqlServer 2008, if this is the case set the setting to `"SqlServer.V2008"` ### Main dom lock +Key: `MainDomLock` +Type: `string` + Specifies the implementation of IMainDomLock to be used. `IMainDomLock` is used to synchronize access to resources like the Lucene indexes. @@ -149,6 +197,9 @@ The default implementation unless configured otherwise is `FileSystemMainDomLock ### Main dom key discriminator +Key: `MainDomKeyDiscriminator` +Type: `string` + For advanced use cases e.g. deployment slot swapping on Azure app services. When using SqlMainDomLock a MainDomKey is used to identify an instance of a running application. @@ -165,16 +216,25 @@ It's worth noting that during the swap operation there is a period where both in ### Main dom release signal polling interval +Key: `MainDomReleaseSignalPollingInterval` +Type: `string` + Gets or sets the duration (in milliseconds) for which the MainDomLock release signal polling task should sleep. The default value is 2000ms. ### Id +Key: `Id` +Type: `string` + This setting doesn't need to be configured. This setting contains a unique ID used to identify your project, and is populated the first time your site runs, you shouldn't change this setting. ### No nodes view path +Key: `NoNodesViewPath` +Type: `string` (default: `~/umbraco/UmbracoWebsite/NoNodes.cshtml`) + This setting specifies what view to render when there is no content on the site. ## SMTP settings @@ -227,10 +287,16 @@ It's unlikely that you will have to change these settings unless you're using a ### Wait time between calls +Key: `DatabaseServerRegistrar.WaitTimeBetweenCalls` +Type: `string` (default: `00:01:00`) + Sets a value for the amount of time to wait between calls to the database on the background thread. ### Stale server timeout +Key: `DatabaseServerRegistrar.StaleServerTimeout` +Type: `string` (default: `00:02:00`) + Sets a value for the time span to wait before considering a server stale, after it has last been accessed. ## Database server messenger @@ -239,22 +305,37 @@ It's unlikely that you will have change these settings, unless you're using a lo ### Max processing instruction +Key: `DatabaseServerMessenger.MaxProcessingInstructionCount` +Type: `string` (default: `1000`) + Sets a value for the maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches). ### Time to retain instructions +Key: `DatabaseServerMessenger.TimeToRetainInstructions` +Type: `string` (default: `2.00:00:00`) + Sets a value for the time to keep instructions in the database; records older than this number will be pruned. ### Time between sync operations +Key: `DatabaseServerMessenger.TimeBetweenSyncOperations` +Type: `string` (default: `00:00:05`) + Sets a value for the time to wait between each sync operation. ### Time between prune operations +Key: `DatabaseServerMessenger.TimeBetweenPruneOperations` +Type: `string` (default: `00:01:00`) + Sets a value for the time to wait between each prune operation. ### Distributed Locking Mechanism +Key: `DistributedLockingMechanism` +Type: `string` + This is not a setting that commonly needs to be configured. Gets or sets a value representing the DistributedLockingMechanism to use. @@ -266,12 +347,18 @@ Valid values: ### Distributed Read Lock DefaultTimeout +Key: `DistributedLockingReadLockDefaultTimeout` +Type: `string` (default: `00:01:00`) + Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed read lock. The default value is 60 seconds. ### Distributed Write Lock DefaultTimeout +Key: `DistributedLockingWriteLockDefaultTimeout` +Type: `string` (default: `00:00:05`) + Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed write lock. The default value is 5 seconds. diff --git a/15/umbraco-cms/reference/notifications/contentservice-notifications.md b/15/umbraco-cms/reference/notifications/contentservice-notifications.md index 7092efaa1c8..2f33e84fd36 100644 --- a/15/umbraco-cms/reference/notifications/contentservice-notifications.md +++ b/15/umbraco-cms/reference/notifications/contentservice-notifications.md @@ -200,20 +200,20 @@ We can suppress notifications at the scope level which makes things consistent a **How to use scopes**: -- Create an explicit scope and call scope.Notifications.Supress(). +- Create an explicit scope and call scope.Notifications.Suppress(). - The result of Suppress() is IDisposable, so until it is disposed, notifications will not be added to the queue. [Example](https://github.com/umbraco/Umbraco-CMS/blob/b69afe81f3f6fcd37480b3b0295a62af44ede245/tests/Umbraco.Tests.Integration/Umbraco.Infrastructure/Scoping/SupressNotificationsTests.cs#L35): ```csharp using (IScope scope = ScopeProvider.CreateScope(autoComplete: true)) -using (IDisposable _ = scope.Notifications.Supress()) +using (IDisposable _ = scope.Notifications.Suppress()) { // TODO: Calls to service methods here will not have notifications } ``` -Child scope will inherit the parent Scope's notification object which means if a parent scope has notifications suppressed, then so does the child scope. You cannot call Supress() more than once for the same outer scope instance else an exception will be thrown. This ensures that you cannot un-suppress notifications at a child level for an outer scope. It also ensures that suppressing events is an explicit thing to do. +Child scope will inherit the parent Scope's notification object which means if a parent scope has notifications suppressed, then so does the child scope. You cannot call Suppress() more than once for the same outer scope instance else an exception will be thrown. This ensures that you cannot un-suppress notifications at a child level for an outer scope. It also ensures that suppressing events is an explicit thing to do. **Why would one want to suppress events?** diff --git a/15/umbraco-cms/release-candidate-guide.md b/15/umbraco-cms/release-candidate-guide.md index 37cf1cdfc6e..4d150146e46 100644 --- a/15/umbraco-cms/release-candidate-guide.md +++ b/15/umbraco-cms/release-candidate-guide.md @@ -79,6 +79,8 @@ Here is a list of all the articles that are new to this version or have been upd * [Working with Caching: Tags example](reference/cache/examples/tags.md) * [Unit Testing](implementation/unit-testing.md) * [Querying: ITagQuery](reference/querying/itagquery.md) + * [UmbracoContext helper](reference/querying/umbraco-context.md) + * [Block Grid](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md) * Replacing the deprecated GetAll() method * [Working with Caching: Tags example](reference/cache/examples/tags.md) diff --git a/15/umbraco-cms/tutorials/creating-a-basic-website/adding-language-variants.md b/15/umbraco-cms/tutorials/creating-a-basic-website/adding-language-variants.md index c3fa5fdaf10..2c65f7acb75 100644 --- a/15/umbraco-cms/tutorials/creating-a-basic-website/adding-language-variants.md +++ b/15/umbraco-cms/tutorials/creating-a-basic-website/adding-language-variants.md @@ -88,3 +88,7 @@ To view the language variant on the browser, follow these steps: ![Viewing the Language Variant Link](images/viewing-langvariant-browser-v14.png) 5. Click on the link to view the new language node in the browser. 6. Alternatively, you can add the domain name to your localhost in the browser. For example: [http://localhost:xxxx/da/](http:/localhost:xxxx/da/) + +## More Information + +Further information on multi-language setups can be found in the [Multilanguage Setup tutorial](../multilanguage-setup.md). diff --git a/15/umbraco-cms/tutorials/multilanguage-setup.md b/15/umbraco-cms/tutorials/multilanguage-setup.md index 801f01d19dc..cedd325f4c1 100644 --- a/15/umbraco-cms/tutorials/multilanguage-setup.md +++ b/15/umbraco-cms/tutorials/multilanguage-setup.md @@ -81,13 +81,13 @@ For this tutorial, we will create the following document types: * Home Page - ![Home Page](../../../10/umbraco-cms/tutorials/images/home-page.png) + ![Home Page](images/home-page.png) * Blogs - ![Blogs](../../../10/umbraco-cms/tutorials/images/Blogs.png) + ![Blogs](images/Blogs.png) * Contact Us - ![Contact Us](../../../10/umbraco-cms/tutorials/images/Contact-us.png) + ![Contact Us](images/Contact-us.png) ## Enabling Language Variants on Document Types and Properties @@ -257,8 +257,111 @@ For viewing purposes, I've added a stylesheet to my website. The final result sh Danish Version: -
+
German Version: -
+
+ +## Using Multiple languages across APIs + +When requesting content over an API, the culture will fall back to the default, unless explicitly set. + +To do this, you can use the IVariationContextAccessor. + +```csharp +public class ExampleController : SurfaceController +{ + private readonly ILanguageService _languageService; + private readonly IVariationContextAccessor _variationContextAccessor; + + public ExampleController(IUmbracoContextAccessor umbracoContextAccessor, IUmbracoDatabaseFactory databaseFactory, ServiceContext services, AppCaches appCaches, IProfilingLogger profilingLogger, IPublishedUrlProvider publishedUrlProvider, ILocalizationService localizationService, IVariationContextAccessor variationContextAccessor) : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider) + { + _localizationService = localizationService; + _variationContextAccessor = variationContextAccessor; + } + + public IActionResult Index(string culture = null) + { + IEnumerable UmbracoLanguages = _languageService.GetAllAsync().Result; //a helpful method to get all configured languages + var requestedCulture = UmbracoLanguages.FirstOrDefault(l => l.IsoCode == culture); + + if (requestedCulture != null) + { + _variationContextAccessor.VariationContext = new VariationContext(requestedCulture.IsoCode); + } + + //this will now be in the requested culture + var content = UmbracoContext.Content.GetAtRoot(); + + //Content requested in this View Component will now be in the requested culture + return ViewComponent(); + } +} +``` + +### Creating a Language Switching Navigation + +To navigate between languages, you need to do two key things: + + 1. Get all the languages that the site can provide + 2. Identify the language used on the current page + +Once you have these, you need to loop through the languages and provide links to each home node. + +### Getting all the languages for a site + +There are three ways to achieve this. The best one is to use `languageService.GetAllAsync();` which retrieves items from the cache. + +Another is to use `localizationService.GetAllLanguages();` to call the database, which is expensive and ideally includes caching. This should only be done if you cannot use the ILanguage service. This service is marked as obsolete. + +The alternative is to get the Home node and find all of the cultures associated with it. This has a few benefits including speed and providing us with a link to show the user. It is the process you will use when following this guide. + +### Identify the language for the current page + +This is achieved in `cs.html` files using `umbracoHelper.AssignedContentItem.GetCultureFromDomains();` + +#### Steps + +Now that you have what you need, take the following steps to create a working example. + +1. Create a new view called `Navigation.cshtml` +2. Paste in the following code: + +```cshtml +@using Umbraco.Cms.Web.Common +@inject IUmbracoHelperAccessor _umbracoHelperAccessor; +@{ + _umbracoHelperAccessor.TryGetUmbracoHelper(out var umbracoHelper); + var homePage = umbracoHelper.ContentAtRoot().FirstOrDefault(c => c.ContentType.Alias == "{{homeNodeContentAlias}}"); + var cultures = homePage?.Cultures; +} +@if (cultures.Count > 1) +{ +
    + @foreach (var cult in cultures) + { + //get the settings for this culture + System.Globalization.CultureInfo culture = new System.Globalization.CultureInfo(cult.Key); + //if the current page has a language variant, otherwise link to the homepage language variant + string langUrl = umbracoHelper.AssignedContentItem.Url(cult.Key, UrlMode.Relative) ?? homePage.Url(cult.Key, UrlMode.Relative); +
  • + @if (cult.Key.ToLower() == umbracoHelper.AssignedContentItem.GetCultureFromDomains().ToLower()) + { + @culture.NativeName + } + else + { + @culture.NativeName + } +
    • + } +
+} +``` + +3. Replace `{{homeNodeContentAlias}}` with the Document Type alias of your Home node. + +This will render links to either the language variant of the current page or the home node for the language variant. + +Additionally, `System.Globalization.CultureInfo` is used to obtain the native name of the language being rendered. This is useful if a user does not speak the default language. diff --git a/15/umbraco-deploy/deployment-workflow/import-export-v7.md b/15/umbraco-deploy/deployment-workflow/import-export-v7.md index 8bd1da497c5..45688355111 100644 --- a/15/umbraco-deploy/deployment-workflow/import-export-v7.md +++ b/15/umbraco-deploy/deployment-workflow/import-export-v7.md @@ -1,17 +1,16 @@ --- -meta.Title: Migrating from Umbraco 7 description: How to export content and schema from Umbraco 7 and import into a newer version --- -### Migrating from Umbraco 7 +# Migrating from Umbraco 7 -The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from there in the same way. +The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service. -We can use this feature to help migrate from Umbraco 7 to a supported major version. However, it requires additional logic to be added to the Deploy Contrib project. +However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions. -#### Exporting Umbraco 7 content and schema +## Exporting Umbraco 7 content and schema -We can generate an export archive in the same format as used by the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project. This archive can then be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents. +You can generate an export archive in the same format as the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents. This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up: @@ -88,7 +87,7 @@ public class DeployExportApplicationHandler : ApplicationEventHandler -#### Importing Umbraco 7 content and schema +## Importing Umbraco 7 content and schema To import this archive into a newer Umbraco project, you need to install either of these packages: @@ -150,6 +149,9 @@ internal class LegacyImportComposer : IComposer builder.DeployArtifactMigrators() .AddLegacyMigrators() .Append(); + + builder.DeployPropertyTypeMigrators() + .AddLegacyMigrators(); // Available from Deploy Contrib 13.3.0 and 14.2.0+ } private class ElementTypeArtifactMigrator : ElementTypeArtifactMigratorBase @@ -167,23 +169,23 @@ internal class LegacyImportComposer : IComposer It is recommended to start by importing only the schema and schema files (by deselecting 'Content' and 'Content files' in the dialog). Then, you can proceed with importing all content and schema together. The order in which the artifacts are imported depends on their dependencies. By importing the schema first, we ensure that the schema is updated before any content is processed. {% endhint %} -#### Obtaining Umbraco Deploy for Umbraco 7 +## Obtaining Umbraco Deploy for Umbraco 7 Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Umbraco Cloud. It was not released for use on-premise. As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed. -If you have an Umbraco 7 on-premise website, you can use this guide to migrate from on-premise to Umbraco Cloud. Or to upgrade to a newer Deploy on-premise version. You will need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature. +If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature. The export feature can be used without a license. {% hint style="info" %} -A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or an on-premise one. +A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or a Deploy On-premises one. {% endhint %} -Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a newer Deploy version on-premise. +Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version. 1. Download the required `dll` files for Umbraco Deploy for Umbraco 7 from the following links: diff --git a/15/umbraco-deploy/deployment-workflow/import-with-migrations.md b/15/umbraco-deploy/deployment-workflow/import-with-migrations.md index 65dd946af4d..92c882eacb0 100644 --- a/15/umbraco-deploy/deployment-workflow/import-with-migrations.md +++ b/15/umbraco-deploy/deployment-workflow/import-with-migrations.md @@ -1,5 +1,4 @@ --- -meta.Title: Import with migrations in Umbraco Deploy description: How to import content and schema while migrating them into newer alternatives --- @@ -15,7 +14,7 @@ For example, we can migrate from a Nested Content property in Umbraco 8 to a Blo We provide the necessary migration hooks for this to happen, divided into two types - **artifact migrators** and **property migrators**. -### Artifact migrators +## Artifact migrators Artifact migrators work by transforming the serialized artifact of any imported artifact, via two interfaces: @@ -37,7 +36,7 @@ We've also made available base implementations that you can use to build your ow - `ArtifactJsonMigratorBase` - migrates the JSON of the specified artifact type - `ReplaceGridDataTypeArtifactMigratorBase` - migrates a Data Type based on the legacy Grid layout into the Block Grid -### Property migrators +## Property migrators Property migrators work to transform the content property data itself. They are used in the Deploy content connectors (documents, media and members) when the property editor is changed during an import: @@ -60,7 +59,7 @@ And a base type to help you build your own migrations: Property editor changes are determined by comparing the `PropertyEditorAliases` dictionary stored in the content artifact to the current Content Type/Data Type configuration. The dictionary contains editor aliases for each content property. {% endhint %} -### Registering migrators +## Registering migrators Migrators will run if you have registered them, so you can enable only the ones needed for your solution. @@ -84,21 +83,50 @@ internal class ArtifactMigratorsComposer : IComposer .Append(); } } - ``` +``` -### Details of Specific Migrations +## Import and migration flow + +When an import is started, the following happens: + +1. Artifact signatures are read from the import provider (using `IArtifactImportProvider.GetArtifactSignatures()`). +2. The artifact signatures are sorted based on dependencies with `Ordering` enabled (ensuring dependent items are processed in the correct order, like parent items before children and data types before document types). +3. For each artifact signature: + 1. Check whether the entity type is allowed to be imported. + 2. Publish an `ArtifactImportingNotification` (cancelling will skip importing the artifact). +4. Publish a `ValidateArtifactImportNotification`: + - Deploy adds a default handler (`ValidateArtifactImportDependenciesNotificationHandler`) to validate whether all dependencies are either in the import or already present in the current environment. It emits warnings for missing content artifacts, missing or different artifact checksums and errors for missing schema artifacts. + - The import fails on validation errors or 'soft' fails on warnings if the `WarningsAsErrors` import option is set. +5. Create a Deploy scope and context (containing the 'owner' user for auditing purposes and cultures to import, in case the user doesn't have edit permissions for all languages). +6. For each artifact signature: + 1. Create a (readonly) `Stream` for the artifact (using `IArtifactImportProvider.CreateArtifactReadStream(Udi)`). + 2. Deserialize the artifact into a generic JSON object (`JsonNode`). + 3. Parse the `__version` and `__type` properties and resolve the artifact type (using `IArtifactTypeResolver`). + 4. Migrate the JSON object (using `IArtifactJsonMigrator`). + 5. Deserialize the JSON object into the artifact type. + 6. Migrate the artifact (using `IArtifactMigrator`). + 7. Initialize artifact processing (using `IServiceConnector.ProcessInit(...)`) and track deploy state with next passes. +7. For each next process pass (starting at the lowest initial next pass): + 1. Process artifact (using `IServiceConnector.Process(...)`). + 2. During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using `IPropertyTypeMigrator`). + 3. When no next pass is required (the deploy state returns -1 as next pass): + 1. Publish an `ArtifactImportedNotification`. + 2. Report the import process (using `IProgress.Report(...)`). +8. The Deploy scope is completed, causing all scoped notifications to be published to handlers implementing `IDistributedCacheNotificationHandler`) and completing the import. + +## Details of Specific Migrations Umbraco Deploy ships with migrators to handle the conversion of core property editors as they have changed, been removed or replaced between versions. -Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for [use](https://www.nuget.org/packages/Umbraco.Deploy.Contrib) and [review](https://github.com/umbraco/Umbraco.Deploy.Contrib/tree/v13/dev/src/Umbraco.Deploy.Contrib/Migrators) via the `Umbraco.Deploy.Contrib` package. +Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for [use](https://www.nuget.org/packages/Umbraco.Deploy.Contrib) and [review](https://github.com/umbraco/Umbraco.Deploy.Contrib/tree/v15/dev/src/Umbraco.Deploy.Contrib/Migrators) via the `Umbraco.Deploy.Contrib` package. -#### Grid to Block Grid +### Grid to Block Grid -The grid editor introduced in Umbraco 7 has been removed from Umbraco 14. It's functionality is replaced with the Block Grid. +The Grid editor introduced in Umbraco 7 has been removed from Umbraco 14. Its functionality is replaced with the Block Grid. With Deploy migrators we have support for migrating Data Type configuration and property data between these property editors. -You can configure the default migration with the following composer: +Deploy adds the `ReplaceGridDataTypeArtifactMigrator` and `GridPropertyTypeMigrator` migrators by default, so using a custom migrator requires replacing the default ones: ```csharp using Umbraco.Cms.Core.Composing; @@ -109,20 +137,24 @@ internal sealed class DeployMigratorsComposer : IComposer public void Compose(IUmbracoBuilder builder) { builder.DeployArtifactMigrators() - .Append(); + .Replace(); builder.DeployPropertyTypeMigrators() - .Append(); + .Replace(); } } ``` +{% hint style="info" %} +The project you are importing into needs to know about any custom legacy Grid editor configurations to migrate to the Block Grid editor correctly. Make sure to either copy the `grid.editors.config.js` and `package.manifest` (containing grid editors) files or override the `GetGridEditors()` method of the artifact migrator to provide this. +{% endhint %} + These implementations make use of the following conventions to migrate the data: - `ReplaceGridDataTypeArtifactMigrator`: - Grid layouts are migrated to an existing or new element type with an alias based on the layout name, prefixed with `gridLayout_` (this can be customized by overriding `MigrateGridTemplate()`); - Row configurations are migrated to an existing or new element type with an alias based on the row name, prefixed with `gridRow_` (this can be customized by overriding `MigrateGridLayout()`); - - Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with `gridEditor_` (this can be customized by overriding `MigrateGridEditor()`). The available editors are retrieved from the `grid.editors.config.js` files (can be overridden in `GetGridEditors()`). Each migrated grid editor will have the following property types added to the element type: + - Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with `gridEditor_` (this can be customized by overriding `MigrateGridEditor()`). The default editors used in version 13 are returned by `GetGridEditors()` and you can override this method to include your custom editors. Each migrated grid editor will have the following property types added to the element type: - The `media` grid editor is migrated to multiple properties: the `value` property contains the selected media item (using Media Picker v3), `altText` the alternate text (using a Textbox) and `caption` the caption (also using a Textbox); - The remaining grid editors create a single `value` property that uses the following editors: - `rte` - the default 'Rich Text Editor', falling back to the first `Umbraco.TinyMCE` editor. @@ -170,7 +202,7 @@ The base classes provide the following functionality. Methods you should look to - Similarly, if a layout block can be found for the grid layout name, all items are wrapped into that block. - The JSON serialized `BlockValue` is returned. -#### Migrating From Doc Type Grid Editor +### Migrating From Doc Type Grid Editor [Doc Type Grid Editor](https://our.umbraco.com/packages/backoffice-extensions/doc-type-grid-editor/) was a community package commonly used with the legacy grid editor. If you are using this with Umbraco 7 and up, you can export and migrate into the Block Grid on Umbraco 13 or above. @@ -200,7 +232,11 @@ The migrators add the following behavior: - `ReplaceDocTypeGridEditorDataTypeArtifactMigrator` extends `ReplaceGridDataTypeArtifactMigrator` and ensures any DocTypeGridEditor is migrated to blocks using the allowed element types. If the element types aren't found the default implementation will migrate to new element types. - `DocTypeGridEditorPropertyTypeMigrator` extends `GridPropertyTypeMigrator` and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data. -#### Migrating from Matryoshka +{% hint style="info" %} +The artifact migrator adds the default DocTypeGridEditor configuration (with alias `docType`). This can be disabled by setting the `AddDefaultDocTypeGridEditor` property to `false` in a custom/inherited class. Similar to the base migrator, any custom DocTypeGridEditor configurations must be available to migrate to the Block Grid editor correctly. +{% endhint %} + +### Migrating from Matryoshka [Matryoshka](https://our.umbraco.com/packages/backoffice-extensions/matryoshka-tabs-for-umbraco-8/) was an Umbraco package that added tab support for document types in Umbraco. The feature was subsequently added to the product itself. @@ -224,7 +260,7 @@ internal sealed class DeployMigratorsComposer : IComposer } ``` -### Source Code Example - Nested Content to Block List +## Source Code Example - Nested Content to Block List As described above, the nested content to block list migration will occur register the corresponding migrator with your application. diff --git a/15/umbraco-forms/.gitbook.yaml b/15/umbraco-forms/.gitbook.yaml index 8865254d413..e9f3f783087 100644 --- a/15/umbraco-forms/.gitbook.yaml +++ b/15/umbraco-forms/.gitbook.yaml @@ -8,3 +8,4 @@ redirects: the-licensing-model: installation/the-licensing-model.md installation/manualupgrade: upgrading/manualupgrade.md installation/version-specific: upgrading/version-specific.md + developer/blocklistfilters: developer/blocklistlabels.md diff --git a/15/umbraco-forms/developer/blocklistfilters.md b/15/umbraco-forms/developer/blocklistlabels.md similarity index 100% rename from 15/umbraco-forms/developer/blocklistfilters.md rename to 15/umbraco-forms/developer/blocklistlabels.md diff --git a/15/umbraco-forms/developer/extending/adding-a-fieldtype.md b/15/umbraco-forms/developer/extending/adding-a-fieldtype.md index a14f7feca06..d9e3170aa7c 100644 --- a/15/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/15/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -172,6 +172,8 @@ With Forms 14, aspects of the presentation and functionality of the custom field To create custom backoffice components for Umbraco 14, it's recommended to use a front-end build setup using Vite, TypeScript, and Lit. For more information, see the [Extension with Vite, TypeScript, and Lit](https://app.gitbook.com/s/G1Byxw7XfiZAj8zDMCTD/tutorials/creating-your-first-extension#extension-with-vite-typescript-and-lit) article. +To display a name and description on a custom field, you need to register a JavaScript file as shown in the [Localization](https://docs.umbraco.com/umbraco-cms/customize-the-backoffice/extending-overview/extension-types/localization) article. + ### Field Preview The alias of the preview to use is defined on the field type via the `PreviewView` property.