Introduction to Scipion web
Django is a free and open source web application framework, written in Python, which follows the model–view–controller architectural pattern. It is maintained by the Django Software Foundation (DSF).
The core Django MVC framework consists of an object-relational mapper which mediates between data models (defined as Python classes) and a relational database ("Model"); a system for processing requests with a web templating system ("View") and a regular-expression-based URL dispatcher ("Controller").
To understand the right works for the templates in Django, firstly, it is necessary to explain the model-view-controller pattern applied to Django.
To render a template Django follow the next steps:
-
When a user using a web browser try to explore a page hosted inside django, the web browser launch a petition to the django view.
-
The view file interact with the model to get the data necessary.
-
The logic of the model obtain the data with his core mechanism developed. Normally the model get the data from a database.
-
When the view got all the data, use the specific template overwritting the elements with the data obtained from the model.
-
The template render the rensponse to the petition from the web browser.
Django settings reside in web/pages/settings.py
URL mapping is defined in web/pages/urls.py
As usual, best option is to pay a direct look to the code (in pyworkflow/web). Here we include a general overview:
-
static content comes from "static" directory. You need to run "python manage.py collectstatic" to actually populate the directory with the required files
-
pages
-
resources
-
templates
-
urls.py
-
-
app: actual application code (models, views…)
-
manage.py: "a thin wrapper around django-admin.py that takes care of two things for you before delegating to django-admin.py" (puts your project’s package on sys.path and sets the DJANGO_SETTINGS_MODULE variable) . For a list of manage.py commands and more details, visit https://docs.djangoproject.com/en/1.6/ref/django-admin/
-
Django Official Documentation: Current and detailed documentation on nearly every aspect of Django. It includes a version selector for information pertaining to specific versions of Django.
-
The Django Book: Released under the GNU Free Documentation License.
-
Django Packages: A directory of reusable apps, sites, tools, and more for Django projects.
-
Django Basics: Installing Django and Setting Up a Project and an App
The templates are a important piece inside the django framework structure, here the MVC diagram applied to the scipion code.
Templates diagram The templates architecture organized inside the Scipion code is the next: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
_basegrid.html: template base with a static style.
-
_baseflex: template base with a flexible style.
-
header.html: common header for base templates, content the Scipion logo and the diferents views
-
footer.html: common footer for base templates with additional interest links.
-
projects.html: this template extends from base_grid and show a list of the projects available to be chosen to work.
-
_projectcontent.html: this template extends from base_flex and show the content of a project with two run views (graph or list), also a tree with the protocols.
-
hosts.html: this template extends from base_grid and show the diferent hosts defined to be used to launch protocols and interact with them.
-
_tree_protview.html: it is a sub-template which content the protocol tree with the diferents protocols to use in the project, the content can be customized and be chosen.
-
_run_tablegraph.html: Its is a sub-template which content the run table list and the run graph with the protocols entries for a project, also content a toolbar to interect with them.
-
form.html: the protocol form with diferent options and structured dynamically.
-
_headerform.html: this template represent the header of the protocol form.
-
_contentform.html: this template is dynamic form used to change diferente variables and options while a protocol is being edited to be launched.
-
_content_groupform.html: It is similar than _contentform.html but used to render groups form.
-
_wizbase.html: template base with a static style used just for wizard templates. All the others wizard templates extend from this base template and redefining specific parts.
-
_wizbandpass.html: wizard template used to execute a fourier filter for a list o particles.
-
_wizctf.html: wizard template to previsualize the low and high frequencies for PSD image converted for a micrograph from a list.
-
_wizdownsampling.html: wizard template to previsualize a downsampled image with a downsampling factor for a micrograph from a list.
-
_wizgaussian.html: wizard template used to execute a gaussian filter for a list o particles.
-
_wiz_filterspider.html: wizard template used to execute a spider filter for a list o particles.
-
_wiz_particlemask.html: wizard template to previsualize a radius for a particle for a list of 100 particles.
-
_wiz_particle_maskradii.html: wizard template to previsualize an inner and outer radius for a particle for a list of 100 particles.
-
_wiz_volumemask.html: wizard template to previsualize a radius for a volume for a list of 100 volumes.
-
_wiz_volume_maskradii.html: wizard template to previsualize an inner and outer radius for a volume for a list of 100 volumes.
-
_showjbase.html: template base with a flex style used just for showj templates.
-
_showjcolumn.html: showj template to visualize single row metadata (particularly ctf metada)
-
_showjgallery.html: showj template to visualize metadata as a gallery of images
-
_showjtable.html: showj template to visualize metadata as plain text
-
_showj_volumeastex.html: showj template to visualize metadata volume with astex viewer applet
-
_showj_volumechimera.html: showj template to visualize metadata volume with headless chimera. Chimera will generate a webgl html page which will be renderized. Headless chimera installation is required.
The location for the scipion templates are in the folder
pyworkflow/web/pages/templates/, so for create a new file, should
be done and put there.
The names chosen for new templates (name and url) should be with
underscores and not with
CamelCase format, like for
example: new_template_to_be_added.html
The new templates created must be added into the
pyworkflow/web/pages/urls.py file, following the next example:
urlpatterns = patterns(
url(r'^new_url/$', 'location of the new template'),
# The '$' symbol after the url means that url could set arguments
)
The django templates using HTML language, but also add a new django language with interesting functionalities to use the potential of the framework synchronizing with the data model information. To take a look for this new template language visit this link.
The architecture for script libraries organized inside the Scipion code is the next:
-
_graphutils.js: Graph methods and variables to use with jsPlumb plugin, used with the template _run_tablegraph.html.
-
_hostutils.js: Methods to manage the template hosts.html.
-
_project_contentutils.js: Methods used in the _projectcontent.html template. Toolbar functions and manage tabs.
-
projectutils.js: Methods used in the _project.html template.
-
_protocol_formutils.js: Methods to manage the protocol form, template form.html.
-
utils.js: Generic library with commons methods used in diferents templates.
-
_wizardutils.js: Methods to manage wizards in the protocol forms.
-
colReorder.js: Library to allow columns to be reordered in a DataTable.
-
colReorderWithResize.js: Library to allow columns to be reordered in a DataTable with an automatic resize.
-
transpose.js: Library to transpose (rotate) a table about the diagonal axis, turning columns into rows and viceversa.
-
waypoint.min.js: Waypoints is a jQuery plugin that makes it easy to execute a function whenever you scroll to an element. Used to load dinamically the images in the showj.
-
jquery.js: jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, animation, and Ajax much simpler with an easy-to-use API that works across a multitude of browsers.
-
jquery-ui.js: jQuery UI is a curated set of user interface interactions, effects, widgets, and themes built on top of the jQuery JavaScript Library.
-
jquery.dataTables.js: DataTables is a plug-in for the jQuery Javascript library. It is a highly flexible tool, based upon the foundations of progressive enhancement, which will add advanced interaction controls to any HTML table.
-
jquery.hoverIntent.minified.js: hoverIntent is a plug-in that attempts to determine the user’s intent with mouse movement. It is similar to jQuery’s hover method.
-
jquery.jeditable.js: Edit in place (inline edit) plugin with possibility to create your own input types.
-
jquery.jlayout.js: The jLayout JavaScript library provides layout algorithms for laying out components.
-
jlayout.border.js: Auxiliar methods to use with the jLayout library.
-
jquery.sizes.js: JSizes is a small plugin for the jQuery JavaScript library which adds convenience methods for querying and setting the CSS.
-
jquery.treeview.js: Lightweight and flexible transformation of an unordered list into an expandable and collapsable tree, great for unobtrusive navigation enhancements. Supports both location and cookie based persistence.
-
jquery.cookie.js: A simple, lightweight jQuery plugin for reading, writing and deleting cookies.
jsPlumb provides a means for a developer to visually connect elements on their web pages. It uses SVG in modern browsers, and VML on IE 8 and below. Can be used with jQuery, MooTools or YUI3 (or another library of your choice if you feel like implementing an adapter for it).
The template _run_tablegraph.html provides a graph view for the protocol runs using the potential of the jsPlumb.
More information about his uses can be found here.
Messi is a jQuery plugin to show clean, elegant messages in a simple way. With Messi you will avoid to use default JavaScript alert notifications or new windows to provide extended information to the user. Display text, html content, images and ajax requests with 5KB code.
To get more information about how to use Messi.js, go here.
Raphael is a small JavaScript library that should simplify your work with vector graphics on the web. If you want to create your own specific chart or image crop and rotate widget, for example, you can achieve it simply and easily with this library. Raphael uses the SVG W3C Recommendation and VML as a base for creating graphics. This means every graphical object you create is also a DOM object, so you can attach JavaScript event handlers or modify them later. Raphael’s goal is to provide an adapter that will make drawing vector art compatible cross-browser and easy. Raphael currently supports Firefox 3.0+, Safari 3.0+, Chrome 5.0+, Opera 9.5+ and Internet Explorer 6.0+.
It is used by the wizards in Scipion, getting the potential to paint circles and images dinamically in a canvas given.
To get more information about how to use it, visit this link.
Sometimes the use of new libraries is necessary and the organization and
ubication of these files is not controlled, to avoid this one, you have
to follow this: We go to take the example for the jQuery library. If we
want add this library into the project folder, at first time you have to
download the specific files. Inside the folder
pyworkflow/web/pages/resources/js/ you have to create another one
with you specific library name, for this case
pyworkflow/web/pages/resources/js/jquery/ and put into the files to
use your library correctly.
Suppose that we want to create a new JavaScript file to interact with
some template. The first step is: to create a file (named, for example
file_script_utils.js) into the folder
pyworkflow/web/pages/resources/js/. The name of the file have to
be refered to the template name dedicated. This file should have the
following general structure:
\1. License (like for example GNU) 1. General description for the file functionalities. 1. List of attributes and brief description. 1. List of the methods and brief description (optional example usages). 1. Implementation of the atrributes and methods (CamelCase used for names)
/*****************************************************************************
* DESCRIPTION:
* Methods used to do a lot of things.
*
* ATTRIBUTES LIST:
* var attr1
* -> Description of the attr1
*
* var attr2
* -> Description of the attr2
*
* METHODS LIST:
*
* // *** Tag for agroup some methods *** //
* function auxMethod1(elm1, elm2)
* -> Function to do something with the parameters passed by arguments.
* Return a new element.
* Usage example: auxMethod1(elm1, elm2)
*
/** ATTRIBUTES ****************************************************************/
var attr1="";
var attr2="";
/** METHODS ******************************************************************/
function auxMethod1(elm1, elm2){
/*
* Comment similar than the first one to describe the function functionalities.
* Function to do something with the parameters passed by arguments.
* Return a new element.
*/
var elm3 = elm1 + elm2
// comment to describe what we do
return elm3;
}
%ENDCODE%
The organization chosen by the CSS files has to be explained taking the templates pages as a reference.
-
_generalstyle.css: Common styles used in all the templates.
-
_general_style_basegrid.css: This file CSS provide a static structure for the templates that include it.
-
_general_style_baseflex.css: This file CSS provide a flexible structure for the templates that include it.
-
jquery-ui.css: Style file used by the jQuery UI library.
-
font-awesome.min.css: Style file where is defined the 'awesome' theme for the fonts and icons.
-
messi.css: File that define the popups showed by the messi.js library.
-
projectsstyle.css: CSS file asociated to the _projects.html template.
-
_project_contentstyle.css: CSS file asociated to the _projectscontent.html template.
-
form.css: CSS file asociated to the form.html template.
-
showjstyle.css: CSS file asociated to the _showj.html template.
-
_jquery-uismoothness.css: This style file define the table appareance for tables and columns in the showj visualizer.
-
_wizardstyle.css: This style file define the appareance for the wizard that are based in the _wizbase.html template.
Suppose that we want to create a new CSS file to interact with some
template. The first step is: to create a file (named, for example
new_file_style.css) into the folder
pyworkflow/web/pages/resources/css/. The name of the file have to
be refered to the template name dedicated. This file should have the
following general structure:
%INICODE% # Brief description for the file. # General CSS for common uses into the template. # CSS for specific structures inside the template, like for example: TOP, RIGHT, LEFT, BOTTOM,... # Specific CSS for parts into the template, like for example TABLE, LIST, TREE,... # CSS overwritten, if we need it. %ENDCODE%
— Main.JoseGutierrezTabuenca - 2015-04-09