.. figure:: /docs/images/scipion_logo.gif :width: 250 :alt: scipion logo .. _introduction-scipion-web: =========================== Introduction to Scipion web =========================== .. contents:: Table of Contents Introduction to Django Web Framework ==================================== Django is a free and open source web application framework, written in Python, that 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 that mediates between data models (defined as Python classes) and a relational database ("Model"); a system for processing requests with a web template system ("View") and a regular-expression-based URL dispatcher ("Controller"). Model-View-Controller into the Django -------------------------------------- To understand the right works for the templates in Django, firstly, it is necessary to explain the model-view-controller pattern applied to Django. .. figure:: /docs/images/wd/DjangoGeneral.png :align: center :width: 500 :alt: DjangoGeneral.png To render a template Django, follow these steps: 1. When a user using a web browser tries to explore a page hosted inside Django, the request reaches the Django view. 2. The view file interacts with the model to get the data necessary. 3. The logic of the model obtains the data with its core mechanism developed. Normally the model gets the data from a database. 4. When the view has all the data, it uses the specified template replacing the elements with the data obtained from the model. 5. The template renders the response back to the web browser. Django setup ~~~~~~~~~~~~ Django settings reside in web/pages/settings.py URL mappings are defined in web/pages/urls.py Web app structure ~~~~~~~~~~~~~~~~~ As usual, the best option is to look directly at the code (in pyworkflow/web). Here we include a general overview: * static content comes from the "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/ Additional Information ----------------------- * `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 Structure of templates HTML inside Scipion ========================================== The templates are an important piece inside the Django framework structure; here the MVC diagram is applied to the Scipion code. MVC diagram applied to the scipion code ------------------------------------------ .. figure:: /docs/images/wd/diagramMVC.png :align: center :alt: diagramMVC Templates diagram ----------------- The template architecture is organized inside Scipion code as follows: General templates ~~~~~~~~~~~~~~~~~ .. figure:: /docs/images/wd/diagram_templates.png :align: center :alt: diagram_templates This templates can be found under 'web/pages/templates' folder. * _base__grid.html__: template base with a static style. * _base__flex__: template base with a flexible style. * __header.html__: common header for base templates, contains the Scipion logo and different views * __footer.html__: common footer for base templates with additional interest links. * __projects.html__: this template extends from base_grid and shows a list of the available projects to work with. * _project__content.html__: this template extends from base_flex and shows 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 shows the different hosts defined to be used to launch protocols and interact with them. * _tree_prot__view.html__: a sub-template which contains the protocol tree with the different protocols to use in the project, the content can be customized and be chosen. * _run_table__graph.html__: a sub-template which contains the run table list and the run graph with the protocol entries for a project, also contains a toolbar to interact with them. * __form.html__: the protocol form with different options and structured dynamically. * _header__form.html__: this template represents the header of the protocol form. * _content__form.html__: this template is a dynamic form used to change different variables and options while a protocol is being edited prior to the run. * _content_group__form.html__: it is similar to _content__form.html__ but used to render groups. Wizard templates ~~~~~~~~~~~~~~~~~ .. figure:: /docs/images/wd/diagram_templates_wiz.png :align: center :alt: diagram_templates_wiz * _wiz__base.html__: template base with a static style used just for wizard templates. All the others wizard templates extend from this base template and redefine specific parts. * _wiz__bandpass.html__: wizard template used to execute a Fourier filter for a list of particles. * _wiz__ctf.html__: wizard template to preview the low and high frequencies for PSD image converted for a micrograph from a list. * _wiz__downsampling.html__: wizard template to preview a downsampled image with a downsampling factor for a micrograph from a list. * _wiz__gaussian.html__: wizard template used to execute a Gaussian filter for a list of particles. * _wiz_filter__spider.html__: wizard template used to execute a Spider filter for a list of particles. * _wiz_particle__mask.html__: wizard template to preview the radius of a particle for a list of 100 particles. * _wiz_particle_mask__radii.html__: wizard template to preview an inner and outer radius of a particle for a list of 100 particles. * _wiz_volume__mask.html__: wizard template to preview the radius of a volume for a list of 100 volumes. * _wiz_volume_mask__radii.html__: wizard template to preview an inner and outer radius of a volume for a list of 100 volumes. Showj templates ~~~~~~~~~~~~~~~ .. figure:: /docs/images/wd/diagram_templates_showj.png :align: center :alt: diagram_templates_showj * _showj__base.html__: template base with a flex style used just for showj templates. * _showj__column.html__: showj template to visualize single row metadata (particularly ctf metadata) * _showj__gallery.html__: showj template to visualize metadata as a gallery of images * _showj__table.html__: showj template to visualize metadata as plain text * _showj_volume__astex.html__: showj template to visualize metadata volume with astex viewer applet * _showj_volume__chimera.html__: showj template to visualize metadata volume with headless chimera. Chimera will generate a webGL html page that will be rendered. Headless chimera installation is required. Creating a new template file ------------------------------ The location for the Scipion templates folder is **pyworkflow/web/pages/templates/**, so new template files should be put there. The names chosen for new templates (name and url) should have underscores and should not be in `[CamelCase] `_ format, like for example: *new_template_to_be_added.html* The new templates created must be added to the *pyworkflow/web/pages/urls.py* file, following the next example: .. code-block:: bash urlpatterns = patterns( url(r'^new_url/$', 'location of the new template'), # The '$' symbol after the url means that url could set arguments ) Django templates use HTML language, but also have a new Django language with interesting functionalities to use the potential of the framework, allowing the access and interaction with the data model information. To take a look at this new language, visit `[The Django template language] `_. Structure diagram of JavaScript libraries inside Scipion ======================================================== The architecture for javascript libraries organized inside the Scipion code is next: .. figure:: /docs/images/wd/diagram_libraries.png :align: center :alt: diagram_libraries Template Libraries ------------------- * _graph__utils.js__: Graph methods and variables to use with jsPlumb plugin, used with the template _run_table__graph.html__. * _host__utils.js__: Methods to manage the template __hosts.html__. * _project_content__utils.js__: Methods used in the _project__content.html__ template. Toolbar functions and manage tabs. * _project__utils.js__: Methods used in the _project.html_ template. * _protocol_form__utils.js__: Methods to manage the protocol form, template __form.html__. * __utils.js__: Generic library with commons methods used in different templates. * _wizard__utils.js__: Methods to manage wizards in the protocol forms. Showj Libraries ------------------ * __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 around the diagonal axis, turning columns into rows and vice versa. * `waypoint.min.js `_: Waypoints is a jQuery plugin that makes easy to execute a function whenever you scroll to an element. Used to load dynamically the images in the showj. jQuery Libraries ------------------- * `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__: Auxiliary methods to use with the jLayout library. * `jquery.sizes.js `_: JSizes is a small plugin for the jQuery JavaScript library which adds convenient methods for querying and setting some size related CSS values. * `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. Tools Libraries ------------------ jsPlumb ~~~~~~~~ jsPlumb provides 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_table__graph.html__ provides a graph view for the protocol runs using the potential of the jsPlumb. More information about its uses can be found `[here] `_ Messi.js ~~~~~~~~ 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 5 KB code. To get more information about how to use Messi.js, go `[here] `_ Raphael JS ~~~~~~~~~~ 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 dynamically in a given canvas. To get more information about how to use it, visit this `[link] `_ Adding a new JavaScript library ------------------------------- Sometimes, the use of new libraries is necessary and the organization and location of these files is not controlled. To avoid this, you have to follow this: We'll take the example of the jQuery library. If we want add jQuery into the project, first, you have to download the specific files. Inside the folder *`pyworkflow/web/pages/resources/js/`* you have to create a subfolder with your specific library name, for this case *`pyworkflow/web/pages/resources/js/jquery/`* and put there the files to use your library correctly. Creating a new JavaScript file ------------------------------ 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 has to be referred to in the template that needs it. This file should have the following general structure: \1. License (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 attributes and methods (`[CamelCase] `_ used for names) Structure example for a new JavaScript file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash /***************************************************************************** * 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; } Cascading Style Sheets (CSS) ============================== The organization chosen by the CSS files has to be explained taking the template pages as a reference. .. figure:: /docs/images/wd/diagram_css.png :align: center :width: 600 :alt: CSS diagram * *_general__style.css*: Common styles used in all the templates. * *_general_style_basegrid.css*: This file provides a static structure for the templates that include it. * *_general_style_baseflex.css*: This file provides 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. * *_projects__style.css*: CSS file associated with the _projects.html_ template. * *_project_contentstyle.css*: CSS file associated with the *_projectscontent.html* template. * *form.css*: CSS file associated with the _form.html_ template. * *_showj__style.css*: CSS file associated with the _showj.html_ template. * *_jquery-uismoothness.css*: This style file defines the table appearance for tables and columns in the showj visualizer. * *_wizardstyle.css*: This style file defines the appearance for the wizards that are based in the *_wizbase.html* template. Creating a new CSS file ------------------------- 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`**) under the folder **`pyworkflow/web/pages/resources/css/`**. The name of the file has to be referred to in the template that needs it. This file should have the following general structure: .. code-block:: bash # 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.