diff --git a/docs/users_guide.rst b/docs/users_guide.rst index bb40a2e..f8c83e4 100644 --- a/docs/users_guide.rst +++ b/docs/users_guide.rst @@ -5,3 +5,5 @@ Guiding your Users .. toctree:: :maxdepth: 2 :caption: Contents: + + users_guide/tripal_content diff --git a/docs/users_guide/tripal_content.rst b/docs/users_guide/tripal_content.rst new file mode 100644 index 0000000..67e2949 --- /dev/null +++ b/docs/users_guide/tripal_content.rst @@ -0,0 +1,9 @@ + +Tripal Content +================ + +.. toctree:: + :maxdepth: 2 + :caption: Tripal Content: + + tripal_content/relationships diff --git a/docs/users_guide/tripal_content/relationships.1.three-projects.png b/docs/users_guide/tripal_content/relationships.1.three-projects.png new file mode 100644 index 0000000..e605d1a Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.1.three-projects.png differ diff --git a/docs/users_guide/tripal_content/relationships.10.drush-command.png b/docs/users_guide/tripal_content/relationships.10.drush-command.png new file mode 100644 index 0000000..cd5bf2d Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.10.drush-command.png differ diff --git a/docs/users_guide/tripal_content/relationships.11.appearance-object.png b/docs/users_guide/tripal_content/relationships.11.appearance-object.png new file mode 100644 index 0000000..2a1f9ff Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.11.appearance-object.png differ diff --git a/docs/users_guide/tripal_content/relationships.2.blank-relationship.png b/docs/users_guide/tripal_content/relationships.2.blank-relationship.png new file mode 100644 index 0000000..ce26711 Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.2.blank-relationship.png differ diff --git a/docs/users_guide/tripal_content/relationships.3.selecting-term.png b/docs/users_guide/tripal_content/relationships.3.selecting-term.png new file mode 100644 index 0000000..ada432c Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.3.selecting-term.png differ diff --git a/docs/users_guide/tripal_content/relationships.4.selecting-project.png b/docs/users_guide/tripal_content/relationships.4.selecting-project.png new file mode 100644 index 0000000..58667ef Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.4.selecting-project.png differ diff --git a/docs/users_guide/tripal_content/relationships.5.reverse.png b/docs/users_guide/tripal_content/relationships.5.reverse.png new file mode 100644 index 0000000..c3f522a Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.5.reverse.png differ diff --git a/docs/users_guide/tripal_content/relationships.6.add-another-item.png b/docs/users_guide/tripal_content/relationships.6.add-another-item.png new file mode 100644 index 0000000..6cf614e Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.6.add-another-item.png differ diff --git a/docs/users_guide/tripal_content/relationships.7.second-relationship.png b/docs/users_guide/tripal_content/relationships.7.second-relationship.png new file mode 100644 index 0000000..7169485 Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.7.second-relationship.png differ diff --git a/docs/users_guide/tripal_content/relationships.8.appearance-subject.png b/docs/users_guide/tripal_content/relationships.8.appearance-subject.png new file mode 100644 index 0000000..15ae3ca Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.8.appearance-subject.png differ diff --git a/docs/users_guide/tripal_content/relationships.9.republish.png b/docs/users_guide/tripal_content/relationships.9.republish.png new file mode 100644 index 0000000..7eb596c Binary files /dev/null and b/docs/users_guide/tripal_content/relationships.9.republish.png differ diff --git a/docs/users_guide/tripal_content/relationships.rst b/docs/users_guide/tripal_content/relationships.rst new file mode 100644 index 0000000..4d04a05 --- /dev/null +++ b/docs/users_guide/tripal_content/relationships.rst @@ -0,0 +1,95 @@ +Relationships between content +=============================== + +Content on your tripal site is almost always related in some way to other types of content. +A *publication* may be about a particular *organism*, or a *project* may consist of several *analyses*. +In other cases, however, the relationship may be between records of the same type of content. +For example, a *chapter* is a part of a *book*, and these are both types of *publication* content. +Similarly, an *exon* may be part of a *gene*, which both are sequence *features*. +A *project* may be part of a larger *umbrella project*. + +These types of relationships can be stored in Chado using one of the *relationship* tables. +These relationships are then presented to site users using the relationship field. + +How to create a new relationship +---------------------------------- + +Through the Tripal user interface, you can specify one or more relationships between similar types of content. +When specifying a relationship, a controlled vocabulary term is used to specify how the +records are related. + +Let's examine an example where we have a high-level umbrella project which +has two smaller projects that are a part of it. + +First we create the three project records. +We have created "The Tripalus Genome Project" which will be the umbrella project, +and two other projects, an assembly and an annotation project. + +.. image:: relationships.1.three-projects.png + :alt: Three projects have been created, "The Tripalus Genome Project", "Tripalus Genome Assembly", and "Tripalus Genome Annotation". + +If we edit the umbrella project "The Tripalus Genome Project", +we will find the relationship field section, which is currently blank. + +.. image:: relationships.2.blank-relationship.png + :alt: The relationship form, currently blank. + +First we select a controlled vocabulary term which indicates the type of relationship. +Here we are selecting *part_of*, because the two other projects will be *part of* this umbrella project. + +.. image:: relationships.3.selecting-term.png + :alt: Selecting a controlled vocabulary term in the relationship field. + +Next we select the related project + +.. image:: relationships.4.selecting-project.png + :alt: Selecting a project in the relationship field. + +Then we toggle *reverse* because the selected project *Tripalus Genome Assembly* is the **subject**, +meaning the selected project is the *subject* of the *part of* relationship, +and the *object* is the project that we are currently editing. + +.. image:: relationships.5.reverse.png + :alt: Selecting reverse in the relationship field. + +We can add a second relationship by clicking the *Add another item* button. + +.. image:: relationships.6.add-another-item.png + :alt: Adding a second relationship in the relationship field. + +After we add the second relationship, the form looks like this, and we can click the "Save" button. + +.. image:: relationships.7.second-relationship.png + :alt: After adding a second relationship in the relationship field. + +After saving, the relationships will appear like this. + +.. image:: relationships.8.appearance-subject.png + :alt: Appearance of relationships in the umbrella project. + +The relationships will not yet appear on the other two projects. +We need to republish for that to happen. + +Go to Tripal → Content → + Publish Tripal Content. + +For *Content Type* select *Project*, and make sure to check *Republish Existing Content*. + +.. image:: relationships.9.republish.png + :alt: Publish form for project with republish selected. + +When this is done, you will see the command you need to run to run the publish job. +It will be different from the one shown here. + +.. image:: relationships.10.drush-command.png + :alt: Republish job submitted showing drush command "drush trp-run-jobs --job-id=1 --username=drupaladmin --root=/var/www/drupal/web". + +Now on the other two projects you will also see the relationship. + +.. image:: relationships.11.appearance-object.png + :alt: Appearance of relationship in the sub-project. + +.. hint:: + You can also run the republish job on the command line using drush. + For the project content type, the command would be: + + ``drush trp-chado-publish project --republish``