diff --git a/docs/site_building/module_usage.rst b/docs/site_building/module_usage.rst new file mode 100644 index 0000000..ce5036d --- /dev/null +++ b/docs/site_building/module_usage.rst @@ -0,0 +1,8 @@ +Module Usage +============= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + module_usage/tripal_file diff --git a/docs/site_building/module_usage/tripal_file.rst b/docs/site_building/module_usage/tripal_file.rst new file mode 100644 index 0000000..b41e17c --- /dev/null +++ b/docs/site_building/module_usage/tripal_file.rst @@ -0,0 +1,10 @@ +Tripal File Module +==================== + +.. toctree:: + :maxdepth: 4 + :caption: Tripal File Module + + tripal_file/overview + tripal_file/install + tripal_file/usage diff --git a/docs/site_building/module_usage/tripal_file/gui-enable-4nobox.DELETE.png b/docs/site_building/module_usage/tripal_file/gui-enable-4nobox.DELETE.png new file mode 100644 index 0000000..d9ca7f7 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/gui-enable-4nobox.DELETE.png differ diff --git a/docs/site_building/module_usage/tripal_file/install.1.gui-enable-extend.png b/docs/site_building/module_usage/tripal_file/install.1.gui-enable-extend.png new file mode 100644 index 0000000..842674f Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/install.1.gui-enable-extend.png differ diff --git a/docs/site_building/module_usage/tripal_file/install.2.gui-enable-tripal-file.png b/docs/site_building/module_usage/tripal_file/install.2.gui-enable-tripal-file.png new file mode 100644 index 0000000..014f4fb Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/install.2.gui-enable-tripal-file.png differ diff --git a/docs/site_building/module_usage/tripal_file/install.3.gui-enable-install.png b/docs/site_building/module_usage/tripal_file/install.3.gui-enable-install.png new file mode 100644 index 0000000..dff8c80 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/install.3.gui-enable-install.png differ diff --git a/docs/site_building/module_usage/tripal_file/install.4.gui-enable-installed.png b/docs/site_building/module_usage/tripal_file/install.4.gui-enable-installed.png new file mode 100644 index 0000000..b0675fd Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/install.4.gui-enable-installed.png differ diff --git a/docs/site_building/module_usage/tripal_file/install.rst b/docs/site_building/module_usage/tripal_file/install.rst new file mode 100644 index 0000000..6011de9 --- /dev/null +++ b/docs/site_building/module_usage/tripal_file/install.rst @@ -0,0 +1,149 @@ +Installation +============ + +Module Installation +-------------------- + +The Tripal File module is one of the core Tripal modules, so will be +available on any Tripal site, it simply needs to be enabled. + +When this module is enabled, it will create two new content types: `File` and `License`. +It will also create a variety of tables in your Chado database for +associating files to other content types. + +You may activate the module either using drush on the command line, or activate via the GUI. + +.. note:: + + The `EDAM vocabulary `_ is imported when the the Tripal File module + is enabled, because it provides terms for many common biological file types (e.g. FASTA, GFF3, VCF, etc.). + Any file that is managed by the Tripal File module requires a file type. + +Install using a Drush command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following command can be used to enable the Tripal File module: + +.. code-block:: bash + + drush pm-enable tripal_file + +You should see output similar to this when the command is run: + +.. code-block:: text + + [notice] Adding new vocabulary terms + [notice] Adding custom tables + [notice] Adding linker table terms + [notice] Creating new content types: file, license + [notice] Creating Tripal Content Types from: Tripal File Content Types (Tripal File) + [notice] Content type, "File", created. + [notice] Content type, "License", created. + [notice] Attaching fields to Tripal content types from: Tripal File Fields + [notice] Added field, "file_name", to content type: "tripal_file". + [notice] Added field, "file_description", to content type: "tripal_file". + [notice] Added field, "file_type", to content type: "tripal_file". + [notice] Added field, "file_license", to content type: "tripal_file". + [notice] Added field, "file_location", to content type: "tripal_file". + [notice] Added field, "file_relationship", to content type: "tripal_file". + [notice] Added field, "file_dbxref", to content type: "tripal_file". + [notice] Added field, "analysis_file", to content type: "tripal_file". + [notice] Added field, "file_contact", to content type: "tripal_file". + [notice] Added field, "organism_file", to content type: "tripal_file". + [notice] Added field, "project_file", to content type: "tripal_file". + [notice] Added field, "file_pub", to content type: "tripal_file". + [notice] Added field, "study_file", to content type: "tripal_file". + [notice] Added field, "license_name", to content type: "tripal_license". + [notice] Added field, "license_summary", to content type: "tripal_license". + [notice] Added field, "license_uri", to content type: "tripal_license". + [notice] Adding and publishing standard license types + [notice] Initializing publish + [notice] Finding all candidate records in the "license" chado table + [notice] Preparing to publish 3 "tripal_license" records + [notice] Step 1 of 6: Find matching records + [notice] Step 2 of 6: Generate page titles + [notice] Step 3 of 6: Find existing published entity titles + [notice] Step 4 of 6: Updating existing page titles + [notice] Step 5 of 6: Publishing 3 new entities + [notice] Step 6 of 6: Adding field items to published entities + [notice] Published 3 items for field "license_name" + [notice] Published 3 items for field "license_summary" + [notice] Published 2 items for field "license_uri" + [notice] Publish completed. Published 3 new entities, checked 0 existing entities, + added 8 new field values, and republished 0 existing field values. + [notice] Installing the EDAM ontology + [notice] Downloading URL "https://edamontology.org/EDAM.obo", saving to "/tmp/obo_v0lM58" + [notice] Importing into schema "chado" + [notice] Step 1: Preloading File "/tmp/obo_v0lM58"... + [notice] Percent complete: 0%. Memory: 98,955,896 bytes. + [notice] Percent complete: 5.00 %. Memory: 99,479,976 bytes. + [notice] Percent complete: 10.01 %. Memory: 100,071,976 bytes. + ... + [notice] Percent complete: 95.01 %. Memory: 108,600,216 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,079,472 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,079,832 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,081,320 bytes. + [notice] Found the following namespaces: EDAM. + [notice] Step 2: Examining relationships... + [notice] Percent complete: 0%. Memory: 109,071,064 bytes. + [notice] Step 3: Loading type defs... + [notice] Percent complete: 0%. Memory: 109,072,680 bytes. + [notice] Percent complete: 15.38 %. Memory: 109,075,352 bytes. + [notice] Percent complete: 30.77 %. Memory: 109,075,416 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,076,024 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,076,384 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,076,056 bytes. + [notice] Step 4: Loading terms... + [notice] Percent complete: 0%. Memory: 109,076,056 bytes. + [notice] Percent complete: 0%. Memory: 109,076,056 bytes. + [notice] Percent complete: 1.02 %. Memory: 109,082,624 bytes. + [notice] Percent complete: 2.00 %. Memory: 109,090,392 bytes. + [notice] Percent complete: 3.02 %. Memory: 109,096,856 bytes. + ... + [notice] Percent complete: 97.01 %. Memory: 109,340,336 bytes. + [notice] Cannot add Alt ID "topic_3040" without an accession + [notice] Percent complete: 98.03 %. Memory: 109,340,944 bytes. + [notice] Percent complete: 99.02 %. Memory: 109,341,360 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,341,808 bytes. + [notice] Percent complete: 100.00 %. Memory: 109,342,168 bytes. + [notice] Step 5: Cleanup... + [notice] Updating the cv_root_mview materialized view... + [notice] Updating the db2cv_mview materialized view... + [success] Module tripal_file has been installed. + +Install using the GUI +^^^^^^^^^^^^^^^^^^^^^ + +You will need to be logged into your site as a user that has administrative permissions. + +1. From the administrative menu select "Extend" + +.. image:: install.1.gui-enable-extend.png + :alt: Appearance of the 'Extend' menu item with puzzle piece icon + +2. Scroll down to the "Tripal File" module, or enter "Tripal File" in the filter box, and check the box for the **Tripal File** module. + +.. image:: install.2.gui-enable-tripal-file.png + :alt: Checkbox next to the Tripal File module, shown not yet checked. Descriptive text is 'A module for associating files with Tripal content and for accessing files via web services' + +3. Click the "Install" button + +.. image:: install.3.gui-enable-install.png + :alt: Appearance of the 'Install' button + +4. After several seconds you should see a screen similar to this + +.. image:: install.4.gui-enable-installed.png + :alt: Appearance after the tripal file module is installed. This includes the drush command 'drush trp-run-jobs --job_id=1 --username=drupaladmin --root=/var/www/drupal/web' + +5. The drush command you will need to run is shown, it is highlighted in this example. + Copy your version of this command, it will be different than the one shown in the + example here, and run it at the command line. + +Set Permissions +---------------- + +.. warning:: + + Permissions have not yet been implemented. + See `Tripal issue 1355 `_ for current status. diff --git a/docs/site_building/module_usage/tripal_file/overview.rst b/docs/site_building/module_usage/tripal_file/overview.rst new file mode 100644 index 0000000..05eaed1 --- /dev/null +++ b/docs/site_building/module_usage/tripal_file/overview.rst @@ -0,0 +1,23 @@ +Tripal File Overview +====================== + +The Tripal File module supports association of data files with content in a Chado database +and integrates those associations with content types on a Tripal website. + +.. image:: https://upload.wikimedia.org/wikipedia/commons/thumb/a/aa/FAIR_data_principles.jpg/320px-FAIR_data_principles.jpg + :alt: The 'FAIR' logo, spelled out is Findable, Accessible, Interoperable, Reusable + +These associations are meant to support +`FAIR data principles `_ +by integrating with Tripal content and web services such that: + +- Files are findable and accessible via Tripal's content web services. +- Metadata about files use globally unique controlled vocabularies. These metadata can be assigned as properties of each file. +- License and usage details can be assigned to each file. + +This module provides two new content types for Tripal sites: **File** and **License**. + +Initial development of the Tripal File module was funded by the +`National Science Foundation award #1659300 `_ +and the `National Research Support Program (NRSP) 10 project `_ +and the McIntire-Stennis project 1019284. diff --git a/docs/site_building/module_usage/tripal_file/usage.1.tripal-menu.png b/docs/site_building/module_usage/tripal_file/usage.1.tripal-menu.png new file mode 100644 index 0000000..61caec6 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.1.tripal-menu.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.10.manage-form-display-settings.png b/docs/site_building/module_usage/tripal_file/usage.10.manage-form-display-settings.png new file mode 100644 index 0000000..4e73962 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.10.manage-form-display-settings.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.10.uploaded-file.pngDELETE b/docs/site_building/module_usage/tripal_file/usage.10.uploaded-file.pngDELETE new file mode 100644 index 0000000..7906303 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.10.uploaded-file.pngDELETE differ diff --git a/docs/site_building/module_usage/tripal_file/usage.11.manage-fields.png b/docs/site_building/module_usage/tripal_file/usage.11.manage-fields.png new file mode 100644 index 0000000..3fe978e Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.11.manage-fields.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.12.create-a-new-field.png b/docs/site_building/module_usage/tripal_file/usage.12.create-a-new-field.png new file mode 100644 index 0000000..8a0845d Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.12.create-a-new-field.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.13.chado-fields.png b/docs/site_building/module_usage/tripal_file/usage.13.chado-fields.png new file mode 100644 index 0000000..97f75ff Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.13.chado-fields.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.14.file-language.png b/docs/site_building/module_usage/tripal_file/usage.14.file-language.png new file mode 100644 index 0000000..d455ef2 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.14.file-language.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.15.chado-property.png b/docs/site_building/module_usage/tripal_file/usage.15.chado-property.png new file mode 100644 index 0000000..c92631b Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.15.chado-property.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.16.cardinality.png b/docs/site_building/module_usage/tripal_file/usage.16.cardinality.png new file mode 100644 index 0000000..c7d7566 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.16.cardinality.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.17.term.png b/docs/site_building/module_usage/tripal_file/usage.17.term.png new file mode 100644 index 0000000..7d44c27 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.17.term.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.18.widget-language.png b/docs/site_building/module_usage/tripal_file/usage.18.widget-language.png new file mode 100644 index 0000000..951c9a1 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.18.widget-language.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.19.add-file-field.png b/docs/site_building/module_usage/tripal_file/usage.19.add-file-field.png new file mode 100644 index 0000000..309b69d Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.19.add-file-field.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.2.add-tripal-content.png b/docs/site_building/module_usage/tripal_file/usage.2.add-tripal-content.png new file mode 100644 index 0000000..9a71cd3 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.2.add-tripal-content.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.20.file-widget.png b/docs/site_building/module_usage/tripal_file/usage.20.file-widget.png new file mode 100644 index 0000000..16e6c92 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.20.file-widget.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.3.add-file-license.DELETE.png b/docs/site_building/module_usage/tripal_file/usage.3.add-file-license.DELETE.png new file mode 100644 index 0000000..e669fd9 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.3.add-file-license.DELETE.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.3.add-license.png b/docs/site_building/module_usage/tripal_file/usage.3.add-license.png new file mode 100644 index 0000000..30e3535 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.3.add-license.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.4.add-license.png b/docs/site_building/module_usage/tripal_file/usage.4.add-license.png new file mode 100644 index 0000000..5f0410d Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.4.add-license.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.5.add-file.png b/docs/site_building/module_usage/tripal_file/usage.5.add-file.png new file mode 100644 index 0000000..bcd6fbd Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.5.add-file.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.6.add-term.png b/docs/site_building/module_usage/tripal_file/usage.6.add-term.png new file mode 100644 index 0000000..0f18675 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.6.add-term.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.7.file-created.png b/docs/site_building/module_usage/tripal_file/usage.7.file-created.png new file mode 100644 index 0000000..1553285 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.7.file-created.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.8.upload-file.png b/docs/site_building/module_usage/tripal_file/usage.8.upload-file.png new file mode 100644 index 0000000..8e1a034 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.8.upload-file.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.9.uploaded-formatted.png b/docs/site_building/module_usage/tripal_file/usage.9.uploaded-formatted.png new file mode 100644 index 0000000..006ef81 Binary files /dev/null and b/docs/site_building/module_usage/tripal_file/usage.9.uploaded-formatted.png differ diff --git a/docs/site_building/module_usage/tripal_file/usage.rst b/docs/site_building/module_usage/tripal_file/usage.rst new file mode 100644 index 0000000..00df7e8 --- /dev/null +++ b/docs/site_building/module_usage/tripal_file/usage.rst @@ -0,0 +1,382 @@ +Tripal File Usage +=================== + +Adding a License +------------------ +To ensure data files offered by your Tripal site meet +`FAIR data principles `_, +all files must be associated with a license. +Therefore, before adding any files, you must first define the **License** types that you will need. +A few standard licenses are created when the module is installed, and +you can create as many other **License** types as needed for the data on your site. + +To create a new license type, on the shortcuts tool bar click on the Tripal icon. + +.. image:: usage.1.tripal-menu.png + :alt: Tripal shortcut menu appearance + +From the drop-down menu select **Content**. +Then click on **+Add Tripal Content** + +.. image:: usage.2.add-tripal-content.png + :alt: Appearance of the Add Tripal Content button + +There you can scroll to the **License** type and click on it. + +.. image:: usage.3.add-license.png + :alt: Appearance of the License content type option + +To create your license page you can: + + * Option 1: Fully define the license by giving it a name and provide the full description + * Option 2: Summarize the license by giving a name, providing a brief summary (or no summary) + and providing the URL to the full license online. + +For example: + +.. image:: usage.4.add-license.png + :alt: Example filled-in form for a license + +.. note:: + + It is best practice to provide a human readable summary of the user's rights in the + Summary field and to provide a link to the full legal text of the license via the URI field. + +Adding a File +--------------- + +A file can be either located locally on your site, or be a URL that references a location anywhere on the internet. + +.. note:: + + If you have followed the Tripal User's Guide you will have an analysis appropriate to link + to the file in the following example, or you can follow + :ref:`these instructions to create an Analysis page `. + However, linking an analysis is optional. + +To create a new file page, on the administrative tool bar click on the Tripal icon. + +.. image:: usage.1.tripal-menu.png + :alt: Tripal shortcut menu appearance + +From the drop-down menu select **Content**. +Then click on **+Add Tripal Content** + +.. image:: usage.2.add-tripal-content.png + :alt: Appearance of the 'Add Tripal Content' button + +There you can scroll to the **File** type and click on it. + +.. image:: usage.5.add-file.png + :alt: Appearance of the 'File' content type option + +On this page you can: + +1. Provide a **name** (required) and **description** for the file. +2. Indicate a file **type** (required). +3. Indicate the file **source** (or contact person) who has rights to the data. +4. Indicate the file **location** (either locally or via remote URL). +5. And set the **license** (required). +6. Optionally specify relationships or other linked records, such as analysis or publication. + +First, we will create a **file** page to reference a FASTA file for scaffold 1 of the whole genome assembly. +Enter the following in the File page fields: + ++---------------------+--------------+--------------------------------------------------------------------------+ +| Field | Value | ++=====================+==============+==========================================================================+ +| Name | *Citrus sinesis* Whole Genome Assembly v1.0 scaffold 1 | ++---------------------+--------------+--------------------------------------------------------------------------+ +| File Type | FASTA (format:1929) | ++---------------------+--------------+--------------------------------------------------------------------------+ +| Description | The whole genome assembly, v1.0, of *Citrus sinensis* GCA_000695605.1, scaffold 1. | ++---------------------+--------------+--------------------------------------------------------------------------+ +| File Source | *Leave blank or provide any contact you may have already* | ++---------------------+--------------+--------------------------------------------------------------------------+ +| File Location | URI | https://www.ncbi.nlm.nih.gov/nuccore/KK784873.1?report=fasta&format=text | ++ +--------------+--------------------------------------------------------------------------+ +| | File Name | Citrus sinensis-scaffold00001.fasta | ++ +--------------+--------------------------------------------------------------------------+ +| | File Size | *Leave blank* | ++ +--------------+--------------------------------------------------------------------------+ +| | MD5 Checksum | *Leave blank* | ++---------------------+--------------+--------------------------------------------------------------------------+ +| License | CC0 1.0 Universal (CC0 1.0) Public Domain Dedication | ++---------------------+--------------+--------------------------------------------------------------------------+ +| Analysis (optional) | Whole Genome Assembly and Annotation of Citrus sinensis (JGI) | ++---------------------+--------------+--------------------------------------------------------------------------+ + +.. note:: + + Specifying the file type uses an autocomplete field. + Type the first few letters and then select from the list presented. + + .. image:: usage.6.add-term.png + :alt: Example autocomplete selecting the FASTA term + +.. note:: + + A file can have more than one download location, and you can combine both local and remote files. + +.. note:: + + Providing a file source or "contact" is optional, but is recommended. + Every file with a license should indicate, via the "file source" field, + who retains the license rights (if applicable). + +After creation, the file page will look similar to this. +In this example, a publication and contact have been included. + +.. image:: usage.7.file-created.png + :alt: Appearance of a completed file entity page + +Uploading Files +----------------- + +Instead of supplying an external URI, you can upload a file to your site's local filesystem using the +"Browse…" button on the "File Upload" section of the form. + +.. image:: usage.8.upload-file.png + :alt: Appearance of the Browse button used for file upload + +The file selected here will be uploaded to a directory as configured for the field, +and once saved, will appear in the URI field with a `public://` prefix. +The default directory uses tokens to place files in a directory path based on the current date. + +An uploaded file will appear similar to this after it has been saved: + +.. image:: usage.9.uploaded-formatted.png + :alt: Appearance of an uploaded file, in this case named 'Supplementary File 1.xlsx' + +.. note:: + + To configure the path used for uploaded files, you can modify this in the settings for the field's form display + by clicking on the gear icon. + If you want to restrict the types of files that can be uploaded, you can also configure this list here. + + .. image:: usage.10.manage-form-display-settings.png + :alt: Appearance of the gear icon in the form display settings for the file location field + +Copying files to the filesystem +--------------------------------- + +You can also manually copy files to your site's filesystem, and enter the +corresponding `public://` URI. For example, if you copy a file to + +`sites/default/files/bulk_data/citrus_project/Citrus_sinensis-scaffold00001.fasta` + +then the corresponding URI would be + +`public://bulk_data/citrus_project/Citrus_sinensis-scaffold00001.fasta` + +.. note:: + + Any locally hosted file using a `public://` URI will have the **File Size** and **MD5 Checksum** + values automatically populated. + +Adding File Metadata +---------------------- + +Manually Adding Metadata +`````````````````````````` + +You can add additional metadata to a file by adding new fields to the file content type. + +On the shortcuts tool bar click on the Tripal icon. + +.. image:: usage.1.tripal-menu.png + :alt: Tripal shortcut menu appearance + +From the drop-down menu select **Page Structure**. +Then on the **Tripal File** content type select **Manage fields** + +.. image:: usage.11.manage-fields.png + :alt: The 'Manage fields' menu item on the 'File' content type + +The next page lists existing fields. We want to create a new property field, so click on **+ Create a new field**. + +.. image:: usage.12.create-a-new-field.png + :alt: Appearance of the 'Create a new field' button + +You will want to select the **Chado Fields** type + +.. image:: usage.13.chado-fields.png + :alt: Appearance of the 'Chado Fields' field collection selector. + +Then you will want to specify a name appropriate for the property you want to add. +For example, we might want to add a field to indicate the language for a document file. + +.. image:: usage.14.file-language.png + :alt: Example label 'File Language' entered into the 'Label' form field + +Then find the **Chado property** type and select it. + +.. image:: usage.15.chado-property.png + :alt: The process of selecting the 'Chado Property' field type + +One document could contain parts written in different languages, so we probably want +to change the **Allowed number of values** to unlimited. + +.. image:: usage.16.cardinality.png + :alt: Changing the 'Allowed number of values' to unlimited + +Finally, we specify an appropriate controlled vocabulary term for the field. All fields require a term. + +.. image:: usage.17.term.png + :alt: Showing the 'Set the Term' field with the term 'Language (TPUB:0000064)' entered into the field + +If we return to any **File** page and edit it, we will now have a new metadata field +for storing the language or languages. + +.. image:: usage.18.widget-language.png + :alt: Appearance of the newly created 'File Language' form field on the 'File' entity widget + +.. note:: + + You can change the Text Filter Format for a property field. In this example, formatting is not needed, + so you could change it from `Basic HTML` to `Plain Text` in the **Manage form display** tab of the field settings. + +Adding Metadata in Bulk +````````````````````````` + +.. warning:: + + A method for adding metadata in bulk has not yet been implemented. + +Associating a File with Other Content +--------------------------------------- + +Now that we have a file page, we can associate that file with any other Tripal-based content. +For this example, we will create a genome assembly project and associate the file with that project. + +Before we can associate a file with a project, we must first add a new field for the file +to the Project content type. + +On the shortcuts tool bar click on the Tripal icon. + +.. image:: usage.1.tripal-menu.png + :alt: Tripal shortcut menu appearance + +From the drop-down menu select **Page Structure**. +Then on the Project content type select **Manage fields** + +The next page lists existing fields. Now click on **+ Check for new fields**. +The File field should be detected and checked by default. + +.. image:: usage.19.add-file-field.png + :alt: Appearance of the discovered 'File' linking field, in this case with the machine name 'project_file' + +Click the **Add fields** button. + +Now create a new **Project** page. +On this page will be a field to add one or more files, for example + +.. image:: usage.20.file-widget.png + :alt: Appearance of the 'File' select element, here selecting 'Citrus Sinensis Whole Genome Assembly v1.0 scaffold 1 [FASTA format]' + +Once the project is saved, clicking the file link will take the user to the +full file page where they can download the file, view the license information, +and view metadata about the file. + +.. note:: + + Once the number of files on your site exceeds a configurable limit, which defaults to 50, + the file select will change to an autocomplete field. + +Accessing Files via Web-Services +---------------------------------- + +.. warning:: + + Web services have not yet been implemented in Tripal 4. + See `Tripal issue 2270 `_ for current status. + +Tripal File Module Chado Tables +--------------------------------- + +The license Table +``````````````````` + +The *license* table houses the base license record. +The *name* field must be a unique value for each file and thus can be selected on for finding licenses. +The *uri* field can be null, but if not null, it must be unique for each license. + ++-------------+-------------------------+------+---------------+---------------------------+ +| Column | Type | Null | Default Value | Constraint | ++=============+=========================+======+===============+===========================+ +| license_id | bigint | No | (auto) | Primary Key | ++-------------+-------------------------+------+---------------+---------------------------+ +| name | character varying(1024) | No | | Unique | ++-------------+-------------------------+------+---------------+---------------------------+ +| summary | text | Yes | | | ++-------------+-------------------------+------+---------------+---------------------------+ +| uri | text | Yes | | Unique or null | ++-------------+-------------------------+------+---------------+---------------------------+ + +The file Table +```````````````` + +The *file* table houses the base file record. +The *name* field must be a unique value for each file and thus can be selected on for finding files. + ++-------------+------------+------+---------------+---------------------------+ +| Column | Type | Null | Default Value | Constraint | ++=============+============+======+===============+===========================+ +| file_id | bigint | No | (auto) | Primary Key | ++-------------+------------+------+---------------+---------------------------+ +| name | text | No | | Unique | ++-------------+------------+------+---------------+---------------------------+ +| type_id | integer | No | | Foreign Key to **cvterm** | ++-------------+------------+------+---------------+---------------------------+ +| description | text | Yes | | | ++-------------+------------+------+---------------+---------------------------+ + +The fileprop Table +```````````````````` + +The *fileprop* table holds the properties or metadata about files. +The CV term is specified using the *type_id* column +and the rank is incremented if multiple values of the same type are stored. + ++-------------+------------+------+---------------+---------------------------+ +| Column | Type | Null | Default Value | Constraint | ++=============+============+======+===============+===========================+ +| fileprop_id | bigint | No | (auto) | Primary Key | ++-------------+------------+------+---------------+---------------------------+ +| file_id | integer | No | | Foreign Key to **file** | ++-------------+------------+------+---------------+---------------------------+ +| type_id | integer | No | | Foreign Key to **cvterm** | ++-------------+------------+------+---------------+---------------------------+ +| value | text | Yes | | | ++-------------+------------+------+---------------+---------------------------+ +| rank | integer | No | 0 | | ++-------------+------------+------+---------------+---------------------------+ + +The fileloc Table +``````````````````` + +The *fileloc* table indicates where files can be downloaded. +The *uri* column must contain the URI of the file. +Even local files have a URI. +For example a Drupal URI usually has a *public://* URI prefix. +For example: *public://bulk_data/citrus_project/Citrus_sinensis-scaffold00001.fasta*. +When a file has more than one location to download the records can be ordered by setting the *rank* column. +The Tripal file module automatically fills in the *size* and *md5checksum* values for local files. + ++-------------+-------------------------+------+---------------+---------------------------+ +| Column | Type | Null | Default Value | Constraint | ++=============+=========================+======+===============+===========================+ +| fileloc_id | bigint | No | (auto) | Primary Key | ++-------------+-------------------------+------+---------------+---------------------------+ +| file_id | integer | No | | Foreign Key to **file** | ++-------------+-------------------------+------+---------------+---------------------------+ +| uri | text | No | | | ++-------------+-------------------------+------+---------------+---------------------------+ +| rank | integer | No | 0 | | ++-------------+-------------------------+------+---------------+---------------------------+ +| md5checksum | character(32) | Yes | | | ++-------------+-------------------------+------+---------------+---------------------------+ +| size | character varying(1024) | Yes | | | ++-------------+-------------------------+------+---------------+---------------------------+ +| filename | text | Yes | | | ++-------------+-------------------------+------+---------------+---------------------------+ diff --git a/docs/sitebuilding_guide.rst b/docs/sitebuilding_guide.rst index 5dd7cd4..f47099d 100644 --- a/docs/sitebuilding_guide.rst +++ b/docs/sitebuilding_guide.rst @@ -8,4 +8,5 @@ Building your Site site_building/anatomy_of_content site_building/create_content_type + site_building/module_usage site_building/example_genomic