DeveloperGuide (by DKThung)

Originally posted by DK Thung, 4 Aug 2010 (computer programming student at Museum of Vertebrate Zoology, UC Berkeley).

If you make a change, please do not remove helpful information: only make it better or more up to date.

Glossary

• instance: a copy of something
• MVZ: the Museum of Vertebrate Zoology. Where you work.
• SVN: aka Subversion. A code version managing software. Keeps the code in a remote repository for all programmers to access and change. (Need to update to GIT, 26 Aug 2015, MSK)
• svn repository: where the code is stored on a server.
• UAM: the University of Alaska Museum. Where Dusty works.
• webapp: a web-based application. Basically, a web-page that has the abilities to do advanced things, like query databases.

The basic structure of Arctos code and instances

• Arctos is a combination of webapps, SVN respositories for code, and database used for a biological museum. One of the primary uses is cataloging specimens, e.g. dead animals, eggs, nests. The stored information can be manipulated and called back for whatever purposes they need.
• (I think this is outdated?? refer to the next bullet) Different institutions have their own instances of the Arctos webapp and their own instances of the database, and generally they have production and development instances. Thus Arctos can have a MVZ prod instance, a MVZ qa instance, a UAM production instance, etc.
  • There are two instances of Arctos for MVZ and UAM. arctos-test.arctos.database.museum is a testing site for developers. This should be where developers test their changes and developers should svn update (more info later) here only (unless Dusty gives you permission otherwise). arctos.database.museum is the production site for all institutions and is controlled by Dusty. Contact him for all necessary svn updates.
  • Each instance of Arctos stores its information in a Oracle database specific to that instance of Arctos (which the code talks to using SQL). Thus, fooling around with the data in the trunk database won't hurt users who use the data in the production. However, fooling around with the data structure is a bad idea, because other programmers will assume that the data structure is the same. Only do this if you have a good reason to (like Carla says, "we're changing the data structure and here's how it's going to be changed").
• The SVN repositories: There is a repository for trunk, and then there are branches (details below).
  • If unsure about updating the webapp, ASK SOMEONE FIRST (like Carla). When you update your code in Eclipse, and SVN commit it, then the changes are made to the SVN repository. However, the webapp won't update until someone does "svn up". This is achieved on a Arctos webapp page, which can be found at "Manage Arctos->Developers Widgets -> SVN". When you wish to do svn up, please make sure that you do it in the correct webapp instance (i.e. arctos-test vs prod arctos).
  • Trunk is where the code is stored for programmers to change their code. If you haven't tested your change on a webapp, then you should be making your code changes here.
  • (might be outdated??) Branches. Branches are a bit more complicated. There will be several different versions in the branches. Generally, one branch is accepted to be the production version of the code, and another branch is accepted to be the QA version of the code. If unsure, check where the SVN update page points to for each instance (if you don't have access to that page for a given webapp, talk to Carla or Dusty).
• The Webapp: MVZ currently has three webapps: trunk, qa (quality assurance), and prod (production).
  • Trunk is for the programmers to do their dirty work. This is where you test any changes to code that you make.
  • QA is for the testers to try out the programmers fixes.
  • Production is for users to do whatever they need to do. Your requirement as programmer is to NOT BREAK PROD.

The general work cycle (needs updating to GitHub)

1. (Your supervisor has a task for you OR (you check Arctos Issue list for an untaken issue (currently at http://code.google.com/p/arctos/issues/list ) AND you check with Carla to make sure that you should do that change)) AND check with other programmers that making this change won't get in their way. Inform other programmers what pages you will be modifying. (You may inform them by making a new issue or finding the relevant issue on the Arctos Issue list, but I also advise you to email them).
2. After making sure that the change is approved by Carla, then you learn what you need to know to make the change. Often, the easiest step is to find a page in the svn repository that does something similar to what you want to do, and you can often just copy that code and use it or make small modifications and use it.
3. Write the code, and put in comments. If making a new page, then put in a header with useful information, like your name (as the author), what the page is supposed to do from a high level sense, what arguments the page needs (generally will be given in a POST or GET command from a form input, or in the url itself like "mypage.cfm?variableA=blah&variableB=2"), what it's dependencies are, and what it is based on. Make sure to update the header as you change the page!
4. Commit your changes to the trunk svn repository, and put in a useful comment in the commit message. If your changes affect a specific action, start your comment with ": ", where you replace with the name itself. This is useful to future programmers (that's why I do that now!).
5. Test out your code in trunk. Don't feel like you can't make new records or change the database through the webapp: it's there for you to test stuff out. If your code involves updating the database, verify that the correct changes are being made using some SQL queries (I use SQL Developer to do that).
6. If your code seems to do what you want it to do, commit the changes to the QA svn repository. Otherwise, go back to step 3.
7. Inform the relevant people of the change (I usually do it through email, but we may change our policy and do this on the Arctos Issue list).

Who you need to know

(See the supplementary guide specific to your institution)

Languages you will find useful

• HTML + the page layout language. Needed to present web pages and layout the elements in a web page. w3schools has an excellent tutorial on this and the tag reference page is invaluable.
• Coldfusion + useful for dynamically generating the page layout based on HTML name-value pairs -e.g., do a different action depending on what the value of "action" is. Many of Dusty's page have multiple purposes + needed for querying the database
• JS (Javascript) + DOM (Document Object Model) + The way that Javascript interacts with HTML is through the use of the DOM, DOM being modeling the elements in a page as objects that are nodes in a tree (See bookmarks for help on DOM). useful for updating the page AFTER it has been made - e.g., someone wants a button added. Then you can use Javascript to do this.
• AJAX (Asynchronous Javascript and XML) + used in the context of CFAjax. + allows for database calls asynchronously. -why do we need this? say you want the user to request data after the page has loaded. then you make an asynchronous call to fetch the data.
• SQL (Structured Query Language) + the language used to talk to the database
• Regex (Regular Expressions) - Ok, it's not really a programming language. However, it is extremely useful. The basic usage of regex is pattern matching. This means that, say, you want to find the word "banana", you use the regex "banana". That sounds useless and stupid. However, regex has some powerful meta characters, that allow you to match different things. Say you wanted to find a number, but not a specific number. Then you could do: [0-9], which will find any number between (inclusive) 0-9 and any more numbers between 0 and 9 (inclusive). Thus, that regex will find any integer (with leading 0's too, but you can find a way around that using [1-9][0-9], but then that'll only find two digit numbers, but you can improve it also). Heck, just read a tutorial on it. There should be one in the bookmarks.

Programs

• Eclipse
  • Useful plugins for Eclipse (can be googled):
    • Subclipse (used for SVN)
      • CFEclipse (used for highlighting Coldfusion stuff, etc.)
      • jOra
• SQL Developer
  • allows you to query the database directly without being on a webpage. Useful for testing your queries before committing it changes to your code. Also useful for finding how things are connected in the database, using the table called all_tab_cols.
  • when logging in, use your Arctos username/password
  • must be on the MVZ subnet (or any institutional subnet) or connected via vpn (see below for more info)
  • Contact Lam for connection information.
• Firefox
  • I highly recommend using this browser. Please don't even consider using anything else while developing. If you insist on using something else, then I won't help you with browser-related problems.
  • Useful plugins for Firefox: - HIGHLY RECOMMENDED Firebug (an insanely powerful plugin that allows you to go step-by-step through Javascript execution. You will need to know Javascript and DOM to understand what's going on. Also, can be used for looking at the HTML source and modify the local copy of the HTML source and modify the page after its been loaded.) - xMarks Bookmark Synchronizer (useful for keeping your bookmarks on several different computers updated at once. Alternatively, you can use iGoogle's bookmark saver, or your own)
• Cisco's vpn client
  • You must be connected via vpn (or connected to mvz subnet) in order to connect to the database.
  • (Outdated)password must come from RSA SecurID Token tool (see next bullet)
  • (Outdated)RSA SecurId? Token -This tool is used to generate a secret encrypted password, which is then used to connect to vpn (what you enter as the password). -Ask Aaron for the rsa token file.

Random Hints/Tips

• Dates are a hassle + As this title says, dates are a BIG hassle. How could such an innocuous thing such as a date be tough? Well it is. + There are several ways to store a date: it can be stored as a string (often called "verbatim_date") or it can be stored a date object (as it should be for the rest of the dates inside Arctos. To find out what it is REALLY stored as, do desc , where is the name of the table that contains the column whose type you want to know). + When dealing with comparing dates, the Oracle function to_date() is useful for turning a string into a date object inside a query. Look up its usage. + When doing ranges of dates, use the sql keyword "between". + The Arctos database as of this writing stores date objects rounded to nearest day. + Google and Wikipedia are your friend. - Consult them if you don't know something. If that fails, consult your supervisor or fellow programmer. How AJAX works: It allows you to submit "XMLHttpRequest"s. This allows Javascript to load HTML AFTER the page has loaded. How to use CFAjax: First learn the basics of AJAX. You use the following JS call:

        DWREngine._execute(_cfscriptLocation, null, 'theCFFunctionName', var1, var2, ..., onSuccessJSFunction);
  
        where:
            _cfscriptLocation - the path to where the Coldfusion document that contains the function that you want called
            null - just leave it null
            'theCFFunctionName' - a string containing the name of the Coldfusion function you want called
            var1, var2, ... - the parameters you want passed to the Coldfusion function
            onSuccessJSFunction - the Javascript function you want called if the Coldfusion function does not have any errors (in other words, returns successfully). 
        Please note that you want your Coldfusion function to return arguments that correspond to parameters for the onSuccessJSFunction. There is a HUGE source of confusion concerning what type in Coldfusion is translated into what type in Javascript. Please be careful, and look up examples online. 
    Data structure
        An especially nice query for finding out the data structure is "select * from all_tab_cols where column_name='
  
        <column>
  
        ' " or "select * from all_tab_cols where table_name='
    ' ". The first one allows you find all tables that have a column named '
  
    <column>
  
    ' (replace
  
    <column>
  
    with whatever column name you want, but keep the single quotes), and the second one allows you to find all the columns in table '
    '. Be sure to use capitals when specifying the table or column name. Alternatively, use "desc
    " and replace
    with the table name to find the columns in a given table.