=========
How Do I?
=========

This is a list of recipies for slightly advanced things you might want
to do with the GAVO DC.


...add computed columns to a dbCore output?
-------------------------------------------

Easy: define an output field with a select attribute, e.g.::

			<outputField name="a_U" tablehead="A_U" ucd="phys.absorption;em.opt.U"
				description="Extinction in U, assuming R_V=3.1"
				select="ev_i*5.434"/>

This will add an output field that looks to the service like it comes
from the DB proper but contains the value of the ``ev_i`` column
multiplied with 5.434.

The expression must be valid SQL.


...do I make an input widget to select output columns?
------------------------------------------------------

In general, selecting fancy output options currently requires custom
cores or custom renderers.  Ideas on how to change this are welcome.

For this specific purpose, however, you can simply define an service key
named _ADDITEM.  This would look like this::

  <service ....>
    ....
 		<inputKey name="_ADDITEM" tablehead="Extinctions for band"
			description="Output extinctions for the respective band (if you want multiple bands, you can use 'additional output fields' below)"
			type="text" required="True" mul>
			<values multiOk="True" showItems="-1">
				<option title="Landolt U">a_U</option>
				<option title="Landolt V">a_V</option>
				<option title="Landolt I">a_I</option>
			</values>
		</inputKey>
    ...
  </service>

Setting showItems to -1 gives you checkboxes rather than a select list,
which is mostly what you want.  Try with and without and see what you
like better.

If you do that, you *probably* do not want the standard "additional
fields" widget at the bottom of the form.  To suppress it, add a line

::

  <property name="noAdditionals">True</property>
  
to the service definition.  The "True" in there actually is a bit of a
red herring, the widget is suppressed for any value.


...add and image to query forms?
--------------------------------

There are various variations to that theme -- you could go for a
custom template if you want to get fancy, but usually putting an image
into an _intro or _bottominfo meta section should do.

In both cases, you need a place to get your image from.  While you could
put it somewhere into rootDir/web/nv_static, it's probably nicer to have
it within a resource's input directory.  So, add a static renderer to
your service, like this::

  <service allowed="form,static" staticData="static"...

This lets you put service-local static data into resdir/static/ and
access it as <serviceURL>/static/<filename>

Usually, your _intro or _bottominfo will be in reStructured text.  Plain
images work in there using substitution references or simply the naked
image directive::

    <meta name="_bottominfo" format="rst">
      The current data set comprises these fields:

      .. image:: \servicelink{cars/q/cat/static/fields-inline.png}
    </meta>

The servicelink macro would ensure that the image would still be found
if the server ran off-root.

This is the recommended way of doing things.  If, however, you insist on
fancy layouts or need complete control over the appearance of your
image (or whatever), you can use the evil "raw" meta format::
  
  <meta name="_bottominfo" format="raw"><![CDATA[
    <a href="\servicelink{cars/q/cat/static/fields.png}">
    <img src="\servicelink{cars/q/cat/static/fields-inline.png}"/>
    </a>]]>
  </meta>

Make sure you enter valid HTML here, no checks are done by the DC
software.


...import data coming in to a service?
--------------------------------------

I a custom renderer or core, you can use code like::

  from gavo import api

  ...

  def import(self, srcName, srcFile):
    connection = api.getDBConnection("admin")
    dd = self.service.rd.getById("myDataId")
    self.nAffected = api.makeData(dd, forceSource=srcFile,
      connection=connection).nAffected
    connection.commit()
    connection.close()

You want to use a separate connection since the default connections
obtained by cores and friends are unprivileged and typically cannot
write to table.

The nAffected should contain the total number of records imported and
could be used in a custom render function.

srcName and srcFile come from a formal File form item.  In
submitActions, you obtain them like::

  srcName, srcFile = data["inFile"]


Note that you can get really fancy and manipulate data in some way up
front.  That could look like this::

  data = rsc.Data.create(dd, parseOptions=api.parseValidating,
    connection=connection)
  data.addMeta("_stationId", self.stationRecord["stationId"])
  self.nAffected = api.makeData(dd, forceSource=srcFile, data=data,
    connection=connection).nAffected


...change the query issued on SCS queries?
------------------------------------------

You may want to do that because for some reason there is no q3c index on
the queried table, or the semantics aren't quite a point vs. point cone
search but close enough.

Sadly, this is quite complicated right now since our inheritance
mechanism ("original") is so simple-minded.  This will hopefully improve
with a generic record/replay mechanism we're thinking about.

That said, the current way looks like this (for a query that does a
proximity search on bboxes)::

	<condDesc original="__system__/scs#humanSCS">
		<phraseMaker original="__system__/scs#humanSCSPhrase">
			<setup original="__system__/scs#scsSetup" id="proxQuery">
				<code><![CDATA[
					def genQuery(inPars, outPars):
						return "POINT(%%(%s)s, %%(%s)s) <-> bbox < %%(%s)s"%(
							vizierexprs.getSQLKey("RA", inPars["RA"], outPars),
							vizierexprs.getSQLKey("DEC", inPars["DEC"], outPars),
							vizierexprs.getSQLKey("SR", inPars["SR"], outPars))
				]]></code>
			</setup>
		</phraseMaker>
	</condDesc>

-- so, you are inheriting from the SCS condition on three levels and then 
override the genQuery function defined in the common setup code.  The
way the condDescs are written, you must return rather than yield
the actual query string.  See the tutorial on how condDesc code
works in general.  The semi-good news is that if you want the same thing
for an SCS query, you can reuse part of what you did above::

 	<condDesc original="__system__/scs#scs">
		<phraseMaker original="__system__/scs#scsPhrase">
			<setup original="proxQuery"/>
		</phraseMaker>
	</condDesc>