Pinax Long Tutorial Slides


Published on

The slides printed for attendees of the Pycon 2010 Long Pinax Tutorial. James Tauber was the co-author and deserves tons of credit for his work. So does Brian Rosner and the rest of the Pinax team.

Published in: Technology
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Mention:      LEGO      scaffolding
  • Mention virtualenvwrapper by Doug Hellman.
  • pip is an important part of Pinax for installing Python packages. We contribute back everything we do with it.
  • At some point we probably want to review the account-relevant settings
  • Point out that pinax groups are a base on which you write your own group app and plug in whatever content apps you need.
  • There's more to static files than this. Mention the three levels of project, pinax theme and app Point out the analogies with template resolution Pluggable storage backend ( allows to "build" static files to non filesystem storages, e.g. S3
  • A proposal was accepted to fix how we handle project-level requirements. we will be working on it during PyCon
  • MAILER_PAUSE_SEND is a boolean value that is checked whether or not the management command should even be ran (from the cron)
  • JT: [REPEAT] I would say that groups are "containers with user membership and content" (i.e. can't skip the user membership aspect of it). JT: [REPEAT] we should point out that pinax groups are a base on which you write your own group app and plug in whatever content apps you need. JT: the key thing is that a content app that is group aware doesn't need to know about the specifics of the site developer's group app
  • JT: we need to explain with examples of and and I think how this all works DG: I'll get a set of simple working examples out before presentation that people can thumb through. Or maybe add to sample_group_project.
  • JL: maby other storage backends could be shown here, e.g. S3 or cloudfiles also see resolve_static management command
  • Technically you can just say $(function() {...});
  • BR: port number is set to 8001 for a common situation where Apache is proxied by a front-end webserver (recommended)
  • Pinax Long Tutorial Slides

    1. 1. Pinax Long Tutorial PyCon 2010
    2. 2. Introduction ~10 minutes
    3. 3. Who are we? - James Tauber Pinax Founder CEO of Eldarion
    4. 4. Who are we? - Daniel Greenfeld Pinax Core Developer Software Engineer for NASA's Science Mission Directorate Author/Instructor for Holden Web, LLC ( Developer for Eldarion
    5. 5. Tutorial Prerequisites <ul><ul><li>Basic understanding of Python </li></ul></ul><ul><ul><li>Basic understanding of Django </li></ul></ul><ul><ul><li>Laptop </li></ul></ul><ul><ul><li>Python 2.5.x or 2.6.x </li></ul></ul>
    6. 6. History of Pinax 2008: James Tauber decides to stop repeating himself 0.5 — First official release 2009: First full year of Pinax 0.7 — Groups, Static Media, Move to pip and virtualenv, Section 508 2010: Today 0.9 — Next great thing
    7. 7. Philosophy of Pinax By integrating numerous reusable Django apps to take care of the things that many sites have in common, it lets you focus on what makes your site different. In other words... D on't R epeat Y ourself
    8. 8. What will we be doing? Installing Pinax Reviewing the core underlying layer Changing the look and feel Various Pinax tricks Building on what Python and Django gives us Deployment Community
    9. 9. Pinax Installation ~10 minutes
    10. 10. Where to get Pinax <ul><ul><li> </li></ul></ul><ul><ul><li>USB key with bundle </li></ul></ul>
    11. 11. virtualenv <ul><ul><li>Ian Bicking </li></ul></ul><ul><ul><li>Isolates all Pinax components from your global environment </li></ul></ul><ul><ul><li>virtual environments is used for dependency control </li></ul></ul><ul><ul><li>You can use multiple virtualenv/pinax-env </li></ul></ul><ul><ul><li> </li></ul></ul>
    12. 12. pip <ul><ul><li>Ian Bicking </li></ul></ul><ul><ul><li>pip is a replacement for easy_install </li></ul></ul><ul><ul><li>All packages are downloaded before installation. Partially-completed installation doesn't occur as a result. </li></ul></ul><ul><ul><li>Supports requirement files for consistently creating environments of many packages. </li></ul></ul><ul><ul><li> </li></ul></ul>
    13. 13. Core Underlying Components ~10 minutes
    14. 14. Core: Accounts Avatar Email Addresses Language OpenID Password Management Signup Timezone
    15. 15. Sign Up Options <ul><li>Closed Sign Up </li></ul><ul><li>Private Beta </li></ul><ul><li>Optional email confirmation </li></ul>
    16. 16. Core: Groups Groups in Pinax are containers with user membership and content. They are a base on which to write your own app and plug in whatever content apps you need. Examples: Tribes (Wiki, Photos) Projects (Tasks, Wiki) Guilds (Events)
    17. 17. Core: Static Media Handling css, images, javascript Project vs Pinax Theme vs App level Separation of static media from user-contributed media. build_static management command for deployment
    18. 18. Pinax Projects ~10 minutes
    19. 19. Overview of the starter projects <ul><li>boilerplate code </li></ul><ul><li>scaffolding to get started more quickly </li></ul><ul><li>already integrated apps </li></ul><ul><li>Examples: </li></ul><ul><ul><li>basic_project </li></ul></ul><ul><ul><li>social_project </li></ul></ul><ul><ul><li>code_project </li></ul></ul><ul><ul><li>company_project (NEW) </li></ul></ul>
    20. 20. Using pinax-admin List all the currently available projects in Pinax pinax-admin clone_project -l Cloning a project pinax-admin clone_project social_project djangofans
    21. 21. What is in a Pinax project? <ul><ul><li>apps directory </li></ul></ul><ul><ul><li>media directory </li></ul></ul><ul><ul><li>slightly extended </li></ul></ul><ul><ul><li>requirements.txt with project dependencies required to run </li></ul></ul><ul><ul><li>deploy directory for modpython, fastcgi, and wsgi. </li></ul></ul><ul><ul><li>templates directory with the blocking done </li></ul></ul><ul><ul><li>tests directory to help push you to test. </li></ul></ul>
    22. 22. Pinax specific ~5 minutes
    23. 23. Some Pinax Settings SITE_NAME (used in some default templates) CONTACT_EMAIL (used in some default templates) PINAX_THEME (prefix for template resolution) ACCOUNT_OPEN_SIGNUP (can anyone join?) ACCOUNT_REQUIRED_EMAIL (is email address required?) ACCOUNT_EMAIL_VERIFICATION (must email be verified?) EMAIL_CONFIRMATION_DAYS (how long before expiry?) LOGIN_REDIRECT_URLNAME (first page to go after login)
    24. 24. Media/Static Files Settings MEDIA_URL / MEDIA_ROOT    (URL and filesystem location for files uploaded/stored by Django only) STATIC_URL / STATIC_ROOT    (URL and filesystem location for site assets such as CSS, JS and images) SERVE_MEDIA      (Used in to hook-up MEDIA_URL and STATIC_URL used for development)
    25. 25. <ul><li>Good place for environmental settings such as: </li></ul><ul><li>     Databases </li></ul><ul><li>     </li></ul><ul><li>     Debug </li></ul><ul><li>     Media locations </li></ul>
    26. 26. Modification of core  Pinax applications ~10 minutes
    27. 27. Profiles Frequently extended application You always want a custom field
    28. 28. Modification of core Pinax applications Before you change a core application: Can you accomplish your tasks with CSS? Can you accomplish your tasks with Javascript? Can you accomplish your tasks with template changes? Can you create a new application that does the work?
    29. 29. But my task needs a code/database change! pinax-env/lib/python2.x/site-packages/Pinax/pinax/apps/<app> pinax-env/src/Pinax/pinax/apps/<app> Don't make changes in Pinax itself!
    30. 30. But my task needs a code/database change! Option 1: Use the apps directory of your project cd apps/ startapp profiles Option 2: Use virtualenv/pip Create a stand alone app (best done eggified) pip install -e my-app
    31. 31. Adding Django applications ~10 minutes
    32. 32. Won't conversion be hard? Remember: Pinax is just Django with an opinion pip install <django-app> (Don't forget to add it to your requirements.txt file) make changes to INSTALLED_APPS, etc in make template changes
    33. 33. Modification of templates ~10 minutes
    34. 34. Customize templates, don't change them cp -r site-packages/pinax/templates/default/profiles my-project/templates Don't edit the Pinax templates directory!
    35. 35. Themes in Pinax Change your look and feel by just changing!  PINAX_THEME = &quot;default&quot; But only one theme is currently shipped with Pinax PINAX_THEME = &quot;default&quot;
    36. 36. Changing the logo Step 1: Add your image to <my-project>/media Step 2: In <my-project>/templates/site_base.html in the logo_link_image block change the name of the logo image to match your own. (but really you should be making more style changes than just the logo)
    37. 37. Handy Pinax template blocks <ul><ul><li>head_title </li></ul></ul><ul><ul><li>extra_head </li></ul></ul><ul><ul><li>extra_body </li></ul></ul><ul><li>Loads after main body. Good for custom Javascript </li></ul><ul><li>     </li></ul><ul><ul><li>footer </li></ul></ul>
    38. 38. Changing the look and feel ~10 minutes
    39. 39. base.html versus site_base.html <ul><li>If you are writing a theme to be used across multiple sites, you  </li></ul><ul><li>should modify base.html, not site_base.html. </li></ul><ul><li>If you want to keep a particular theme but modify content for a  </li></ul><ul><li>specific site, you should modify site_base.html. </li></ul>
    40. 40. Adding and removing tabs <ul><ul><li>In site_base.html add a new li in the right_tabs block. Make sure that li has and id specific to that to that tab, e.g. tab_myapp </li></ul></ul><ul><ul><li>Create a myapps/base.html template that all pages under that tab will extend. Make sure it defines a block body_class with contentmyapp </li></ul></ul><ul><ul><li>edit the CSS file (site_tabs.css if it exists) and at the appropriate points add the selectors: </li></ul></ul><ul><ul><ul><li>body.myapp #tab_myapp </li></ul></ul></ul><ul><ul><ul><li>body.myapp #tab_myapp a </li></ul></ul></ul><ul><li>see for more information </li></ul>
    41. 41. Adding CSS In templates/site_base.html {% block extra_head_base %}:      <link rel=&quot;stylesheet&quot; href=&quot;{{ MEDIA_URL }}custom.css&quot; /> mkdir site_media mkdir site_media/media touch custom.css body {      background-color: #000; }
    42. 42. Changing Avatar defaults ~10 minutes
    43. 43. django-avatar by default uses Gravatar Pros: Gravatars follow a user's account name across the Internet Means users get a default avatar anywhere Cons: You might not want the default Gravatar avatar image You might not want to lock user avatars into a single service
    44. 44. Changing the default Gravatar logo In AVATAR_DEFAULT_URL =  STATIC_URL + &quot;<our_custom_avatar.jpg>&quot; AVATAR_GRAVATAR_BACKUP = False
    45. 45. django-groups ~10 minutes
    46. 46. What are groups? Groups in are containers with user  membership and content. Example: A project with tasks and wiki A guild with a forum and events
    47. 47. What does django-groups give you? <ul><ul><li>Base model on which to build your group app </li></ul></ul><ul><ul><li>A way to do all your URL routing so you get to the right content objects for the group. </li></ul></ul><ul><ul><li>Nested group support (group apps can be content object apps at the same time) </li></ul></ul>
    48. 48. Creating a group app <ul><ul><li>Adding content objects is simple: </li></ul></ul><ul><li>     from groups.bridge import ContentBridge </li></ul><ul><li>     bridge = ContentBridge(Project) </li></ul><ul><li>     urlpatterns = patterns(&quot;&quot;, ...) # URLs for the group views </li></ul><ul><li>     urlpatterns += bridge.include_urls(&quot;topics.urls&quot;, r&quot;^project/(?P<project_slug>[-w]+)/topics/&quot;) </li></ul><ul><ul><li>Group model interface is simple: </li></ul></ul><ul><ul><ul><li>member_queryset (needed if member m2m is named other than members) </li></ul></ul></ul><ul><ul><ul><li>user_is_member </li></ul></ul></ul><ul><ul><ul><li>get_url_kwargs </li></ul></ul></ul>
    49. 49. Creating content object apps <ul><ul><li>Most bits must be aware of group association. Views, forms, model and template context. </li></ul></ul><ul><ul><li>By 0.9 most all major apps will support group protocol for content apps. </li></ul></ul><ul><ul><li>Apps don't need to depend on django-groups </li></ul></ul><ul><ul><li>Protocol bits of note </li></ul></ul><ul><ul><ul><li>ContentBridge </li></ul></ul></ul><ul><ul><ul><ul><li>get_group </li></ul></ul></ul></ul><ul><ul><ul><ul><li>reverse </li></ul></ul></ul></ul><ul><ul><ul><li>Group model instance </li></ul></ul></ul><ul><ul><ul><ul><li>content_objects(Model, [ join=[...] ]) </li></ul></ul></ul></ul><ul><ul><ul><li>Template context </li></ul></ul></ul><ul><ul><ul><ul><li>{% extends group_base|default:&quot;site_base.html&quot; %} </li></ul></ul></ul></ul>
    50. 50. Looking at django-groups pinax-admin clone_project sample_group_project sgp cd sgp python syncdb python runserver
    51. 51. django-uni-form ~10 minutes
    52. 52. What is Section 508? <ul><ul><li>Rules for making technology theoretically accessible by individuals with disability. </li></ul></ul><ul><ul><li>Easy to implement if you know how. </li></ul></ul><ul><ul><li>Unfortunately doesn't actually force software to be accessible to the disabled. </li></ul></ul><ul><ul><li>Enforceable across all government agencies or organizations accepting money from government agencies. </li></ul></ul>
    53. 53. Why do we care? <ul><ul><li>US Government work requires it. </li></ul></ul><ul><ul><li>Disability software is said to be a $170 billion a year industry. </li></ul></ul><ul><ul><li>Open source tends to support accessibility/usability well. </li></ul></ul><ul><ul><li>Its the right thing to do! </li></ul></ul>
    54. 54. Django forms rock!
    55. 55. Tables are for tabular data
    56. 56. In Section 508, some tabular forms are allowed
    57. 57. Out of the box pretty Django forms are tabular
    58. 58. Django Uni-Form = Django forms docs + template tag + Uni-Form css/js forms library
    59. 59. Basic Usage
    60. 61. Advanced Django Uni-Form ~10 minutes
    61. 62. Making form generation easier {% load uni_form_tags %} {% with form.helper as helper %} {% uni_form form helper %} {% endwith %}
    62. 63. Adding action handlers {% load uni_form_tags %} {% with form.helper as helper %} {% uni_form form helper %} {% endwith %}
    63. 64. Media Handling ~10 minutes
    64. 65. Static Files <ul><li>css, images, javascript </li></ul><ul><li>Separation of static media from user-contributed media. </li></ul><ul><li>build_static management command for deployment </li></ul><ul><li>STATIC_URL context variable </li></ul><ul><li>SERVE_MEDIA for development </li></ul>
    65. 66. Static media is good Caching Security Separating servers
    66. 67. build_static tool python help build_static Copy static media files from apps and other locations in a single location. --dry-run (don't copy but show what will be done) --link (create symlinks rather than copy) Project vs Pinax Theme vs App level
    67. 68. STATIC_URL <ul><li>TEMPLATE_CONTEXT_PROCESSORS = [ </li></ul><ul><li>     &quot;staticfiles.context_processors.static_url&quot;, </li></ul><ul><li>] </li></ul><ul><li>(be sure to use RequestContext) </li></ul><ul><li><link href=&quot;{{ STATIC_URL }}css/polls.css&quot; rel=&quot;stylesheet&quot; type=&quot;text/css&quot; /> </li></ul>
    68. 69. STATICFILES_DIRS <ul><ul><li>Defines resolution order for static media handling </li></ul></ul><ul><li>     STATICFILES_DIRS = [ </li></ul><ul><li>         os.path.join(PROJECT_ROOT, &quot;media&quot;), </li></ul><ul><li>         os.path.join(PINAX_ROOT, &quot;media&quot;, PINAX_THEME), </li></ul><ul><li>     ] </li></ul>
    69. 70. Serving Static Files During Development <ul><li>from django.conf import settings </li></ul><ul><li>if settings.SERVE_MEDIA:     </li></ul><ul><li>  </li></ul><ul><li>urlpatterns += patterns(&quot;&quot;,          </li></ul><ul><li>     (r&quot;&quot;, include(&quot;staticfiles.urls&quot;)),      </li></ul><ul><li>) </li></ul>
    70. 71. JavaScript, jQuery and Pinax ~5 minutes
    71. 72. Why was jQuery chosen for Pinax? Because Pinax has an opinion But you can still use YUI, Mootools, or plain old JavaScript
    72. 73. Best practice for JavaScript use
    73. 74. django-ajax-validation ~5 minutes
    74. 75. django-ajax-validation In      from my_app.forms import MyAppForm      (r&quot;^validate/$&quot;, &quot;ajax_validation.views.validate&quot;, {          &quot;form_class&quot;: MyAppForm,          &quot;callback&quot;: lambda request, *args, **kwargs:                   {&quot;user&quot;: request.user}      }, &quot;myapp_form_validate&quot;),
    75. 76. django-ajax-validation <ul><li>in templates/my-app/edit.html: </li></ul><ul><li>{% block extra_body %} </li></ul><ul><li>     {% load jquery_validation %} </li></ul><ul><li>     {% include_validation %} </li></ul><ul><li>     <script type=&quot;text/javascript&quot;> </li></ul><ul><li>         $(function(){ </li></ul><ul><li>             $('#myapp_form').validate('{% url  myapp_form_validate %}', {type: 'uni_form'}); </li></ul><ul><li>         }); </li></ul><ul><li>     </script> </li></ul><ul><li>{% endblock %} </li></ul>
    76. 77. django-pagination ~2 minutes
    77. 78. django-pagination <ul><li>{% load pagination_tags %} </li></ul><ul><li>... </li></ul><ul><li>{% autopaginate results 10 %} </li></ul><ul><li>... </li></ul><ul><li>         </li></ul><ul><li>{% paginate %} </li></ul><ul><li>style with CSS: </li></ul><ul><li>.pagination, .page, .page.selected, .page-prev, .page-next </li></ul>
    78. 79. Testing your Pinax application ~5 minutes
    79. 80. Why should you bother testing? &quot;Untested code is broken code&quot; Martin Aspelli &quot;Code without tests is broken as designed&quot; Jacob Kaplan-Moss &quot;All the cool kids are doing tests&quot; Chris Shenton &quot;If I go to another testing talk I'm going to die&quot; Daniel Greenfeld
    80. 81. Pinax Deployment ~10 minutes
    81. 82. What Pinax gives you <ul><ul><li>Each project has a deploy/ directory </li></ul></ul><ul><ul><li>deploy/ contains working mod_wsgi, FastCGI and mod_python deployment files. </li></ul></ul><ul><ul><li>Much of Pinax has been designed to be a simple deployment with the way we've constructed settings. </li></ul></ul>
    82. 83. Example Apache config <ul><li><VirtualHost *:8001> </li></ul><ul><li>     ServerName </li></ul><ul><li>     </li></ul><ul><li>     WSGIDaemonProcess user=eldarion group=eldarion processes=1 threads=25 python-path=/home/eldarion/virtualenvs/eldarion_project/lib/python2.5/site-packages </li></ul><ul><li>     WSGIProcessGroup </li></ul><ul><li>     </li></ul><ul><li>     WSGIScriptAlias / /home/eldarion/webapps/ </li></ul><ul><li>     <Directory /home/eldarion/webapps/> </li></ul><ul><li>         Order deny,allow </li></ul><ul><li>         Allow from all </li></ul><ul><li>     </Directory> </li></ul><ul><li>     </li></ul><ul><li>     ErrorLog /var/log/apache2/ </li></ul><ul><li>     LogLevel warn </li></ul><ul><li>     CustomLog /var/log/apache2/ combined </li></ul><ul><li>     </li></ul><ul><li></VirtualHost> </li></ul>
    83. 84. Things to remember when deploying <ul><ul><li>Setup cron jobs for clearing mail queue and notification queue </li></ul></ul><ul><ul><li>Recommended to create a maintenance.wsgi script that you can simply cp over pinax.wsgi to take the site down for deployment (don't forget to actually do this) </li></ul></ul><ul><ul><li>Always remember to run build_static before claiming your deployment is complete </li></ul></ul>
    84. 85. Community ~10 minutes
    85. 86. How to communicate <ul><li>1. Don't be ' that guy '. </li></ul><ul><li>2. Be friendly. </li></ul><ul><li>3. Be patient. </li></ul><ul><li>4. Tell us your operating system and version of Python. </li></ul><ul><li>5. Use a pasting service for code or shell statements: </li></ul><ul><li> </li></ul><ul><li> </li></ul>
    86. 87. Finding Help <ul><li>Documentation: </li></ul><ul><li> </li></ul><ul><li> </li></ul><ul><li>IRC: </li></ul><ul><li>     #pinax </li></ul><ul><li>Mailing List: </li></ul><ul><li> </li></ul>
    87. 88. Contributing back <ul><li> </li></ul><ul><li>     Task tracker and wiki for the Pinax project </li></ul><ul><li>     Search the tickets before creating a new ticket </li></ul><ul><li> </li></ul><ul><li>     Fork and submit pull requests </li></ul><ul><li>     Tests and documentation are required </li></ul><ul><li>     Documentation must be in restructured text </li></ul>
    88. 89. Contributing back - Modular Efforts <ul><li>For stand-alone Django or Python efforts: </li></ul><ul><li>     Documentation and tests are required </li></ul><ul><li>     Make your work modular and easy to use </li></ul><ul><li>     Put your finished work on PyPI </li></ul>
    89. 90. Q & A