-
Notifications
You must be signed in to change notification settings - Fork 5
getting started
This set of small tutorials will give you an introduction on how to use and extend the retina framework. But what does the retina framework do?
Imagine you have a web page that features a table. The data for the table is located in a database on your server that makes it available via a REST API. You want your users to be able to filter and sort the table, then pick a row and show a detail view of that item. The detail view shows so text and a pie-chart.
You can use stm to connect to the database server and retrieve the data. The data is then rendered using the table renderer. You add a callback to the table that causes stm to retrieve detail information about the item from the database server and then show the result as some text and enhance it with the output of a pie-chart renderer.
To do this you create an HTML page that includes retina and stm and on page load instanciates your application widget. The widget handles the action flow. It initializes stm, it makes a call to get the data. It formats the data so it suits the table renderer, then instanciates the table renderer. It adds a callback to the table and has a function to have stm retrieve the detail data. It then displays the details and instanciates a pie-chart-renderer.
To setup your first retina webapp, create a folder to host your project and clone the Retina repository into it.
cd RetinaTutorial
git clone git@github.com:MG-RAST/Retina.git
Now copy the tutorial.html from the tutorial directory to your main directory. For your other resources you should create a couple of directories to keep things organized. Then copy the tutorial widget into your widget directory, the config file into the js directory, your favicon into the image directory and the stylesheet into the css directory.
mkdir widgets css images js
cp Retina/tutorial/widget.tutorial.js widgets/
cp Retina/tutorial/config.js js/
cp Retina/tutorial/favicon.ico images/
cp Retina/tutorial/tutorial.css css/The root directory will host all of your html files (if you choose to have more than one). Stylesheets are placed in the css directory, images in the image directory. The js directory will host your config file (if you need one) and external libraries you want to include. The widgets directory holds all of the control widgets of you webapplication.
If you open the tutorial.html file in your browser, you will see the initial version of the tutorial app.
Open the tutorial.html in your favorite text editor so we can take a closer look at what is happening.
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Retina Turorial</title>
<link rel="icon" href="images/favicon.ico" type="image/x-icon">
<!-- bootstrap style-->
<link rel="stylesheet" href="Retina/css/bootstrap.min.css">
<!-- custom style-->
<link rel="stylesheet" href="css/tutorial.css">
<!-- javascript files-->
<script type="text/javascript" src="Retina/js/stm.js"></script>
<script type="text/javascript" src="Retina/js/retina.js"></script>
<script type="text/javascript" src="Retina/js/jquery.min.js"></script>
<script type="text/javascript" src="Retina/js/bootstrap.min.js"></script>
<!-- config file-->
<script type="text/javascript" src="js/config.js"></script>
<!--initialization-->
<script type="text/javascript">
jQuery(document).ready(function() {
stm.init({});
Retina.init({ widget_resource: "widgets" });
Retina.load_widget("tutorial").then( function () {
Retina.Widget.create("tutorial", { "target": document.getElementById("content")});
});
});
</script>
</head>
<body>
<h2>Welcome to the Retina Tutorial</h2>
<div class="content"></div>
</body>
</html>In the head section of the HTML document we load the bootstrap style and the basic required javascript files for Retina, stm, jQuery and Bootstrap. Your custom stylesheet and config file is also added here.
The next part is the application initialization. Since we need to make sure this happens after all content of the page, including all javascript files are loaded, we use the jQuery document ready function.
<script type="text/javascript">
jQuery(document).ready(function() {
stm.init({});
Retina.init({ widget_resource: "widgets" });
Retina.load_widget("tutorial").then( function () {
Retina.Widget.create("tutorial", { "target": document.getElementById("content")});
});
});
</script>The init function of both stm and Retina are called. They both accept a parameter object. For the purpose of this tutorial we do not need additional options for stm, but we do need to tell Retina where to look for widgets. This is done via the widget_resource parameter and is a path relative to the HTML base.
The next line loads the tutorial widget. Since we just told Retina where to find the widgets, all we need is the widget name. The actual file that contains the widget must always be prefixed widget. followed by the widget name and ending in .js. The load_widget function returns a promise so we can call the create function as soon as the loading has completed.
The create function receives the name of the widget as the first parameter and an object of options as the second. All widgets should have at least a target parameter, specifying the DOM element that should contain the content the widget produces. You could additionally or alternatively place target divs for different parts of your application into the HTML and reference those later in your widget.
The div passed to the tutorial widget is referenced by the id property, you can find it in the body section of the HTML document.
If everything went according to plan, your should see the hello world app in your browser. This concludes the first part of the tutorial. The next section will cover