Merge pull request #58 from galviset/feature/federated-content-md-dev…

…elopers (Shared content: metadata schema and developers guide)

_includes/shared_doc/developer_guide/api_key.md

@@ -0,0 +1,3 @@
+Use of the {{ page.portal }} REST APIs requires an API key. The API key can be found in the Account Settings of logged in users.
+
+![How to retrieve your API key]({{site.figures_link}}/{{include.portal}}/find_apikey.png)

_includes/shared_doc/developer_guide/api_key_examples.md

@@ -0,0 +1,9 @@
+Use of the {{ page.portal }} REST APIs requires an API key. The API key can be found in the Account Settings of logged in users.
+
+![How to retrieve your API key]({{site.figures_link}}/{{include.portal}}/find_apikey.png)
+
+1. Using the api key query string parameter: `'https://{{include.resturl}}/{media types}/{acronym}?apikey=your api key'`
+
+2. Providing an Authorization header: `Authorization: apikey token=your_apikey` 
+
+3. When using a web browser to explore the API, if you provide your API Key once using method 1, it will be stored in a cookie for subsequent requests. You can override this by providing a different API Key in a new call.

_includes/shared_doc/developer_guide/index.md

@@ -0,0 +1,5 @@
+All the content that the {{ page.portal }} uses (and more!) is available via REST services by means users can:
+- access all {{ page.portal }} {{ page.atoms }}, their different versions, and metadata for those versions;
+- access information about any {{ page.atom }} concept in {{ page.portal }} (with definitions, synonyms, and other properties);
+- search across all {{ page.atoms }} in {{ page.portal }};
+- get hierarchy information for {{ page.portal }} {{ page.atoms }} (such as parents, children, or siblings of a class, roots or leaves of a class hierarchy).

_includes/shared_doc/developer_guide/usecases.md

@@ -0,0 +1,9 @@
+### Using {{ page.portal }} technology in your project
+Several ways exist in which {{ page.portal }} technology can be applied. Here some use cases:
+- **I have a list of terms that were used to annotate a dataset, how can I see if any of these terms exist in standard {{ page.atoms }}?** Use the “Search” web service to search terms in all {{ page.portal }} {{ page.atoms }}. If you have a limited number of terms, searching each one individually via the {{ page.portal }} Search tool with the user interface may be sufficient. Otherwise, for a long list of terms, use the “Search” web service directly.
+- **I would like to find all the terms mapped from my {{ page.atom }} to other {{ page.atoms }} in {{ page.portal }}.** Use the “Mapping” web service to find terms in other {{ page.portal }} {{ page.atoms }} that are similar to the terms in your {{ page.atom }}. These mappings include those generated manually (DbXrefs) and programmatically (LOOM).
+- **I have a web form including text fields which I would like to populate with {{ page.atom }} terms, e.g., to select relevant terms from a specific {{ page.portal }} {{ page.atom }}.** Use the “Autocomplete” widget. Click on the "Get Code" button for the code and instructions on how to add this JavaScript to your web form.
+- **I would like to add the graph displaying my {{ page.atom }} on my website. Use the “Visualization” widget.** Click on the "Get Code" button for the code and instructions on how to add this JavaScript to your website.
+- **I would like to get all terms from a {{ page.atom }} and re-format the data to use in my own system.** Use the “Get All Terms” web service to get all the terms and properties for the {{ page.atom }} that you are interested in.
+- **I need to navigate through a {{ page.atom }} and go through the {{ page.atom }} hierarchy for my software application. Is there a web service to do this?** Use the “Get All terms” web service.
+- **How can I limit the selection of {{ page.atoms }} used with the Annotator to a given Category or Domain?** Use the “List all {{ page.atoms }}” and “Get Groups/Domains” web service to identify the group/domain of interest.

_includes/shared_doc/developer_guide/widgets_intro.md

@@ -0,0 +1,9 @@
+### {{ page.portal }} widgets: how to use them
+{{ page.portal }} widgets are snippets of HTML or JavaScript code that users can embed in their website/web form to use the {{ page.portal }} functionalities. Using {{ page.portal }} widgets is just one of the ways in which users can use {{ page.portal }} technologies on your website/application.
+Developers can add any {{ page.portal }} widget to their HTML page or web form by following these steps:
+1. find the {{ page.atom }} that users are interested in by browsing the list of {{ page.portal }} {{ page.atoms }};
+2. click on the {{ page.atom }} name to get to the page with Details for that {{ page.atom }};
+3. in the {{ page.atom }} details page, go to the “Widgets” tab;
+4. select the widget that want to use;
+5. click the button below the widget to get usage instructions.
+

_includes/shared_doc/developer_guide/widgets_search.md

@@ -0,0 +1,25 @@
+### {{ page.atom }} search widget
+Developers can add a search box to their website that will allow users to search a specific {{ page.portal }} {{ page.atom }}. When the user selects the term of interest (with the help of the auto-complete feature), she/he can move directly to the {{ page.portal }} summary page of the corresponding concept.
+To add a search widget to a HTML page that allows users to search for a specific {{ page.atom }}: 
+download the quick_jump.js file, put it on your server, copy the code below and paste it to your HTML page:
+```js
+ <div id="bp_quick_jump"></div>
+ <script type="text/javascript">
+   var BP_ontology_id = "ACRONYM";
+ </div>
+ <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
+```
+
+**Note:** To use Quick Jump across multiple {{ page.atoms }}:
+- enter a comma-separated list of {{ page.atom }} ids: var BP_ontology_id = "ACRONYM, ACRONYM2", or
+- you can set the variable to 'all' to search all {{ page.atoms }} in {{ page.portal }}: var BP_ontology_id = "all".
+
+Update the copied code by changing the path to the quick_jump.js file that has to point to the server location where you put the HTML file. For example, if you put the **quick_jump.js** file in the same directory as your HTML file, this is the code that you have to use:
+```js
+<script type="text/javascript">
+ var BP_ontology_id = "ACRONYM";
+ </div>
+<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
+```
+to limit the term search to a particular branch of a {{ page.atom }}, include the following JavaScript in your page (remember to replace the conceptid with the ID for the term that you want to use as the root of your branch): var BP_search_branch = "{class_id}";
+to display definitions with the list of terms that are returned, include the following JavaScript in your page: var BP_include_definitions = true;

_includes/shared_doc/developer_guide/widgets_term_selection.md

@@ -0,0 +1,38 @@
+**Term-selection field on a form**
+Developers can add a text field to their web form that will allow users to enter a term from a controlled vocabulary (e.g., terms from a single {{include.atom}})
+
+**What does the term-selection field do?**
+Auto-complete the text field so that user don't need to type the whole term
+The controlled vocabulary provides consistency in the manner in which different users use a specific term
+When a new version of your controlled vocabulary becomes available in {{ page.portal }}, the widget will automatically use that new version.
+To add a field to a web form that allows users to retrieve a term from the {{ page.atom }} of interest, do the following:
+- download the form_complete.js file and put it on your server;
+- in the header of the page where want the field, include the form_complete.js file;
+- in the form, specify the field class in the following format: bp_form_complete-{semantic_resource_acronym_list}-{value} 
+  - Note: In addition to single ontology IDs, you can use a list:
+bp_form_complete-FISHTRAITS, ENVTHES-uri OR you can use 'all' to search across all {{ page.portal }} {{ page.atom }}: bp_form_complete-all-uri 
+- Developers can use the following parameters to select which value will be placed into the user-visible input field: 
+  - uri: the complete URI of the term;
+  - shortid: the short ID of the term, as used in {{ page.portal }};
+  - name: the preferred name of the term;
+
+**Auto-generated hidden form elements**
+In addition to the input element you defined, there are four hidden form elements that are automatically created and set when users select a term from the list. For example, if you create a field with this code:
+```
+<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/> 
+The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute:
+ <input type="hidden" id="a_{{ page.portal }}_preferred_name">
+ <input type="hidden" id="a_{{ page.portal }}_concept_id">
+ <input type="hidden" id="a_{{ page.portal }}_ontology_id">
+ <input type="hidden" id="a_{{ page.portal }}_full_id">
+```
+
+**Optional attributes**
+- **Include term definitions** Use `data-bp_include_definitions="true"`  to display definitions with the list of terms that are returned.
+- **Limit search to terms below a root term.** Use data-bp_search_branch="{class_id}", replacing {class_id} with the class ID for the term to use as the branch root.
+
+**Object types:**
+- **Search 'class' and 'property' objects.** Use data-bp_objecttypes="class,property".
+- **Search only 'property' objects.** Use data-bp_objecttypes="property".
+- **Search 'class' and 'individual' objects.** Use data-bp_objecttypes="class,individual".
+- **Search only 'individual' objects.** Use data-bp_objecttypes="individual".

_includes/shared_doc/developer_guide/widgets_tree.md

@@ -0,0 +1,77 @@
+#### {{ page.portal }} Ontology Tree Widget
+Developers can put a widget on their website that displays the {{ page.atom }} tree, or a part of it, with the same result obtained in the "Visualize" tab in {{ page.portal }}.
+
+**Description**
+The {{ page.atom }} tree widget is an embeddable Flex application that allows users to interact with a tree to browse {{ page.atoms }}. The widget can be configured to display a list of all the EcoPortal {{ page.atoms }}, allowing users to select which one to view, or can be set to view a particular {{ page.atom }}. Moreover, there are several JavaScript helper functions for the widget, allowing it to be used as a fully functional component in other applications.
+
+**Location**
+To use the tree widget, you have to add the following files:
+- http://{{ page.portalURL }}/widgets/jquery.ncbo.tree.css
+- http://{{ page.portalURL }}/widgets/jquery.ncbo.tree-2.0.2.js
+
+or the minified versions:
+- http://{{ page.portalURL }}/widgets/minified/jquery.ncbo.tree.min.css
+- http://{{ page.portalURL }}/widgets/minified/jquery.ncbo.tree-2.0.2.min.js
+
+**Setup**
+jQuery is required in order to use the tree widget. If jQuery is not still in your project, you have to include it as follows:
+```js
+<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
+```
+
+Then, you have to create a div element to store the tree:
+```js
+<div id="tree"></div>
+```
+
+initialise the tree with the following JavaScript code:
+```js
+var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "ACRONYM"});
+```
+
+The div you created will contain a tree showing the roots of the ACRONYM {{ page.atom }}. Additional setup options include:
+- **autoclose**: to close other branches of the tree when expanding a new one;
+- **treeClass**: the class to identify the tree;
+- **autocompleteClass**: the class to identify the autocomplete (search) input;
+- **width**: the width of the tree;
+- **startingClass**: to start with this class selected (and expanded to) in the tree;
+- **startingRoot**: to start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing;
+- **ncboAPIURL**: to use a different NCBO REST instance (not normally used);
+- **ncboUIURL**: to use a different NCBO UI instance (not normally used).
+
+**Callbacks and event triggers**
+Developers can interact programmatically with the tree by using JavaScript and jQuery. Callbacks can be passed when setting up the tree:
+```js
+var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "ACRONYM", afterSelect: function(event, classId, prefLabel, selectedNode){console.log(classId);}});
+```
+The available callbacks with their arguments are:
+- **beforeExpand**, arg: expandedNode
+- **afterExpand**, arg: expandedNode
+- **afterExpandError**, arg: expandedNode
+- **afterSelect**, arg: classId, prefLabel, selectedNode
+- **afterJumpToClass**, arg: classId
+
+It’s possible to listen to these callbacks as jQuery events:
+tree.on("afterSelect", function(event, classId, prefLabel, selectedNode){console.log(classId);}
+
+The events with their arguments are:
+- **beforeExpand**, arg: event,expandedNode
+- **afterExpand**, arg: event,expandedNode
+- **afterExpandError**, arg: event,expandedNode
+- **afterSelect**, arg: event,classId, prefLabel, selectedNode
+- **afterJumpToClass**, arg: event,classId
+
+**Public methods**
+There are a variety of methods to call on the object that is returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.
+```js
+var tree = $("#tree").data("NCBOTree");
+OR
+var tree = $("#tree")[0].NCBOTree;
+OR
+var tree = document.getElementById("tree").NCBOTree;
+```
+Once you have the tree instance, you can call the following methods:
+- **tree.selectedClass()**: returns an object that represents the currently-selected class. The object includes attributes for ID, prefLabel, and URL. URL is the REST location of the class, and performing an HTTP GET on that URL will provide a JSON representation of the class;
+- **tree.selectClass(classId)**: activates the class in the tree with the matching URI (classId). This will only work if the class is already visible;
+- **tree.jumpToClass(classId)**: replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns;
+- **tree.changeOntology(ontologyAcronym)**: replaces the current tree with the roots from the given {{ page.atom }}.

_includes/shared_doc/developer_guide/widgets_visualization.md

@@ -0,0 +1,6 @@
+**{{ page.atom }} visualisation widget**
+Developers can put a widget on their website that shows {{ page.atom }} of interest, or a part of it, and obtain the same result as in the "Visualize" tab in {{ page.portal }}.
+To add a widget visualising your {{ page.atom }} in your HTML page, copy the code from the Widget page of your {{ page.atom }} of interest. Here is an example:
+```html
+<iframe src="http://{{include.resturl}}/widgets/visualization/?ontology=ACRONYM&class=SELECT_CLASS&apikey=YOUR_API_KEY"frameborder="0"></iframe>
+```

_includes/shared_doc/metadata_schema/BioPortal.md

@@ -0,0 +1 @@
+// write about BioPortal metadata schema

_includes/shared_doc/metadata_schema/MOD.md

@@ -0,0 +1,5 @@
+The {{ page.portal }} Metadata Schema is built upon the Metadata Vocabulary for Ontology Description and Publication ([MOD 2.0](https://w3id.org/mod/2.0)). This comprehensive schema integrates various vocabularies, such as Dublin Core, OMV, DCAT, and VoID, and was introduced by [Dutta et al. 2017](http://dx.doi.org/10.1007/978-3-319-70863-8_17). Its primary purpose is to empower ontology developers to annotate and describe their ontologies, while also enabling ontology libraries to provide semantic descriptions of ontologies in the form of linked data.
+
+{{ page.portal }} with other members of the OntoPortal Alliance has embraced a set of 106 elements, comprising classes and properties organised into distinct categories. Each metadata element is linked to a FAIR principle, adding a layer of semantic richness to the description. The assessment of metadata elements is facilitated through the O'FAIRe tool, ensuring a systematic evaluation of the ontology's Findability, Accessibility, Interoperability, and Reusability aspects.
+
+{{ page.portal }} administrators encourage the creators of semantic artefacts to compile the metadata fields by adding as much detail as possible to ensure the accurate communication of information to users and to be compliant to the FAIR principles when publishing a resource.