DocAPI.v1.Content

hidden class DocAPI.v1.Content extends %Library.RegisteredObject

This class, which supports DocAPI.v1.REST, provides an API to retrieve content from the DocBook database. Depending on the element accessed, it returns either a table of contents or the full content (every last character). The methods in this class can return either an instance of %Library.DynamicObject or a JSON string. The returned object has the following properties:

• dbtype - indicates the DocBook element type of the returned unit. This is provided so that the client can style appropriately.
• topid - indicates the DocBookId of the containing book or article, if any.
• displayType - one of "toc", "para", "page", or "mixed".
• key - indicates the DocBookId of the returned unit.
• url - URL needed to access this content.
• title - contains the title of the returned unit.
• text - contains the text of the returned unit.
• subtitle - contains the subtitle of the returned unit. This property is included only if the item has a subtitle.
• navigator - an object that contains navigation information for the returned unit. This object has the following properties:
  • locator - an array of objects, each of which corresponds to a higher heading level. This array goes down to the sect3 level (if applicable). The first item in the array identifies the book or article. The second item identifies the chapter, appendix, or other unit at that level. The next item identifies the heading level below that, etc. Each object in this array has two properties: key (the DocBookId of that item) and title.
  • previous - identifies the "previous" item at the same level, if any. This is an object with three properties: key (the DocBookId of that item), url, and title.
  • next - identifies the "next" item at the same level, if any. This is an object with three properties: key (the DocBookId of that item), url, and title.
• children - a hierarchy of objects that collectively represent the content found within the given unit. Each object in this hierarchy can have the same properties as given in this list.

These methods have the following arguments:

• DocBookId -- this is the value you provide via the KEY parameter in a request to the DocBook app. This value corresponds to the blockid field in the database; each record has a unique blockid. The DocBookId value is case-insensitive (although our custom is to have the first part in all caps). There is one hardcoded special values for the argument:
  • ALL - gets an object that contains all the SETs followed by the group of articles (TOC content only).
• lowestSectLevel -- specifies the lowest <sectn> heading to include. This argument is used in all scenarios where we are returning a table of contents, as follows:
  • -1 means that we get only <book> or <article> elements (nothing lower).
  • 0 means that we also get <chapter>, <appendix>, <preface>, <glossary>, and <reference> elements, but nothing lower than that. Note that each of these items is currently (in the existing DocBook app.) displayed as a single page; we will stick with that paradigm. EXCEPTION: For a part within a book, lowestSectLevel=0 means that we get both <part> and its <chapter> elements. There didn't seem to be any reason to get only the parts.
  • 1 means that we also get <sect1> and <refentry> elements, but nothing lower than that.
  • 2 means that we also get <sect2> elements, but nothing lower than that. This is the default.
  • 3 means that we also get <sect3> elements, but nothing lower than that.
  • 4 means that we also get <sect4> elements, which is currently the lowest supported <sectn>.

  For ALL, it's probably best to specify lowestSectLevel as 0 or 1 at the most.

Method Inventory

• GetContent()
• GetContentFromOBJ()
• GetExternalDoc()
• GetFlattenedContent()
• GetHomePageArray()
• GetIndexTokens()
• GetLoadType()
• GetLoadTypeFromFilename()
• GetNavParents()
• GetNavParentsArray()
• GetPageCount()
• GetShowPageTOC()
• GetTOC()
• GetTopIdFromKey()
• GetTypeFromKey()

Methods

classmethod GetContent(DocBookId As %String = "", getDescriptions As %Boolean = 0) as %Library.DynamicAbstractObject

This method is the primary way to retrieve content.

There are some special values of DocBookId:

• GSTD_SYNTAX is hardcoded to get content for ROBJ_classdef, for reasons of history.
• GSTU_INSTDIST_INSTALLER is hardcoded to get content for GCI_manifest, for reasons of history.
• GettingStarted is hardcoded to get the home page.
• ALL is hardcoded to get "all content" -- a generated structure
• NOHELPFOUND gets the "no help found object". For this, if GSA is loaded in the database, the content object displays the table of contents for that book. If GSA is not loaded, the content object says to see the System Administration Guide, but there is no link.

Given a DocBookId, GetContent() returns an instance of %Library.DynamicAbstractObject that contains the content of that DocBookId, according to these rules.

• If DocBookId corresponds to a <set>, a <book>, or a <reference>, the "content" is just the table of contents for that element.
• If the DocBookId is any of the special hardcoded items, the "content" is a table of contents.
• In all other cases, the object contains the full content of the given DocBookId.

In other words, apart from the ability to control the TOC depth, what you get back is the same content we currently display in the application given any of those DocBookIds.

classmethod GetContentFromOBJ(object As %DynamicObject) as %String

classmethod GetExternalDoc() as %DynamicObject

classmethod GetFlattenedContent(key As %String) as %String

classmethod GetHomePageArray() as %Library.DynamicArray

classmethod GetIndexTokens(DocBookId As %String = "") as %DynamicArray

classmethod GetLoadType(docbookid As %String, ByRef topLevel As %Boolean) as %String

Given a DocBookId, return the loadtype of item so that we know how to load it. The types are "article", "component" (a file within a book), "book", "set", and "navpage"

classmethod GetLoadTypeFromFilename(filename As %String) as %String

Given a complete path and filename, return the type of the file. See GetLoadType() for types.

classmethod GetNavParents(DocBookId As %String = "") as %String

Returns an $LB list of "parents" (all at the same level). This is the KEY of the container of the item.

classmethod GetNavParentsArray(DocBookId As %String = "") as %DynamicArray

Returns a dynamic array of "parents" according to the hierarchy determined by following links from the home page. Each object in the array has the properties title and url.

classmethod GetPageCount(DocBookId As %String = "") as %Integer

classmethod GetShowPageTOC(docbookid As %String = "") as %Boolean

Given a DocBookId, returns 1 or 0 depending on whether it is suitable show a page TOC in addition to the normal content returned by GetContent

classmethod GetTOC(DocBookId As %String = "", lowestSectLevel As %Integer = 2, includeDescriptions As %Boolean = 0, forRightTOC As %Boolean = 0) as %Library.DynamicAbstractObject

This method is provided to help with diagnosis.

Given a DocBookId (e.g., the value you provide via the KEY parameter in a request to the DocBook app.), this method returns an instance of %Library.DynamicAbstractObject that contains the TOC for that DocBookId. See comments for GetContent(). GetTOC() returns an empty object if the DocBookId does not directly contain headings.

classmethod GetTopIdFromKey(DocBookId As %String = "") as %String

Given a DocBook ID, return the Topid to which that item belongs

classmethod GetTypeFromKey(DocBookId As %String = "") as %String

Given a DocBook ID, return the name of the DocBook element it represents.

Inherited Members

Inherited Methods

• %AddToSaveSet()
• %ClassIsLatestVersion()
• %ClassName()
• %ConstructClone()
• %DispatchClassMethod()
• %DispatchGetModified()
• %DispatchGetProperty()
• %DispatchMethod()
• %DispatchSetModified()
• %DispatchSetMultidimProperty()
• %DispatchSetProperty()
• %Extends()
• %GetParameter()
• %IsA()
• %IsModified()
• %New()
• %NormalizeObject()
• %ObjectModified()
• %OriginalNamespace()
• %PackageName()
• %RemoveFromSaveSet()
• %SerializeObject()
• %SetModified()
• %ValidateObject()