Customizing Hydroshare

Hydroshare is a Django “project”. This document is part of the Hydroshare Developers' Guide.

Getting a working copy of Hydroshare to extend

We are currently using Docker to make getting Hydroshare as simple as possible. You can follow the Getting a working copy of Hydroshare guide.

Alternately, you can of course get Hydroshare through the GitHub repository. You will need to get the latest version of the code. Do a git pull in the Hydroshare directory, or see the document How to Push/Pull in GitHub for more detailed instructions.

Hydroshare project structure

git clone https://github.com/hydroshare/hydroshare2

After following the steps above, you'll get something like this:

hydroshare/__init__.py        # empty.
hydroshare/settings.py        # project level settings. lead developers only.
hydroshare/local_settings.py  # override settings for your project here.
hydroshare/requirements.txt   # autogenerated by pip, library dependencies.
hydroshare/uwsgi.py           # do not modify. webserver interface.
hydroshare/urls.py            # url mappings. see tutorial.
hydroshare/celeryworker.py    # do not modify. task queue definition.
hydroshare/hs_core/*          # hydroshare core services.
hydroshare/hs/*               # hydroshare apps go here.
hydroshare/ga_resources/      # geoanalytics core.
hydroshare/ga_applications/	  # geoanalytics core.
hydroshare/ga_ows/            # geoanalytics core.
hydroshare/ga_irods/          # django IRODS interface.
hydroshare/ga_interactive/    # django-IPython Notebook int. (experimental)

All of your code goes in the hs/ directory inside of this. Change to this directory and then proceed to the next section.

Working on your own Hydroshare extension

Extending this core will involve creating a new Hydroshare app. We have a template for hydroshare apps in GitHub.

1. Create a new GitHub repository with the same name as your new Hydroshare extension.

2. Pull from the master branch of the hs_app_template into your newly created repository.

3. Next, you can clone that repository in your Hydroshare project.This will result in a new directory in your machine with the same name as the repository. This is your new Hydroshare "app name".

4. Open hydroshare/local_settings.py and add the Hydroshare "app name" to the list of HYDROSHARE_APPS like so:

   HYDROSHARE_APPS=( 'hs_core', 'hs.my_app_name', )

5. Now that you have added the app, Hydroshare recognizes it as a new application. You are essentially off and running at this point. From here, depending on what your extension does, you may want to:

• Add new resource types or other objects that persist in the Hydroshare database
• Add web application endpoints for users to interact with in their browser
• Add long-running tasks that may run on different machines or in the background
• Add web API endpoints meant to allow other applications to work with your extensions
• Add automated tests that ensure your functionality runs properly

Hydroshare app template structure

git clone https://github.com/hydroshare/hs_app_template

hs_app/__init__.py         # utility or broad functions.
hs_app/models.py           # database interface.
hs_app/views.py            # website interface.
hs_app/urls.py             # url-to-view endpoint mapping.
hs_app/api.py              # api interface.
hs_app/tasks.py            # deferred application tasks.
hs_app/admin.py            # registrations of models into the admin interface.
hs_app/tests.py            # automatic tests.  
hs_app/static/hs_app/js/   # application specific javascript libraries.
hs_app/static/hs_app/css/  # application specific CSS libraries.
hs_app/templates/includes  # template includes.
hs_app/templates/hs_app    # application specific templates.
hs_app/templates/pages     # automatically discovered page rendering.
requirements.txt           # application specific library requirements.