field guide

docs/dev_guide/custom_data_loader.rst

@@ -0,0 +1,2 @@
+Creating Custom Data Loaders
+==============================

docs/dev_guide/custom_field.rst

@@ -0,0 +1,44 @@
+Creating a Custom Field
+========================
+
+The most common way that new content will be added to an existing site is by creating new fields, or field displays.  In Tripal v2 customizations were added by editing PHP templates files.  These template files were  relatively easy to create and customize, but they provided less flexibility and did not integrate well with other Drupal features such as GUI-based page layout and Drupal Views.  Tripal v3 fields now provide this flexibility.  They also support data exchange and data collections!
+
+By default Tripal v3 provides many fields for display of Chado data. However, you may find that these fields do not display data as you want, or you want to display data that the current fields do not already provide. This section of the Handbook describes how to create new fields that are integrated into the display, search and exchange abilities of both Drupal and Tripal.
+
+If you are already familiar with Drupal fields you may be aware of the API functions and hooks that Drupal provides.  However, for the quantity of fields needed to support biological data, the Drupal API hooks quickly become overwhelming.  Additionally, documentation for fields in the Drupal API can someitmes be difficult to discover when first working with fields.   Therefore, Tripal provides several new PHP classes to simplify creation of fields and to consolidate all functionality into one easy to find set of files.  To develop new fields you should be somewhat familar working with PHP's Object-Oriented Classes. The new classes provided by Tripal are these:
+
+
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Class Name           | Description                                                                                                                                                                                                               |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TripalField          | The TripalField class provides the basic information about a new field. It provides loaders for extracting data from the database and functions for querying data managed by the field.                                   |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TripalFieldWidget    | The TripalFieldWidget class provides the necessary form elements when editing and Entity to allow the end-user to edit the value of the field (if desired). It provides the necessary validators and submittor functions. |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| TripalFieldFormatter | The TripalFieldFormatter class provides the visualization of the field when viewed on the page.                                                                                                                           |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ChadoField           | The ChadoField class extends the TripalField class and provides the necessary settings to allow the field to map entities to data in Chado                                                                                |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ChadoFieldWidget     | Extends the TripalFieldWidget class but currently provides no additional functionality. Use this class when working with Chado data to ensure future backwards compatibility.                                             |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ChadoFieldFormatter  | Extends the TriplFieldFormatter class but currently provides no additional functionality. Use this class when working with Chado data to ensure future backwards compatibility.                                           |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+
+The process for creating a custom field are as follows:
+
+* Determine the controlled vocabulary term that best describes the data your field will create.
+* Decide if you need the Chado field classes or the base Tripal field classes.  If you intend to work with data housed in Chado then you should use the Chado field classes.
+* Decide if you want to build your class manually from the ground up or speed development by using the Staton Lab Fields Generator tool.
+* Create new implementations of classes that extend those listed in the table above.  If you implement the functions properly your field is plug-and-play!  Tripal will find it and be able to use it.
+The rest of this section will walk you through these steps.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table of Contents
+
+   custom_field/select_vocab_terms
+   custom_field/manual_field_creation
+   custom_field/tripal_field_generator

docs/dev_guide/custom_field/manual_field_creation.rst

@@ -0,0 +1,2 @@
+Manual Field Creation
+======================

docs/dev_guide/custom_field/select_vocab_terms.rst

@@ -0,0 +1,2 @@
+Selecting Vocabulary Terms
+============================

docs/dev_guide/custom_field/tripal_field_generator.rst

@@ -0,0 +1,4 @@
+Easier Field Creation: Tripal Field Generator 
+============================================
+
+The Staton Lab has created a `specialized tool <https://github.com/statonlab/fields_generator>`_ for automatically generating a ChadoField or TripalField and populating them with the basic controlled vocabulary and database information.  Instructions are available at https://github.com/statonlab/fields_generator.

docs/dev_guide/custom_modules.rst

@@ -0,0 +1,6 @@
+Creating Custom Modules
+========================
+
+The Tripal API, in conjunction with the Drupal API allow developers to create their own modules that can "plug-in" with Tripal. Developers may create their own modules if they desire new or different functionality. A custom module can also be desired to house a sites "customizations." The Tripal API provides an interface for module developers to interact with the Chado database as well as the other Tripal core functions such as jobs management, materialized views, in-house vocabularies, external database cross-references, properties, etc. An understanding of the Drupal API and Drupal module development is required.
+
+Basic instructions for creating custom Drupal module can be found here:  https://www.drupal.org/docs/7/creating-custom-modules.   Before you can create custom modules that interact with Tripal, you should review those instructions and have practiced creating at least a simple module.   Tripal follows Drupal module development rules and API.  

docs/dev_guide/custom_web_services.rst

@@ -0,0 +1,2 @@
+Creating Custom Web Services
+==============================

docs/dev_guide/lorem_ipsum.rst

@@ -1,4 +0,0 @@
-Example file
-===============
-
-Lorem ipsum