Adding New GCIS Capabilities in Seven Steps - USGCRP/gcis GitHub Wiki

There are Seven Steps to adding new GCIS capabilities:

  1. Database tables
  2. Model (Database Object Role Modeling (ORM) objects)
  3. Unit tests
  4. Additional helpers for the new Model objects
  5. Controller
  6. Routes
  7. View (Templates)

Each new 'thing' (lexicon, exterm, and later things like case studies, or other resources we add) needs each of these.

GCIS is organized around a Model/View/Controller (MVC), and each new thing we add needs a new bit of code for each of those. They should be modeled largely following the existing code for each of those. Each step should be small and and include additional git commits for each.

A good way to understand where to go, do a grep for an existing thing (e.g. "lexicon/exterm") throughout the GCIS source tree. The first time will seem like a lot of work, but subsequent changes will come easier.

The details below should give an idea what is involved in each step.

1. Database tables

See: http://search.cpan.org/~bduggan/Module-Build-Database-0.57/lib/Module/Build/Database.pm

Make a new file in "db/patches" with database schema changes, then go through ./Build dbtest, dbdist, dbdocs, dbfakeinstall, dbinstall, etc. as described on that page.

2. Model (Database ORM Objects)

Review Rose::DB::Object:

http://search.cpan.org/~jsiracusa/Rose-DB-Object-0.815/lib/Rose/DB/Object.pm

which is the Object Role Modeling (ORM) that GCIS uses to interact with database objects.

Whenever you add a new table, you may have to add some Rose DB Objects in here:

https://github.com/USGCRP/gcis/tree/master/lib/Tuba/DB/Mixin/Object

3. Unit tests

Make a new test, something like this one:

https://github.com/USGCRP/gcis/blob/master/t/012_lexicon.t

that exercises putting things in and querying them back out.

4. Add additional helpers for the new Model objects (Optional)

May need something in here:

https://github.com/USGCRP/gcis/blob/master/lib/Tuba/Plugin/TubaHelpers.pm

5. Controller

Add a new thing in here:

https://github.com/USGCRP/gcis/tree/master/lib/Tuba

6. Routes

Add the new routes in here:

https://github.com/USGCRP/gcis/blob/master/lib/Tuba.pm

7. View (Templates)

Add the new templates here:

https://github.com/USGCRP/gcis/tree/master/lib/Tuba/files/templates