Code

Changes between Version 4 and Version 5 of HydroAdmin


Ignore:
Timestamp:
12/15/12 15:35:09 (16 months ago)
Author:
abki
Comment:

rework the page, less hydro, more insights

Legend:

Unmodified
Added
Removed
Modified
  • HydroAdmin

    v4 v5  
    11Admin revamp project. 
    2  
    3 ''Planning to remove this editorial content'' 
    4 > Basically what the admin lacks is hooks to extend it as needed and in unexpected fashion, while it's always possible to extend it, current methods are considered hacks and introduce code that is not easy to maintain.  
    52 
    63What we propose here is a revamp of the the admin app looking for minimal work to customize the admin, striving for reusability and maintenability while still making it possible to: 
     
    96- Refresh the design and make it responsive 
    107 
    11  
    12 == Big picture == 
    13  
    14  
    15 The idea is taken from [http://en.wikipedia.org/wiki/PHP-Nuke PHP-Nuke] which blew some minds in its time: 
    16  
    17 - Use of a class per page 
    18 - Populate templates with widgets 
    19  
    208== Current admin limitations == 
    219 
    22 - Current workflow for most page is to customize the pages of the admins are the following: 
    23  - most common way: Override ModelAdmin or Admin class methods, inject needed variables in template context and then override the templates: this can be made simpler, overriding templates is not considered future proof and can be made simpler 
    24  - There are hooks to insert custom code (filter spec, admin actions) but it's predefined, not flexible and bound to features already defined in the admin. What if one wants a custom sidebar that fills the form dynamically from generated list of templates ? 
    25  - Insert Javascript, this is the most flexible way to extend the admin, it's hacky and promotes creation of code that might not be accessible. 
    26  - Adding a view is two way process a) subclass get_urls, add the url b) create a new method of ModelAdmin as view 
     10Current methods to customize the pages of the admin are the following: 
     11 
     12- most common way: Override ModelAdmin or Admin class methods, inject needed variables in template context and then override the templates: this can be made simpler, overriding templates is not considered future proof and can be made simpler 
     13- There are hooks to insert custom code (filter spec, admin actions) but it's predefined, not flexible and bound to features already defined in the admin. What if one wants a custom sidebar that fills the form dynamically from generated list of templates ? 
     14- Insert Javascript, this is the most flexible way to extend the admin, it's hacky and promotes creation of code that might not be accessible. 
     15- Overrindg templates: this is tricky since and has the same limitations as above lake of maintenability, readability and reusability and can make an extensive (anti-pattern) use of templatetags to get things done. 
     16- Monkeypatching: ''I have no example of that but I know it's used in production on some sites'' 
    2717 
    2818Following limitations are from my own and might not reflect reality don't hesitate to comment or strip if it's not appropriate: 
    2919 
    3020- In a context where you have several admin sites or experiences because of different user permissions or settings, templates are the only reusable part. You can create functions to encapsulate some functionality but there is no canvas for that and can become a bit messy with a big file named like admin_views_utils.py. 
     21- Since urls are computed for every requests, it makes the admin impractical for user facing applications. 
    3122- ... 
    3223 
     24== Usecases == 
     25 
     26- Create a dashboard 
     27- Manipulate objects which are not model instances ([http://code.larlet.fr/django-roa/wiki/Home django-roa] [https://github.com/liberation/django-sneak django-sneak], [https://github.com/liberation/django-admincommand django-admin-commands]) 
     28- Read-only objects 
     29- Going beyond what is offered by current ModelAdmin in terms of form layout/experience ([https://github.com/liberation/django-admin-tabs django-admin-tabs]) 
     30- Customize user experience based on cookie 
     31- Target other devices ([https://github.com/jezdez/django-mobileadmin django-mobileadmin], maybe something more up-to-date ?) 
     32- Integrate frontend features/experience in the backend 
     33- Add links to other views in the admin index page 
    3334 
    3435== Features == 
    3536 
    36  - Same features as current admin 
    37  - Responsive 
    38  - Use class-based-views throughout 
     37High: 
     38- Same features as current admin 
     39- Responsive 
     40- Use class-based-views throughout 
     41- Clear patterns to extend the admin 
     42- ... 
    3943 
     44Low: 
     45- Reusable components across projects and within the same project 
     46- ... 
    4047 
    41 === Features that need further definition === 
    42  - Each page is a widget composition 
    43  - Each widget is class 
     48Spotlight of current feature of the admin 
     49- The new admin app should, like the current admin app, allow the user to enable full secure (permission-based) CRUD in one line of code. 
    4450 
    4551== Examples of Admin Extension in the Wild == 
     52 
    4653In alphabetical order: 
    4754 
    4855* django-admin-tools (http://pypi.python.org/pypi/django-admin-tools/0.4.1) 
     56 - a full featured and customizable dashboard 
     57 - a customizable menu bar 
     58 - tools to make admin theming easier (''what does it mean ?'') 
    4959* Grappelli (http://www.grappelliproject.com/) 
    50 * … 
     60 - It's a skin 
     61* [https://github.com/divio/djangocms-admin-style djangocms-admin-style]  
     62* [https://github.com/django-djam/django-djam Django-djam] 
    5163 
    5264Built on top of admin-tools: 
     
    6274* … 
    6375 
     76 
    6477== Pros == 
    6578 
    6679- No more hacks: Offers a clear canvas to extend the admin  
    6780- More reusable components for Django 
    68 - The framework/application upon which HydroAdmin is built can be used to create frontends just like PHP-Nuke making Django even-more accessible (and maybe even to non-developpers) 
    6981- No more monkey-patching 
    7082- ... 
     
    7385 
    7486- Backward incompatible 
    75 - More layer in view infrastructure 
    76 - No more hacks 
     87- More layer in view stack 
    7788- ... 
    7889 
    79 == Code layout == 
     90== Possible implementation == 
    8091 
    81 - '''Hydro''' this is an application framework with all of what is needed to create an application using the page/widget classes  
    82  - Hydro is named like that because of wrong assumption, it goes as follow: I thought that nuke was another name for nucelar bomb, what is better than an nuclear bomb is a Hydrogen bomb, it doesn't work because nuke is used for both hydrogen nukes and plutonium nukes. 
    83  - Another name ? 
    84 - '''HydroAdmin''' this is an example app of the Hydro application that use the page/widget classes to build a backend equivalent in feature to current admin 
    85  - HydroAdmin is the project name, eventually it will be named admin just like newforms became forms 
     92= Hydro = 
    8693 
    87 About using boostrap: 
    88 - is the licensing Ok ? 
    89 - should it be embedded compiled or as a git submodule ? 
     94Solution inspired from [http://en.wikipedia.org/wiki/PHP-Nuke#Features_of PHP-Nuke] in a compound word it's a ''compositing widget framework''. 
     95 
     96- '''Hydro''' this is an application framework with all of what is needed to create an application using pages/widgets classes  
     97- '''HydroAdmin''' this is an example app of the Hydro application that use the compositing widget framework to build a backend equivalent in feature to current admin 
    9098 
    9199[https://github.com/amirouche/django-hydro Current code of the widget compositing framework at github] 
    92100 
    93  
    94 == Example code == 
    95  
    96 The following is deprecated, have a look at [https://github.com/amirouche/django-hydro/tree/master/example examples in the code repository of the project]. 
    97  
    98 ---- 
    99  
    100 Rough draft of how page class and widget classes works 
    101  
    102 Current admin index would be implemented in hydro like that: 
    103  
    104  
    105 {{{ 
    106 class AdminMainPage(OneColumnLayout): 
    107  
    108     template = 'admin/index.html' 
    109     widgets = [ 
    110         SplitPane("subheader", Menu(), Login()), 
    111         SplitPane("main", Applications(), RecentChanges()), 
    112         QuickLinks(), 
    113     ] 
    114  
    115    def __init__(self, *args, **kwargs): 
    116        super(AdminMainPage, self).__init__(*args, **kwargs) 
    117        self.apps = [] 
    118  
    119    def register(self, app): 
    120        self.apps.append(app) 
    121 }}} 
    122  
    123 A frontend can be implemented like this: 
    124  
    125  
    126 {{{ 
    127 class FrontPage(TwoColumnLayout): 
    128  
    129     path = '/' 
    130     template =  
    131     header = [Menu(), Login()] 
    132     column_one = [Menu()] 
    133     column_two = [FrontPageArticleList()] 
    134     footer = [QuickLinks(), Credits()] 
    135 }}} 
    136  
    137 The change list is similar in fashion to the above examples. 
    138  
    139 Here is an example widget class: 
    140  
    141 {{{ 
    142 class Applications(Widget): 
    143  
    144     javascript = ['frontpage.js'] 
    145     css = ['frontpage.css'] 
    146     template = 'frontpage_article_list.html' 
    147      
    148     def get_context(self, page, request): 
    149         return {'articles': Article.object.all() } 
    150 }}} 
    151  
    152 Another example: 
    153  
    154 {{{ 
    155 class FrontPageArticleList(Widget): 
    156  
    157     template = 'apps.html' 
    158      
    159     def get_context(self, page, request): 
    160         return {'apps': page.apps } 
    161 }}} 
    162  
    163  
    164101== Comments == 
    165102 
    166  
    167103- Instead of proposing a specific solution, let's focus on identifying the issues that the current admin has without the editorial content.  For example "no more monkey patching" as a pro without an actual example of functionality that can not be done without monkey patching the admin is baseless. ''–Travis Swicegood'' 
    168  
    169 - Is it OK to allow both a string and a list of strings as argument/attributes, like it's done for templates ? that way the above examples can be made simpler by dropping some brackets, it's bit more documentation but when you have to do lot of those it makes things easier I think. 
    170 - ... 
    171  
    172 I put here comments about the current code: 
    173  
    174 - Should widegts get access to outer level contexts ? -1 
    175  
    176 Don't hesitate to comment! 
     104 - I reworked the page to try to make it more obvious that it's not Hydro the next admin and main topic but that the Hydro application is just an idea with code. ''–Amirouche'' 
     105- A refresh of the  UI can be done in a separate project and land in master sooner, I think, same goes for [https://groups.google.com/forum/?fromgroups=#!topic/django-developers/aj1VEkA3FwI improving current javascript facility]. ''–Amirouche''