SVOCat Documentation

Version 0.5, June 2016, author: Carlos Rodrigo

HomeDownloadDocumentationExamplesCreditsHelp-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:

(See some technical details below)

We assume that:

and that your have your data either:

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 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.

Technical details:

We have tested the application only in Ubuntu Linux, in particular in two different installations:

and some examples in this documentation are specific for linux/unix systems.

In principle, there is no reason why you need any specific distribution or any special version of the software because SVOCat does not need any specially modern feature of any of the needed software. But, just in case, we recommend you to use some Linux distribution and install the most up to date Apache+MySQL+PHP packages for that distribution (in some cases you can find them under the "LAMP" label).

Installing all the software in Ubuntu should be quite easy. You can find a lot of examples if you search in google for "Installing LAMP in ubuntu", for instance: ApacheMySQLPHP in ubuntu. But it should be as straightforward as opening a terminal and writing:

sudo apt-get install tasksel
sudo tasksel install lamp-server

During the installation process you will be asked for a password for the "root" user. This is not the typical unix root administrator. It's the default mysql user with all the permissions to interact with the databases. You should choose some password for that user and remember it. You can leave it empty if you wish, but then the "root" user will have an empty password and that's quite bad security.

You can also install everything in other operating systems like windows or Mac OS, but the technical details on how to install each software in those operating systems are out of the scope of this documentation.

 

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).

> cd /var/www/
> sudo mkdir catalogues
> sudo chown carlos:carlos catalogues

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.

> mv SVOCat.tar.gz /var/www/catalogues/
> cd /var/www/catalogues/
> tar xvfz SVOCat.tar.gz

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 mycat.

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

/var/www/catalogues/mycat/

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/mycat/

We will asume in this documentation (when we need to refer to them) that these ones are the abolute 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:

> cd /var/www/catalogues/mycat/
> sudo chmod -R ugo+r .
> sudo chmod ugo+x `find . -type d`

 

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 make them (and their contents) owned by the www-data user and make them writable by that user.

> cd /var/www/catalogues/mycat/
> sudo chown -R www-data:www-data config/ work/
> sudo chmod -R u+rw config/ work/

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 contact your server administrator.

 

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) 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 and search.php implement the four main functionalities in the web page and you could want to edit some of them (news and 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 decide to include this functionality in the configuration process you must also edit it and include the 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   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/mycat/admin.php

The admin directory includes files used by admin.php.

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/mycat/index.php
http://www.mylab.org/catalogues/mycat/

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/mycat/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   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 files are used by the web page to be able to send catalogue search results to the Aladin application through JNLP.

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 CMC15 data.

As a very brief summary:

In the data-csv/cmc15n2-part1.csv file you have the data in csv format.

These data are equivalent to a table with 5000 lines and 11 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 (catuser)

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

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

mysql> use mysql;

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

mysql> grant all privileges on vocats.* to 'catuser'@'locahost' identified by 'catp@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 (mycat)

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 "mycat".

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

cd /var/www/catalogues/mycat/
mysql -u catuser -p vocats < work/create_table.my

(where "catuser" 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/cmc15n2-part1.csv.my which is a quite ugly file with instructions to load the data line by line:

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

cd /var/www/catalogues/mycat/
mysql -u catuser -p vocats < work/cmc15n2-part1.csv.my

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/mycat/

where, remember, http://www.mylab.org/catalogues/mycat/ 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/mycat/)

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

The catalogue is small. To get a results try for instance:

 

Configuration

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

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

(where, remember, http://www.mylab.org/catalogues/mycat/ 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 data-csv/cmc15n2-part1.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 "mycat" directory (where you will have the example catalogue) and once in "mycat2" 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:

For SVOCat we need:

In our example:

Web options

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.

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:

What you must do here is:

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).

SVOCat does not help to generate the coverage map, you must do it by yourself. It only provides a simple way to display these files once you have generated them.

In order to do this you must first generate a MOC fits file. You must generate it by yourself (using, for instance, STILTS) and just write here where the location of your MOC file.

You can also generate some images displaying the coverage in a user friendly way so that we can show these images in the web page.

SVOCat expects that you provide:

A SVOCat installation includes a folder named "coverage" as a covenient place to store these files. But you can decide to put them weherever you want.

The information provided in the configuration will be automatically used to generate the "Coverage" web page, as follows:

WEB logos

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/mycat/cs.php?format=metadata

(where, remember, http://www.mylab.org/catalogues/mycat/ 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.

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 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:

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 11 columns with different meanings. We want to know the meaning of each column (and some extra information).

IMPORTANT!. SVOCat needs that there exist two columns named RAdeg and DECdeg with the RA (Right Ascension) and DEC (Declination) in decimal degrees. In this example case they are the fourth and fifth columns and we just need to name them correctly in the configuration form.

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 11 properties in your catalogue.

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 this 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.

In the configuration you must do two different things:

For each photometry group you just need to specify:

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.

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 will include a simple Cone Search form where users can search for catalogue entries around a given point in the sky (RA and DEC) and within a search radius (SR).

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

For each field (except RA and DEC, that are always required) 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.

You must set this configuration values wisely. For instance:

In our case we have allowed to restrict searches using 'objID' and 'magJ' and we have allowed ranges for 'magJ'. 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 664 catalogue entries in a radius of one degree around RA=0, DEC=10.

But users can restrict the results to those with a 2MASS.J magnitude between 14 and 14.5 (just an example):

you can see that the list of results has changed. Now there are 78 objects in a radius of one degree around RA=0, DEC=10 and with magJ between 14 and 14.5.

But users can also restrict the query asking for results which objID contains the string '050':

and now only three catalogue entries match all the restrictions.

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

where a user could have seen a list of all values for magJ 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, but of course it's your decision.

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/mycat/cs.php?format=metadata

(where, remember, http://www.mylab.org/catalogues/mycat/ 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).

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

depending on how the user wants to restrict the query.

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).

(in this case, the value for the path is somewhere in my computer, you should change it to somewhere 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 data-csv directory that comes with the SVOCat distribution.

If you have created the database by your own means, you can ignore this configuration section in most cases. That is, unless you have set in the 'Fields' section that one of your fields corresponds to a file type ('img+coor').

In the very special case that you have set, in the 'Fields' section, that one (or several) of your fields corresponds to a file type ('img+coor') you must say here where those files are located.

This will be explained better in the 'advanced' section. But, just for giving an example, if we had set the magH and magKs fields as 'img+coor' we would have to specify here where the corresponding files are located:

(of course, the mag fields do not correspond to any file and this particular example does not make much sense, but we show the image just as an example of how this configuration section can change depending on the fields types.

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.  

  3. 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

 

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:

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.

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).

In summary:

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:

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:

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:

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)

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).

 

Extra tips

There are some important operations that you have to do outside SVOCat, although SVOCat will help to display results (as for MOC files) or can help to easy the operation (as for the registry case).

Here we give you some tips with the hope of helping you with these operations.

MOC files

SVOCat does not automatically generate the files necessary to display the coverage of you catalogue. You need to generate this files by yourself, include them in the configuration and, then, SVOCat will display them.

Here we give some tips on how to generate the corresponding files.

If you want to generate the files to show a coverage map for your catalogue, we recommend to do it as follows:

 

  1. Generate a VOTable with all your data. You only need two columns containing RA and DEC in decimal degrees. Make sure that these two columns are named RA and DEC (otherwise, you could change the examples below accordingly).

    Save your file as myvotable.xml

     

  2. Use stilts to generate the MOC file.
    • Download stilts.jar.
    • Execute:
      java -jar stilts.jar pixfoot in=myvotable.xml ra=RA dec=DEC order=8 mocfmt=fits out=moc.fits
    • You can give different integer values for "order". Try 4, 8... depending on your catalogue.

     

  3. Open this mod.fits file using Aladin.
    • Download Aladin
    • Run Aladin:
      java -jar Aladin.jar
    • Open the fits file: "File -> Open local file".
    • Add a grid: "Overlay -> Grid".
    • Change the type of projection: "Edit -> Properties".
    • Play with aladin options till you are satisfied with what you see.
    • Save the image: "File -> Save the current view -> PNG".

    Repeat the last three steps for each type of projection: AITOFF, Cartesian.

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 see and access your catalogue.

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
     
  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.