| 1 | | '''THIS PAGE IS OUT OF DATE''' |
| 2 | | = S3UI v1 - ExtJS based UI for Eden = |
| 3 | | [[TOC]] |
| 4 | | S3XRC being a powerful backend that serves XML and JSON in a RESTful manner has now got a front-end framework that can exploit its positives. S3UI - the new ExtJS based front-end help us not only utilize S3XRC but also save a lot of bandwidth by exchanging information in JSON instead of full page reloads. This in turn aims to create an easy and quick workflow for different tasks that a user does with Sahana Eden. |
| 5 | | == Architecture == |
| 6 | | [[Image(S3UI Framework.png)]] |
| 7 | | |
| 8 | | '''S3UI Framework is has 4 major components''' |
| 9 | | * '''Custom views''' - these views contain appropriate javascript and html required to render the S3UI widgets, however they are minimal and look almost similar to old views for matter of simplicity and similarity. |
| 10 | | |
| 11 | | * '''Javascript''' - |
| 12 | | * '''_s3ui_list.js''' - generates the grid view, included by _s3ui_list and _s3ui_list_create views - |
| 13 | | * Setting up metadata |
| 14 | | * fetching column model |
| 15 | | * Parsing json data from s3xrc into an Ext Datastore |
| 16 | | * Configuring and rendering a Grid widget on desired DOM element |
| 17 | | |
| 18 | | * '''core.js''' - |
| 19 | | * Provides S3UI objects and S3UI_Elements list |
| 20 | | * Manages creation of different widgets - used in custom views |
| 21 | | * Naming convention - |
| 22 | | * data_FunctionName - any function pertaining to parsing, formatting or manipulating data, nothing that affects UI |
| 23 | | * tools_FunctionName - various helpers that aid larger widgets - Eg. plugin implementors, micro-widget generators (date picker, checkbox, combo box) |
| 24 | | * widget_FunctionName - Larger widgets that can be used directly to create new visible UI elements |
| 25 | | * '''plugins''' - various ExtJS based plugins used by core.js |
| 26 | | |
| 27 | | * '''Extcrud.py''' |
| 28 | | * is used to override necessary functions of s3crud.py that are useful to S3UI |
| 29 | | * Alters flow through pre, post hooks to plug in code required by new UI |
| 30 | | * list_fields is no longer relevant, the modified S3XRC has a url/listfields.json handler that gives back list of fields needed by a resource, it is implemented in the post processing hook here. |
| 31 | | * Implements xrc_list - a replacement for shn_list. It doesn't do as much work as shn_list, but leaves the rendering of datagrid to the frontend, page loads fast but rest of the processing is done by core.js |
| 32 | | * contains S3XRC_FRONTEND switch. Whats that? setting S3XRC_FRONTEND = false results in disabling all S3UI functionalities and lets one fall back to old UI. Useful when S3UI fails, or for testing. |
| 33 | | * overrides shn_rest_controller to setup hooks. |
| 34 | | == Widgets == |
| 35 | | * '''Grid View widget''' - |
| 36 | | * Seen in _s3ui_list , _s3ui_list_create views |
| 37 | | * Utilized in _s3ui_list.js |
| 38 | | * Produced by core.js - |
| 39 | | * once all required metadata is setup (see _s3ui_list.js), the following are called up in order - |
| 40 | | * widgets_getGridView() |
| 41 | | * widgets_gridView.create(dom element id) |
| 42 | | * widgets_gridView.show() |
| 43 | | |
| 44 | | * '''Rheader tabs''' - |
| 45 | | * Seen in _s3ui_update , _s3ui_display views as they are found to be primary to record's default view |
| 46 | | * Utilized in _s3ui_update and _s3ui_display views itself |
| 47 | | * Produced by core.js - |
| 48 | | * once base_url, update_url, uid_prefix, setupElementNames() is set, following are called to produce tabs |
| 49 | | * widgets_tabs_parseHtml() [ subject to change in version 2 ] |
| 50 | | * widgets_tabs_render() |
| 51 | | |
| 52 | | * '''widgets_formPanel''' - |
| 53 | | * Seen in grid view widget, views where there are no records in the list |
| 54 | | * widgets_formPanel parameters |
| 55 | | * action - either of 'create' or 'update' indication which type of form window to generate |
| 56 | | * window title - caption for form window |
| 57 | | * also has ability to generate buttons for actions - widgets_formPanel_createButton(action, caption, title, dom element id) |
| 58 | | * handles form submission, has very basic error indicaton as of now. |
| 59 | | == Roadmap == |
| 60 | | '''Wishlist for S3UI v2 -''' |
| 61 | | * Frontend validation |
| 62 | | * Exploiting more ExtJS power |
| 63 | | * New Rheader tabs, non IFrame implementation |
| 64 | | * SQLFORM2 as a replacement of SQLFORM to give out json form configuration |
| 65 | | * More speed, less load on backend, free the logic layer of presentation tasks |
| 66 | | == FAQ == |
| 67 | | |
| 68 | | '''Q. How to turn off S3UI and fall back to old UI?''' |
| 69 | | |
| 70 | | '''A.''' In models/01_extcrud.py change - |
| 71 | | {{{ |
| 72 | | S3XRC_FRONTEND = True |
| 73 | | }}} |
| 74 | | into |
| 75 | | {{{ |
| 76 | | S3XRC_FRONTEND = False |
| 77 | | }}} |
| 78 | | |
| 79 | | See Also: |
| 80 | | * wiki:UserGuidelinesS3UI |
| | 1 | See [[wiki:S3]] |
