SVOCat Documentation

Version 2.2-nocoor, Last change: March 30, 2021; Author: Carlos Rodrigo

Home

Download

Documentation

Examples

Credits

Help-Desk

Introduction

SVOCat is an application intended to make easier the publication of an astronomical catalogue, both as a web page and as a Virtual Observatory ConeSearch service.

Our intention is not no make it "magical" so that it makes all the work for you. We have tried to make it so that it's easier for you to learn about what is being done, to start the installation and configuration process at different steps if you wish, and to change the application if you need to do it for your case.

Requirements:

• A web server (Apache, for instance) and access to a web directory to install the files.
• PHP
• MySQL database.

(See some technical details below)

We assume that:

• Your catalogue can be seen as a single table with several columns (one for each property provided by the catalogue) and several lines (one for each catalogue entry, for instance, each observed object)

and that your have your data either:

• as a csv file with different columns separated by commas. It can be a series of different csv files with the same structure if your catalogue is very big and you prefer to split it in different files.
• as a table in a mysql database.

If you have the data in another format just transform it to csv. In any case, at the end of the day we will need the database table. If you already have it (or you want to create it in your own way) you don't need a csv file and you can skip some steps in the installation process.

Installation summary:

1. Download the SVOCat.tgz file.

2. Uncompress the file in a directory that can be accessed by the web server.

3. Access the admin.php file with a web navigator to configure everything.

4. Create the database tables using the scripts that will be created in the configuration process (or any other method)

5. Edit the style files to make the web pages look as you wish.

Download

Contact us at svo-support@cab.inta-csic.es and we will send you a gzipped tar file SVOCat.tar.gz (~ 0.5Mb).

Extract the files

You need to unpack the SVOCat.tar.gz in a directory within the web server.

If you have no idea about what this means or how to do it, you maybe should contact your system or your web administrator. Nevertheless, we will give you here some tips about it (most of the examples correspond to a linux installation, but you can translate them to the corresponding ones for any other system).

For instance, a typical path for the Apache web root directory is /var/www/.

You can go to some directory within that path, for instance /var/www/catalogues/ and unpack the SVOCat.tar.gz there:

First you probably need to create some directory to host the data. We call it catalogues (you can choose the name that you wish).

where you should use your own username instead of "carlos". Now the catalogues folder exists and it belongs to you.

Now you can move the SVOCat.tar.gz file to that folder and unpack it.

it will generate a directory named SVOCat containing all the files and you will probably want to rename it as you wish. For instance, let's assume that you rename it as exfitlers (we will use this name in what follows, but you can choose any name that you want).

The absolute path for your SVOCat installation (the place in your computer where the files are located) will be:

/var/www/catalogues/exfilters/

And, assuming that your server main URL is http://www.mylab.org, the root URL for your catalogue (the web address for accesing it) will be:

http://www.mylab.org/catalogues/exfilters/

We will asume in this documentation (when we need to refer to them) that these ones are the absolute path for your files and the root url for your catalogue.

When you unpack you will get a fresh installation of SVOCat with several files and directories:

A detailed description of the most important files and folders will be given in another section.

Permissions

Just in case, it's good to make sure that the Apache web server is able to read all the files in the directory where you have installed SVOCat.

In a typical linux installation of Apache, this means that you make all the files and folders readable by the www-data user and all the folders "executable" by that user. For instance, you can do:

 

IMPORTANT! There are two special directories: config/ and work/. Both directories must be writable by the web server. Change their permisions as needed so that it is allowed.

In a typical linux installation of Apache, this means that you, at least, make them (and their contents) owned by the www-data group and make them writable by that users in that group. For instance:

The point is that when you configure the application with the properties of your catalogue, the files in config/ and work/ will be changed to save the new properties. And in order to be able to do that the web server must be able to write on them. If you are not able to do this, please contact your server administrator.

In general, it is a good idea to make everything owned by your user and the apache (www-data) group. At the end, if you take a look to the output of ls -la commands, you should see something similar to this:

> ls -la drwxr-x--- carlos www-data . drwxr-x--- carlos www-data admin/ -rw-r----- carlos www-data admin.php drwxr-x--- carlos www-data availability/ drwxr-x--- carlos www-data capabilities/ drwxrwx--- carlos www-data config/ -rw-r----- carlos www-data credits.php -rw-r----- carlos www-data cs.php -rw-r----- carlos www-data dl.php drwxr-x--- carlos www-data docs/ -rw-r----- carlos www-data documentation.php drwxr-x--- carlos www-data files/ -rw-r----- carlos www-data home.php drwxr-x--- carlos www-data includes/ -rw-r----- carlos www-data index.php drwxr-x--- carlos www-data javascript/ -rw-r----- carlos www-data news.php -rw-r----- carlos www-data other1.php -rw-r----- carlos www-data search.php -rw-r----- carlos www-data ssap.php drwxr-x--- carlos www-data style/ -rw-r----- carlos www-data version.php drwxrwx--- carlos www-data work/

> ls -la admin/ drwxr-x--- carlos www-data . -rw-r----- carlos www-data check.php -rw-r----- carlos www-data conf_admuser.php -rw-r----- carlos www-data conf_dlink.php -rw-r----- carlos www-data conf_fields.php -rw-r----- carlos www-data conf_init.php -rw-r----- carlos www-data conf_mysql.php -rw-r----- carlos www-data conf_paths.php -rw-r----- carlos www-data conf_phot.php -rw-r----- carlos www-data conf_project.php -rw-r----- carlos www-data conf_refs.php -rw-r----- carlos www-data conf_registry.php -rw-r----- carlos www-data conf_scripts.php -rw-r----- carlos www-data conf_search.php -rw-r----- carlos www-data conf_spectra.php -rw-r----- carlos www-data conf_vo.php -rw-r----- carlos www-data conf_web.php -rw-r----- carlos www-data functions.php -rw-r----- carlos www-data init_page.php -rw-r----- carlos www-data login.php

> ls -la config/ drwxrwx--- carlos www-data . -rw-rw---- carlos www-data config_admuser.php -rw-rw---- carlos www-data config_dates.php -rw-rw---- carlos www-data config_dlink.php -rw-rw---- carlos www-data config_fields.php -rw-rw---- carlos www-data config_mysql.php -rw-rw---- carlos www-data config_paths.php -rw-rw---- carlos www-data config_phot.php -rw-rw---- carlos www-data config.php -rw-rw---- carlos www-data config_project.php -rw-rw---- carlos www-data config_refs.php -rw-rw---- carlos www-data config_scripts.php -rw-rw---- carlos www-data config_search.php -rw-rw---- carlos www-data config_spectra.php -rw-rw---- carlos www-data config_vo.php -rw-rw---- carlos www-data config_web.php

In particular, permissions for config/ and work/ should be similar to what is shown for config/. And permissions for other subfolders should be similar to those shown for admin/.

The files

We will describe here, briefly, the most important files and directories that are contained in the SVOCat installation.

You will probably want to read this at least once. In some cases just for getting an idea about what is there. But, what is more important, because you will surely need to edit a few of these files.

As a very fast summary:

index.php (the web catalogue), cs.php (the VO ConeSearch service), ssap.php (the VO SSAP service), dl.php (the VO DataLink service) and admin.php (the administration page) are the most important files and the only ones that should be accessed directly as web pages. All the others are files used by any of these ones.

home.php, documentation.php, news.php, search.php, credits.php and coverage.php implement the main functionalities in the web page and you could want to edit some of them (at least documentation).

The style directory contains everything related to the look and feel of the web page and you can (and probably want to) change some things there.

More details:

Edit/custom			The style directory includes all the files related to the look and feel of the web page (css style sheets, images, headers, footers, etc). You will surely want to edit at least some of these files to provide some "coorporative" image to the web site.
Edit/custom			The documentation.php is a page that you must edit to include the documentation about your catalogue. It can be an html page, a series of links, you can include php code if you want... It's up to you. The docs directory is a convenient place to include documents (pdf files, images, etc) that you want to reference from the documentation.php file. The docs directory name is not harcoded anywhere in the application. This means that you can rename it, delete it if you don't need it or do what you wish with it.
Edit/custom			news.php is the content that will be loaded by index.php when a user clicks in the "News" link at the menu (if you have included it in the configuration). This page will show, as default, when the catalogue was created, the last update and examples on how to access the active VO services that you have created. But you can add other entries editing this file and including other news that you want to comunicate to your users. We have styled it as a series of title/text pairs but you are free to edit it as you wish.
Edit/custom			credits.php is the content that will be loaded by index.php when a user clicks in the "Credits" link at the menu (if you have included it in the configuration). This page will show, as default, all the references that have been configured in the corresponding admin sections. In principle you don't need to edit this page (SVOCat should generate a good version if you have given all the information in the configuration) but you can edit it if you want to provide more (or a different) information.
Edit/custom			This is in practice a placeholder just in case you want to add another custom functionality to the web page. During the configuration you can include it and define the text that will be shown in the menu for this functionality. Then you can edit other1.php and include whatever you want using html or PHP. Otherwise, if you don't need anything special, just ignore this file.
Edit/custom			This is the recommended directory where to place your catalogue files if they are in csv format (see the corresponding section). You can put the files in some other place of your computer if you want, but this directory can be a good place. In a fresh installation of SVOCat we have included here the file cmc15n2-part1.csv as an example. This is only important if you want that SVOCat helps you to populate the database starting with csv files. If you want to populate the database by your own means, you don't need this directory.
Don't touch			The admin.php is the file that allows you to configure the application and you will have to access it using a web browser as: http://www.mylab.org/catalogues/exfiles/admin.php The admin directory includes files used by admin.php. You shouldn't need to edit anything in these files.
Don't touch			This folder is here to allow external VO applications to check the availability of VO services for this catalogue. You shouldn't need to edit anything in these files.
Don't touch			This folder is here to allow external VO applications to find what VO services are available for this catalogue and some properties about them. You shouldn't need to edit anything in these files.
Don't touch			The config directory includes all the configuration files. They should be writen by the web server accordingly with the configuration that you give in the admin.php administrative application. Remember that this directory and the files in it must be writable by the web server. In principle you shouldn't need to touch anything here (with the only exception that you want to include extra functionalities, implemented by you, in the web page, as it will explained later).
Don't touch			If you have your catalogue data as a csv file, the administrative application will generate some scripts to help you to create a MySQL database table and load the data into it. This directory will contain these scripts created using the information that you give in the configuration. In principle, you shouldn't need to edit the scripts but you are free to do it if you need it and you know what you are doing. In a fresh installation of SVOCat this directory will include the scripts corresponding to the "Example Catalogue" and they will be changed later by the admin application. Remember that this directory and the files in it must be writable by the web server.
Don't touch			index.php is the main script for the web page. You can access it as: http://www.mylab.org/catalogues/exfiles/index.php http://www.mylab.org/catalogues/exfiles/ This script uses other files as needed, depending on what is requested by the user (home, search, documentation, catalogue search, etc). You shouldn't need to edit anything here.
Don't touch			cs.php is the file implementing the VO ConeSearh protocol and can be accessed as: http://www.mylab.org/catalogues/exfiles/cs.php specifying the adequate parameters. Read the ConeSearch section for further explanation. You shouldn't need to touch anything in this file.
Don't touch			ssap.php is the file implementing the VO SSAP protocol if your catalogue includes spectra and you have configured to offer this service. It can be accessed as: http://www.mylab.org/catalogues/exfiles/ssap.php specifying the adequate parameters. Read the SSAP section for further explanation. You shouldn't need to touch anything in this file.
Don't touch			dl.php is the file implementing the VO DataLink protocol if you have configured to offer this service. It can be accessed as: http://www.mylab.org/catalogues/exfiles/dl.php specifying the adequate parameters. Read the DataLink section for further explanation. You shouldn't need to touch anything in this file.
Don't touch			home.php is the content that will be loaded by index.php when a user clicks in the "Home" link at the menu. It is also the default content. In principle, this content is generated just using the configuration that you give in the admin application and you shouldn't need to edit this file. But you can edit if if you want to add something.
Don't touch			search.php is the content that will be loaded by index.php when a user clicks in the "Data Retrieval" link at the menu. It implements the catalogue search and data retrieval accordingly to the configuration given by you in the admin application. You shouldn't need to edit anything there.
Don't touch			This is a directory including files defining functions used by other files. You shouldn't edit anything here unless you really want to hack the application and you know what you are doing.
Don't touch			This directory includes javascript libraries that are used in the web page to implement several functionalities. It includes: wz_tooltip.js (by Walter Zorn) to implement tooltips explaining catalogue properties samp.js (by Mark Taylor) to implement SAMP comunication between the web page and VO tools vsamp0.js as a connector between PHP and the SAMP library. showhide.js to hide/show a certain layer at the user convenience. You shouldn't edit anything here unless you know what you are doing.
Don't touch			This file contains information about the version of SVOCat that you are using. You shouldn't need to change anything there.

Example catalogue

When you download SVOCat you get it preconfigured with the properties of an example catalogue.

The idea is that you can get, as fast as posible, a working version of SVOCat so that you can see it at work and get tips on how to configure your own catalogue.

This example catalogue is made using a very small subset of the SVO Filter Profile Service (but only a few filters and properties).

As a very brief summary:

In the work/exfilters.csv file you have the data in csv format.

These data are equivalent to a table with 42 lines and 8 columns.

Create a MySQL database (vocats)

We need to create a MySQL table with that structure and then load the data into it (you could want to take a look at the MySQL database configuration).

First, we need a database that you must create in your own way. A typical command to create a database is:

mysqladmin -u root -p create vocats

If you decide to use other name for the database, please go to the administration application and change it too in the Mysql section.

Create a MySQL user (mycatuser)

Creating a mysql user is a little more tricky. If you don't know how to do it you should probably ask for some help from your system administrator.

In any case, we give you a simplified example.

You first open the MySQL command line interface:

mysql -u root -p

Then, under the mysql prompt, you select the "mysql" database:

mysql> use mysql;

then you create a user named "mycatuser" with all privileges in the 'vocats' database and password "mycatp@ss"

mysql> grant all privileges on vocats.* to 'mycatuser'@'locahost' identified by 'mycatp@ss';

and you exit the mysql interface:

mysql> quit;

But take this as just a tip. You maybe want to be more restrictive about catuser permissions.

Create a MySQL table (exfilters)

We now must create a table to contain the catalogue data. In the work/ folder you have a file work/create_table.my with the mysql instructions to create a table named "exfilters".

drop table if exists exfilters; create table exfilters ( id int not null auto_increment, id char(255), descrip char(255), lmean double, leff double, lpiv char(255), fwmh char(255), weff char(255), refer char(255), primary key (id), index idx_ra (RAdeg), index idx_dec (DECdeg));

you can use this file to create the table in the database as:

(where "mycatuser" must be a mysql-user allowed to create a table).

You can also create the table by your own means (using phpMyAdmin, by the command line mysql interface or by any other way that you are used to). Just use the same table definition shown above.

Load data into the table

The last step is loading the catalogue data into the table.

To do this you have work/exfilters.csv.my which is a quite ugly file with instructions to load the data line by line:

insert into exfilters (id,descrip,lmean,leff,lpiv,fwmh,weff,refer) values ('Bessell.B', 'Bessell B generic filter', '4400','4360', '4371.0712428546', '800', '900', null); insert into exfilters (id,descrip,lmean,leff,lpiv,fwmh,weff,refer) values ('Bessell.I', 'Bessell I generic filter', '8059.88359087', '7978.80497373', '8020.1456743209', '1543.1148203', '1495.06790617', null); insert into exfilters (id,descrip,lmean,leff,lpiv,fwmh,weff,refer) values ('Bessell.R','Bessell R generic filter', '6585.90688216', '6414.19957623', '6498.0740027738', '1567.05882353', '1591.02942387', null); insert into exfilters (id,descrip,lmean,leff,lpiv,fwmh,weff,refer) values ('Bessell.U','Bessell U generic filter', '3605.06847343', '3663.60780571', '3584.7749245969', '652.838404278', '640.396985034', null); ...

You can use this script to load the data in the table as:

If everything has gone right, you should have now a database table containing the catalogue data. You should be able to go to:

http://www.mylab.org/catalogues/exfilters/

where, remember, http://www.mylab.org/catalogues/exfilters/ should be the main URL that corresponds to your installation. (if you are trying to install this in a laptop or any other computer without a real internet address, try http://localhost/catalogues/exfilters/)

And search for data in the "Data Retrieval" section.

Configuration

In order to configure the application with the properties of your catalogue please point your web navigator to:

http://www.mylab.org/catalogues/exfilters/admin.php

(where, remember, http://www.mylab.org/catalogues/exfilters/ should be the main URL that corresponds to your installation)

Before starting

It is now when we are starting to work with your catalogue.

In a first installation you will get all the configuration sections filled wih the properties of the example catalogue. You must change those properties to the ones corresponding to your catalogue.

You should also delete the file work/exfilters.csv and put there the CSV file with your catalogue data.

If you want to keep both, the example catalogue and your own catalogue, for being able to make comparations during installation, we recommend you to install SVOCAT twice. Once in "exfilters" directory (where you will have the example catalogue) and once in "mycat" directory, where you will make your own configuration with your own data. That means repeating the steps in the Download section but using a different directory.

The first time: admin password

The first time that enter the web admin page, you will be asked to choose an administrative password. Please, remember this password because you will need it in the future to log in into admin.php.

Once you give some password here you will be asked to log in using it

Write the same password that you wrote before and you can start configuring things.

If you ever forget your admin password, you can delete the file config/config_admuser.php. And the admin.php application will prompt you for a new password as explained above.

Project

In this section we ask you just for a label to identify the project. It must be a single word with no blanks or special symbols. It is not used in very obvious places, but we will need it to create files and things like that.

(You can click in this image to see a larger version. Actually, if some image is not very clear in this documentation, you will usually have the option to see a larger version clicking on it)

MySQL database configuration

This application uses a MySQL relational database to store the catalogue data.

We assume that you have MySQL installed in your server, you are allowed to create a database (or you can use an existing one) to store the data and you know how to do this. Otherwise, please contact your system administrator.

There are useful applications that help to work with MySQL databases, like phpMyAdmin. You can take a look at it to see if it makes your life easier. Here we will give examples assuming the simple command line interface coming with MySQL itself.

If you are used to work with MySQL most of the explanations that follow will probably be obvious. If you have never worked with it, they will probably be confusing and not enough and you will need help from somebody. We just try to give some tips in the hope that they are useful.

Just to give a naive description of concepts:

• A database is mostly a collection of tables.
• A table is a collection of data structured as rows and columns.
• There are users (each one with its password) that are allowed to interact with the database. At least there will exist a user named "root" (not the same one as the linux root) but other ones can be created.
• There are different levels of permissions specifying in detail what a user can do with a given database or with a particular table in a database or even a column of a table. Some users can be allowed to do whatever they want (like the "root" user) while some others can be restricted to do only some specific things.

For SVOCat we need:

• A database already existing. SVOCat will not attempt to create it.
• The name of a table to store the catalogue data.
  • SVOCat will not create the table. It will generate a small "MySQL" script that you can use to create the table accordingly with the information given by you in the configuration (Fields section).
  • SVOCat will not insert the data in the table. If you provide a CSV file with the data (and the structure in this CSV file corresponds with the configuration given by you in the Fields configuration section) SVOCat will generate a "MySQL" script that you can use to insert the data in the database.
  • You can use these scripts or you can create the database table by your own means and just provide here the name of the table.
  • For any of these missions you will need a mysql user who is allowed to create a database, to create a table and to insert data in the table. But SVOCat does not need any information about that user.
• SVOCat only will use the database to make search (SELECT) queries. And we need that you provide, in the configuration, a mysql username and password who is allowed to do, at least, that. SVOCat will not create the user in the database, it must be an existing one and with the adequate permissions.

In our example:

• We have a MySQL server running in "localhost" as hostname at the default port. This in fact is the usual situation. If your server has a special configuration (running in a remote machine, or in a different port) the system administrator will tell you what to write here.
• We have created a database named "vocats". You can choose another name and create it or use a previously existing database. In any case, give here the name of an existing database.
  Just in case this is useful, a typical command to create a database is:

  > mysqladmin -u root -p create vocats

• We have chosen to use a table named "exfilters". A database can contain many different tables. We only need one to store the data from your catalogue. Choose some name for your table. There are many restrictions about table names in MyQSL. Choose a name with no blanks and no special characters.

• We have created a user for our database named "mycatuser" with password "mycatpass" who is allowed to make SELECT queries in the "exfilters" table (in practice, in all tables in the "vocats" database). You can (and probably should) use a different username/password in your final configuration.

WEB page texts

In order to generate the web page for your catalogue some information is needed about it.

In these images we show you where these texts will be used in the web page so that you have a better idea of what you want to put there.

• 'Title' will be used in the top header of all pages, but also as a title in the homepage.
• 'Subtitle' will be used in the top header of all pages, but also as part of the title in the homepage.
• 'Email' must be a valid e-mail address and will be used as the Help-Desk email contact.
• 'Description' will be used as the first part of the home page, describing the project.
• 'Acknowledge' will be used as the last part of the home page, below the list of resources. It is typically used to include acknowledgements, and hence its name, but you can write there whatever you want.

You can include html in these fields.

WEB functionalities/menu

In fact, as you see in the image above, SVOCat will generate not only a search form so that people can see your data but a simple web portal to offer more information about it. That's why a menu is included and you can configure which items you want to show in the menu and, thus, which functionalities you want to offer.

The currently available options are:

• 'Data Retrieval': it is the main functionality here. It creates a web form to search for data in the catalogue and displays the data corresponding to the search criteria allowing to visualize them, download them or send them to other VO applications. This is implemented in the search.php, that you should not edit.
• 'News': this should be a page showing news that you want to communicate to your users. We haven't done anything smart here. It is just a HTML/PHP file (news.php) that you must edit to include the news.
• 'Documentation': should be a web page showing the documentation about your catalogue. It is also a HTML/PHP file (documentation.php) that you must edit to include the documentation, as html, as links to pdf documents or in the way you wish.
• 'Coverage Map': This does not apply for catalogues without astronomical coordinates (RA,DEC). So you don't need to worry about it here. And you probably don't want to offer this in the menu.
• 'Credits': this link will provide a list of credits for the catalogue. It will include the text configured as 'Acknowledge' above but it could include more information that will be configured in the 'References' section later.
• 'Help-desk': this is a link to send an email to the email address that you have specified in the previous form.
• The "Other (1)" option is a placeholder just in case you want to program some extra functionality yourself and add it easily to the menu. For instance, you could just set "Team pictures" as the Menu Title here and include the team pictures editing the other1.php file. If you want more extra functionalities read the Advanced section of this documentation.

What you must do here is:

• You must check each item that you want to offer (on uncheck it if you don't want it). I would say that this application does not make sense if you don't ckeck the "Data Retrieval" functionality, but you can uncheck it also if you want.
• In the 'Menu Title' field you can write an alternative text to name the link that will be offered in the menu. For instance, you could rename "Data Retrieval" as "Catalogue Search" and this will be the text shown in the menu. If you don't write an alternative text, the one shown in the "Functionality" column will be used for the menu. Be careful about changing this because long titles could be very ugly in the menu. And please, don't use html here or you could get terrible results.

Coverage Map

One of the available options above is including a "Coverage Map" page.

A coverage map gives a fast idea of what area of the sky is covered by your catalogue, both to VO applications and to final users (if you make a simple image displaying the coverage).

For catalogues that do not contain astronomical coordinates (RA,DEC) this coverage map option does not make sense. So you don't need to configure anything here.

WEB logos

You can finally configure what logos to show in the top right corner of the web page.

We have configured this example to show our logos, but you can use your own/s.

VO curation

Virtual Observatory services are usually services that respond to special http queries with a document in a particular XML format named VOTable.

In these VOTables it is important to include information about the origin of the data, authors, etc. In the configuration application a short explanation of the meaning of these fields has been given. For a better explanation you can take a look to the SSAP VO Standard (sections 4.2.5.5 and 4.2.5.6 mainly).

These fields will be used in the metadata header of all the VO query responses for this service. If, for instance, you take a look to:

http://www.mylab.org/catalogues/exfilters/cs.php?format=metadata

(where, remember, http://www.mylab.org/catalogues/exfilters/ should be the main URL that corresponds to your installation)

in the first lines you will see a series of PARAMS giving the information that we have writen above.

... <DESCRIPTION> This is a fresh installation of SVOCat. Please, edit this and change to a text description of your catalogue. </DESCRIPTION> <PARAM name="Title" utype="ssa:DataID.Title" datatype="char" arraysize="*" value="Test catalogue"/> <PARAM name="Creator" utype="ssa:DataID.Creator" datatype="char" arraysize="*" value="SVO"/> <PARAM name="DataSource" utype="ssa:DataID.DataSource" datatype="char" arraysize="*" value="survey"/> <PARAM name="CreationType" utype="ssa:DataID.CreationType" datatype="char" arraysize="*" value="archival"/> <PARAM name="Publisher" utype="ssa:Curation.Publisher" datatype="char" arraysize="*" value="SVO/CAB"/> <PARAM name="PublisherID" utype="ssa:Curation.PublisherID" datatype="char" arraysize="*" value="ivo://svo.cab"/> <PARAM name="Reference" utype="ssa:Curation.Reference" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/vocats/v2/exfilters/documentation.php"/> <PARAM name="Contact.Name" utype="ssa:Curation.Contact.Name" datatype="char" arraysize="*" value="Enrique Solano"/> <PARAM name="Contact.Email" utype="ssa:Curation.Contact.Email" datatype="char" arraysize="*" value="esm@cab.inta-csic.es"/> ...

Given that these values must be included in XML responses like the ones above and that XML has some restrictions about it, please, try to use plain text here (no html tags, no & symbols...).

ConeSearch options

ConeSearch is a very simple protocol that is used in the Virtual Observatory for giving information about astronomical catalogues. You could want to take a look to the Simple Cone Search IVOA specification for more details (it is a very simple protocol, so it is a good point to start if this is the first time that you read a VO 'standard' document).

As a summary, the main idea of this protocol is that it allows to search for objects in a catalogue around a given point (specified by its RA and DEC coordinates in decimal degrees) and within a Search Radius (SR) also in decimal degrees.

Thus, a typical ConeSearch query would be something like:

http://.../cs.php?RA=1.01&DEC=10.04&SR=0.1

meaning that we want objects in the catalogue around RA=1.01, DEC=10.04 (degrees) and within a radius of 0.1 degrees.

The answer will be a VOTable (special VO document in XML format) containing the info in the catalogue for objects that match the conditions.

In practice, this does not make sense if your catalogue does not include RA,DEC columns.

But in the version of ConeSearch implemented by SVOCat we have included aditional options that allow to restrict the queries using other catalogue columns if you want to allow it. We will explain that later.

In this configuration section we only ask for very simple information:

• 'MaxSR': the maximum Search Radius (in decimal degrees) that is allowed for queries. This, again, does not apply if the catalogue does not contain (RA,DEC) columns. So you can leave it as 180 degrees.
• 'Description': A simple description of the catalogue that will be included in all the VOTables generated by the service (See the example above). You can not use html here. Use plain text.

SSAP options

SSAP (Simple Spectra Access Protocol) is a VO protocol designed to offer information about available spectra. You could want to read the IVO SSA standard for more information about it.

If your catalogue does not include spectra you just won't active SSAP.

If you have spectra to offer and you want to activate SSAP you need also to choose one of the catalogue fields as 'object unique ID' (after you configure the fields) and you will also have to cofigure how to access your spectra and their properties in the Spectra section later.

VO Availability

VO applications can query a VO service about its availability. If you configure it here as "Not available" those applications that query for this information will probably not query your service for data. But take into account that this won't make you service really unavailable.

In principle, we recommend you to let this configuration option as 'Available' and don't worry about this.

Catalogue fields

This one is probably the most important section of the configuration. And, given that you must write a lot of information, it can be the most confusing one. So we will try to explain the meaning of everything.

The main idea is that your catalogue can be seen as a series of rows (one for each observation) and columns (a column for each property of that observation).

We want that information stored in a database table with the same structure: rows and columns.

And you probably have the information in a CSV file with the information separated by commas (meaning different columns).

Here we ask you several things about the columns.

In order to explain this more clearly let's look at the example included with the distribution.

The structure of the data is:

and you have it as a CSV file like:

The idea is that there are 8 columns with different meanings. We want to know the meaning of each column (and some extra information).

Now let's go to the configuration form:

(Click in the image for a larger version. It will be opened in a different window)

Here you must fill as many rows as columns you have in your CSV file. That is, you have to give information about the 8 properties in your catalogue.

You can also add columns in this configuration that are not part of your CSV or the database table. In this case we have included two columns (lnk_dat, lnk_png) as placeholders to show links to datafiles. These columns will be further configured later, in the Links section.

• First, you must give a name to each property. This name will be the name of this property in the MySQL database when we create it (or it must be the name of the column in the database if you have already created it by yourself). It can only contain alphanumeric characters and the '_' symbol. And none of them can be a reserved word in MySQL.
• Then you say the datatype of this field. It can be: string, double or integer. This will be used to create the table properly. String fields allow searches with wildcards characters whereas numerical fields allow searches by range (see the Search Options section below).
• The 'Show' column says if you want to show this field in the search results or not deppending on the level of verbosity required. The ConeSearch protocol defines three different possible levels of verbosity: 1 for minimal verbosity (only show the most important properties), 2 for medium verbosity (this is the default) and 3 for maximum (usually: show all fields). You can specify 'never' if you don't want that a property is shown in any case. In our example catalogue we want to show all the available columns by default, so we configure all the columns with 'VERB=1' so that all of them will be always shown in the search results.
• If you mark 'No VO = Yes' this column won't be show in the response of VO services (ConeSearch for instance). This makes sense when you want to show something in the web page but it does not make sense to include it in listings as VOTable or CSV.
• By default, you have the option to sort the results table clicking in any column header. If you consider that it does not make sense to do this for some specific column, you can configure 'No sort = Yes'. In our example catalogue we do this for the last two columns (lnk_dat, lnk_png) that are special columns that we have included here to show links and do not correspond to columns in the database.
• 'CSV Order': here you must say in what position is this field in your CSV file. In our case, we have written the fields here in the same order than in the CSV file and the numbers run from 1 to 8. This only makes sense for columns that are already included in the CSV file. If we want to add other columns in this configuration we must set 'CSV Order = -1'.
• 'Res. Order': here you must say how you want to order the fields in search results. For instance, in our example, the 'epoch' property is in the eight position in the CSV file (before J,H,Ks magnitudes) but we want to show it in the last position in the search results. And as we don't want to show ra_hms and dec_hms we don't give an order for them.
• 'Title': this is the title that you want for this field when we show it in the search results table in the web page. For instance, we decide that the DECdeg column must be shown as 'DEC (ICRS)' although its name in the database will continue to be 'DECdeg'.
• You can also group several columns under the same title. If you want to do so, you just need to use the same word for them in the 'Web group' column. We don't need to do that in this case.
• 'Unit': write a string for the unit corresponding to this field. Leave it empty if units don't apply.
• 'Description': a text description of this property. It will be used both in the web page (a window is opened with the field description if the users moved the mouse over the "?" symbol) and the ConeSearch VO responses. You can use html here but be cautious because some html or symbols could generate problems (or look bad) in the VO services. If this happens try to use simple ascii here (no accents, no symbols, no html tags).
• 'UCD': the UCD's, or Unified Content Descriptors, are a special vocabulary defined for the Virtual Observatory to give more information, in VO services, about the physical meaning of each field. The ConeSearch protocol requires:
  • UCD=POS_EQ_RA_MAIN for RAdeg.
  • UCD=POS_EQ_DEC_MAIN for DECdeg.
  • UCD=ID_MAIN for the main object identifier (it will probably there exist such a field in your catalogue, in our example, it is the ID field).
  
  (In this case, as there are not RA,DEC coordinates in the catalogue, the first two requirements do not apply).

  For the other fields you can use the UCD builder at the CDS to find the adequate UCD for each case. It is not a big problem if you decide to leave this blank if you don't find a good UCD for a given catalogue property.

• The 'UType' column allows you to include a reference to a VO data model. In our example we are not going to go that further.
• 'Format (Web)' gives you the option to specify a particular format for this column when it is displayed in the web page. In some cases, for instance, it looks ugly to show to omany decimals in a column and you could prefer to limit them. Formats should be compliant to those allowed by the PHP sprintf function.
• 'Format (VO)' gives you the option to specify a particular format for this column when it is included in a VO response. In most cases you won't need to restrict anything here and you will leave this option empty to show, in the VO response, the actual content of your database.
• 'Phot. Group': if some fields correspond to photometric data give a name here to label the group to which it belongs. Then you will have to describe the group properties in the 'Photom. Groups' configuration section. Take into account that several fields can belong to the same group (for instance, a given magnitude and its error). In our example catalogue we don't have photometric properties, so we don't write anything here.

Here you can see the effect of some of these configuration options (but for understanding the three last columns you have to go to the Links and References sections).

Photometry groups

Astronomical catalogues often contain information about photometric measures of the catalogued objects (usually as magnitudes). When this happens it is very useful to have as much information about these magnitudes as possible.

The IVOA Photometry Data Model specifies how to describe a photometric value (and/or the associated photometric filter) in the VO context and you could want to read it for further information.

Warning!! Most catalogues that don't contain astronomical coordinates (RA,DEC) will not contain photometric information either. So you probably don't need to read this section further. If you do, you will read that each photometric point can/must be associated to a photometric filter in the SVO Filter Profile Service. This does not have anything to do with the fact that we have choosen to build an example catalogue using filter information (we wish this does not confuse you). In our example catalogue (exfilters) we don't have photometric information. In other catalogues, if you want to include photometric information, follow the instructions below.

In the configuration you must do two different things:

• In the "Fields" tab (see figure above), group together those columns that correspond to the same "photometric filter" (for instance, a magnitude and its error will be in the same group). That means:
  • For each magnitude, give an arbitrary name to the "Phot.Group" column (usually, a different one for each magnitude).
  • It there are other columns that can be associated to a given magnitude, repeat the same "Phot.Group" name that you chose for the magnitude.
  • In our example catalogue we have four different magnitudes and we have chosen:
    • magr field ⇒ sdss_r group.
    • sig_magr field ⇒ sdss_r group (this corresponds to the same "filter" than magr so we asign the same group to it and, thus, they will share the same filter information.
    • magJ field ⇒ 2mass_j group.
    • magH field ⇒ 2mass_h group.
    • magKs field ⇒ 2mass_ks group.
• In the "Photom. Groups" tab:
  • give the main characteristics of each photometric filter.

For each photometry group you just need to specify:

• 'Phot.Group': the name for the photometry group.
• 'Value type': if it is a magnitude or a flux (flux, flux density.. whatever).
• 'Filter ID': The filter name in the SVO FPS.
• 'Mag type': Is this a pogson magnitude (the usual case) or asinh o linear?
• 'Zero Point': if the value is given as a magnitude and you do not find the right filter in the Filter Profile Service, you can give a zero point here (in erg/cm2/s/A, please).
• 'ZP type': Is the zero point in Vega, AB or ST system?

We assume here that each photometric value can be described as corresponding to one of the photometry filters available in the SVO Filter Profile Service. Ideally, this means that the observation has been made using that filter, but it is enough if you think that the observing filter is close enough to one in the Filter Porfile Service.

Giving a Filter ID for the observation implies including a lot of information about the filter and, thus, about the observation (and how to understand a given magnitude/flux).

All this information about filters will be used in the web page so that when a user moves the mouse over the table header a small windows appears giving the description of each field.

And, what's more important, it will be used in the VO ConeSearch response to include metadata groups with the fields corresponding to the same filter and the appropiate links to the Filter Profile Service's to get extra information about the filter and the adequate calibration. This allows a VO application to automatically retrieve all the data that it needs about this photometric measure. It could be a zero point to transform it to flux, a wavelength to plot the value or even the actual filter transmission curve to compute synthetic photometry to compare with the observed one.

... <GROUP name="phot_sdss_r"> <PARAM name="phot_sdss_r_fid" utype="photDM:PhotometryFilter.uniqueIdentifier" datatype="char" arraysize="*" value="SLOAN/SDSS.r"/> <PARAM name="phot_sdss_r_filterurl_web" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/index.php?id=SLOAN/SDSS.r"/> <PARAM name="phot_sdss_r_filterurl_vot" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/fps.php?ID=SLOAN/SDSS.r"/> <PARAM name="phot_sdss_r_pcid" utype="photDM:PhotCal.identifier" datatype="char" arraysize="*" value="SLOAN/SDSS.r/AB"/> <PARAM name="phot_sdss_r_pcurl_vot" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/fps.php?PhotCalID=SLOAN/SDSS.r/AB"/> <PARAM name="phot_sdss_r_mtype" utype="photDM:PhotCal.magnitudeSystem.type" datatype="char" arraysize="*" value="asinh"/> <FIELDref ref="magr"/> <FIELDref ref="sig_magr"/> </GROUP> <GROUP name="phot_2mass_j"> <PARAM name="phot_2mass_j_fid" utype="photDM:PhotometryFilter.uniqueIdentifier" datatype="char" arraysize="*" value="2MASS/2MASS.J"/> <PARAM name="phot_2mass_j_filterurl_web" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/index.php?id=2MASS/2MASS.J"/> <PARAM name="phot_2mass_j_filterurl_vot" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/fps.php?ID=2MASS/2MASS.J"/> <PARAM name="phot_2mass_j_pcid" utype="photDM:PhotCal.identifier" datatype="char" arraysize="*" value="2MASS/2MASS.J/Vega"/> <PARAM name="phot_2mass_j_pcurl_vot" datatype="char" arraysize="*" value="http://svo2.cab.inta-csic.es/theory/fps/fps.php?PhotCalID=2MASS/2MASS.J/Vega"/> <PARAM name="phot_2mass_j_mtype" utype="photDM:PhotCal.magnitudeSystem.type" datatype="char" arraysize="*" value="pogson"/> <FIELDref ref="magJ"/> </GROUP> ...

You don't need to find that information very intuitive. It's there more for being understood by applications than for human reading. Just as a short summary, in each GROUP there are several PARAM's giving information about the group (in this case, links to the Filter Profile Service filter and calibration) and one or several FIELDref's giving the fields that share those properties.

Search Options

By default the 'Data Retrieval' section of the web page would include a simple Cone Search form where users could search for catalogue entries around a given point in the sky (RA and DEC) and within a search radius (SR).

But if your catalogue does not include RA,DEC coordinates, this type of Cone Search queries do not make sense, and this search form will not be shown.

Instead, you have the option to configure your service so that users can restrict searches using other catalogue fields.

For each field you can set the 'Search' column to "Yes" and it will be optionally allowed for searches.

If you mark a field as "Yes", you must also set the "Search type" and "Form Type" to specify how this field shoud be used.

• 'Search Type' can have three different values:
  • 'Value': the user will be allowed to specify only a value for this field. In this case, only results matching the given value will be displayed. For numeric type fields this means that the value is exactly the same. For string fields, the search will be done in a SQL "...like 'value'..." way, what means that "%" can be used as wildcard.
  • 'Range': the user can specify a range of values. Queries will be restricted to results so that the field value is in the range. A open range (for instance, leaving the maximum blank) will be understood as no boundary.
  • 'List': the user can specify a list of desired values separated by commas.
• 'Form type' can have two different values:
  • 'input': a open field will be shown to the user so that he/she can write a free value.
  • 'select': a select box will be shown to the user with all the available values in the database for this field.

You must set this configuration values wisely. For instance:

• It does not make sense to set 'Search type'='range' for string fields.
• It is usually better to set 'Search type'='range' for double fields (they often contain an unspecified number of decimals and it's difficult for the user to match an exact value).
• It only makes sense to set 'Form type'='Select' if the list of different values for that field (in the whole catalogue) is short. For instance, if you have a catalogue column specifying the object type as "star, galaxy, probably star, probably galaxy, unknown" it is ok. But it does not make much sense offering a select box with hundreds or thousands of values in it.

In our case we have allowed to restrict searches using 'descrip', 'lmean' and 'weff' and we have allowed ranges for both 'lmean' and 'weff'. Now the search form will show the corresponding entries for these two fields:

of course, if the user does not set any restriction on them, the search results won't be affected. In this case, there are 42 catalogue entries that are shown as default.

But users can restrict the results to those with a λ_mean between 3550 and 4000 Angstroms (just an example):

you can see that the list of results has changed. Now there are only 5 filters that meet the condition.

But users can also restrict the query asking for results which description contains the string 'colors' (using % as wildcard):

and now 14 catalogue entries match the restriction.

Just as an example, if we had set 'Form type'='select' for the 'λ_mean' field the web form would have been different, showing a select box for minimum and maximum λ_mean values.

where a user could have seen a list of all values for λ_mean present in the catalogue and choose among them (both for the minimum and maximum of the range). I don't think that this makes sense when the list of posible values is very long, and it is not usually a good choice for double type fields, but of course it's your decision.

Mags/Colors search

In the case that your catalogue contains photometry values, an special form can be included to search for magnitude and colors ranges.

It does not apply in the case of our example catalogue. So we leave it empty.

Object Name/Target search

In the case that your catalogue contains astronomical objects you could want to configure special options to allow for alternative object names using Simbad information.

In our example catalogue this does not apply and we leave this form empty.

Default search

When a user first accesses the 'Data retrieval' section it is usual to show, at least, a part of the catalogue by default. This means performing a "Default search" and showing the results of this search.

You can configure here if you want to show the catalogue as default, how many results you want to show and if you want to add some restrictions to the default search.

In our example catalogue we have choosen to show all the results sort by the λ_mean value (oby=lmean).

But you can include more restrictions. For instance, you can ask to show only entries with λ_mean in a given range:

and the default result would include that restriction:

Other search options

In this section you need to allow to make searches without using RA,DEC coordinates. This is necessary for catalogues that do not contain RA,DEC.

Special listings

In the search page you can specify some special listings for catalogue entries with certain properties. These will appear as links so that, when the user clicks on of them, a search will be done and the corresponding results will be shown. To do this you must specify the text that will appear highlighted and the restrictions in terms of the database fields (only for database fields that have been configured above as available for search, that is: descip, lmean or weff in our case).

In our example catalogue this does not make much sense because it is very small. But we could, for instance, define some links as:

The first one would produce a list of filters that contain 'Bessell' in the description (note the % wildcards).

The second one would produce a list of filters with an "effective width" smaller than 300A.

Search options in ConeSearch

Although the VO ConeSearch protocol only specifies that RA/DEC/SR must be the search criteria, it does not forbid to restrict searches using other catalogue fields.

In our particular implementation of ConeSearch all the search restrictions that are allowed for the web page are also allowed for the ConeSearch queries.

In order to make these options public, we have implemented a 'format=metadata' option in the same way as it is specified in the SSA protocol:

http://www.mylab.org/catalogues/exfilters/cs.php?format=metadata

(where, remember, http://www.mylab.org/catalogues/exfilters/ should be the main URL that corresponds to your installation)

There, among other things, the list of parameters allowed for queries are specified in the usual fashion (and the available range or list of posible values when appropiate).

... <PARAM name="INPUT:VERB" datatype="integer"> <DESCRIPTION>Allowed values for verbosity: 1=minimum, 2=default, 3=maximum</DESCRIPTION> </PARAM> <PARAM name="INPUT:descrip" datatype="char" arraysize="*"> <DESCRIPTION>Filter short description.</DESCRIPTION> </PARAM> <PARAM name="INPUT:lmean_MIN" unit="Angstrom" ucd="em.wl" datatype="double"> <DESCRIPTION>Minimum value for lmean. Mean wavelength.Defined as:λmean ≡ ∫λT(λ)dλ / ∫T(λ)dλwhere: T(λ) ≡ filter transmission</DESCRIPTION> <VALUES> <MIN value="3374.5464234215"/> <MAX value="103240.68468228"/> </VALUES> </PARAM> <PARAM name="INPUT:lmean_MAX" unit="Angstrom" ucd="em.wl" datatype="double"> <DESCRIPTION>Maximum value for lmean. Mean wavelength.Defined as:λmean ≡ ∫λT(λ)dλ / ∫T(λ)dλwhere: T(λ) ≡ filter transmission</DESCRIPTION> <VALUES> <MIN value="3374.5464234215"/> <MAX value="103240.68468228"/> </VALUES> </PARAM> <PARAM name="INPUT:weff_MIN" unit="Angstrom" ucd="instr.bandwidth" datatype="double"> <DESCRIPTION>Minimum value for weff. Effective width.Defined as:Weff ≡ ∫T(λ)dλ / Max[T(λ)]where: T(λ) ≡ filter transmission. Equivalent to the horizontal size of a rectangle with height equal to maximum transmission and with the same area that the one covered by the filter transmission curve.</DESCRIPTION> <VALUES> <MIN value="116.25001071944"/> <MAX value="43744.436381959"/> </VALUES> </PARAM> <PARAM name="INPUT:weff_MAX" unit="Angstrom" ucd="instr.bandwidth" datatype="double"> <DESCRIPTION>Maximum value for weff. Effective width.Defined as:Weff ≡ ∫T(λ)dλ / Max[T(λ)]where: T(λ) ≡ filter transmission. Equivalent to the horizontal size of a rectangle with height equal to maximum transmission and with the same area that the one covered by the filter transmission curve.</DESCRIPTION> <VALUES> <MIN value="116.25001071944"/> <MAX value="43744.436381959"/> </VALUES> </PARAM> ...

so that valid queries to the catalogue ConeSearch service could be, for instance:

• http://www.mylab.org/catalogues/exfilters/cs.php?descrip=%25Bessell%25
• http://www.mylab.org/catalogues/exfilters/cs.php?lmean_MIN=3000&lmean_MAX=5000
• http://www.mylab.org/catalogues/exfilters/cs.php?lmean_MIN=3000&lmean_MAX=5000&descrip=%25Bessell%25

depending on how the user wants to restrict the query.

(note that the % wildcards must be urlencoded as %25 when included in urls).

File Paths

In principle, this section is only important if you are going to populate the database starting with a CSV file and you want SVOCat to generate scripts to make it easier for you.

If this is the case you only have to write here the computer path to the folder containing the CSV file or files (if there are several .csv files in that folder, all of them will be considered).

By default the .csv files should be in the "work/" folder in your SVOCat installation. When you download and unpack SVOCat you will find a file exfilters.csv in that folder. But you can put the files in a different folder and write its full path here.

(in this case, the value for the path is somewhere in my computer, you should change it to the right path in YOUR computer).

Remember that this path (and the .csv files in the directory) must be readable by the Apache web server. We recommend you to put the csv files in the work directory that comes with the SVOCat distribution.

If you have created the database by your own means, you can ignore this configuration section.

Scripts

In practice you don't need to configure anything here.

This configuration section is there so that you can click on the "Create scripts" button whenever you want and the scripts in the "work" folder will be generated again taking into account any changes that you have made in other configuration sections.

These scripts intend to be useful to help you to create and populate the database with your catalogue data starting with your csv file/s. If you want to create the database and populate the database table by your own, you can ignore this configuration section.

If you want to use the scripts you can do as follows:

1. First, you need to create a table in the database with the columns that correspond to your catalogue. In the "work/create_table.my" file you have the commands in SQL to create the table (SQL is the language for interacting with relational databases).

   If you understand a little SQL you can read the file. If not, in summary, it deletes the table named "mycat" (or the name given by you in the "Mysql database" configuration section) if it already exists and then creates the table again using the information about the fields given by you in the "Catalogue fields" section.

   Typically you can use this file as follows:

   > mysql -u catuser -p vocats < work/create_table.my

 

2. The second step is reading the csv file/s and loading the actual data in the mysql table. For this, SVOCat generates a simple csh script named work/load_data2.csh. This script will read your csv file/s and generate files in SQL so that you can insert the data in the MySQL database easily.

   Typically you can use this file as follows:

   • First you move to the directory where you have installed your catalogue:

     > csh /var/www/catalogues/mycat

   • Then you execute the script:

     > csh work/load_data2.csh

     This will generate a XXX.csv.my file for each of your XXX.csv files.

   • Then you load each of those files in the database as:

     > mysql -u catuser -p vocats < XXX.csv.my

VO Registry

When you have configured your catalogue and everything works as desired, there is one more step to take: register your service in a VO Registry
You need to do this so that VO applications are able to find and access your catalogue.

In order to register your service you have to go to a VO Registry and fill a form or upload an XML file with your service record.

In this configuration section we use the information that you have provided in other configuration sections to build an XML file that you can upload to a VO Registry to register your service more easily.

You need to check all the details, then click on 'Continue' and a file will be created in your "work/" folder named registry.xml. And you will see a "Download it" that you can also click to retrieve the file.

Once you have done this, in order to register your service you have to:

1. Go to a VO-Registry web page. There are several ones available and you can choose the one that you prefer, but our explanations will refer to the EURO-VO Registry.

   (Please, take into account that the image captures shown below correspond to the current version of the EURO-VO Registry but they could be outdated when you try to access the registry. We hope that, if this happens, this explanation is still useful for you in essence).

2. You need an "authority id" to register services.
   If you already have one, you have probably registered other services in the past and you maybe don't need more help.
   If you don't have a registered authority yet, go to the EURO-VO Registry, click the Join button in the EURO-VO Registry webpage and register an authority

   
   Use the same values that you have writen in the 'VO Curation' configuration

   • Username: Curation.PublisherID
   • Person name: Curation.Contact.Name
   • E-mail: Curation.Contact.Email
3. Click in the Login button to identify yourself using that username.

   

4. Click in the Add new resource button.

   

   Here you can choose to use a wizard to create a minimal resource. But SVOCat builds a full xml file that you can upload to the registry to finish the process. So it's easier to select that option.

5. Then click in the Browse button, select the registry.xml file that is saved in your "work" folder and finally, click in the Submit

   
   You should see a message commenting the creation of the new resource. If you get some errors, please, solve them (edit the corresponding configuration and create again the registry.xml file) and submit the file again.

Spectra

Some astronomical catalogues offer spectra either as the main product (as in spectral libraries) or together with other object properties.

In our example catalogue there are not spectra so, by now, we leave this configuration section empty.

Links to external URLs in results table

You can add links to any column in the results table. In some cases, you can even include columns only to contain links.

In our example we include three different links:

• A link in the ID column pointing that will go to the entry for the same filter in the SVO Filter Profile Service.
• A link in the so called "lnk_dat" column to download the transmission data for the filter.
• A link in the so called "lnk_png" column to show, only in VO services, the url to download the transmission plot. This link does not apply to the catalogue web presentation.

See that you can use, in some configuration options, {$MYFIELD} as a place holder that will be replace with the value of the MYFIELD column for each catalogue entry.

Links with OpenWindow in results table

You can also include links that open a windows displaying some content. This is often used to preview some images associated to catalogue entries. But other types of html content could be displayed.

In the case of our example catalogue we include a link that will open a window showing a preview of the filter transmission curve.

This only applies to the web presentation of the catalogue. That's why in the section above we have included a link to download the plot only in the VO services and we include here the preview of the curve in the web service.

Datalink configuration

Datalink is a VO protocol designed to associate links to catalogue entries. If you activate it you need to define also a field to be used as Datalink ID. And,below, you will have to define what links you want to show and their properties.

Links for Datalink

In our example catalogue we have three types of links:

• Link to the SVO Filter Profile Service.
• Link to the transmission curve (ascii file).
• Link to the plot of the transmission curve (png file).

Reference display options

It is quite common that a catalogue contains different references (papers, web pages) for different catalogue entries.

For instance, in our example catalogue, there are references for the origin of the information about the different filters. These references are included in our database as simple labels separated by commas ("A,C" for instance) and we, of course, want to display this information.

There are two places where references can be displayed:

• As a column in the results table.
• In the "Credits" web page section.

This configuration option here especifies the behaviour of the links displayed in the results column.

The available options are:

• 'Direct link to URL': if there is a url associated to a reference label, links are displayed that open the corresponding url directly.
• 'Open window with list': when the user clicks in a reference, a small window opens showing the list of references.
• 'Link to list at the bottom': the list of references is included at the bottom of the results table. When the user clicks in a reference, the browser centers in the list.
• 'Link to credits page': when the user clicks in a reference it opens the 'Credits' page where a list of all the credits is shown.

An example of how it looks for the 'Open window with list' option:

Global References

Global references are those that you want to display as general references for your service. They will be displayed in the Credits section.

Explore Database for reference fields

In the typical case you have one or several columns in your database with labels for references to external sources.

You should specify here:

• What column/s contain reference labels.
• In the case that a column can contain several references with a repeated text separating them (for instance "A,B" or "Smith 2012; Johnson 2013; McDonalds et al 1987", etc) please specify which is the text separating labels.
• A title that describes the type of reference (if you have references in different columns it is likely that you also want to display them under a different list).

Once that you have saved this informacion you have the option to click in the "Explore" button below. SVOCat will scan your database for all the different reference labels to offer the list in the form below.

References corresponding to database values

Here you have to specify, for each different reference label:

• The database field where it can be found.
• The label in the database.
• How you want to display that label. For instance, we decide that the label "A" should be displayed as "(Cousins)".
• The link that corresponds to this reference.
• Some texts to include before and/or after the link.

Edit records

SVOCat gives you the posibility to edit your records one by one.

This is not practical for adding a lot of new records or making massive changes. But it is good if you want to correct particular mistakes or add a few new records to the database.

In order to do this you have to point your browser to:

http://www.mylab.org/catalogues/excat2/edit.php (where, remember, http://www.mylab.org/catalogues/excat2/ should be the main URL that corresponds to your installation)

You will be asked for the administrative password

And, once you have identified yourself correctly, you will see a search form equivalent to the one that you have designed for your catalogue.

You can make any search and, when you see the results, you will also see, on the left of each record, a link to edit it. And also a link at the botton to add new records.

If you click in the "(edit)" link, you will see a form where you can change the values in the database for this record. You just need to change whatever you want and change the "Save" button.

You also have the option to delete a record. If you want to do so you have to click in the "(Delete this record)" link.

You will we asked to confirm the deletion. If you want to confirm you have to click the "Yes, delete" button and this record will be deleted from the database (be careful, this cannot be undone). Otherwise, click the "No!!" button and nothing will ce changed.

Instead, if you want to add a new record to the database, you click the "Add new record" link and you get a form that you have to fill with the new record properties.

Web page design

You can use this application as it is once you have configured it. The main web texts and logos can be changed through the administrative interface so that it reflects the main characteristics of your project.

But, in any case, we have tried to make the web page design as simple and structured as posible so that it's not difficult to change it as you need.

The page layout is composed by 5 main layers:

• Header: the top layer, containing title and subtitle.
• Menu: a thin layer below the header. It contains the web page menu.
• Logos: a layer containing the logos. It is positioned over the header and menu layers, on the top right corner of the page.
• Main: this is the area where the main content of the page is located. Depending on the menu item selected, the homepage, news, documentation or data retrieval pages are shown here.
• SVOCat footer: this is a thin layer shown at the bottom of the page. It displays a link to SVOCat.

If you want to customize the look and feel of the web page you can do it just by editing the files available in the "style" folder. In order to do this you will probably need some knowledge about CSS and even a little PHP (depending on what you want to change). We will give here some tips about it.

Web page design

Customizing: style.css

If you decide to customize the look at feel of your web page, it could be enough to change the style/style.css file.

All the styles used in the public web page are defined here.

If you are used to working with CSS style sheets you will know what to do. If not, you maybe want to learn a little about it (see, for instance, W3C page about style sheets) but, in any case, you could be satisfied changing just the color of some elements in the page, which is quite easy.

If you take a look to style/style.css you will see that it is quite simple (we show here only an schematic structure, look into the real file for the details).

body {} a {} a img {} h2 {} select, input, textarea, button {} /*================ HEADER ============================================*/ #cat_div_header {} #cat_div_header h2 {} #cat_div_header h3 {} #cat_div_logos {} #cat_div_menu {} .cat_menu {} .cat_menusel {} .cat_menu a {} .cat_menusel a {} /*================ MAIN ==============================================*/ #cat_div_main {} #cat_div_main ul li {} #cat_div_main h3 {} /*================ FOOTER ==============================================*/ #cat_div_svocat {} /*================ SPECIAL STYLES ======================================*/ /* special style for showing command-like texts */ .cat_comm {} /* special style for showing errors or, sometimes, messages that we want to highlight for the users */ .cat_error {} /* special style for showing text in a smaller font. */ .cat_mini {} /*================ home.php ======================================*/ #cat_div_home_descrip {} #cat_div_home_resources {} #cat_div_home_acknowledge {} /*================ search.php ======================================*/ .cat_search_form_tit {} .cat_search_form_fld {} .cat_search_list_tit {} .cat_search_list_fld {} .cat_search_more_tab {} .cat_search_more_lnk {} a.cat_search_help {} /*================ news.php ======================================*/ .cat_news_tit {} .cat_news_txt {}

In summary:

• We set some general properties for the web page: body (default font, background, etc), for the links (a) for headers (h2) and form elements (select, input, textarea, button).
• Then we define styles for the different layers:
  • Header: header itself, menu and logos.
  • Main content area.
  • SVOCat footer.
• We define some special styles for displaying some special kind of texts (command-like texts, errors, text in smaller font).
• And finally some styles only to be used for specific contents:
  • Home page: the different layers contained in the home page.
  • Search (Data Retrieval): styles for the search form and list of results.
  • News page.

Just changing colors

If you just want to change some colors in the web page, look in the style/style.css file for color definitions. You will find them as: "color" (for font color), background or background-color (for background color) or in some "border" definitions (for line color).

Colors are specified as things like #abc, it is, a "#" symbol followed by three characters. Those three characters represent a color in RGB format. That means that the first number is the amount of Red, the second the amount of Green and the third the amount of Blue. These amounts are writen as hexadecimal numbers (where 0 is minimum and f(16) is maximum). For instance:

• #000 is "nothing of red, nothing of green, nothing of blue", and the result is: black.
• #fff is "maximum of red, maximum of green, maximum of blue", and the result is: white.
• #ff0 is "maximum of red, maximum of green, nothing of blue", and the result is: yellow.
• #f80 is "maximum of red, 50% of green, nothing of blue", and the result is: orange.

You can try some combinations using numbers and letters (a,b,c,d,e,f) and see what you get.

Given that the web page design is simple, I would guess that, if you want to change colors, you will want to change the often used "Red" colors (menus, titles...) to some other color. Let's imagine that you want a mostly white-and-blue design instead white-and-red. You will want to change:

• h2 → color: #900; to color: #447;
  (to change all the big titles)
• #cat_div_header h3 → color: #900; to color: #447;
  (to change the small subtitle in the top header)
• #cat_div_menu → background-color: #900; to background-color: #447;
  (to change the background of the menu)
• .cat_menusel a color: #900; to color: #447;
  (to change the color of the link in the menu when an item is selected)
• #cat_div_main h3 → color: #900; to color: #447;
  (to change all the small titles in the content)

and we get a more bluish look:

Customizing: header.php

In the file style/header.php we define everything that is to be shown before the main content. That is: header (title, subtitle), logos and menu.

	First we show the "cat_div_header" layer (with title and subtitle).
	Then we show the "cat_div_logos" layer (with the logos). In practice this is generated by an special function using the configuration that you set in the administration tool. You probably don't want to change anything here.
	Then the "cat_div_menu" layer (with the menu). In practice this is generated by an special function using the configuration that you set in the administration tool. You probably don't want to change anything here.
	Finally we start the "cat_div_main" layer where the main content will be displayed. This layer will be closed later in the style/footer.php file.

One posible change that you could want to make here is changing the text title and subtitle on the top-left corner by some image. If this is the case you could do as follow:

• Take your title image and save it in the style/images/ folder. In our case we have done some fancy title image named "othertit.png".
• Edit the header.php file as this:

  ⇒

  and you will get the fancy image as title:

  

Customizing: footer.php

The file footer.php makes the actions that must be performed at the end of the page (after showing the main content)

• First we close the main content layer
• and then we show the SVOCat layer telling that SVOCat has been used here.

But you could want to add your own text:

and you get the new footer:

⇒

Or even drop the SVOCat line (if you do so, please send us a note saying that you are using the application so that we know it and we can see that our work is being useful for somebody).