Grok Community Docs Documentation Release 1.2 2010-11, The Grok Community November 16, 2011 CONTENTS 1 About the grok documentation3 1.1 Introduction...............................................3 1.2 Building the docs.............................................3 2 Data Access 5 2.1 Acess content in the static directory from Python code.........................5 2.2 Indexing and Searching Objects in the ZODB..............................6 2.3 Basic ORM with megrok.rdb and SQLAlchemy............................ 11 2.4 Grok ORM with Storm.......................................... 18 2.5 How I Got Grok Talking To CAS.................................... 22 2.6 Navigating To Transient Objects Tutorial................................ 25 2.7 Create simple 1:2 relationship with Megrok.rdb and SqlAlchemy (over MySql)............ 36 2.8 Understanding default values for object database backed attributes................... 41 3 Security and Authentication 45 3.1 Authentication with Grok........................................ 45 3.2 Authentication and authorization in Grok................................ 48 4 Views, Templating, Client Side 55 4.1 Fanstatic resources............................................ 55 4.2 Using a KSS plugin for Drag-and-Drop................................. 56 4.3 Using z3x.form with Grok........................................ 59 4.4 Traversing subpaths in views....................................... 61 4.5 Adding AJAX to Grok with KSS.................................... 63 4.6 Automatic Form Generation....................................... 65 4.7 Rest support in Grok........................................... 70 4.8 What is XML-RPC ?........................................... 72 4.9 Working with Forms in Grok....................................... 74 4.10 Understanding viewlets......................................... 96 4.11 Using Viewlets for Layout........................................ 98 4.12 Plugging in new template languages................................... 102 4.13 How to internationalize your application................................ 105 4.14 Using sources in your forms....................................... 109 4.15 Use the same view in multiple models.................................. 110 4.16 Creating forms with megrok.z3cform.................................. 112 4.17 Generate URLs with the url() function in views............................. 115 5 Life Cycle of Grok Applications 117 5.1 The lifecycle of a Grok application................................... 117 i 5.2 Selecting the port and interface where Grok listens........................... 121 5.3 Install Grok on MS Windows...................................... 123 5.4 Placing your Grok project under version control............................ 124 5.5 Profiling with Grok............................................ 126 5.6 Eggs, Known Good Sets and developing with unreleased Grok source code.............. 130 5.7 How to pack your ZODB database.................................... 134 5.8 Graphical debugging of Grok with Komodo IDE............................ 135 5.9 Grok, Virtual Hosting and Nginx.................................... 136 5.10 Grok and Apache............................................. 137 5.11 Releasing software............................................ 138 5.12 Using Virtualenv for a clean Grok installation.............................. 140 5.13 Install multiple Grok apps using zc.buildout............................... 142 5.14 Use Apache HTTP server with Grok (on Debian Sid).......................... 144 5.15 Legal stuff................................................ 147 5.16 Set custom configurations on a system level that your application can use............... 150 6 Testing 153 6.1 How to test docstrings with z3c.testsetup ............................. 153 6.2 Writing tests, discovering and running them with Grok.testing..................... 155 7 Egg Collections 159 7.1 Dolmen.................................................. 159 8 Eggs in Production 169 9 Entry Level Eggs 171 9.1 gp.fileupload............................................... 171 9.2 zope.sendmail.............................................. 172 10 Snippets 175 10.1 Getting the current user/principal.................................... 175 10.2 Finding out if you are in devmode.................................... 175 10.3 Getting custom config from ZCML................................... 175 10.4 Getting the user’s language....................................... 176 11 Solving Common Tasks 177 11.1 File Uploads............................................... 177 11.2 JSON................................................... 177 11.3 Sending e-mail.............................................. 178 11.4 Using a relationfield to express relationships between objects..................... 178 11.5 Workflow................................................. 184 11.6 Exporting content as xml......................................... 184 11.7 How to automatically install and maintain your Grok application in to the ZODB........... 184 12 User Tutorials 187 12.1 Contribute to the Grok documentation.................................. 187 12.2 A Grok-Centric Explanation of Adaptation............................... 192 12.3 Macros with Grok Tutorial........................................ 197 12.4 Navigating to transient objects...................................... 200 12.5 Permissions Tutorial........................................... 211 12.6 Musical Performance Organizer - Annotated.............................. 215 13 License 269 14 Copyright 271 ii 15 Indices and tables 273 iii iv Grok Community Docs Documentation, Release 1.2 Contents: CONTENTS 1 Grok Community Docs Documentation, Release 1.2 2 CONTENTS CHAPTER ONE ABOUT THE GROK DOCUMENTATION Author Matthias (nitrogenycs) Version n/a 1.1 Introduction This documentation was created by the grok community. If there is anything missing or unclear, please don’t hesitate to _contact us: http://grok.zope.org/community ! The #grok irc channel and mailing lists are full of very helpful people. Even better, you can help us improving the docs in an easy way. Just take a quick look at the next section. 1.2 Building the docs To build the docs you need mercurial (hg). Windows Users Install mercurial if you don’t have it already, create a folder and execute these commands: hg clone http://bitbucket.org/jhsware/grok-doc bootstrap.py bin\buildout bin\sphinx-build source build Unix/Mac Users Install mercurial if you don’t have it already. Debian/Ubuntu users can do so by: $ sudo apt-get install mercurial Then, get the sources and build the docs: $ hg clone http://bitbucket.org/jhsware/grok-doc $ cd grok-doc $ python bootstrap.py $ bin/buildout $ make 3 Grok Community Docs Documentation, Release 1.2 Now you should be able to open the docs at build/index.html. The commands above pulled the sphinx source code for the documentation and built it. Now you can just go wild and modify the files in the /source subfolder to your liking. If you are not familiar with the syntax, just take a look at the sphinx docs: http://sphinx.pocoo.org/markup/index.html. Don’t be afraid to make mistakes, your changes will be reviewed anyway. To rebuild the local docs after changes run: $ make on Unix/Mac or: bin\sphinx-build source build on Windows. To commit your changes you need to make a push request on bitbucket.org or ask jhsware (in #grok channel or on the mailing list) to grant you commit access to the grok-docs repository. Thanks for helping us to improve the documentation! 4 Chapter 1. About the grok documentation CHAPTER TWO DATA ACCESS Contents: 2.1 Acess content in the static directory from Python code Author Sebastian Ware (jhsware) Version Grok <= 1.2.x An interesting addition to this tutorial is how to access these static resources through python code, for instance inside a grok View. I’ll quickly describe it here and you guys can massage it into mini-tutorial style whichever way you want. CAVEAT, al- most nothing below was tested, I mostly read the “zope.app.publisher.browser.directoryresource” and ”...fileresource” code. say you have: class MyView(grok.View): def someMethod(self): [...] inside the method above, you can access the static resources through “self.static” which is a DirectoryResource, a dictionary-like object representing the “static” folder. suppose you have an “image.png” file inside an “images” folder inside the “static” directory, you can access it like: image_resource= self.static[’images’][’image.png’] or even: image_resource= self.static[’images/image.png’] The forward slash is important as this actually represents a url traversal, not a file-system traversal. If you’re not sure the image is really there, you can do: image_resource= self.static.get(’images/image.png’, None) if you got None back the image is not there. Now that you have the image resource, what do you do with it? The main motivation for accessing the static resources is returning their URLs on the server to the browser, so you can do this by just calling the resource: 5 Grok Community Docs Documentation, Release 1.2 return image_resource() # returns the URL for the static resource. If you really need to manipulate the resource in the filesystem, you can do it like this: fspath= image_resource.context.path file= open(fspath,"rb") The same goes for snooping the static resource directory and subdiretories under it: image_dir= self.static[’images’].context.path os.listdir(image_dir) Cheers, Leo 2.2 Indexing and Searching Objects in the ZODB Author Sebastian