# AllegroGraph Web View ― reference guide

The AllegroGraph Web View is an interface for exploring, querying, and managing AllegroGraph triple stores through a web browser.

## Basic usage

The web view can be loaded in two ways -- either simply `load` the file `load.lisp` that comes with the source code, or set up your ASDF to be able to find the `db.agraph.webview.asd` file (as well as the `.asd` files for the st-json and salza2 libraries), and load it with `(asdf:oos 'asdf:load-op :db.agraph.webview)`.

If you already have a triple store open, and the variable `db.agraph:*db*` points to it, the web server can be started with:

    (db.agraph.webview:start-webview (make-instance 'db.agraph.webview:simple-site :db db.agraph:*db*))

This will try to start the server on port 80. If you do not have access to that port, pass `start-webview` a `:port` keyword argument to specify another port.

Now direct your web browser to http://localhost/ (or something like localhost:8080 if you specified another port). You will see some general information about the store, and can try some SPARQL or Prolog queries by clicking 'Queries: new' in the navigation bar. See below for a more detailed description of the interface.

## Programming interface

The AllegroGraph Web View runs in an AllegroServe server. The most straightforward way to start a server is...

start-webview (site &key hostname port)
→ server

Starts a server and publishes the given site in it. `port` defaults to 80. See below for more information about site objects.

publish-webview (site server)

Often you'll need to have more control about the way the server is created (as per `net.aserve:start`), or you'll want to publish several applications in the same server. This function publishes a site in a given server. See the `:prefix` argument to a site for a way to prevent URLs from clashing.

Site objects hold the configuration and state used to run a web view. There are three types of sites:

make-instance 'simple-site (&key db spec name blurb namespaces notable queries use-reasoner prefix allow-prolog google-key)
→ site

Creates a simple 'appliance mode' site that is configured entirely programmatically. The arguments are mostly optional, and have the following meaning:

`db`
  The triple store to serve. Should be an instance of `db.agraph:abstract-triple-store`. Either this or `spec` should be given when creating a simple site.
`spec`
  Use this to have the web view open the triple-store itself (and close it again when closed). Can have the form `(:local filename write-p)`, which opens a local file, in read-only mode if `write-p` is `nil`, or `(:remote filename host port write-p)`, which opens a remote store through a Lisp socket connection.
`name`
  Give the store a name, which overrides the filename as the name shown in the interface.
`blurb`
  A short text describing the database. Shown in the overview.
`namespaces`
  A list of `(abbreviation url)` lists determining the namespaces used by the web view. These will cause matching URLs to be abbreviated (as in `rdf:type`), and can be used when entering queries.
`notable`
  A list of 'notable' nodes, in `(node description)` form. Will be shown in the store overview, and can be used to give people a starting point to explore the store. The nodes should use either be AllegroGraph parts (!-notation), or strings using an N-triples-like notation. Descriptions can be arbitrary strings.
`queries`
  A list of `(type name query)` lists, where `type` is either `"SPARQL"` or `"Prolog"`, and `name` and `query` are arbitrary strings. These will be shown as 'pre-defined queries' in the store overview.
`use-reasoner`
  Configures whether reasoning is available when querying the store. Set to `t` to use the default `rdfs++-reasoner`, or to a symbol to use a specific reasoner. When `nil` (the default), no reasoning is used.
`prefix`
  Sets a URL prefix to publish the web view under. This should start and end in a slash. Defaults to `"/"`.
`allow-prolog`
  Enables Prolog queries on this site. Defaults to `nil`, since reading and executing Prolog is (theoretically) not entirely secure.
`google-key`
  Sets a key for use with the Google Maps API (create one here) for displaying geospatial data. When left at `nil`, the map functionality is disabled.

make-instance 'site (&key db spec cache-file prefix allow-prolog google-key allow-new-accounts-p anonymous-users-p)
→ site

Sites of class `site` use AllegroCache to store persistent data. Such sites allow user accounts and can be configured through the web interface. See `add-admin` for a way to give yourself a superuser account. The `db`, `spec`, `prefix`, and `google-key` arguments work as in `simple-site`.

`cache-file`
  A string that determines where on the filesystem the AllegroCache data is stored. If this directory does not exists, it is created as the site is initialized.
`allow-new-accounts-p`
  Configure whether users are allowed to create their own accounts.
`anonymous-users-p`
  Determines whether the web view is accessible without logging in. If `nil` people have to log in before being able to do anything.

make-instance 'multi-site (&key cache-file prefix allow-prolog google-key allow-new-accounts-p anonymous-users-p allow-new-local-stores-p allow-new-remote-stores-p allow-new-empty-stores-p)
→ site

Sites of this type can serve multiple triple stores and allow users with the right permissions to create or open new stores. Most arguments have the same meaning they have for `site`, the others mean:

`allow-new-local-stores-p`
  When `t`, users with the `:site` permission can open new stores from local files. Defaults to `t`.
`allow-new-remote-stores-p`
  As above, but for remote stores through a socket connection. Also defaults to `t`.
`allow-new-empty-stores-p`
  Determines whether users can create new empty local stores. Defaults to `nil`.

close-site (site)

Close a site, releasing resources like open triple stores and AllegroCache databases.

add-user (site name password &optional roles)

Adds a new user to a site. `roles` can be a list of permissions this user has: `:site` for being allowed to configure the AllegroGraph Web View site, `:store` for being able to modify stores opened in read-write mode, and `:user` for being allowed to manage users.

add-admin (site name password)

Adds a user with all roles enabled.