You can find tips for configuration of the Version Controlled Documentation in this article to help you implement changes for fulfilling your organization needs.
Configuration
Name of the version controlled documentation
There is a message with the code page_title. It represents name of the documentation that is displayed in the page headline and also in the browser tab title.
Languages
You can add whatever language into the documentation. Just add a new record into the class Language.
Default language
One language should be set up as a default one. It is the language of the article that will be displayed if the article will not have a text in the required language. All the articles should have a text in this default language.
The setting is performed by means of a parameter Default language for articles. Enter a language code, e.g. en-US, cs-CZ, de-DE...etc. in the parameter.
Default article
In case of article display request the article is searched in the database by URL or article number. However, if the article is not found, a univeral article is displayed. It is necessary to inform users in this article that the searched article was not found, due to which possible reasons and how they can continue in search.
This default article has to be created and its ID should be defined in the parameter Default article.
Appearance of the Version Controlled Documentation
Appearance of the documentation is defined in the page article. If you need to change it, then modify the page scheme.
At the same time adapt also references to the social networks and include also other webs that you are using.
Access to pictures
Anonymous user that will work with the documentation has to have access to pictures used in the documentation. However, pictures can be accessed by authenticated users only in a standard way. We will ensure anonymous access by adding file web.config with below stated content into the folder with pictures.
<?xml version="1.0"?>
<configuration>
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</configuration>
Development
The whole documentation as it appears to the article reader is implemented in a single page Version Controlled Documentation. Loading of articles and menu from the database and searching is performed by scripts in the page. The display of the searched article is performed by the webpart script that is inserted into the page.
Change of appearance and colours
If you need to customize the appearance according to your company colours or change the layout, modify the scheme of page Version Controlled Documentation.
Changes in styles can be performed in file Modules/OG.VersionDoc/VersionDoc.css (it is attached in the webpart script with code common).
The appearance of the displayed article can be changed in the webpart script with code text. In this way you can display value from a new column that you add to the article or just slightly change the appearance.
Social networks
There are links to social networks in the scheme of the page Version Controlled Documentation. Update their url and add another webs or social networks that you are using in your company.
<a href="https://www.linkedin.com/company/objectgears" title="LinkedIn" target="_blank" class="nsp"><img src="modules/OG.VersionDoc/linkedin.png" /></a>
<a href="https://twitter.com/ObjectGears" title="Twitter" target="_blank" class="nsp"><img src="modules/OG.VersionDoc/twitter.png" /></a>
<a href="https://www.facebook.com/objectgears" title="Facebook" target="_blank" class="nsp"><img src="modules/OG.VersionDoc/facebook.png" /></a>
Redirect to VCD
The Documentation is implemented as a page in ObjectGears. Such a page has a standard url in the following format: WebContentPage.aspx?Id=80. This is not a nice address, however, ObjectGears provides you with an opportunity to work with url according to your preference. We are routing to addresses like VCD/....in Version Controlled Documentation. This is performed in the application event After application start.
var m = OG.Model.GetByCode('vcd');
var cp = OG.ContentPage.GetAll().GetByCode(m.Id, 'article');
var r = OGRoute.Create('vcd_an_v', 'vcd/{lang}/an/{an}/v/{version}', '~/WebContentpage.aspx');
r.AddPar( 'id', cp.Id.ToString());
r.AddPar( 'version', '');
r.AddPar( 'lang', '');
r.Use();
...
There are several addresses configured like this which you can use to access the documentation. You will utilize this e.g. when sending URL requests from another systems that should display search results. We are showing several examples below:
vcd
vcd/{lang}/an/{an}/v/{version}
vcd/{lang}/tag/{tag}
vcd/{lang}/search/{search}
Redirect from the original documentation
There was a previous documentation under domain doc.objectgears.cz in the past that was not implemented in ObjectGears system and that was accessed by means of url Help.aspx?h=... However, such an url does not exist in ObjectGears system. Because somebody can still use these addresses we have created a routing to the correct address in the application event After error occurence.
if ( OGErrorInfo.IsInvalidPage && OGErrorInfo.Request.Url.AbsolutePath.ToLower().Contains('help.aspx'))
{
OGErrorInfo.RedirectPermanent = true;
OGErrorInfo.RedirectToUrl = './vcd/en-us/' + OGErrorInfo.Request.QueryString['h'] + '/v/1.7.1.0/';
}
Routing from / to VCD
If the user types in the browser just doc.objectgears.cz, then Login.aspx for user login would be displayed as a standard response. Usual article readers do not have ObjectGears account and therefore in order we avoid displaying this logon page, we have added a routing in the application event At the beginning of web request to the page VCD.
//routing from default.aspx to VCD
var url = System.Web.HttpContext.Current.Request.Url.AbsolutePath.ToLower();
if ( !OG.Person.IsAnyLogin() && (url == '/' || url == '/default.aspx'))
{
System.Web.HttpContext.Current.Response.Redirect( OG.GetWebUrl() + 'vcd');
}
Priority of article sorting at search
Search results are sorted according to the relevance. The searched text can be found in several article properties. Since each occurence type has a different relevance it has different points assigned. We sum up points for each found article (points for each occurrence type are multiplied by number of occurrences in that type) and articles are listed to users in this order.
The point evaluation is set up in a script in the page Version Controlled Documentation in the function FindByText. If you need to search also in another columns, then adapt the corresponding SQL command and allocate new points as needed.
Table with points:
| Occurrence |
Points |
| Article number |
100 |
| Article text URL |
50 |
| Tag in the article |
25 |
| Title of the article text |
15 |
| Meta Description of the article text |
3 |
| In the article text |
1 |
Logging of erroneous search
If no article is found, default article is displayed. At the same time a new record in the class wrong_search is created which contains what the user was searching for. In this way you can reveal links from other pages or external sources that do not exist.
The record is created by method LoadArticle in the script in page Version Controlled Documentation:
if ( firstArt == null)
{
//save the searched article that was found
var clBad = OGModel.ClassDefs['wrong_search'];
var drBad = OG.DataRow.CreateNew(clBad.Id);
drBad['an'] = an;
drBad['url'] = url;
drBad['topic'] = topic;
drBad['loc'] = loc;
drBad['version'] = v;
OG.DataRow.SaveData(drBad);
//if the user does not have access rights or the article was not found, default article is returned
firstArt = FindArticle(null, null, null, loc, null, OG.DataParameter.GetDataParameter( OGModel.Id, 'no_rights').ValueInteger, null, isEditor);
}