Getting started

Assuming you have installed the HadronZoo Download, as instructed in the Download page. You will have chosen a suitable location for the software, created the base directory, untarred the download in this directory and set the environment variable $HADRONZOO to point to it. You will then have gone to the library source directory (../HadronZoo/code/hzlib[ver]/src), typed 'make' to compile it, and then gone to the Dissemino source directory (../HadronZoo/code/syst/dissemino) and typed 'make' again to compile the Dissemino web engine.

If you look in the Dissemino source code directory you don't have to be a C++ programmer or even a programmer at all, to note that there isn't much there. This is because virtually all the functionality is vested in the library. The Dissemino web engine itself does little. Other than reading command line arguments to get the location of the configs and to set various options, all it does is declare instances of various system wide entities and call initialization functions. Some of this demarcation would be expected. It makes sense for library classes and functions to do such things as handle socket connections and effect a proprietary database. The HadronZoo library allows Dissemino to go the whole hog. All the necessary web specific entities are defined as classes in the library, as are all the functions that read the configs which lead to their instantiation.

The classes related to web entities form a distinct group within the library. They are known collectively as the 'Dissemino classes' and their names are prefixed with a mnemonic of 'hds' instead of the default 'hz' given to library classes in general. The only other distinct group are the database classes whose names are prefixed with a mnemonic of 'hdb'. The reason why the Dissemino classes are in the library and not part of the Dissemino web engine program is simple. The library is first and foremost, intended as a framework for Linux C++ server programs, many of which require a web front end. From this perspective, it makes sense for the Dissemino classes to be in the library. From the perspective of a website developer, looking to the C++ interface only where the standard configurable functionality does not quite suffice, it would probably make more sense for the classes that effect web specific entities and the methods for reading the configs, to be part of the web engine.

Be that as it may, the view currently taken is that it ultimately does not matter where the source code of the Dissemino classes is located. The entire set of Dissemino classes are defined in the header file "hzDissemino.h" in the library's include directory (../HadronZoo/code/hzlib[ver]/inc) and the implimentation of them is spread accross several .cpp files in ../HadronZoo/code/hzlib[ver]/src (all with filenames begining with the hds mnemonic). In any event, any use of the C++ interface will necessitate familiarity with the Dissemino classes and this in turn makes a forray into the wider library inevitable. Thus for the time being at least, the Dissemino classes are part of the HadronZoo library.

The What and the Where

The C++ interface is relatively straightforward because server-side, there isn't the plethora of different events to cater for as there would be in the client. There is no mouse to move over, to move out or to hover, and nothing ever pops up, shape-shifts or changes color. Instead there are just two possible tasks, addition of a percent entity and addition of a Dissemino tag fact there is only one over-arching event the server will ever see - and that is the arrival of a HTTP request. Under Dissemino, all such HTTP requests are processed by the hdsApp::ProcHTTP() function. This is defined in hdsSystem.cpp and ... The C++ interface itself is relatively straightfoward because on the server side there isn't the plethora of different events to cater for, as there is on the client side. There is no mouse to move over, to move out or to hover, and nothing ever pops up, shape-shifts or changes color. In fact there is only one over-arching event the server will ever see - and that is the arrival of a HTTP request. Under Dissemino, all such HTTP requests are processed by the hdsApp::ProcHTTP() function. This is defined in hdsSystem.cpp and ... GET CMD POST It is assumed you will be doing this because in C++ you can do what you like while all Dissemino can do is recieve HTTP requests and formulate HTTP responses in accordance with its config files and the limited set of tags these comprise. This limitation applies to any website 'engine' and is normally overcome by calling scripts. The whole point of Dissemino is to avoid distribution of functionality and keep all the variables within the one program space.

Before embarking on such an endeavour it pays to understand at least in outline, how Dissemino works. Dissemino draws on many classes in the HadronZoo C++ Class Library including those related to the handling of HTTP over TCP/IP connections and those belonging to the HadronZoo Database Suite. Of greatest importance with regards to the task in hand, are the classes defined in the hzDissemino.h header file. Implimentation of these latter clsses is spread across five .cpp files as follows:-

    1) hzHtmlcfg.cpp - Read config files and define data classes, declare repositories and user classes, define pages, articles etc.
    2) hzHtmlgen.cpp - Generate HTML pages and part pages.
    3) hzHtmlres.cpp - Manage respources such as import/export files and control allocation of unique identifiers of pages, articles etc.
    4) hzHtmlscr.cpp - Generate JavaScripts for pages.
    5) hzHtmlsys.cpp - Deal with requests.

The two most important things to understand is how form-handlers call functions and how functions are called during the process by which HTML is generated. Form handlers process incoming data. HTML generation is where if necessary, data is retrieved.

The How: The <xappdef> tag

In the dissemino.cpp file you will see s_appspecFuncs which is a mapping of tag names to function pointers. And in main() a comment "insert application specific function here". Give your functions tag names of something like appspec_[function_name] and then for each function, put a line beneath the comment as follows:-

    s_appspecFuncs.Insert(tagname, function) ;

The <xappdef> tag tells Dissemino what application specific function to call in respect of what tag. It has a single attribute of tagname. There will need to be an <xappdef> tag for each function you have added to s_appspecFuncs and tagname must correspond. This must be done after the opening <DisseminoWebsite> tag and before any of the pages are declared. As long as the tagnames correspond, these application specific tags will now invoke your functions.