This issue of having user manuals online and if possible, that it is contextual to the point where you request help is something that I have been worrying about since the beginning of my programming (1972).
In all these years I have worked on different platforms, architectures and solutions, so I have been adapting the solutions to each of them.
In recent years, almost all applications are of web architecture, so initially the approach was to make these contextual aids in HTML format, but the reality and maintenance difficulties have forced me to use a single format (PDF) Both for the application manual used in the training (if it exists) and the online and contextual manual.
I have tried to use tools (very expensive) that from a single source is capable of generating the document in PDF and in HTML format, but I have dismissed it as expensive, difficult to use and not good results in either PDF or HTML.
What do I use for both SAP applications and PHPRunner applications (large and small)? Well, something simple, I use Word as a tool to create content and PDF format for Training Manuals and online and contextual help. This simplifies the creation and maintenance of the materials and the (contrasted) result is pleasant and practical for end users.
The aspect would be:
The orange button is the one that requests contextual help and manages the opening of another tab with the requested information.
You can use a button anywhere on the screen, loose, as is the case or integrated into the header menu, this will be defined by the developer of the application.
The appearance of the contextual help tab is:
We see that it is the visualization of the PDF, opened by the page that explains the project option and an important aspect, on the left side is the document index to jump from one point to another and review the information in the manual.
This article explains what to do to:
- Build the WORD document with the required structure.
- Build the PDF from Word, with the required characteristics.
- How we integrate it (it is one of the possibilities) in the PHPRunner developments.
You can see the operation (DEMO) at: https://fhumanes.com/meetings2
Use the username and password (admin/admin)
Construction of the Word document
It is quite complex for me to describe all the aspects that all documents should have, therefore, at the end of the article, I leave examples of all document formats, so that what I have not described with sufficient description can be seen in them.
Word documents must have a table of contents, my proposal is that each of the options or pages be at the level of "Title 1" and that they start on a new page. That it does not have more than 2 or 3 levels, depending on the length (number of pages) of the document.
In case you want to make links between part of the text, these can be defined in the Word document by means of "Cross references" and "Bookmarks"
In addition, hyperlinks can be established to integrate videos, etc. I am not an expert in Word, nor do I have the latest version of the product. Normally I use Word 2007 and with it I get to do everything I need.
Construction of the PDF document
In my Word 2007 version I had to install the plugin to get PDF documents and that plugin is all we require to create the PDF document from Word.
The options with which the document is exported are very important. As there are many versions of Word, I leave you the image of the export of my Word
Well, it is that simple and it is all there is to do.
Integration of the manual in contextual help in PHPrunner
As I indicated this is one of the possible ways, because the important thing is to know how we can open the PDF document in a new tab, on a certain page and with the index of the PDF document to the left of it.
An example of a URL to build is:
Button programming:
As we all know, in PHPRunner a button has 3 parts in the coding:
- Javascript. Client. Before passing control to the PHP server code.
At this point we collect the URL information for the construction of the PDF URL and to know on which page the user is located.
- PHP. Server. Composition of the URL.
It is identified if the APP is working in several languages.
Identify the file with the “pdf” extension in the manual and choose the language in which you are working.
The name of the file is independent for each one to version as they deem most appropriate or to be marked by their organization.
Search the “help” table for the number of the PDF page, according to the name of the application page. If not found, it will be positioned on page 1.
- Javascript. Client. Opening a new window with the PDF document
With the PDF URL, built on the server, open a new window and run that URL.
The code used is generic and exposed to any application, provided that solution satisfies.
Client Before:
params["url"]= window.location.pathname; // local URL page
params["host"]= window.location.hostname; // local URL page
params["protocol"]= window.location.protocol; // local URL page
Server:
include "ICM/help.php";
help.php:
<?php
$chunks = explode("/", $params["url"]); // Separate from URL the application name and the option you are running
$app = $chunks[1];
$comand = explode(".", $chunks[2]);
$option = $comand[0];
$extension = $comand[1];
$directory_help = __DIR__.'/../help/'; // Directory of files PDF
$files_help = scandir($directory_help);
$language = $_SESSION['language']; // Language in WEB
$help = ''; // File PDF od Help
if ($language <> NULL) {
for($i = 0; $i < count($files_help); ++$i) {
$chunks = explode(".", $files_help[$i]);
if ($chunks[1] == 'pdf' || $chunks[1] == 'PDF' ) {
$help = $files_help[$i]; // In case the language file is not found
$chunks = explode("_", $files_help[$i]);
if ($chunks[0] == $language) {
$help = $files_help[$i]; // Found the language manual file
break;
}
}
}
} else { // It has no language
for($i = 0; $i < count($files_help); ++$i) {
$chunks = explode(".", $files_help[$i]);
if ($chunks[1] == 'pdf' || $chunks[1] == 'PDF' ) {
$help = $files_help[$i]; // In case the language file is not found
break;
}
}
}
$page = 1; // Default page in PDF
// Find the page of the displayed page for contextual help
$sql = "SELECT pageNumber FROM help WHERE comand = '$option'";
$resql = db_query($sql,$conn);
if ($resql->num_rows <> 0) { // Found
$row = db_fetch_array($resql);
$page= $row['pageNumber'];
}
$pdf = $params["protocol"].'//'.$params["host"].'/'.$app.'/help/'.$help.'#pagemode=bookmarks&page='.$page; // https://localhost/fdfdfdf/manual.pdf
$result["pdf"] = $pdf;
?>
Client After:
var pdf = result["pdf"];
// ajax.setMessage(pdf);
var myWindow = window.open(pdf,'_blank');
As always, in my portal you have all the documentation and examples and if you want any information or clarification, you can contact me in my email account [email="fernandohumanes@gmail.com"]fernandohumanes@gmail.com[/email]
fhumanes author