Help kao Web strana

U pola noći zazvonio je telefon - klijent kome ste instalirali najnoviju verziju programa nije znao kako da dođe do neke od osnovnih funkcija. Po završetku razgovora ležete u krevet svesni da ste sve to mogli da izbegnete izradom makar kakvog Help-a...
Vladimir Ilić

Jedna od najneophodnijih komponenti svakog programa je dobar sistem za pomoć - dobar Help daće korisniku vašeg programa mogućnost da sam pronađe rešenje problema. Help sistem Windows-a je od prvih dana unifikovan, pa svi ga programi koriste iste šablone, kojima se olakšava rad sa aplikacijom. Ipak, vremena se menjaju: Windows 95 i NT 4 omogućavaju da se u help ugradi animacija ili zvuk.
Jedno od rešenja je dobijeno korišćenjem HTML formata: koriste ga mnogi, pa ste verovatno primetili da je tokom instalacije Visual Studia 97 na disk prenesen i Internet Explorer 3.01. HTML help se, ma kako komplikovano delovao, Visual Basic-u 5 ugrađuje veoma brzo i efektno - sve što je potrebno bejzik već donosi sa sobom. Treba samo da povežete komponente u celinu.

Kreiranje Help-a

Pre nego što počnemo, proverite da li ste instalirali Internet Explorer 3 ili (još bolje) IE 4. Krenite od VB-ovog Application Wizard-a - po startovanju izaberite kreiranje Explorer Style aplikacije. U drugom prozoru Wizard-a selektujte View Help menije; po želji možete da koristite i resource fajl, mada on neće biti predmet ovog teksta. Sledeći ekran je najvažniji: izaberite korišćenje/kreiranje svog Web browser-a. Link za home page vam verovatno neće biti potreban, mada možete da umesto Microsoft-ovog stavite svoj URL. Najzad izaberite ime svog projekta (u našem slučaju ActiveHelp) i kliknite Finish. Tako ste napravili kostur aplikacije.
Unutar projekta dobili ste dva formulara (frmMain i frmBrowser). Prvi korak je da iz frmMain izbacite lvListView kontrolu i na njeno mesto ubacite brwWebBrowser kontrolu iz frmBrowser. Posle toga zamenite sva mesta gde se pominje listview kontrola novom browser kontrolom. Obratite pažnju na podešavanja kontrola unutar formulara, kada korisnik odluči da promeni njegovu veličinu. ToolBar koji će se kreirati prepravite tako da sadrži standardne browser komande (Back, Forward, Home, Refresh), u ImageList dodajte ikone za pomenute tastere, a View meni ispravite tako da sadrži: ToolBar, StatusBar, Refresh i Close opcije. Help meni može da sadrži poziv na vaš Splash screen.
Da bi Help mogao da radi, vaš program treba da komunicira sa njim. Postoje više načina da se to uradi. Jedan od njih je da Shell komandom startujete ActiveHelp.exe prosleđujući mu u komandnoj liniji parametre. Ovo je najlakše izvesti - na mestu gde je potreban Help prosledite:

Dim strActiveHelpPath as string strActiveHelpPath = App.path & ActiveHelp.exe RetVal = Shell(strActiveHelpPath /p ""D:\Projects\PCPressActiveHelp\MyHelp\"" /h ""D:\Projects\ PCPressActiveHelp\MyHelp\Helpindex.inx"" /i I101", vbNormalFocus)

Pretpostavka je da će se ovaj program nalaziti u istom direktorijumu kao i aplikacija. Prosledili smo: /p (prefiks za putanju do HTML fajlova), /h (ime osnovnog index fajla, čija će namena kasnije biti objašnjena) i /i, naziv teme koja treba da se prikaže prema index fajlu. Za raščlanjivanje parametara komandne linije iskoristićemo kod sa slike 1, što je ujedno i izgled naše Sub Main funkcije.
Programu treba proslediti parametre, koji će otvoriti odgovarajući HTML dokument i pozicionirati se na željeni tag. To radimo uz pomoć HelpIndex.inx fajla, čija struktura može da izgleda kao na slici 2. Ako želimo da korisnik, klikom na TreeView, otvori željenu temu ili stranicu, moramo da unesemo podatke o nodovima. To činimo uz pomoć HelpIndex.inx fajla: prvi parametar u drugom redu, I001, je index noda u listi, I000 za taj nod je član liste koji je roditeljski našeg noda (u ovom slučaju root), treći parametar Active Help Main Menu je tekst koji će se ispisati pored odgovarajuće teme. ActiveHelp-TOC.html je ime HTML fajla koji treba da se otvori, a 0 ili 2 su oznake kojim odvajamo teme od tekstova. Tako možemo da postavimo ikonu za imena celina, unutar kojih se nalazi jedan ili više tekstova.
Kada smo učitali spisak tema, treba da unesemo kod koji će reagovati na klik unutar treeview kontrole. U okviru TreeView_NodeClick događaja proveravamo da li je korisnik kliknuo na naslov teme, kada samo otvaramo treeview kontrolu (Node.Expanded = True), ili je izabrao jedan od tekstova koje treba prikazati u Browser delu forme. Ako je izabran neki od tekstova, koristimo kod sa slike 3.

HTML je sada svuda - čak i Help datoteke se u novim verzijama
Visual Basic-a i C++-a pripremaju u ovom jeziku.

Kada sam prvi put pokušao da izvršim program, browser je davao poruku o grešci (File not found), iako je i putanja do HTML dokumenta bila ispravna, a i on je bio na svom mestu. Posle više pokušaja došao sam do zaključka da "standardno" prikazivanje putanje tipa: C:\Test\Activehelp.html ne može da se primeni; treba koristiti file:///C:/Test/ActiveHelp.html. Ovu konverziju obavlja funkcija FstrConvertToURL sa slike 4.

Predloženo rešenje sa otvaranjem programa sa Shell funkcijom ima par ozbiljnih nedostataka. Ako na više mesta pozivate Help, možete zapasti u situaciju da istovremeno budu otvorene više instanci programa, što se rešava dodavanjem koda koji proverava da li je prethodna instanca aplikacije već startovana u form_load (program ćete naći kao jedan od MSDN knowleage base topic-a). Ako je startovana, treba ili da zatvorite prethodnu instancu, ili da joj prosledite potrebne parametre. Jedno od rešenja ovog problema je slanje podataka preko DDE linka, a drugi je izvođenje Help browser-a kao ActiveX komponente.

Kreiranje ActiveX-a

Elegantno rešenje komunikacije između vaše aplikacije i Help programa može se dobiti korišćenjem ActiveX-a, bolje reći ActiveX EXE komponente. Izabrao sam ActiveX EXE, jer radi u sopstvenom adresnom prostoru, pa se može sprečiti da njegov eventualni pad obori ceo program. Drugi razlog je što lansiranjem Help-a nećete morati da prekinete izvršavanje aplikacije.
Unutar programa kreiraćemo dve klase: ActiveHelp_Class), uz pomoć koje ćemo prikazivati željeni Help, i ActiveConnector, koja će omogućiti da više aplikacija koriste isti ActiveX, a da se tek terminiranjem poslednje klase oslobađa memorija. Da biste kreirali ActiveX EXE, kliknite na Project / Properties i izaberite Project Type: ActiveX EXE. Kao startup object kliknite na Sub Main, koji će u ovom slučaju biti prazan i jedina uloga će mu biti da podigne aplikaciju. Posle ovoga kliknite na Project prozor i dodajte Class Module, koji će te nazvati ActiveConnector, a u polju Instancing unesite 5 (Multi Use). Kod za inicijalizaciju klase je:

Private Sub Class_Initialize() If gActiveHelpClass Is Nothing Then Set gActiveHelpClass = New ActiveHelp_Class End If glngUseCount = glngUseCount + 1 Debug.Print "Initialize Connector "; glngUseCount End Sub

Dok je kod za terminiranje klase:

Private Sub Class_Terminate() glngUseCount = glngUseCount - 1 If glngUseCount = 0 Then Set gActiveHelpClass = Nothing End If Debug.Print "Terminate Connector "; glngUseCount End Sub

Kliknite na Tools i Add Procedure, izaberite Property i u polje za ime stavite ActiveHelpClass. Na osnovu toga kreiraćete funkciju:

Public Property Get ActiveHelpClass() As ActiveHelp_Class Set ActiveHelpClass = gActiveHelpClass End Property

Svuda se pominje ActiveHelp_Class koju ćemo sada kreirati. Dodajte još jedan ClassModule u project i dajte mu ime ActiveHelp_Class. U polju Instances stavite 2 - PublicNotCreatable. Ova klasa će komunicirati sa našom frmMain, a i njoj će klijent aplikacija prosleđivati parametre Help topic-a i item-a koje treba prikazati. Osim Class_Initialize i Terminate funkcija, napravićemo još public jednu funkciju, preko koje ćemo proslediti potrebne parametre (slika 5). Privatni član klase (Private mWorkForm As frmMain) smo već učitali u Class_Initialize, ovde ćemo samo podatke koje smo dobili kao parametre funkcije prebaciti u globalne promenljive i preneti fokus na naš formular.

Obaveštavanje klijenta

Ako želite da obavestite klijent program o nekom od događaja koji se desio tokom korišćenja ActiveHelp-a, možete da kreirate event-ove koje će primati vaš program. VB 5.0 omogućava kreiranje događaja, ali samo delimično: možete samo da napravite "kvazi događaj", tako što ćete svoju WithEvent funkciju "prilepiti" na neki od VB objekata (commandButton, menu, textbox...). Kada korisnik klikne na neki od objekata unutar formulara, recimo menu, aktiviraće se event procedura vaše klase i proslediti događaj klijentu. Da biste napravili event, u General-Declaration delu klase unesite: Private WithEvents mwmnuActiveHelp As Menu i tako ćete kreirati Event vezan za menu objekat programa. Još dodajte funkciju:

Private Sub mwmnuActiveHelp_Click() RaiseEvent ActiveEnd End Sub

Poziv ActiveHelp-a

U aplikaciju iz koje treba da se pozove ActiveHelp treba uneti sledeći kod u form_load:

'Učitavanje help Class Set mactClassQuickHelp = New ActiveConnector Set maxhClassQuickHelp = mactClassQuickHelp.ActiveHelpClass

A u General - Declaration forme:

Private mactClassQuickHelp As ActiveConnector Private WithEvents maxhClassQuickHelp As ActiveHelp_Class

U button-u koji treba da pozove help dodajt kod sa slike 6.

Šta je još ostalo

Da bi sve ovo atraktivno izgledalo, treba da dodate program koji će sinhronizovati TreeView kontrolu sa tekstom koji je prikazan u Browser-u. Kod za Back i Forward može se najlakše implementirati sa po linijom koda: brwPageBrowser.GoBack ili brwPageBrowser.GoForward. Da program ne bi dobijao RunTime Error svaki put kada kliknete na Back, a već ste na osnovnom dokumentu, dodajte jedno On Error Resume Next ispred ovih naredbi. Posle njih možete da testirate kod greške, pa ako je različit od 0, onemogućite klik na taster.
Po završetku aplikacije, ostaje vam da uz pomoć nekog HTML editora kreirate atraktivan Help. Predlažem da glavni topic bude HTML dokument koji će predstavljati sadržaj i obuhvatutu linkove ka ostalim temama i njihovim stranicama. Ostale teme možete da razdelite u više fajlova (svaki po jedna tema) ili da sve smestite u isti. Stranice unutar tema odvojite HTML tagovima i... nemojte zaboraviti da na mašini svog klijenta instalirate IE 4.0, bez njega vaš Help neće biti od velike pomoći.

Slika 1


Sub Main()
  Dim strCommand As String
  Dim intAnchor As Integer
  Dim strSilentLog As String
  Dim fSilent As Boolean
  Dim fErr As Boolean
  '(r)itaj parametre komandne linije
  strCommand = Command()
  'Uzmi prvi argument
  intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix1 & gstrAPPLICATIONPATH)
  If intAnchor = 0 Then
    intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix2 & gstrAPPLICATIONPATH)
  End If
  If intAnchor > 0 Then
    strCommand = Trim(Mid(strCommand, intAnchor + 2))
    gstrHTMLFilesPath = strExtractFilenameArg(strCommand, fErr)
    If fErr Then GoTo BadCommandLine
  Else
    'Komandni parametri ne postoje, završi program
    End
  End If
  'Uzmi sledeći parametar
  intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix1 & gstrHELPINDEXPATH)
  If intAnchor = 0 Then
    intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix2 & gstrHELPINDEXPATH)
  End If
  If intAnchor > 0 Then
    strCommand = Trim(Mid(strCommand, intAnchor + 2))
    gstrHelpFileNamePath = strExtractFilenameArg(strCommand, fErr)
    If fErr Then GoTo BadCommandLine
  Else
    ' Komandni parametar nije unet, završi program
    End
  End If
  'Očitaj ime index fajla
  intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix1 & gstrINDEXTOSHOW)
  If intAnchor = 0 Then
    intAnchor = InStr(LCase(strCommand), gstrSwitchPrefix2 & gstrINDEXTOSHOW)
  End If
  If intAnchor > 0 Then
    strCommand = Trim(Mid(strCommand, intAnchor + 2))
    gstrSelectedNodeIndex = strExtractFilenameArg(strCommand, fErr)
    If fErr Then GoTo BadCommandLine
  Else
    ' Komandni parametri ne postoje, završi program
    End
  End If
  Set mWorkForm = New frmMain
  Load mWorkForm
  mWorkForm.Show
  mWorkForm.SetFocus
BadCommandLine:
End Sub

Slika 2


I000, I000, "Active Help TOC", 		"ActiveHelp-TOC.html",0
I001, I000, "Active Help Main Menu",		"ActiveHelp-TOC.html",2
I100, I000, "Active Help Main Menu",		"",0
I101, I100, "Main Active Help Screen", 	"FullActiveHelp.html#MainMenu",2
I200, I000, "Active Help First Page", 	"",0
I201, I200, "Active Help First Page", 	"FullActiveHelp.html#FirstPage",2
I202, I200, "Add New Second Page",		"FullActiveHelp.html#SecondPage",2

Slika 3


If ndNodesList(nIndex).strNodeisTopic = 2 Then
  'Prvo proverimo da li fajl postoji
  'odvojimo html tag od imena fajla
  strHelpIndexFilePath = gstrHTMLFilesPath &
                       FstrStripTagFromString(ndNodesList(nIndex).strNodePathtoHTML, "#")
  If Dir(strHelpIndexFilePath) <> "" Then
    strHelpIndexFilePath = gstrHTMLFilesPath & ndNodesList(nIndex).strNodePathtoHTML
    strHelpIndexFilePath = FstrConvertToURL(strHelpIndexFilePath)
    brwPageBrowser.Navigate strHelpIndexFilePath
  Else
    'prijavimo gresku
    MsgBox ("Fajl nije pronadjen")
  End If
Else
  'Topic je nod, samo ga otvaramo
  Node.Expanded = True
End If

Slika 4: FstrConvertToURL


Public Function FstrConvertToURL(strInputString As String) As String
  'Konvertuje dati path u IE prepoznatljiv URL
  'Prvo pronalazi sve "\" i umesto njih stavlja "/"
  Dim strTemp1 As String
  Dim strTemp2 As String
  Dim jj As Integer
  'Na početak stringa stavi oznaku da je u pitanju fajl sa lokalnog diska
  strTemp1 = "file:///" & strInputString
  strTemp2 = ""
  For jj = 1 To Len(strTemp1)
    If Mid(strTemp1, jj, 1) = "\" Then
      strTemp2 = strTemp2 & "/"
    ElseIf Mid(strTemp1, jj, 1) = " " Then
      strTemp2 = strTemp2 & "%20"
    Else
      strTemp2 = strTemp2 & Mid(strTemp1, jj, 1)
    End If
  Next jj
  FstrConvertToURL = strTemp2
End Function

Slika 5


Public Sub ShowForm(Optional strHelpPath As String, Optional strHelpIndex As String)
  'Function to Show form.
  'Input variables:
  '           strHelpPath  - File Path to HelpIndex.inx
  '           strHelpIndex - Index to htlm document to show
  gstrHelpFileNamePath = strHelpPath
  gstrSelectedNodeIndex = strHelpIndex
  gstrHTMLFilesPath = strHelpIndexFilePath
  mWorkForm.Show
  mWorkForm.SetFocus
End Sub

Slika 6


Private Sub cmdHelp_Click()
'Poziv ActiveHelp
  If Dir(App.Path & "\HelpFiles\HelpIndex.inx") <> "" Then
    maxhClassQuickHelp.strHelpIndexFilePath = App.Path & "\ HelpFiles\"
    maxhClassQuickHelp.ShowForm achmodeless, , App.Path & "\ HelpFiles\HelpIndex.inx", "I001"
  Else
    Dim bResponse As Boolean
    bResponse = ReportHelpError
  End If
End Sub