Skip to content

Commit c0fd7ea

Browse files
committed
Production release of page transformation
1 parent eabde47 commit c0fd7ea

File tree

4 files changed

+235
-14
lines changed

4 files changed

+235
-14
lines changed

docs/toc.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1338,11 +1338,13 @@
13381338
- name: Transform classic pages to modern client-side pages
13391339
href: transform/modernize-userinterface-site-pages.md
13401340
items:
1341+
- name: Page transformation configuration options
1342+
href: transform/modernize-userinterface-site-pages-configuration.md
13411343
- name: Page transformation model
13421344
href: transform/modernize-userinterface-site-pages-model.md
13431345
- name: Page layout mapping
13441346
href: transform/modernize-userinterface-site-pages-layout.md
1345-
- name: Page transformation API
1347+
- name: Page transformation Functions and Selectors
13461348
href: transform/modernize-userinterface-site-pages-api.md
13471349
- name: Modernize customizations
13481350
href: transform/modernize-customizations.md
Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
title: Options to control the page transformation process
3+
description: Explains how to configure the page transformation process
4+
ms.date: 09/25/2018
5+
ms.prod: sharepoint
6+
---
7+
8+
# Page transformation configuration options
9+
10+
When you use the page transformation framework you do have a lot of control on how the page transformation is done. The model to control this is by specifying the correct configuration as part of the `PageTransformationInformation` instance that you use to launch page transformation. In this article you'll learn more about the available options.
11+
12+
> [!IMPORTANT]
13+
> The SharePoint PnP Modernization framework is continuously evolving, checkout [the release notes](https://github.com/SharePoint/PnP-Tools/blob/master/Solutions/SharePoint.Modernization/Modernization%20Framework%20release%20notes.md) to stay up to date on the latest changes. If you encounter problems please file an issue in the [PnP Tools GitHub issue list](https://github.com/SharePoint/PnP-Tools/issues).
14+
15+
## Overwrite option
16+
17+
Type | Default value if not specified
18+
-----|----
19+
Bool | false
20+
21+
When you configure `Overwrite = true` then the page transformation framework will overwrite the target page if needed. By default the new page name has a prefix of Migrated_, which then implies that if Migrated_YourPage.aspx already exists (typically from a previous page transformation effort) it will be overwritten. Below snippet shows how to use this option.
22+
23+
```Csharp
24+
PageTransformationInformation pti = new PageTransformationInformation(page)
25+
{
26+
Overwrite = true,
27+
};
28+
```
29+
30+
## TargetPagePrefix option
31+
32+
Type | Default value if not specified
33+
-----|----
34+
String | Migrated_
35+
36+
The new modern page is named as {TargetPagePrefix}{OriginalPageName} (e.g. Migrated_MyPage.aspx). If you want another prefix then use this option.
37+
38+
```Csharp
39+
PageTransformationInformation pti = new PageTransformationInformation(page)
40+
{
41+
TargetPagePrefix = "New_",
42+
};
43+
```
44+
45+
## TargetPageTakesSourcePageName option
46+
47+
Type | Default value if not specified
48+
-----|----
49+
Bool | false
50+
51+
The default behavior is to give the created modern page a name that starts with the prefix Migrated_ and let the original page keep it's existing name. When this option is specified the newly created page gets the name of the original page and the original page is renamed with a prefix Previous_. Set this option if you're sure you want to move forward with the modern page as it will ensure that all links pointing the original page now result in the new modern page being loaded.
52+
53+
```Csharp
54+
PageTransformationInformation pti = new PageTransformationInformation(page)
55+
{
56+
TargetPageTakesSourcePageName = true,
57+
};
58+
```
59+
60+
> [!IMPORTANT]
61+
> During the rename of the original page to a page starting with the Previous_ prefix the version history of the original page is not retained.
62+
63+
## SourcePagePrefix option
64+
65+
Type | Default value if not specified
66+
-----|----
67+
String | Previous_
68+
69+
If you've set `TargetPageTakesSourcePageName = true` then the original page gets renamed with a default prefix Previous_. If you want another prefix then use this option.
70+
71+
```Csharp
72+
PageTransformationInformation pti = new PageTransformationInformation(page)
73+
{
74+
SourcePagePrefix = "New_",
75+
};
76+
```
77+
78+
## ReplaceHomePageWithDefaultHomePage option
79+
80+
Type | Default value if not specified
81+
-----|----
82+
Bool | false
83+
84+
The default behavior is to transform your site's home page to a modern page like any other regular page. If you set this option to true then a site's home page will be transformed to a 'default' out-of-the-box modern home page, so the one you would get with a newly created modern team site.
85+
86+
```Csharp
87+
PageTransformationInformation pti = new PageTransformationInformation(page)
88+
{
89+
ReplaceHomePageWithDefaultHomePage = true,
90+
};
91+
```
92+
93+
## KeepPageSpecificPermissions option
94+
95+
Type | Default value if not specified
96+
-----|----
97+
Bool | true
98+
99+
The default behavior is to copy over any item level permissions that might exist on the source page, if you don't want this then set this option to false
100+
101+
```Csharp
102+
PageTransformationInformation pti = new PageTransformationInformation(page)
103+
{
104+
KeepPageSpecificPermissions = false,
105+
};
106+
```
107+
108+
## HandleWikiImagesAndVideos option
109+
110+
Type | Default value if not specified
111+
-----|----
112+
Bool | true
113+
114+
A wiki page can contain embedded video and text which is not possible in a modern text part. By default the wiki text will be split at each embedded image or video, a video or image web part will be added to the modern page and then the remainder of the original text. If you don't like this automatic fixing you can set this option to false which will result in each embedded image and video being replaced by a text placeholder combined with individual video and image web pars at the bottom of the page.
115+
116+
```Csharp
117+
PageTransformationInformation pti = new PageTransformationInformation(page)
118+
{
119+
HandleWikiImagesAndVideos = false,
120+
};
121+
```
122+
123+
## PageHeader option
124+
125+
Type | Default value if not specified
126+
-----|----
127+
ClientSidePageHeader | Null
128+
129+
The default page header for the modern page is of type `ClientSidePageHeaderType.None` which comes closest to the the wiki page header. However if you prefer a default modern page header (the one wit the large gray zone) you can do that using this option (see below sample as well). You can also configure a custom page header with all it's associated options like background image, alignment etc.
130+
131+
```Csharp
132+
PageTransformationInformation pti = new PageTransformationInformation(page)
133+
{
134+
PageHeader = new ClientSidePageHeader(cc, ClientSidePageHeaderType.Default, null),
135+
};
136+
```
137+
138+
## PageTitleOverride option
139+
140+
Type | Default value if not specified
141+
-----|----
142+
Func<string, string> | null
143+
144+
The title of the modern page is deducted from the source page by taking the page name and dropping the extension, but you can insert any custom page title in the transformation flow by this callout. The shown example adds a suffix _1 to the default title.
145+
146+
```Csharp
147+
// Local functions
148+
string titleOverride(string title)
149+
{
150+
return $"{title}_1";
151+
}
152+
153+
PageTransformationInformation pti = new PageTransformationInformation(page)
154+
{
155+
PageTitleOverride = titleOverride,
156+
};
157+
```
158+
159+
## LayoutTransformatorOverride option
160+
161+
Type | Default value if not specified
162+
-----|----
163+
Func<ClientSidePage, ILayoutTransformator> | null
164+
165+
The page transformation engine has a default layout transformator that can handle all the out of the box wiki and web part page layouts, but if you want to override this one you can specify your own.
166+
167+
```Csharp
168+
public class MyLayout : ILayoutTransformator
169+
{
170+
private ClientSidePage page;
171+
172+
public MyLayout(ClientSidePage page)
173+
{
174+
this.page = page;
175+
}
176+
177+
public void Transform(PageLayout layout)
178+
{
179+
// custom layout transformation...add sections to the target page based upon the recieved page layout
180+
switch (layout)
181+
{
182+
case PageLayout.Wiki_OneColumn:
183+
case PageLayout.WebPart_FullPageVertical:
184+
case PageLayout.Wiki_Custom:
185+
case PageLayout.WebPart_Custom:
186+
{
187+
page.AddSection(CanvasSectionTemplate.OneColumn, 1);
188+
return;
189+
}
190+
// add more incoming layouts...
191+
default:
192+
{
193+
page.AddSection(CanvasSectionTemplate.OneColumn, 1);
194+
return;
195+
}
196+
}
197+
}
198+
}
199+
200+
// Local functions
201+
ILayoutTransformator layoutOverride(ClientSidePage cp)
202+
{
203+
return new MyLayout();
204+
}
205+
206+
207+
PageTransformationInformation pti = new PageTransformationInformation(page)
208+
{
209+
LayoutTransformatorOverride = layoutOverride,
210+
};
211+
```

docs/transform/modernize-userinterface-site-pages-model.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.prod: sharepoint
1010
The heart of the page transformation solution is the model that feeds the transformation: the model tells the engine which web part properties are important, allows you to manipulate these properties and dynamically choose a mapping for your web part.The page transformation model is expressed in XMl and comes with a schema that's used to validate the correctness of the model.
1111

1212
> [!IMPORTANT]
13-
> The SharePoint PnP Modernization framework is currently in preview. If you encounter problems please file an issue in the [PnP Tools GitHub issue list](https://github.com/SharePoint/PnP-Tools/issues).
13+
> The SharePoint PnP Modernization framework is continuously evolving, checkout [the release notes](https://github.com/SharePoint/PnP-Tools/blob/master/Solutions/SharePoint.Modernization/Modernization%20Framework%20release%20notes.md) to stay up to date on the latest changes. If you encounter problems please file an issue in the [PnP Tools GitHub issue list](https://github.com/SharePoint/PnP-Tools/issues).
1414
1515
## Page transformation model structure
1616

@@ -86,6 +86,9 @@ Let's assume that the web part property originally contains a guid formatted lik
8686

8787
If a function returns multiple values then each returned key/value pair that already exists as web part property overwrites that properties value.
8888

89+
> [!NOTE]
90+
> All the out-of-the box functions are described in [Page Transformation Functions and Selectors](modernize-userinterface-site-pages-api.md)
91+
8992
### Mappings element
9093

9194
This element defines one or more possible target configurations for the given source web part. Since you can define multiple targets there needs to be a mechanism to determine which mapping to use:
@@ -94,6 +97,9 @@ This element defines one or more possible target configurations for the given so
9497
- If there's only one mapping then that's taken if there was no selector result
9598
- If there's no selector result and there are multiple mappings defined then the mapping marked as Default is taken
9699

100+
> [!NOTE]
101+
> All the out-of-the box selectors are described in [Page Transformation Functions and Selectors](modernize-userinterface-site-pages-api.md)
102+
97103
Next up is explain the Mapping element itself.
98104

99105
### Mapping element

docs/transform/modernize-userinterface-site-pages.md

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Classic SharePoint sites typically have classic pages being wiki pages or web pa
1212
The SharePoint PnP Modernization framework ([Nuget](https://www.nuget.org/packages/SharePointPnPModernizationOnline), [source code](https://github.com/SharePoint/PnP-Tools/tree/master/Solutions/SharePoint.Modernization/SharePointPnP.Modernization.Framework)) does bring page transformation capabilities which will be explained in the upcoming chapters.
1313

1414
> [!IMPORTANT]
15-
> The SharePoint PnP Modernization framework is currently in beta, checkout [the release notes](https://github.com/SharePoint/PnP-Tools/blob/master/Solutions/SharePoint.Modernization/Modernization%20Framework%20release%20notes.md) for more details. If you encounter problems please file an issue in the [PnP Tools GitHub issue list](https://github.com/SharePoint/PnP-Tools/issues).
15+
> The SharePoint PnP Modernization framework is continuously evolving, checkout [the release notes](https://github.com/SharePoint/PnP-Tools/blob/master/Solutions/SharePoint.Modernization/Modernization%20Framework%20release%20notes.md) to stay up to date on the latest changes. If you encounter problems please file an issue in the [PnP Tools GitHub issue list](https://github.com/SharePoint/PnP-Tools/issues).
1616
1717
## Before you start
1818

@@ -32,17 +32,6 @@ Connect-PnPOnline -Url "<your web url>"
3232
Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force
3333
```
3434

35-
## Overview of the page transformation solution
36-
37-
Below picture explains the page transformation in 4 steps:
38-
39-
1. At the start you need to tell the transformation engine how you want to transform pages and that's done by providing a page transformation model. This model is an XML file which describes how each classic web part needs to be mapped to a modern equivalent. Per classic web part the model contains a list of relevant properties and mapping information. See the [Understanding and configuring the page transformation model](modernize-userinterface-site-pages-model.md) article to learn more. If you want to understand how classic web parts compare to modern web parts it's recommended to checkout the [Classic and modern web part experiences](https://support.office.com/en-us/article/classic-and-modern-web-part-experiences-3fdae6c3-8fc1-49ab-8708-8c104b882e64) article.
40-
2. Next step is analyzing the page you want to transform: the transformation engine will break down the page in a collection of web parts (wiki text is broken down in one or more wiki text web parts) and it will try to detect the used layout.
41-
3. The information retrieved from the analysis in step 2 is often not sufficient to map the web part to a modern equivalent and therefor in step 3 we'll enhance the information by calling functions: these functions take properties retrieved in step 2 and generate new properties based upon the inputted properties from step 2. After step 3 we have all the needed information to map the web part...except we optionally need to call the defined selector to understand which mapping we'll need in case one classic web part can be mapped to multiple client side configurations.
42-
4. The final step is creating and configuring the client side page followed by adding the mapped modern client side web parts to it.
43-
44-
![page transformation](media/modernize/pagetransformation_1.png)
45-
4635
## Quick start to page transformation for .Net developers
4736

4837
The page transformation engine is built using .Net and is distributed as a [nuget](https://www.nuget.org/packages/SharePointPnPModernizationOnline) package. Once you've added the nuget package you'll see that 2 additional files are added to your solution:
@@ -67,6 +56,8 @@ using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl, userNa
6756
{
6857
// If target page exists, then overwrite it
6958
Overwrite = true,
59+
// Migrated page gets the name of the original page
60+
TargetPageTakesSourcePageName = true,
7061
};
7162

7263
try
@@ -88,6 +79,17 @@ The page transformation engine can also be used from PowerShell. This allows it
8879

8980
[!code-powershell[transformpages](../../PnP-Tools/Solutions/SharePoint.Modernization/Scripts/PageTransformation/TransformPageSample.ps1 "Transform pages to modern pages using PowerShell")]
9081

82+
## Page transformation high level architecture
83+
84+
Below picture explains the page transformation in 4 steps:
85+
86+
1. At the start you need to tell the transformation engine how you want to transform pages and that's done by providing a page transformation model. This model is an XML file which describes how each classic web part needs to be mapped to a modern equivalent. Per classic web part the model contains a list of relevant properties and mapping information. See the [Understanding and configuring the page transformation model](modernize-userinterface-site-pages-model.md) article to learn more. If you want to understand how classic web parts compare to modern web parts it's recommended to checkout the [Classic and modern web part experiences](https://support.office.com/en-us/article/classic-and-modern-web-part-experiences-3fdae6c3-8fc1-49ab-8708-8c104b882e64) article.
87+
2. Next step is analyzing the page you want to transform: the transformation engine will break down the page in a collection of web parts (wiki text is broken down in one or more wiki text web parts) and it will try to detect the used layout.
88+
3. The information retrieved from the analysis in step 2 is often not sufficient to map the web part to a modern equivalent and therefor in step 3 we'll enhance the information by calling functions: these functions take properties retrieved in step 2 and generate new properties based upon the inputted properties from step 2. After step 3 we have all the needed information to map the web part...except we optionally need to call the defined selector to understand which mapping we'll need in case one classic web part can be mapped to multiple client side configurations.
89+
4. The final step is creating and configuring the client side page followed by adding the mapped modern client side web parts to it.
90+
91+
![page transformation](media/modernize/pagetransformation_1.png)
92+
9193
## See also
9294

9395
- [Modernize your classic SharePoint sites](modernize-classic-sites.md)

0 commit comments

Comments
 (0)