kaliber

package module
v0.12.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2019 License: GPL-3.0 Imports: 32 Imported by: 0

README

Kaliber

Golang GoDoc Go Report Issues Size Tag License View examples

Note

Please note that this is a work in progress. Changes – even API breaking changes – can happen at any time.

Purpose

I love books. Always have. Since I was a kid. Over the years several thousand books gathered in my flat; so many that I sort of ran out of space. Relunctantly I started to investigate and then use eBooks, first on my main desktop computer, later with a dedicated eBook reader.

Soon – and again – there were so many that I started looking for some convenient way to handle, store, and retrieve them for reading. That's when I became acquainted with Calibre, a great software for working with eBooks. Of course, there were some problems but since the software is actively maintained and extended all the time those problems either went away on their own with the next update or I found some way around them. And sure, it took some work to get all the eBooks into that library system, and since there are always coming new titles the work kind of never ends.

Another question soon became urgent: How to access my books when I'm not at home? As it turned out, Calibre comes bundled with its own web-server. After figuring out how to start it automatically when the machine gets restarted (which happens once in a while when some kernel software upgrade requires it) the server did its job. Quite another question, however, is how it does its job. And there the problem lies. The web-server coming with Calibre serves pages that are heavily dependent on JavaScript; so much so that the pages simply don't appear or work at all if you have JavaScript disabled in your browser e.g. for privacy or security reasons. For a while I grudgingly activated JavaScript whenever I wanted to access my books remotely. I asked the author of Calibre whether he'd be willing to provide a barrier-free alternative (i.e. without JavaScript) but unfortunately he declined: "Not going to happen."

Well, due to other projects I didn't find the time then to do something about it, and it took some more years before I started seriously to look for alternatives. Therefore now there's Kaliber, a barrier-free web-server for your Calibre book collection. It doesn't depend on – or even need – JavaScript, but just requires a web-browser capable to read plain HTML on the remote user's side. So even privacy or security conscious people or those who depend on assisting technologies (like e.g. screen-readers) can now access their library.

As an aside:

I never really understood the desire to multiply the work needed to be done for a web page.

A server is a server which means it should serve. When in a restaurant ordering a meal you surely expect it to be brought to you fully prepared and ready to be consumed. You'd probably were seriously annoyed if the waiter/server just brought you the ingredients and left it to you to prepare the meal for yourself.

For some strange reason, however, that's exactly what happens on a growing number of web-presentations: Instead of delivering a ready-to-read web-page they send every user just program code and let the user's machine do the preparing of the page. In other words: Instead of one server doing the work and delivering it to thousands of remote users nowadays the server forces thousands (or even millions) of remote users to spend time and electricity to just see a single web-page.

Since I couldn't find a documentation of the database structure and/or API used by Calibre to store its meta-data I had to reverse engineer ways to access the stored book data. The same is true – to a certain lesser degree – for the web-pages served by Kaliber: it's kind of a mix of Calibre's normal (i.e. JavaScript based) and mobile pages. The overall layout of the web-pages served by Kaliber is intentionally kept simple (KISS).

Features

  • Simplicity of use;
  • Barrier-free (no JavaScript required);
  • Books list layout either Cover Grid or Data List;
  • Easy navigation (First, Prev, Next, Last button/links);
  • Fulltext search as well as datafield-based searches;
  • Ordered in either ascending or descending direction;
  • Selectable number of books per page;
  • Sortable by author, date, language, publisher, rating, series, size, tags, or title;
  • Anonymised access logging;
  • Optional user/password based access control.

Installation

You can use Go to install this package for you:

go get -u github.com/mwat56/kaliber

//TODO

Usage

After downloading this package you go to its directory and compile

cd $GOPATH/src/github.com/mwat56/kaliber
go build app/kaliber.go

which should produce an executable binary.

Commandline options
$ ./kaliber -h

Usage: ./kaliber [OPTIONS]

-booksperpage int
	<number> the default number of books shown per page  (default 24)
-certKey string
	<fileName> the name of the TLS certificate key
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber/certs/server.key")
-certPem string
	<fileName> the name of the TLS certificate PEM
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber/certs/server.pem")
-datadir string
	<dirName> the directory with CSS, FONTS, IMG, SESSIONS, and VIEWS sub-directories
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber")
-ini string
	<fileName> the path/filename of the INI file to use
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber/kaliber.ini")
-lang string
	(optional) the default language to use  (default "de")
-libraryname string
	Name of this Library (shown on every page)
	(default "MeiBucks")
-librarypath string
	Path name of/to the Calibre library
	(default "/var/opt/Calibre")
-listen string
	the host's IP to listen at  (default "127.0.0.1")
-log string
	(optional) name of the logfile to write to
	(default "/dev/stdout")
-port int
	<portNumber> the IP port to listen to  (default 8383)
-realm string
	(optional) <hostName> name of host/domain to secure by BasicAuth
	(default "This Host")
-sessiondir string
	<directory> (optional) the directory to store session files
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber/sessions")
-sessionttl int
	<seconds> Number of seconds an unused session keeps valid  (default 1200)
-sidname string
	(optional) <name> the name of the session ID to use
	(default "sid")
-sqltrace string
	(optional) name of the SQL logfile to write to
-theme string
	<name> the display theme to use ('light' or 'dark')
	(default "light")
-ua string
	<userName> (optional) user add: add a username to the password file
-uc string
	<userName> (optional) user check: check a username in the password file
-ud string
	<userName> (optional) user delete: remove a username from the password file
-uf string
	<fileName> (optional) user passwords file storing user/passwords for BasicAuth
	(default "/home/matthias/devel/Go/src/github.com/mwat56/kaliber/pwaccess.db")
-ul
	(optional) user list: show all users in the password file
-uu string
	<userName> (optional) user update: update a username in the password file

Most options can be set in an INI file to keep the command-line short ;-)
$ _

As you can see there are quite a few options available, but almost all of them are optional since they come with reasonable default values most of which can be set in the accompanying INI-file.

INI file

You don't have to give all those commandline options listed above every time you want to start Kaliber. There's an INI file which can take all the options (apart from the user handling options) all in one place:

$ cat kaliber.ini
# Default configuration file for the Kaliber server

[Default]

# Number of books to show per page
booksperpage = 24

# Path-/filename of TLS certificate's private key to enable TLS/HTTPS
# (if empty standard HTTP is used)
# NOTE: a relative path/name will be combined with `datadir` (below).
certKey = ./certs/server.key

# Path-/filename of TLS (server) certificate to enable TLS/HTTPS
# (if empty standard HTTP is used)
# NOTE: a relative path/name will be combined with `datadir` (below).
certPem = ./certs/server.pem

# The directory root for CSS, FONTS, IMG, and VIEWS sub-directories.
# NOTE: this should be an _absolute_ path name.
datadir = ./

# The default language to use:
lang = de

# Name of this library (shown on every page)
libraryname = "MeiBucks"

# Path of Calibre library.
# NOTE: this must be the absolute pathname of the Calibre library.
librarypath = "/var/opt/Calibre"

# The host's IP to listen at:
listen = 127.0.0.1

# The IP port to listen to:
port = 8383

# Name of the optional logfile to write to.
# NOTE: a relative path/name will be combined with `datadir` (above).
logfile = /dev/stdout

# Password file for HTTP Basic Authentication.
# NOTE: a relative path/name will be combined with `datadir` (above).
passfile = ./pwaccess.db

# Name of host/domain to secure by BasicAuth:
realm = "This Host"

# Name of the directory to store session files.
# NOTE: a relative path/name will be combined with `datadir` (above).
sessiondir = "./sessions"

# Number of seconds an unused session keeps valid:
sessionttl = 1200

# Name of the session ID field:
sidname = "sid"

# Default web/display theme to use: `dark` or `light':
theme = light

# _EoF_
$ _

An INI-file as shown above is looked for at three different places

  1. in the your (i.e. the current user) directory (./kaliber.ini),
  2. in the computer's main config directory (/etc/kaliber.ini"),
  3. in the current user's home directory ($HOME/.kaliber.ini).

All these files (if they exist) are read in the given order at startup before finally parsing the commandline options shown earlier. So each step overwrites the previous one, the commandline options having the highest priority.

//TODO
Authentication

But why, you may ask, would you need an username/password file anyway? Well, there may be several reasons one of which could be Copyright problems. If not all your books are in the public domain and Copyright-free in most countries you may not make them publically available. In that case you're most likely the only actual remote user allowed to access the books in your library.

Whenever there's no password file given (either in the INI file or the command-line) all functionality requiring authentication will be disabled which in turn means that everybody can access your library. Depending on your country's legislation you may or may not include your family members. If in doubt please consult a Copyright expert.

Note that the password file generated and used by this system resembles the htpasswd used by the Apache web-server, but both files are not interchangeable because the actual encryption algorithms used by both are different.

User/password file & handling

Only usable from the commandline are the -uXX options, most of which need an username and the name of the password file to use. Note that whenever you're prompted to input a password this will not be echoed to the console.

$ ./kaliber -ua testuser1 -uf pwaccess.db

 password:
repeat pw:
    added 'testuser1' to list
$ _

The password input is not echoed to the console, therefor you don't see it.

Since we have the passfile setting already in our INI file (see below) we can forget the -uf option for the next options.

With -uc you can check a user's password:

$ ./kaliber -uc testuser1

 password:
    'testuser1' password check successful
$ _

This -uc you'll probably never actually use, it was just easy to implement.

If you want to remove a user the -ud will do the trick:

$ ./kaliber -ud testuser1
    removed 'testuser1' from list
$ _

When you want to know which users are stored in your password file -ul is your friend:

$ ./kaliber -ul
matthias

$ _

Since we deleted the testuser1 before only one entry remains.

That only leaves -uu to update (change) a user's password.

$ ./kaliber -ua testuser2

 password:
repeat pw:
    added 'testuser2' to list

$ ./kaliber -uu testuser2

 password:
repeat pw:
    updated user 'testuser2' in list

$ ./kaliber -ul
matthias
testuser2

$ _

First we added (-ua) a new user, then we updated the password (-uu), and finally we asked for the list of users (-ul).

Directory structure

Under the directory given with the datadir = entry in the INI file (or the -datadir commandline option) there are several sub-directories expected:

  • css: containing the CSS files used,
  • fonts: containing the fonts used,
  • img: containing the images used,
  • views: the Go templates used to generate the pages.

All of this directories and files are part of the Kaliber package. You can use them as is or customise them as you see fit to suit your needs. However, please note: I will not support any customisations, you're on your own with that – and you should know what you're doing.

Caveats

There are some Calibre features which are not available (yet) with Kaliber and not currently supported:

  • custom columns defined by the respective Calibre user;
  • different/multiple libraries for the user to switch between;
  • book uploads are not planned to be included.

Once I figure out how they are realised by Calibre I expect they find their way into Kaliber as well (provided I find actually time to do it).

Logging

Like almost every other web-server Kaliber writes all access data to a logfile (logfile = in the INI file and -log at the commandline).

As privacy becomes a serious concern for a growing number of people (including law makers) – the IP address is definitely to be considered as personal data – the logging facility anonymises the requesting users by setting the host-part of the respective remote address to zero (0). This option takes care of e.g. European servers who may not without explicit consent of the users store personal data; this includes IP addresses in logfiles and elsewhere (eg. statistical data gathered from logfiles).

Since the generated logfile resembles that of the popular Apache server you can use all tools written for Apache logfiles to anylyse the access data.

Libraries

The following external libraries were used building Kaliber:

Licence

    Copyright © 2019 M.Watermann, 10247 Berlin, Germany
                    All rights reserved
                EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

Documentation

Overview

Package kaliber implements a server for the `Calibre` library software. 

Copyright © 2019 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// AppArguments is the merged list for the cmdline arguments
	// and INI values for the application.
	AppArguments tAguments
)

Functions

func AddUser 

func AddUser(aUser, aFilename string)

AddUser reads a password for `aUser` from the commandline and adds it to `aFilename`.

NOTE: This function does not return but terminates the program with error code `0` (zero) if successful, or `1` (one) otherwise.

`aUser` the username to add to the password file.

`aFilename` name of the password file to use.

func CalibreCachePath 

func CalibreCachePath() string

CalibreCachePath returns the directory of the copied `Calibre` databse.

func CalibreDatabaseFile added in v0.9.0 

func CalibreDatabaseFile() string

CalibreDatabaseFile returns the complete path-/filename of the `Calibre` library.

func CalibreLibraryPath 

func CalibreLibraryPath() string

CalibreLibraryPath returns the base directory of the `Calibre` library.

func CalibrePreferencesFile added in v0.9.0 

func CalibrePreferencesFile() string

CalibrePreferencesFile returns the complete path-/filename of the `Calibre` library's preferences file.

func CheckUser 

func CheckUser(aUser, aFilename string)

CheckUser reads a password for `aUser` from the commandline and compares it with the one stored in `aFilename`.

NOTE: This function does not return but terminates the program with error code `0` (zero) if successful, or `1` (one) otherwise.

`aUser` the username to check in the password file.

`aFilename` name of the password file to use.

func DeleteUser 

func DeleteUser(aUser, aFilename string)

DeleteUser removes the entry for `aUser` from the password list `aFilename`.

NOTE: This function does not return but terminates the program with error code `0` (zero) if successful, or `1` (one) otherwise.

`aUser` the username to remove from the password file.

`aFilename` name of the password file to use.

func GetMetaFieldValue added in v0.8.0 

func GetMetaFieldValue(aSection, aField string) (interface{}, error)

GetMetaFieldValue returns the value of `aField` of `aSection`. 

aSection Name of the field metadata section.
aField Name of the data field within `aSection`.

func GetVirtLibOptions added in v0.7.0 

func GetVirtLibOptions(aSelected string) string

GetVirtLibOptions returns the SELECT/OPTIONs of virtual libraries. 

aSelected Name of the currently selected library.

func InitConfig added in v0.12.0 

func InitConfig()

InitConfig reads the commandline arguments into a list structure merging it with key-value pairs read from INI file(s).

The steps here are: 

(a) read the INI file(s),
(b) merge the commandline arguments with the INI values

into the global `AppArguments` variable.

func ListUser 

func ListUser(aFilename string)

ListUser reads `aFilename` and lists all users stored in there.

NOTE: This function does not return but terminates the program with error code `0` (zero) if successful, or `1` (one) otherwise.

`aFilename` name of the password file to use.

func OpenDatabase added in v0.12.1 

func OpenDatabase() error

OpenDatabase establishes a new database connection.

func RemoveWhiteSpace 

func RemoveWhiteSpace(aPage []byte) []byte

RemoveWhiteSpace removes HTML comments and unnecessary whitespace.

This function removes all unneeded/redundant whitespace and HTML comments from the given <tt>aPage</tt>. This can reduce significantly the amount of data to send to the remote user agent thus saving bandwidth.

func SQLtraceFile added in v0.4.7 

func SQLtraceFile() string

SQLtraceFile returns the optional file used for logging all SQL queries.

func SetCalibreCachePath 

func SetCalibreCachePath(aPath string) string

SetCalibreCachePath sets the directory of the `Calibre` database copy. 

`aPath` is the directory path to use for caching the Calibre library.

func SetCalibreLibraryPath 

func SetCalibreLibraryPath(aPath string) string

SetCalibreLibraryPath sets the base directory of the `Calibre` library. 

`aPath` is the directory path where the Calibre library resides.

func SetSQLtraceFile added in v0.4.7 

func SetSQLtraceFile(aFilename string)

SetSQLtraceFile sets the filename to use for logging SQL queries.

If the provided `aFilename` is empty the SQL logging gets disabled. 

`aFilename` the tracefile to use; if empty tracing is disabled.

func SetThumbWidth added in v0.2.0 

func SetThumbWidth(aWidth uint) uint

SetThumbWidth set the new width for generated thumbnails.

If `aWidth` is smaller than `64` it's increased.

func ShowHelp 

func ShowHelp()

ShowHelp lists the commandline options to `Stderr`.

func ThumbWidth added in v0.2.0 

func ThumbWidth() uint

ThumbWidth returns the configured width of generated thumbnails.

func Thumbnail added in v0.2.0 

func Thumbnail(aDoc *TDocument) (string, error)

Thumbnail generates a thumbnail of the document's cover.

func ThumbnailName added in v0.2.0 

func ThumbnailName(aDoc *TDocument) string

ThumbnailName returns the name of thumbnail file of `aDoc`.

func ThumbnailRemove added in v0.2.0 

func ThumbnailRemove(aDoc *TDocument) error

ThumbnailRemove deletes the thumbnail of `aDoc`.

func ThumbnailUpdate added in v0.2.0 

func ThumbnailUpdate()

ThumbnailUpdate creates thumbnails for all existing documents

func URLparts 

func URLparts(aURL string) (rDir, rPath string)

URLparts returns two parts: `rDir` holds the base-directory of `aURL`, `rPath` holds the remaining part of `aURL`.

Depending on the actual value of `aURL` both return values may be empty or both may be filled; none of both will hold a leading slash.

func UpdateUser 

func UpdateUser(aUser, aFilename string)

UpdateUser reads a password for `aUser` from the commandline and updates the entry in the password list `aFilename`.

NOTE: This function does not return but terminates the program with error code `0` (zero) if successful, or `1` (one) otherwise.

`aUser` the username to remove from the password file.

`aFilename` name of the password file to use.

Types

type TCustomColumn added in v0.11.4 

type TCustomColumn struct {
	ID                    int
	Label, Name, Datatype string
}

TCustomColumn contains info about a user-defined data field.

type TCustomColumnList added in v0.11.4 

type TCustomColumnList []TCustomColumn

TCustomColumnList is a list/slice of `TCustomColumnRec`.

func QueryCustomColumns added in v0.11.4 

func QueryCustomColumns() (*TCustomColumnList, error)

QueryCustomColumns returns data about user-defined columns in `Calibre`.

type TDocList 

type TDocList []TDocument

TDocList is a list of `TDocument` instances.

func QueryBy 

func QueryBy(aOptions *TQueryOptions) (rCount int, rList *TDocList, rErr error)

QueryBy returns all documents according to `aOptions`.

The function returns in `rCount` the number of documents found, in `rList` either `nil` or a list list of documents, in `rErr` either `nil` or an error occurred during the search. 

`aOptions` The options to configure the query.

func QueryIDs added in v0.2.0 

func QueryIDs() (*TDocList, error)

QueryIDs returns a list of documents with only the `ID` and `path` fields set.

This function is used by `thumbnails`.

func QuerySearch 

func QuerySearch(aOptions *TQueryOptions) (rCount int, rList *TDocList, rErr error)

QuerySearch returns a list of documents.

The function returns in `rCount` the number of documents found, in `rList` either `nil` or a list list of documents, in `rErr` either `nil` or an error occurred during the search. 

`aOptions` The options to configure the query.

func (*TDocList) Add added in v0.2.0 

func (dl *TDocList) Add(aDoc *TDocument) *TDocList

Add appends `aDoc` to the list of documents.

type TDocument 

type TDocument tDocument

TDocument represents a single document (e.g. book)

func QueryDocMini 

func QueryDocMini(aID TID) *TDocument

QueryDocMini returns the document identified by `aID`.

This function fills only the document fields `ID`, `formats`, `path`, and `Title`. 

`aID` The document ID to lookup.

func QueryDocument 

func QueryDocument(aID TID) *TDocument

QueryDocument returns the `TDocument` identified by `aID`. 

`aID` The document ID to lookup.

func (*TDocument) Authors 

func (doc *TDocument) Authors() *TEntityList

Authors returns a list of ID/Name author fields.

func (*TDocument) Comment 

func (doc *TDocument) Comment() template.HTML

Comment returns the comments of the document.

func (*TDocument) Cover 

func (doc *TDocument) Cover() string

Cover returns the absolute URL path-filename of the document's cover image.

func (*TDocument) CoverFile added in v0.10.0 

func (doc *TDocument) CoverFile() (string, error)

CoverFile returns the complete path/filename of the document's cover file. 

func (doc *TDocument) DocLink() string

DocLink returns a link to this document's page.

func (*TDocument) Filename 

func (doc *TDocument) Filename(aFormat string) string

Filename returns the path-/filename of `aFormat`.

func (*TDocument) Filenames 

func (doc *TDocument) Filenames() *TPathList

Filenames returns a list of path-/filename for this document

func (*TDocument) Files 

func (doc *TDocument) Files() *TEntityList

Files returns a list of ID/Name/URL fields for doc format files.

func (*TDocument) Formats 

func (doc *TDocument) Formats() *TEntityList

Formats returns a list of ID/Name/URL fields for doc formats.

func (*TDocument) Identifiers 

func (doc *TDocument) Identifiers() *TEntityList

Identifiers returns a list of ID/Name/URL identifier fields.

func (*TDocument) Language 

func (doc *TDocument) Language() *TEntity

Language returns an ID/Name/URL language struct.

func (*TDocument) PubDate 

func (doc *TDocument) PubDate() string

PubDate returns the formatted `pubdate` property.

func (*TDocument) Publisher 

func (doc *TDocument) Publisher() *TEntity

Publisher returns an ID/Name/URL publisher struct.

func (*TDocument) Series 

func (doc *TDocument) Series() *TEntity

Series returns an ID/Name/URL series struct.

func (*TDocument) SeriesIndex 

func (doc *TDocument) SeriesIndex() string

SeriesIndex returns the document's series index as formatted string.

func (*TDocument) Tags 

func (doc *TDocument) Tags() *TEntityList

Tags returns a list of ID/Name/URL tag fields.

func (*TDocument) Thumb added in v0.2.0 

func (doc *TDocument) Thumb() string

Thumb returns the path-filename of the document's thumbnail image.

func (*TDocument) Timestamp 

func (doc *TDocument) Timestamp() string

Timestamp returns the formatted `timestamp` property.

type TEntity 

type TEntity struct {
	ID   TID
	Name string
	URL  string
}

TEntity is a basic entity structure.

type TEntityList 

type TEntityList []TEntity

TEntityList is a list of entities

type TID 

type TID = int

TID is the database index type.

type TPageHandler 

type TPageHandler struct {
	// contains filtered or unexported fields
}

TPageHandler provides the handling of HTTP request/response.

func NewPageHandler 

func NewPageHandler() (*TPageHandler, error)

NewPageHandler returns a new `TPageHandler` instance.

func (*TPageHandler) Address 

func (ph *TPageHandler) Address() string

Address returns the configured `IP:Port` address to use for listening.

func (*TPageHandler) GetErrorPage 

func (ph *TPageHandler) GetErrorPage(aData []byte, aStatus int) []byte

GetErrorPage returns an error page for `aStatus`, implementing the `TErrorPager` interface.

func (*TPageHandler) NeedAuthentication 

func (ph *TPageHandler) NeedAuthentication(aRequest *http.Request) bool

NeedAuthentication returns `true` if authentication is needed, or `false` otherwise. 

`aRequest` is the request to check.

func (TPageHandler) ServeHTTP 

func (ph TPageHandler) ServeHTTP(aWriter http.ResponseWriter, aRequest *http.Request)

ServeHTTP handles the incoming HTTP requests.

type TPathList 

type TPathList TStringMap

TPathList is a map of document formats holding the respective library file.

type TQueryOptions 

type TQueryOptions struct {
	ID          TID       // an entity ID to lookup
	Descending  bool      // sort direction
	Entity      string    // query for a certain entity (authors, publisher, series, tags)
	GuiLang     uint8     // GUI language
	Layout      uint8     // either `qoLayoutList` or `qoLayoutGrid`
	LimitLength uint      // number of documents per page
	LimitStart  uint      // starting number
	Matching    string    // text to lookup in all documents
	QueryCount  uint      // number of DB records matching the query options
	SortBy      TSortType // display order of documents (`qoSortByXXX`)
	Theme       uint8     // CSS presentation theme
	VirtLib     string    // virtual libraries
}

TQueryOptions hold properties configuring a query.

This type is used by the HTTP pagehandler when receiving a page's data.

func NewQueryOptions 

func NewQueryOptions() *TQueryOptions

NewQueryOptions returns a new `TQueryOptions` instance.

func (*TQueryOptions) DecLimit 

func (qo *TQueryOptions) DecLimit() *TQueryOptions

DecLimit decrements the LIMIT values.

func (*TQueryOptions) IncLimit 

func (qo *TQueryOptions) IncLimit() *TQueryOptions

IncLimit increments the LIMIT values.

func (*TQueryOptions) Scan 

func (qo *TQueryOptions) Scan(aString string) *TQueryOptions

Scan returns the options read from `aString`.

func (*TQueryOptions) SelectLanguageOptions added in v0.5.1 

func (qo *TQueryOptions) SelectLanguageOptions() *TStringMap

SelectLanguageOptions returns a list of two SELECT/OPTIONs.

func (*TQueryOptions) SelectLayoutOptions added in v0.3.0 

func (qo *TQueryOptions) SelectLayoutOptions() *TStringMap

SelectLayoutOptions returns a list of SELECT/OPTIONs.

func (*TQueryOptions) SelectLimitOptions 

func (qo *TQueryOptions) SelectLimitOptions() string

SelectLimitOptions returns a list of SELECT/OPTIONs.

func (*TQueryOptions) SelectOrderOptions 

func (qo *TQueryOptions) SelectOrderOptions() *TStringMap

SelectOrderOptions returns a list of SELECT/OPTIONs.

func (*TQueryOptions) SelectSortByOptions 

func (qo *TQueryOptions) SelectSortByOptions() *TStringMap

SelectSortByOptions returns a list of SELECT/OPTIONs.

func (*TQueryOptions) SelectThemeOptions added in v0.5.0 

func (qo *TQueryOptions) SelectThemeOptions() *TStringMap

SelectThemeOptions returns a list of two SELECT/OPTIONs.

func (*TQueryOptions) SelectVirtLibOptions added in v0.7.0 

func (qo *TQueryOptions) SelectVirtLibOptions() string

SelectVirtLibOptions returns the SELECT/OPTIONs of virtual libraries.

func (*TQueryOptions) String 

func (qo *TQueryOptions) String() string

String returns the options as a `|` delimited string.

func (*TQueryOptions) Update 

func (qo *TQueryOptions) Update(aRequest *http.Request) *TQueryOptions

Update returns a `TQueryOptions` instance with updated values read from the `aRequest` data.

type TSearch 

type TSearch struct {
	// contains filtered or unexported fields
}

TSearch provides text search capabilities.

func NewSearch 

func NewSearch(aSearchTerm string) *TSearch

NewSearch returns a new `TSearch` instance.

func (*TSearch) Clause 

func (so *TSearch) Clause() (rWhere string)

Clause returns the produced WHERE clause.

func (*TSearch) Parse 

func (so *TSearch) Parse() *TSearch

Parse returns the parsed search term(s).

func (*TSearch) String 

func (so *TSearch) String() string

String returns a string field representation.

func (*TSearch) Where added in v0.7.0 

func (so *TSearch) Where() string

Where returns the SQL code to use in the WHERE clause.

type TSortType added in v0.11.4 

type TSortType uint8

TSortType is used for the sorting options.

type TStringMap 

type TStringMap map[string]string

TStringMap is a map of strings indexed by string.

type TView 

type TView struct {
	// contains filtered or unexported fields
}

TView combines a template and its logical name.

func NewView 

func NewView(aBaseDir, aName string) (*TView, error)

NewView returns a new `TView` with `aName`.

`aBaseDir` is the path to the directory storing the template files.

`aName` is the name of the template file providing the page's main body without the filename extension (i.e. w/o ".gohtml"). `aName` serves as both the main template's name as well as the view's name.

func (*TView) Render 

func (v *TView) Render(aWriter http.ResponseWriter, aData *TemplateData) error

Render executes the template using the TView's properties.

`aWriter` is a http.ResponseWriter, or e.g. `os.Stdout` in console apps.

`aData` is a list of data to be injected into the template.

If an error occurs executing the template or writing its output, execution stops, and the method returns without writing anything to the output `aWriter`.

func (*TView) RenderedPage 

func (v *TView) RenderedPage(aData *TemplateData) (rBytes []byte, rErr error)

RenderedPage returns the rendered template/page and a possible Error executing the template.

`aData` is a list of data to be injected into the template.

type TViewList 

type TViewList tViewList

TViewList is a list of `TView` instances (to be used as a template pool).

func NewViewList 

func NewViewList() *TViewList

NewViewList returns a new (empty) `TViewList` instance.

func (*TViewList) Add 

func (vl *TViewList) Add(aView *TView) *TViewList

Add appends `aView` to the list.

`aView` is the view to add to this list.

The view's name (as specified in the `NewView()` function call) is used as the view's key in this list.

func (*TViewList) Get 

func (vl *TViewList) Get(aName string) (*TView, bool)

Get returns the view with `aName`.

`aName` is the name (key) of the `TView` object to retrieve.

If `aName` doesn't exist, the return value is `nil`. The second value (ok) is a `bool` that is `true` if `aName` exists in the list, and `false` if not.

func (*TViewList) Render 

func (vl *TViewList) Render(aName string, aWriter http.ResponseWriter, aData *TemplateData) error

Render executes the template with the key `aName`.

`aName` is the name of the template/view to use.

`aWriter` is a `http.ResponseWriter` to handle the executed template.

`aData` is a list of data to be injected into the template.

If an error occurs executing the template or writing its output, execution stops, and the method returns without writing anything to the output `aWriter`.

func (*TViewList) RenderedPage 

func (vl *TViewList) RenderedPage(aName string, aData *TemplateData) (rBytes []byte, rErr error)

RenderedPage returns the rendered template/page with the key `aName`.

`aName` is the name of the template/view to use.

`aData` is a list of data to be injected into the template.

type TVirtualLibraryList added in v0.11.4 

type TVirtualLibraryList map[string]string

TVirtualLibraryList is the `virtual_libraries` JSON metadata section.

func GetVirtualLibraryList added in v0.11.4 

func GetVirtualLibraryList() (TVirtualLibraryList, error)

GetVirtualLibraryList returns a list of virtual library definitions and SQL code to access them.

type TemplateData 

type TemplateData map[string]interface{}

TemplateData is a list of values to be injected into a template.

func NewTemplateData 

func NewTemplateData() *TemplateData

NewTemplateData returns a new (empty) `TDataList` instance.

func (*TemplateData) Set 

func (dl *TemplateData) Set(aKey string, aValue interface{}) *TemplateData

Set inserts `aValue` identified by `aKey` to the list.

If there's already a list entry with `aKey` its current value gets replaced by `aValue`.

`aKey` is the values's identifier (as used as placeholder in the template).

`aValue` contains the data entry's value.

Source Files

View all Source files

Directories

Path Synopsis
db module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.