DYNAMIC FAQ AND DOCUMENTATION PAGES IN SHAREPOINT A modern, reusable, and easy-to-use model

Use Case: Building Better Documentation ■Requirements –Create template structure for authoring and navigating documentation and FAQs –Design must be extremely simple for authors not familiar with SharePoint to use –Organization of content should be “baked in” to the design –Viewers should be able to navigate like a normal website – again, no knowledge of SharePoint required –Documents (Word, PDF, etc) not an option –Content must be searchable

Design Process: Initial Ideas ■Pages (versus Lists) –Custom page layouts –Custom navigation elements –SEO ■Metadata, metadata, metadata! –Managed metadata –Hierarchies ■The (n)ever popular CQWP ■Javascript ■CSS

Designing the Layouts ■Documentation versus FAQs –FAQs grouped together according to topics in Question/Answer format –Documentation grouped together according to topics, but generally verbose and less predictable content pattern ■2 Page Layouts for each type –“Landing” page – designed to introduce a topic (documentation) or display all content under a topic (FAQs) –Content Page – holds the actual content/documentation/FAQ Question/Answer

Designing the Layouts (cont) ■Building the Content Types –Standard approach to content types ■You can create 2 content types to support each layout or ■You can create a single content type for both and differentiate solely by layout and other metadata –Metadata column definitions ■Lots of metadata to support design

Designing the Layouts (cont) ■Basic design plan –70x30 layout –Fixed navigation elements on right rail –Editable content area in main panel –FAQs – Listing of sibling FAQs under a given topic –Documentation – Listing of sibling documentation pages under a given topic Breadcrumbs Title Related Topic Landing Pages Editable Content Area Related Content

Designing the Layouts (cont) ■Creating the “dynamic” aspect: metadata –Parent Topic ■Used to create the super-categories of content; uses managed metadata –Current Topic ■Used to identify the current category of content; uses managed metadata –Page type ■Simple Choice column

Designing the Layouts (cont) ■Build page layouts based on content types –General rule: Use the Authoring Panel to configure your design for Authors and Viewers. Authors will need to see and manage all page metadata, but viewers will not. –3 Edit Mode Panels (one for author editing, one for author viewing, one for viewer viewing)

Designing the Layouts (cont) ■Link stylesheets and (if needed) javascript. –Tip: Although this example uses embedded javascript, for performance purposes you should point to a.js file ■Performance (caching) ■Maintenance (one place to edit) ■Sometimes it’s just necessary to insert code inline, though ■Alternately, css or js code can be injected at author design- time by using an HTML Form Web Part

Designing the Layouts (cont) ■Web parts embedded on the page –One CQWP for topic-wide navigation –One CQWP for intra-topic navigation (or display, as in FAQs) –One custom CQWP used to display custom breadcrumbs

Designing the CQWPs ■Challenge: Making the web part generic for any site in the site collection –By using Pages instead of lists, one is always assured that the list name will ALWAYS be called Pages –Didjaknow? You can dispense with the GUIDs in the CQWP and reference items by name or SP object (e.g. ~site)? Manually edit the.webpart file’s XML to do this.

Designing the CQWPs (cont) ■Making the Dynamic pieces –CQWP filtering based on fields on current page –Use Custom Item Style XSLT (less clutter) –Make it possible for users to do custom sorting –Always use CSS to style your content ■Ease of maintenance ■Easier to use jQuery to manage things like an accordion-style interface ■Necessary for responsive design

Designing the CQWPs (cont) ■Embedded FAQ Accordion Script –Yes, jQuery is probably overkill –Yes, this should have been in a.js file and referenced from the layout

Designing the CQWPs (cont) ■Design tip: define the CQWPs on your pages using the appropriate layouts. –Once correctly configured, you can export them for reuse –In order to insert the web parts into a page layout in SPD, you’ll need to add them to the Web Part Gallery in your site collection

Putting it all together Documentation Topic/Landing Page Documentation Subtopic Page (no children)

Putting it all together (cont) ■Metadata to support a Landing Page ■Metadata to support a Subtopic page

Putting all together (cont) ■FAQ Accordions in Action

Putting all together (cont) ■Under the covers….

■Some Administrative tips –Keep Documentation and FAQs in separate subsites –Use Default Page Layouts for each (make sure to use the Topic Content pages versus the Landing Pages)

Putting it all together (cont) ■Final touches – Custom Breadcrumbs –Based on a custom content type –List-driven –Embedded script determines if the custom breadcrumbs should be displayed or the SP default breadcrumbs

Putting it all together (cont) ■The CQWP code and the breadcrumb controls in the layout, plus script

Conclusion