|
| 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 | +``` |
0 commit comments