Merge pull request #65 from tripal/49-addPlaceholderPages

User Permissions + Example Genomics Site

docs/_static/theme_overrides.css

@@ -12,6 +12,26 @@ See: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
    }
 }
 
+/**
+ * Todo directive.
+ Note: We've taken over `.. hint::` to indicate todo notes in the documentation.
+ */
+.rst-content .hint .admonition-title::before {
+  content: "\f14a";
+}
+.rst-content .hint .admonition-title {
+  background: #e3e3e8;
+  color: #adadba;
+}
+.rst-content .hint {
+  background: #f5f5fa;
+  color: #8b8b99;
+}
+.rst-content .hint a {
+  color: #74748c;
+  text-decoration: underline;
+}
+
 /**
  * Buttons on Extension Module pages.
  */

docs/admin_guide/publishing.rst

@@ -1,2 +1,10 @@
 Publishing
 ==========
+
+.. warning::
+
+  This functionality is still being actively developed. Currently you cannot
+  create pages for records added to chado through any other method than the
+  Create Content forms.
+
+  This work will be completed and documented before the next release of Tripal 4.

docs/admin_guide/user_permissions.rst

@@ -1,2 +1,184 @@
+.. warning::
+
+  These docs are still being developed. In the future this page will contain a
+  very short introduction to user management in Drupal and practical examples
+  for site administration of a Tripal site.
+
 User Permissions
-================
+================
+
+*Users* : Anyone who visits your website including you. There are three groups of users. *anonymous users* (who are not logged in), *authenticated users* (who are logged in) and *administrative users* (created when a site was installed, or User 1).
+
+*Permissions* : A group of actions (example - import a GFF3 file, view/edit content and change configuration). Permissions are defined by the modules that provide the actions.
+
+*Roles* : Permissions are grouped into roles, each of which can be defined and then permissions are granted. Exaample roles are Curators or Data Submittors.
+
+Users and permissions allow you to give certain groups for example, researchers access to private data. Roles can help you setup groups of collaborators so you can assign the permission to the group 
+as a whole which makes it easier if any one member leaves or joins the group.
+
+Refer to https://www.drupal.org/docs/user_guide/en/user-concept.html for more details.
+
+It is a good practice to make several roles on your Tripal site.
+For example, for managing biological data and knowledgebases like model organism database, you might want a Curator role that allows data curators to curate information on a specific organism using appropriate unique traceable identifiers, and providing necessary metadata including source and provenance. a set of genes, and their associated mRNA, CDS, UTRs, etc. For more information, see https://en.wikipedia.org/wiki/Biocuration.
+
+Creating Roles to enable Curation
+---------------------------------
+
+Biocuration involves the collection, curation, annotation, validation, writing related grants, and publications and integration of information related to the biological sciences into databases or resources.
+
+Here is a walk through creating a “Curator” role in Tripal based on a need and then assign these roles permissions by the Administrator. For example, a curator of genomic data would need access to specific importers and content types associated with the genome of the organism.
+
+Steps 
+-----
+From the top menu :
+
+**Home** -> **Administration** -> **People** -> **Roles** -> 
+
+You will find default roles Anonymous user, Authenticated user, and Administrator already present.
+
+Create User
+***********
+
+From the top menu :
+
+**Home** -> **Administration** -> **People** -> **+Add User** -> 
+  * Username : curator_user
+  * Password : `abcd_123_!@#`
+  * Roles : Content editor  
+
+Click on **Create new account** leaving other items as default 
+
+From the top menu -> **People** -> *curator_user* now appears in list of Usernames.
+
+Create Roles and Assign them to Users
+*************************************
+
+**Home** -> **Administration** -> **People** -> **+Add Role** -> 
+
+ .. figure:: add_curator_role.png
+
+Type *Curator* for Role name in text box and click Save. A status message is displayed.
+
+ .. figure:: role_created_status.png
+
+And you can find the Curator Role added to the list of Roles under Name.
+
+To perform same action on multiple users, for example, to add the Curator role to more than 1 user, from the top menu, 
+
+**Home** -> **Administration** -> **People** -> click inside checkbox before all usernames having prefix `curator_`.
+
+ .. figure:: applied_curator_roles.png
+
+Click on dropdown next to Action -> select
+**Add the Curator role to the selected users** -> **Apply to selected items**.
+
+ .. figure:: multiple_users_role.png
+
+All user names having prefix `curator_` now have the role of Curator.
+
+**Home** -> **Administration** -> **People** ->
+
+ .. figure:: curator_roles_for_users.png
+
+Curator Roles are now assigned to the users under Roles.
+
+Edit User's Role
+****************
+
+To Edit options for a user 
+
+**Home** -> **Administration** -> **People** -> **curator_user** -> **Edit** (under **Operations** column )
+
+To remove the Content editor role for this user,
+
+ .. figure:: edit_curator_user.png
+
+Uncheck Content Editor Role for example, make any other changes in this screen as required and Click Save.
+
+Permissions for Role to define collaborative groups
+***************************************************
+
+From the top menu -> **People** -> **Permissions**
+
+Click in applicable checkboxes for **Content editor**.
+
+The following Tripal content sections are available to assign permission options for each Role :
+ * Block
+ * Block Content
+ * Comment
+ * Configuration Manager
+ * Contact
+ * Contextual Links
+ * Devel 
+ * Devel PHP 
+ * Field UI 
+ * File 
+ * Filter 
+ * Image 
+ * Node 
+ * Path
+ * Search 
+ * Shortcut
+ * System 
+ * Taxonomy 
+ * Toolbar 
+ * Tour 
+ * Tripal 
+ * Tripal Chado 
+ * Update Manager 
+ * User 
+ * Views UI 
+
+Some of the checkboxes are already checked are some are not changeable.
+
+An administrator can change the default permissions for roles. For example, to change the recently created role of *Curator*, 
+
+From the top menu click on -> **People** -> **Permissions**. 
+
+ .. figure::curator_permissions_top.png
+
+In this screen individual permissions can be set for a Role by the administrator viewing the permissions checked for other roles.
+
+Here are some recommended permissions checked for the Role of the Curator in the File, Node and Tripal categories:
+
+File permissions 
+******************
+
+ .. figure:: curator_permissions_file.png
+
+Node permissions 
+******************
+
+ .. figure:: curator_permissions_node.png
+
+Tripal permissions 
+******************
+
+ .. figure:: curator_permissions_tripal.png
+
+Permissions checked for the Curator role shown in screenshots above help in editing, revising and reverting content in addition to several others not available to other Roles for importing content into Tripal, edit and maintain them.
+
+Site administrators wanting to allow their curators to delete Tripal content can do so by applying the "Delete Tripal Content" permission. If their curator also imports data via available custom data importers like GFF3 importer they may want to assign the Tripal Importer permissions, publish and "Upload Tripal Data files". 
+
+Permissions by Term
+*******************
+
+The Permissions by Term is a module that extends Drupal by providing functionality for restricting view access to single nodes via taxonomy terms. This module can be useful for Tripal users interested in creating, documenting and maintaining Ontologies, for example. 
+
+Taxonomy term permissions can be coupled to specific user accounts and/or user roles. It relies on the entities, which are shipped traditionally with Drupal core: taxonomy terms and nodes.
+
+More information is available at 
+https://www.drupal.org/docs/contributed-modules/permissions-by-term and 
+https://www.drupal.org/project/permissions_by_term. 
+
+An example use-case in Tripal is Sub-editors working on a research publication. Collecting content together in a taxonomy term allows you to manage that content as a sub site and assign its own administrator. This is useful where you might need someone to produce lots of different types of content but only want them to be able to add it to a specific area of the website that is working on the publication.
+
+Sub-communities within a membership organisation. The topics a membership organisation may cover can be very broad and individual members may only be interested in seeing content from a sub-selection of the areas it covers. The sub-community may have their own executive members who can contribute to the research topic or approve new members to their sub-community.
+
+
+Additional Resources:
+ - `Official Drupal Docs: What are Users, Roles, and Permissions? <https://www.drupal.org/docs/user_guide/en/user-concept.html>`_
+ - `Official Drupal Docs: Creating a Role <https://www.drupal.org/docs/user_guide/en/user-new-role.html>`_
+ - `Official Drupal Docs: Assigning Permissions to a Role <https://www.drupal.org/docs/user_guide/en/user-permissions.html>`_
+ - `Official Drupal Docs: Changing a User’s Roles <https://www.drupal.org/docs/user_guide/en/user-roles.html>`_
+ - `Official Drupal Docs: Creating a User Account <https://www.drupal.org/docs/user_guide/en/user-new-user.html>`_

docs/site_building/example_genomic.rst

@@ -0,0 +1,15 @@
+Example Genomic Site Setup
+============================
+
+The following tutorial will walk you through creating content and loading genomic data. This is a good introduction to Tripal 4 Content Types and the new Administrative User Interface regardless of whether you intend to store genomic data in your particular Tripal 4 site.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Steps
+
+   example_genomic/create_types
+   example_genomic/organisms
+   example_genomic/analyses
+   example_genomic/cross_references
+   example_genomic/controlled_vocabs
+   example_genomic/genomes_and_genes

docs/site_building/example_genomic/analyses.rst

@@ -0,0 +1,38 @@
+Create a Genome Assembly Page
+===============================
+
+For this tutorial we will later import a set of genes, and their associated mRNA, CDS, UTRs, etc. Tripal's Chado loader for importing genomic data requires that an analysis be associated with all imported features. This has several advantages, including:
+
+- The source of features (sequences) can be traced. Even for features simply downloaded from a database, someone else can see where the features came from.
+- Provenance describing how the features were created can be provided (e.g. whole genome structural and functional annotation description).
+- The analysis associates all of the features together.
+
+To create an analysis for loading our genomic data, navigate to the Add Tripal Content and click on the link: **Analysis**
+
+The analysis creation page will appear:
+
+.. image:: analyses.1.png
+.. image:: analyses.2.png
+
+Here you can provide the necessary details to help others understand the source of your data. For this tutorial, enter the following:
+
+.. csv-table::
+  :header: "Form Element",	"Value"
+
+  "Name", "Whole Genome Assembly and Annotation of Citrus Sinensis (JGI)"
+  "Description (Set to Full HTML):", "<p> <strong><em>Note: </em>The following text comes from phytozome.org:</strong></p> <p> <u>Genome Size / Loci</u><br /> This version (v.1) of the assembly is 319 Mb spread over 12,574 scaffolds. Half the genome is accounted for by 236 scaffolds 251 kb or longer. The current gene set (orange1.1) integrates 3.8 million ESTs with homology and ab initio-based gene predictions (see below). 25,376 protein-coding loci have been predicted, each with a primary transcript. An additional 20,771 alternative transcripts have been predicted, generating a total of 46,147 transcripts. 16,318 primary transcripts have EST support over at least 50% of their length. Two-fifths of the primary transcripts (10,813) have EST support over 100% of their length.</p> <p> <u>Sequencing Method</u><br /> Genomic sequence was generated using a whole genome shotgun approach with 2Gb sequence coming from GS FLX Titanium; 2.4 Gb from FLX Standard; 440 Mb from Sanger paired-end libraries; 2.0 Gb from 454 paired-end libraries</p> <p> <u>Assembly Method</u><br /> The 25.5 million 454 reads and 623k Sanger sequence reads were generated by a collaborative effort by 454 Life Sciences, University of Florida and JGI. The assembly was generated by Brian Desany at 454 Life Sciences using the Newbler assembler.</p> <p> <u>Identification of Repeats</u><br /> A de novo repeat library was made by running RepeatModeler (Arian Smit, Robert Hubley) on the genome to produce a library of repeat sequences. Sequences with Pfam domains associated with non-TE functions were removed from the library of repeat sequences and the library was then used to mask 31% of the genome with RepeatMasker.</p> <p> <u>EST Alignments</u><br /> We aligned the sweet orange EST sequences using Brian Haas's PASA pipeline which aligns ESTs to the best place in the genome via gmap, then filters hits to ensure proper splice boundaries.</p>"
+  "Program, Pipeline Name or Method Name", "Assembly and Annotation Performed by JGI"
+  "Software Version", "Phytozome v9"
+  "Data Source Name", "JGI Citrus sinensis assembly/annotation v1.0 (154)"
+  "Data Source URI", "http://www.phytozome.net/citrus.php"
+
+.. note::
+  Above, the description is provided as HTML code.  However if you enabled the **ckeditor** module (as instructed in the Tripal Prerequisites section), you should click the link **Switch to plain-text editor** found below the Description field before cut-and-pasting the code above.  Normally, you would enter the text free-hand but for this tutorial it is fastest to cut-and-paste the HTML.
+
+.. note::
+
+  Features **Publication**, **Project** and **Database Reference Annotations** have not yet been implemented for Tripal v4, documentation will be added once this feature is available.
+
+After saving, you should have the following analysis page:
+
+.. image:: analyses.created_page.png

docs/site_building/example_genomic/controlled_vocabs.rst

@@ -0,0 +1,24 @@
+Import the Gene Ontology
+=========================
+
+Before we proceed with setup of our example genomics site we will want to load the Gene Ontology.  This is because we will be loading a whole genome, genes and transcripts with annotations.  These annotations include Gene Ontology terms.  To load the Gene Ontolgoy, navigate to **Tripal → Data Loaders → OBO Vocabulary Loader**. You will see the following page:
+
+.. image:: controlled_vocabs.1.png
+
+The Ontology loader allows you to select a pre-defined vocabulary for loading or allow you to provide your own. If you provide your own, you give the remote URL of the OBO file or provide the full path on the local web server where the OBO file is located. In the case of a remote URL, Tripal first downloads and then parses the OBO file for loading. If you do provide your own OBO file it will appear in the saved drop down list for loading of future updates to the ontology.
+
+To import for example, the Sequence Ontology, select it from the drop-down and click the Import Vocabulary button. You will notice a job is added to the jobs system. Now manually launch the jobs
+
+::
+
+  drush trp-run-jobs --username=administrator --root=/var/www/html
+
+If Tripal is running from a docker container named $cntr_name,
+
+::
+
+  docker exec -it $cntr_name drush trp-run-jobs --username=drupaladmin --root=/var/www/drupal/web
+
+.. note::
+
+  Loading an Ontology may take several hours.

docs/site_building/example_genomic/create_types.rst

@@ -0,0 +1,52 @@
+
+Setup Tripal Content Types
+============================
+
+When you first install Tripal, you do not yet have any content types created. This is to provide you with flexibility to only add the content types you need for your data.
+
+For a site containing genome assemblies, genes and associated content, you will want to import the *Genomic* content type collections. This is done by navigating to **Admin > Tripal > Page Structure** and then clicking "Import type collection" button. You want to select **Genomic Content Types (Chado)** and click on **Import**
+
+.. note::
+  We expect in this tutorial that you already have the "General" content types for Tripal. If you don't have a number of content types already listed that say "General" in the first column when you go to the Page Structure listing then you will also want to select General in the following form.
+
+.. image:: import_tripal_collection.png
+
+Now run the submitted Tripal job from command line as follows if Drupal/Tripal is running as a web application:
+
+::
+
+  drush trp-run-jobs --username=drupaladmin --root=/var/www/drupal/web
+
+
+If Tripal is running from a docker container named $cntr_name, run:
+
+::
+
+  docker exec -it $cntr_name drush trp-run-jobs --username=drupaladmin --root=/var/www/drupal/web
+
+You will see the following output:
+
+::
+
+  2024-02-14 21:34:50
+  Tripal Job Launcher
+  Running as user 'drupaladmin'
+  -------------------
+  2024-02-14 21:34:50: Job ID 1.
+  2024-02-14 21:34:50: Calling: import_tripalentitytype_collection(Array)
+  [notice] Creating Tripal Content Types from: Genomic Content Types (Chado)
+  [notice] Content type, "Gene", created.
+  [notice] Content type, "mRNA", created.
+  [notice] Content type, "Phylogenetic Tree", created.
+  [notice] Content type, "Physical Map", created.
+  [notice] Content type, "DNA Library", created.
+  [notice] Content type, "Genome Assembly", created.
+  [notice] Content type, "Genome Annotation", created.
+  [notice] Content type, "Genome Project", created.
+  [notice] Attaching fields to Tripal content types from: Chado Fields for Genomic Content Types
+  :::
+  :::
+  :::
+
+
+Now, when you go to **Admin > Tripal > Page Structure** you will see a Genomic Category that includes Gene and other content required for the Example Genomic site.

docs/site_building/example_genomic/cross_references.rst

@@ -0,0 +1,25 @@
+Setup Cross References to external sites
+=========================================
+
+.. note::
+  This feature has not yet been implemented for Tripal v4, documentation will be added once this feature is available
+
+For our gene pages and mRNA pages we want to link back to JGI where we obtained the genes. Therefore, we want to add a database reference for JGI. To add a new external databases, navigate to **Tripal → Data Loaders →  Chado Databases** and click the link titled **Add a Database**. The resulting page provides fields for adding a new database:
+
+Enter the following values for the fields:
+
+.. csv-table::
+  :header: "Field Name", "Value"
+
+  "Database Name", "Phytozome"
+  "Description", "Phytozome is a joint project of the Department of Energy's Joint Genome Institute and the Center for Integrative Genomics to facilitate comparative genomic studies amongst green plants"
+  "URL", "http://www.phytozome.net/"
+  "URL prefix", "https://phytozome.jgi.doe.gov/phytomine/portal.do?externalid=PAC:{accession}"
+
+The URL prefix is important as it will be used to create the links on our gene pages. When an object (e.g. gene) is present in another database, typically those database have a unique identifier (or accession) for the resource.  If we want to link records in our database to records in the remote database we need to provide a URL prefix that Tripal will use to create the URL.   Typically a remote database has a standard URL schema by which someone can specify a unique resource.  Often the resource accession is the last word in the URL to allow others to easily build the URL for any resource.  Tripal can take advantage of these type URL schemas via the URL Prefix field.
+
+The URL prefix should be the URL used to identify a resource.  Two tokens, {db} and {accession}, can be used in place of where the database name and accession might be needed to create the URL. If no {db} or {accession} are provided in the URL prefix then Tripal will append the database name and the accession to the URL prefix to form the final URL.  In this example, the Phytozome URL only requires the accession. The position where that accession will be placed is indicated with the {accession} token.  The {db} token is not needed.
+
+Click **Add**.
+
+We now have added a new database!