Back to dataSeltzer documentation index

Configuring and customizing dataSeltzer

dataSeltzer is an highly configurable component.
e.g. you could legitimately wish to customize the visual appearance of the HTML pages being published on your own website:

css brown style

brown-yellow style

css azure style

azure style

css green style

green style

dataSeltzer widely supports CSS styling: all the above figures directly corresponds to practical examples of the three alternative CSS stylesheets directly shipped within any source distribution of dataSeltzer. You'll find all them into the resources/css_styles directory.

italian

National translation in the Italian language

Simply choosing a CSS style of your own isn't enough: you could probably wish to translate any descriptive item of the User Interface into a different national language; or may be, you could simply wish to arrange such elements in a different way.
dataSeltzer has very few hard-coded text strings: you can easily change almost any UI element by simply editing the standard dataSeltzer.conf configuration file supporting every instance of dataSeltzer.

CSS stylesheet

If you are a WebMaster you'll surely already have a profound competence about this topic.
If you instead ignore quite almost about CSS you can easily find many comprehensive how-to guides and tutorials on the Web; e.g. this one is a good starting point.

You'll find three alternative pre-configured CSS stylesheets into the resources/css_styles directory of the standard source distribution of dataSeltzer.
Feel absolutely free to use these pre-defined CSS stylesheet as they are in your production installation; but you could more probably use them simply as a source of further inspiration, then writing at your own taste the final CSS stylesheet you intend to deploy on your installation.
All CSS pre-defined samples are detailed commented point by point: so you could simply read these stylesheets in order to get more detailed informations.
Just a quick reference, these are the CSS classes internally used by the HTML pages dynamically generated by the dataSeltzer CGI:

UI elements (dataset selection, filters, aggregate criteria and buttons):
- params_table: the style supporting the <TABLE> containing all UI elements.
- params_label: the style supporting any <TD> element in the above table containing a description (aka label).
- params_background the style supporting any other different <TD> element in the above table (left aligned).
- params_background_right: same as the previous one, but right aligned.
- params_background_center: same as the previous one, but centered.
- params_fill: the style supporting the last <TD> element in a <TR> intended to always ensure a nicely-looking alignment of the right margin.
- params_combo: the style supporting any <SELECT> (aka combobox) UI element.
- params_input: the style supporting any <INPUT> UI element.
- params_input_disabled: the style supporting any <INPUT> UI element in its disabled state.
- params_icon_disabled: the style supporting any <IMG> (icon/hyperlink) UI element in its disabled state.
- params_button: the style supporting any <BUTTON> UI element.
resultset elements:
- results_table: the style supporting the <TABLE> containing the whole resultset.
- results_title: the style supporting any <TH> element in the above table containing column descriptions.
- result_odd_row: the style supporting any <TD> element in the above table containing a cell value (left aligned).
- result_num_odd_row: same as the previous one, but supporting numeric values (right aligned).
- result_even_row and result_num_even_row: exactly as the last two styles, but intended for any other row by applying an alternate odd/even rule.
- result_page_count: the style supporting the current page/row title.

HTML templates

Not all the HTML code composing a Web page dynamically created by dataSeltzer will be directly generated by the CGI itself.
Many fragments will be simply copied / included from static external files expected to be found in the html_include directory supporting every dataSeltzer instance.
Such a layout will nicely support many kind of customization: you simply have to manually edit the appropriate HTML template then inserting any other HTML stuff you think to be useful.

You'll find a complete set of HTML pre-configured templates (identified by a .inc suffix) into the resources/html_include directory of the standard source distribution of dataSeltzer. Feel absolutely free to use these pre-defined HTML templates as they are in your production installation; or simply use them as a source of further inspiration, as wish better. Here is a quick reference of all HTML templates required by the dataSeltzer CGI so to correctly work as expected:

frame.inc: a main <FRAMESET> acting as a general container and structured in two individual <FRAME> elements:
- one intended for the User Interface (params: datasource selection, filters, buttons and alike).
- the other one hosting any resultset or error message (results).
params_header.inc and params_footer.inc: all HTML elements belonging to the params page and not directly generated by the CGI itself.
geturl_header.inc and geturl_footer.inc: same as above, but intended to support the GetUrl result page.
misconfigured.inc and zip_error.inc: two HTML pages required by the CGI itself in order to inform the user about any abnormal error condition.

JavaScript support

dataSeltzer just relies on a very minimalistic and unsophisticated JavaScript support, mainly intended to intercept and handle user actions dynamically affecting the User Interface.
The standard implementation of all JS functions required by dataSeltzer is usually defined into the params_header.inc template; you'll be obviously free to relocate or change the basic JS implementation if you think this could be useful and appropriate. In this case you have to consider the following mandatory constraints:

function formUpdate(void): this is expected to handle onChange events raised by <SELECT> elements and onClick events raised by the add filter button.
function formResetAll(void): this is expected to handle any onClick event raised by reset button.
function formsResults(void): this is expected to handle any onClick event raised by both go and GetUrl buttons.
function searchFieldValueFilter(col_fld, field_name): this is expected to handle any onClick event raised by help buttons and is intended to open a popup window then copying a selected value into the target <INPUT> field.
function searchFieldValueAggregate(col_fld, field_name): same as above, but intended to support Aggregate queries.

The dataSeltzerMain.conf main configuration file

This is a rather simple XML file specifying the overall configuration of dataSeltzer. This file is always expected to be found on the same directory where the CGI component is.
You'll find a copy of the standard dataSeltzerMain.conf file into the resources/conf directory of the standard source distribution of dataSeltzer.
Starting from this very basic sample is always suggested, and will enable you to quickly edit your own configuration file.
The main configuration file is internally divided into a single section named <dataSeltzerMainConfig> grouping the following items:

<LogFileDirPath> relative (or possibly better: absolute) pathname to a directory where all logfiles will be stored.
Please note well: the CGI component must be granted read-write permissions on this directory.
<LogInsulationCriterion>: one of the following values is expected:
- mixed a single logfile will be created for all instances.
- separate an individual logfile will be created for each instance.
<LogRotationCriterion>: one of the following values is expected:
- daily all logfiles will rotate on a per day basis.
- monthly all logfiles will rotate on a per month basis.
<EnableMultiInstances> (boolean) if enabled dynamically switching from an instance to another one will be an option directly supported by the User Interface; if disabled switching to another instance will always require referencing an explicit request URL.
<InstanceConfig>: you can declare as many <InstanceConfig> items as required, there is no imposed limit. Anyway at least a single enabled instance is strictly required by dataSeltzer in order to correctly work.
For each instance the following arguments should be declared:
- "name" unique name identifying that specific instance.
- "title" some human readable description identifying the instance.
- "configPath" path to the corresponding configuration file.
- "enabled" (boolean) if that instance is enable/disabled.

The dataSeltzer.conf instance-specific configuration file

This too is a rather simpleXML file specifying many fine-grained details of the specific configuration intended for each single dataSeltzer instance.
You'll find a copy of the standard dataSeltzer.conf file into the resources/conf directory of the standard source distribution of dataSeltzer.
Starting from this very basic sample is always suggested, and will enable you to quickly edit your own configuration file.
The configuration file is internally divided into several sections so to keep the whole configuration in a properly ordered state:

the <MainSection> will contain any functional configurable option:
- <DBPath> absolute or relative pathname to the SQLite/SpatiaLite DB-file to be published.
- <MaxResultsetRows> maximum allowable number of rows for every resultset; after exceeding this limit truncation will be applied.
- <MaxHelpResultsetRows> same as above, but intended to limit auxiliary Help queries.
- <MaxRowsPerHtmlPage> determines how a resultset is shown into many separate HTML pages.
- <HttpRequestMethod> one between GET or POST.
- <HtmlIncludeDir>absolute or relative path to the directory containing all HTML templates (.inc files) required by dataSeltzer.
  Please note well: the CGI component must be granted read-access permissions on these two paths.
  This usually implies changing the ownership of these directories/files to the user apache (many other different solutions are anyway conceivable).
- <TempDir>absolute or relative to the directory required by the CGI component when creating temporary files (during ZipFiles generation).
  Please note well: the CGI component must be granted read-write access permissions on this directory.
- <CgiUrl>: the URL corresponding to the CGI itself.
- <IconHelpUrl>, <IconAddUrl>, <IconFirstPage>, <IconLastPage>, <IconPrevPage> and <IconNextPage>: the URLs corresponding to the small icons required respectively by the Help, Add and page navigation UI buttons.
  Please note: You'll find all standard PNG icons into the resources/icons directory of the standard source distribution of dataSeltzer.
- <CssStyleSheetUrl>the URL corresponding to the CSS stylesheet supporting the CGI component.
- <EnableTextXml>: (boolean) determines if text/xml requests should be serviced or not.
- <FullBlobXml>: (boolean):
  - if true / 1 any BLOB value being exported into the XML file will be represented as:
    - the corresponding WKT notation if this BLOB does actually corresponds to a Geometry value.
    - the corresponding Hexadecimal notation in any other case.
    - Caveat: enabling the <FullBlobXML> could easily imply a really impressive increase of the XML file size; carefully evaluate if activating this option could eventually cause an intolerable slowness when downloading the XML format.
  - if false / 0 any BLOB value being exported into the XML file will simply report a generic "BLOB" value.
- <FullXmlColumnInfos>: (boolean):
  - if true / 1 the XML file will report the exact data-type and max-length for each column in the resultset. (this requires a preliminary resultset scan so to determine the appropriate values)
  - if false / 0 the XML file will simply report generic data-types exactly as available from SQLite's own metadata (may be inaccurate or misleading, due to the intrinsic type-less nature of SQlite) and will always suppress any max-length information; the data-type for every column being the result of an SQL expression or function will always be undetermined.
- <TimestampsLocalTime>: (boolean) determines if all Timestamps are to be expressed as local- or GMT-time.
the <LabelSection> will contain any UI descriptive text (aka label):
- enumerating each individual <LabelXxxx> option will simply be boring and confusing.
  Please read the sample configuration file and carefully study comments supporting each item.
<HiddenSection>: the intended scope of this section is to group in a single place all <HiddenView> declarations:
- dataSeltzer will publish by default any VIEW found within the SQLite/Spatialite DB-file.
  Please note well: every TABLE will always be ignored; only VIEWs are eligible for Web publishing.
  Anyway, you can have many good reasons suggesting to hide some VIEW thus completely forbidding its publication.
  In this case you simply have to declare a <HiddenView> directive just specifying the name of the forbidden/undisclosed View.
  You can declare as many <HiddenView> items as required, there is no imposed limit.
and finally the <ExtraDataSection> is intended to support automatic inclusion of generic extra-files within every ZipFile dynamically generated for downloading.
But we'll examine this specific point in more detail in the next paragraph.

Distributing extra files

You'll eventually wish to include several extra files within every ZipFile being downloaded: e.g. you'll probably be required to include some data license, some credit acknowledgement or may be some metadata or even a generic Readme.txt file.
dataSeltzer supports various alternative mechanisms allowing to obtain all this in the easiest, more flexible and painless way:

you can eventually declare as many <ExtraDataFile> directives as required, specifying an absolute or relative file path.
In this case each single file referenced by these directives will be unconditionally included in every ZipFile being created (this one is a coarse and not at all selective mechanism).
Please note well: the CGI component must be granted read-access permissions on these files.
you can also specify a single <ExtraDataDir> directive referencing an absolute or relative path to some directory:
- this optional <ExtraDataDir> will be always inspected by the CGI component when creating a ZipFile; and all files within the directory matching the current datasource name will be then automatically included within the ZipFile.
- a further <ExtraDataSubDirs> directive could be eventually declared so to choose between two alternative (and mutually exclusive) layouts.

The ExtraDataSubDirs=FALSE layout (default)

by applying the ExtraDataSubDirs=FALSE layout only the directory pointed by the ExtraDataDir path will be inspected.
any other sub-directory will be completely ignored.
all files exactly matching the current datasource name (i.e. starting with the same name) will be included into the ZipFile created for downloading.
as shown in this example, both datasource1_license.txt and datasource1_readme.txt will be included when exporting any resultset coming from datasource1.

The ExtraDataSubDirs=TRUE layout

by applying the ExtraDataSubDirs=TRUE layout only first-level sub-directories within the main directory pointed by the ExtraDataDir path will be inspected.
any file directly contained within the main directory itself will be completely ignored.
exactly as any other lower-level sub-directory will be ignored.
if a first-level sub-directory exists exactly matching the name of the current datasource, then all files contained within such sub-directory will be included into the ZipFile created for downloading.
as shown in this example, both datasource1/license.txt and datasource1/readme.txt will be included when exporting any resultset coming from datasource1.

Back to dataSeltzer documentation index

Credits
Development of dataSeltzer has been funded by Tuscany Region - Territorial and Environmental Information System
Regione Toscana - Settore Sistema Informativo Territoriale ed Ambientale.