Customizing your SharePoint sites using the SharePoint Theming Engine

2. Customizing your SharePoint sites using the SharePoint Theming Engine Jonathan Keslin, Senior Developer, Microsoft Lionel Robinson, Program Manager, Microsoft SPC326

3. Before we start... Session Feedbackchannels Yammer on the second screen experience Twitter: #spc326, #spc14, @MSFT_JKeslin, @LionelRo_MSFT Session evaluations on MySPC Find us after the talk Applause is appreciated 

4. Agenda

5. Theming overview

6. Demo Changing the look in SharePoint

7. Change the look • Ask how many have gone through the UX to gauge speed of demo • Go to SP site • Click change the look on getting started carousel • Composed looks - choose City • Make it your own • Change background • Pick orange on black palette • Pick Oslo layout • Pick typewriter font • Click try it out • Preview • Keep it

8. Under the hood Color palette Font scheme Background image Core product CSS Style Library _themes folder OR Theme Gallery

9. How it works Start with un-themed CSS _layouts/15[/<lcid>]/styles/Themable/*.css Style Library[/<culture>]/Themable/*.css For each file, iterate through the “interesting” bits Colors, font declarations, URL references Transform annotated lines If there’s an annotation preceding the “interesting” part, transform it based on the theme specification

10. Example /*[ReplaceColor(themeColor:"BodyText")]*/ color: #000; color: #fff;

11. Why theming? It’s the safest way to change colors and fonts New features will continue to match Variety through the ecosystem Other approaches are fragile Overriding product CSS creates dependencies on continued use of classes Custom CSS that targets product HTML creates dependencies on specific markup

12. Recoloring images

17. How it works for each themable CSS file { for each url(…) value in the file { if it is preceded with an annotation { recolor it } } }

18. Example /*[RecolorImage(themeColor:"BodyText")]*/background-image:url("myimage.png"); background-image: url("/_catalogs/theme/Themed/<HASH1>/myimage-<hash2>.themedpng");

19. Recoloring methods

20. Image recoloring methods Three methods to recolor with:

21. Tinting Maintain the luminance and alpha channels of each pixel, but replace the hue and saturation.

22. Blending For each pixel, average the red, blue, and green channels between the old and new colors, while maintaining the alpha channel.

23. Filling Set each pixel to the new color, but maintain the original alphachannel.

24. Recoloring regions

25. Recoloring regions Image clusters Multiple regions Rectangular region

26. Example /*[RecolorImage(themeColor:"ErrorText", method:"Filling", includeRectangle:{x:1,y:30,width:97,height:97})]*/background-image: url("spcommon.png");

27. Detaching

28. Detaching Recolor an image or region in more than one way Output a separate copy of the image rather than layering recoloring rules

29. Example /*[RecolorImage(themeColor:"Hyperlink", method:"Tinting")]*/background-image: url("myimage.png"); /*[RecolorImage(themeColor:"ErrorText", method:"Tinting")]*/background-image: url("myimage.png"); Last annotation wins, both lines point to the same image

30. Example /*[RecolorImage(themeColor:"Hyperlink", method:"Tinting")]*/background-image: url("myimage.png"); /*[RecolorImage(themeColor:"ErrorText", method:"Tinting", detach:"true")]*/background-image: url("myimage.png"); Different images with different recolorings

31. Example /*[RecolorImage(themeColor:"ErrorText", method:"Filling", includeRectangle:{x:1,y:30,width:97,height:97})]*/background-image: url("spcommon.png"); /*[RecolorImage(themeColor:"SearchURL", method:"Filling", includeRectangle:{x:1,y:30,width:97,height:97}, detach:"true")]*/background-image: url("spcommon.png");

32. Theming foreground images

33. Background vs. foreground Background images are defined in CSS files background-image: url(…); Foreground images are defined in HTML <imgsrc="…" />

34. Why foreground images?

35. How to theme foreground images

36. Part 1: CSS hashOverridemakes the output filename predictable /_catalogs/theme/Themed/<HASH1>/myimage-<hash2>.themedpng detachkeeps the foreground use separate from any background uses Doesn’t need to be loaded – just present in a themable path /*[RecolorImage(themeColor:"Hyperlink", method:"Filling", hashOverride:"myimage", detach:"true")]*/src: url("myimage.png");

37. Part 1: CSS /*[RecolorImage(themeColor:"Hyperlink", method:"Filling", hashOverride:"myimage", includeRectangle:{x:100,y:50,width:32,height:32})]*/src: url("myimage.png"); Works for clusters too Just skip the detach parameter

38. Part 2: ASP.NET ThemeKey attribute maps to the hashOverride in CSS If the site is themed, show the themed image Else, fall back to the original image Subclasses ASP.NET Image control Other attributes like CssClass and AlternateText work too <SharePoint:ThemedForegroundImagerunat="server" ThemeKey="myimage" ImageUrl="myimage.png" />

39. Part 2: ASP.NET <SharePoint:ClusteredImagerunat="server" ThemeKey="myimage" ImageUrl="myimage.png" OffsetX="100" OffsetY="50" Width="32" Height="32" /> Many other image controls accept ThemeKey attribute ClusteredImage, ClusteredHyperlink, see MSDN documentation for more

40. Part 2: C# SPUtility.GetThemedImageUrl("myimage.png" /* url */,"myimage" /* ThemeKey */); Get the expected URL for the themed image Not ideal – prefer the ASP.NET approach

41. Part 2: JS GetThemedImageUrl("myimage"); Get the expected URL for the themed image Only works within a CSR context Must register for the image in server-code for a Web Part Override GetThemedImages() and/or GetThemedLocalizedImages()

42. Theming your site logo

45. Demo Theming your site logo

46. Demo script – site logo theming • Show partner portal site and say we want to apply a logo to it • Show logo image • Explain that we want to theme three regions • Create CSS • In SPD, go to Style Library • Create Themable folder • Create blank CSS file inside • Add theme annotation rule with appropriate theme key • Save AND CHECK IN/PUBLISH the file • Edit master page • Edit seattle.master • Add ThemeKey attribute to SiteLogoImage control • Save • Add logo image via site settings in browser • Site settings -> Title, Description, and Icon • Add icon • Show site with new icon • Theme site • Show themed icon

47. Using font schemes and WebFonts