Documenting the PKB app

The Public Knowledge for Mobile, Web and Facebook works well enough, but it is coded badly and is really difficult to customise. 

I HAVE to get to the bottom of this because I have to get a developer to make it able to be multi-branded. Here is my documentation on unpacking this beast to see how it works. 

Overview

I love the PKB App, but I need some additional features - notably multiple branding. It can look and function exactly like PKB2 but if it looks nicer that would be great. I need

• Multi Language
• Multiple brands
• Faceted Search
• Share this (just print and email)
• A better support ticket function (nicer looking, more questions)

I don't need

• Facebook 
• Deflection

Most importantly it needs to be able to be used with the ServiceCloud share Knowledge Article via URL feature https://help.salesforce.com/ap ex/HTViewSolution?urlname=Know ledge-One-widget-Share-an-arti cle-as-a-URL-Email-an-article- as-a-PDF-unavailable&language= en_US 

Structure

Pages

• pkb_Home VF Page is the first page that is called when the visitor comes to the site. This is set up in the Sites settings as the Active Site Home Page. It is not visible in the URL as the Path as defined in the sites is shown only. eg xxxx.force.com/mykb is xxxx.force.com/mykb/pkb_Home 
  • All this page does is call pkb_Template 
  • and sets the controller as pkb_Controller
  • and gets the Language from the URL
  • Structure
    • Apex
      • Turn off all SF look
        • standardStylesheets="false"
        • showHeader="false"
        • sidebar="false"
      • Controllers
        • Extension - pkb_Controller
      • Parameters
        • language = CurrentPage.parameters.1
      • Composition
  • The Good
    • There is no CSS in this page. 
  • Notes
    • Create your own Home Page name and set the Active Site Home Page in Sites to the new Home page - eg just Home rather than pkb_Home might be nicer. 
      • But for brands have brandXhome and brandyhome pages
• pkb_Home_fb the Facebook Home page - I'm ignoring this at the moment. 
• pkb_Template the main HTML layout of the page that is displayed when the visitor first sees your site - this is probably going to be the main page you customise. 
  • Notes
    • Controller - controls everything coming out of Salesforce
    • Javascript - sets some parameters
    • CSS - is everywhere
    • theKad - the variable name for the actual Data of the Article. This comes from the Controller
  • Structure
    • Apex
      • Turn off all SF look
        • standardStylesheets="false"
        • showHeader="false"
        • sidebar="false"
        • this is where the Externally viewed feature can be added - see slidedeck in links to the right
        • this is where you set your docType to be "html-5.0"
      • Controllers
        • Standard - KnowledgeArticle
        • Extension - pkb_Controller
      • Parameters
        • language = controller.selectedLanaguage
    • Head
      • Title = pageTitle from the KnowledgeArticle
      • Metadata
        • Article URL controller.CurrentSiteURL controller.SelectedLanguageURL typeName controller.theKad.UrlName
      • Static Resource - JQuery
      • Static Resource - JQuery Simple Modal
      • This is where you put the link to the favicon image
      • This is where you reference in bootstrap or similar to make your HTML easier to build
      • Header Text
        • Sets the article name in the tab text if viewing an article otherwise just shows the site name and the Home page name - eg My Knowledge Base - Home. 
      • Component - pkb_css
      • Component - pkb_js
        • Sends the parameter of the Controller
        • Change this to also send the parameter of the home page

          • <c:pkb_js pkbCon="{!pkbCon}" pkbHome="{!$Page.pkb_home}" />

    • Body
      • Debug values
      • Header
        • inline style for margin
        • Logo - Static Resource - pkb_logo
          • URL to Home page
          • with Language parameter xxxx.force.com/mykb/pkb_Home?l=en_US
      • Body Div
        • Left Column
          • Left Header
            • Inline Style for Height
          • (no div)
            • Immediate Help
              • Custom Label PKB2_Answers_Might_Help
          • Left Content
            
            • Faceted Search Component - pkb_narrow
            • Contact US
              • Custom Label PKB2_Contact_Us_Link_Prompt
              • Custom Label PKB2_Contact_US
              • Sets parameters for Contact US - Value, Feedback, Language
            • Related - Component - pkb_related (if viewing article)
        • Right Column
          • Right Header
            • Search - Component - pkb_search
            • Inline Style for Height
          • Right Content
            • If no articles are shown
              • Featured Article List - Component - pkb_featured
              • Popular Articles List - Component - pkb_popular
              • Search Results - Component - pkb_results
              • Contact Us - Component pkb_contactus_buttons_article
            • If Articles are shown
              • Backlinks (a parameter in the pkb_articleview component - showBackLinks="true") 
              • Article Content - Component - pkb_articleview
              • Feedback (a parameter in the pkb_articleview component - showFeebackYesNo="true") 
      • Footer Div
        • Powered by SFDC Logo
          • Has Class and Inline Styles
    • Customising
      • Set up a new template for each brand eg pkb_temp_brandx
    • The Bad
      • Inline CSS
      • Not responsive
    • The good
      • Nice use of hiding things and showing things based on what is happening
      • Simple two column layout
      • Straightforward HTML

Components

HTML

• pkb_results
  • Parameters (Attributes)
  • showHeaderInfo - shown if there are no results found
  • Results is a HTML Form
  • Div id=results
    • If Header info is shown
      • Search Results - Custom Label - PKB2_Search_Results
      • div articleViewIcons - shows the RSS feed icon for this results list
      • probably get rid of this
      • Custom Label - PKB2_You_Searched_For then shows what you searched for
      • If you searched within a category it shows the category with a Custom Label - PKB2_Within_Category and then the Category Label
    • Recommended Articles
      • Component - pkb_article passing in parameters
        • Article ID
        • Title
          Summary
        • URL Name
        • Article Type Name
        • Article Type Label
        • Last Modified Date
        • first Published Date
        • Last Published Date
      • Or displays no results found.
      • Custom Label - PKB2_Recommended
    • Article List
      • Sets up variables for Articles per page, categories, keywords, page numbers and language
      • Shows the Component - pkb_article - passing int he same parameters as above. 
    • Javascript to show more results or shows No Results Found
    • If No Results Found
      • Display Contact Us
        • Has Inline CSS for margin
        • Custom Label PKB2_No_Results
    • Results Pagination Links
      • Has Inline CSS
      • Has apex facets
      • Has static resource pkb_loadingdots
      • Custom Label PKB2_Next_Link and PKB2_Previous_Link
    • If Contact Us should be displayed
      • Javascript to prepare to render the overlay - calls a function 

        prepareToRenderOverlay() but I have not found where that is yet.

    • Something in here also for Javascript function to hideImmediateHelp - I still have not worked this one out. 
• pkb_article - this is the main HTML for viewing the article summary in a list - this is only called from Component - pkb_results. I would not do too much customisation to this, unless you have different fields you need to display from your article types. 
  • Parameters (Attributes)
    • Article ID
    • Title
      Summary
    • URL Name
    • Article Type Name
    • Article Type Label
    • Last Modified Date
    • first Published Date
    • Last Published Date
  • Sets Variables
    • typeName uses Controller.kavExtension
    • feedback - the source of the feedback it seems to be
    • pageNum - the page number this article is displayed on
    • params - The search parameters
    • siteArticleURL - controller.CurrentSiteURL controller.SelectedLanguageURL typeName UrlName
    • nonSiteArticleURL - the ID of the Article for if this is displayed from inside Salesforce. 
    • articleURL - sets up if it should display the site or non site URL
  • Div Article - displays the Title with the URL to the Article - uses the Variables articleURL and params to work out the correct URL
    
    • Div Data - displays the Article Type Label and the firstPublishedDate - eg my Article type is Knowlege 15 May 2001
      • Remove the Article Type if you don't have multiple types on display. 
      • Change date to Last Updated Date: 15 May 2001
    • Div Content
      • Summary - only shows the first 255 chars then a ... 
        
• pkb_articleview - this is the main article HTML. It's probably not wise to change this much - have the background of the article distinguished from the rest of the site. 
  • Parameters (Attributes)
    • The controller
    • showFeedbackYesNo
    • showBackLinks
    • Add an Attribute for what the Breadcrumbs should display as for each site
  • Sets variable for pageNum 
  • Div
    • inline styles for margin
  • Div - Class = articleViewIcons - shows the share this icons
    • Component - pkb_articleicons 
  • Div Backlinks - sets up the backlinks and breadcrumbs 
    • Dependant upon the toggle for displaySearchResultsLink in the controller
  • Div id = articleContainer
    • Inline styles for width

    OK, here is the crux of the whole thing - it uses an <apex:insert tag to insert the body of the article in here.

    Insert seems to be like an include page. Now to find out where the body is defined... I have no idea.

     

    • Output panel with inline sytels for margins
    • Weird code to not display the article content if you are displaying through standard apex - weird. 
  • Shows component pkb_related only if it's facebook - WHY? 
  • Shows component pkb_feedbackyesno if showFeedbackYesNo is true
    
    • Replace this with a 5 star rating
• pkb_articleicons - the Share This icons - all call a JS source or URL or even iFrame - now, calling an external javascript from a Salesforce page is not allowed is it? 
  • Div
    • inline CSS
    • Google Plus
      • not needed anymore
    • Facebook
      • get rid of it - you are a business, not promoting scandals on Facebook. 
    • RSS
      • may be useful if you have RSS on the rest of your site. Otherwise delete it.
    • Twitter
      • Only if you are really strong on monitoring your twitter otherwise it HAS to go. 
    • Print
      • Yeah, probably keep it
    • Email
      • It just sends a URL to the article - not very useful
      • Yep, keep it. 

Javascript

• pkb_js 
  • Notes
    • This javascript is displayed in full view on a PKB site - you can copy all the javascript that another site using PKB has modified. 
  • takes parameter (attribute) of the controller 
  • Change this to also take the parameter of the home page
  • Has JQuery
  • Has JQuery to detect if the browser is a mobile device. 
    • Remove this when making your HTML responsive
  • Sets some variables - these are captured from the Apex controller and stored in JS variables so the javascript can use it - noted only important ones. 
    • baseURL - pkbCon.currentSiteURL
    • currLanguage - pkbCon.SelectedLanguage
    • contactUS - pkbCon.displayContactUs
    • viewingArticle - pkbConViewingArticle
    • pkbHome - 

      "{!IF(pkbCon.facebook,$Page.pkb_Home_fb,$Page.pkb_Home)}";

      Nope, you don't want this, you don't need Facebook - you want the home page passed in from the template

  • Functions
    • These are well documented. 
    • searchButtonClicked
      • Displays the error message from custom label - PKB2_js_search_string_length when there is less than 3 chars entered. 
    • There are some functions to 
      • toggle when feedback is displayed
      • show or hide featured articles
      • show or hide the contact form
    • To adjust the height of the right column. 

Controller

• Terms 
  • KAD = KnowledgeArticleData
  • KAV = KnowledgeArticleVersion
• This is the interface between the Salesforce data and the HTML
• It does all the queries and the logic
• Do not mess around with this - you will break things
• Definitely do not change anything that comes from CUSTOM SETTINGS
• Some things you may want to change. 
  • // populate the case data 
    • To add extra fields to the Case
    • Also look at the CONTACT US FOR WRAPPER CLASS
  • // attempt to create the account and contact if configured to do so
    • To add extra Contact and Account fields
  • // send email only if siteAdmin isn't null
    • To send the Case email with different fields

Still to do:

• Where does the body of the article display come from
• How does the language work
• Where to pass in the site name