Metadata-Version: 1.1
Name: pyramid_extdirect
Version: 0.6.1
Summary: ExtDirect Implementation for Pyramid
Home-page: http://github.com/jenner/pyramid_extdirect
Author: Igor Stroh
Author-email: igor.stroh@rulim.de
License: BSD-derived (http://www.repoze.org/LICENSE.txt)
Description: pyramid_extdirect README
        ===========================
        
        Introduction:
        -------------
        
        This `pyramid`_ plugin provides a router for the `ExtDirect Sencha`_ API
        included in `ExtJS`_ .
        
        .. _`pyramid`: http://docs.pylonsproject.org/en/latest/docs/pyramid.html
        .. _`ExtDirect Sencha`: https://docs.sencha.com/extjs/6.0/backend_connectors/direct/specification.html
        .. _`ExtJS`: http://www.sencha.com/products/extjs/
        
        
        ExtDirect allows to run server-side callbacks directly through JavaScript without
        the extra AJAX boilerplate. The typical ExtDirect usage scenario goes like this::
        
            MyApp.SomeClass.fooMethod(foo, bar, function(response) {
                // do cool things with response
            });
        
        or even better, if ExtDirect is used in a GridStore::
        
            var usersStore = new Ext.data.Store({
                fields: ['id', 'name', 'title'],
                proxy: {
                    type: 'direct',
                    directFn: MyApp.Users.loadAll,
                    reader: {
                        type: 'json',
                        rootProperty: 'items'
                    }
                }
                // ...
            });
        
        Here ``MyApp`` is the application namespace, ``SomeClass`` or
        ``Grids`` are classes or *actions* and ``fooMethod`` and 
        ``loadGridData`` are methods.
        
        Usage example:
        --------------
        
        The minimum requirement for pyramid_extdirect is to create an ExtDirect API and Router::
        
            from pyramid.config import Configurator
            from exampleapp.resources import Root
        
            def main(global_config, **settings):
                """ This function returns a Pyramid WSGI application.
                """
                config = Configurator(root_factory=Root, settings=settings)
                config.add_view('exampleapp.views.my_view',
                                context='exampleapp:resources.Root',
                                renderer='exampleapp:templates/mytemplate.pt')
                config.add_static_view('static', 'exampleapp:static')
                # let pyramid_extdirect create all the needed views automatically
                config.include('pyramid_extdirect')
                # scan your code once to make sure the @extdirect_method decorators
                # are picked up
                config.scan()
                return config.make_wsgi_app()
        
        After this you can decorate arbitrary functions or class methods using @extdirect_method::
        
            @extdirect_method(action='SomeAction')
            def do_stuff(a, b, c):
                return a + b + c
        
        Or, if you'd like to group your methods into classes (actions), you can do so by decoration
        class methods:
        
        The ``UsersController`` class could combine all methods for users CRUD operations, the only
        requirement is that this class accepts ``request`` as its first and only constructor argument,
        this is needed to make sure your methods have access to ``request`` at any time::
        
            from pyramid_extdirect import extdirect_method
        
            class UsersController(object):
        
                __extdirect_settings__ = { 
                    'default_action_name': 'Users',
                    'default_permission': 'view'
                }
        
                def __init__(self, request):
                    self.request = request
        
                # we don't need to set ``action`` here, because
                # it's already defined via __extdirect_settings__
                @extdirect_method(permission='view', method_name='loadAll')
                def load_all(self, params):
                    # params is a simple dict that will contain the
                    # paging and sorting options as well as any other
                    # extra parameters (defined using proxy.extraParams
                    # your store config)
                    users = []
                    for user in users_db.fetch_all():
                        users.append({
                            id: obj.id,
                            name: obj.name,
                            title: obj.title,
                            # ...
                        })
                    return dict(success=True, items=users)
        
        As you can see, the ``Users#loadAll`` method doesn't even know it's been called through
        a HTTP request, it's just a plain old python method which returns a dict.
        The ``@extdirect_method(permission='view')`` decoration adds it to
        the ``Users`` action (also making sure only users with *view* permission are allowed
        to run it). We're returning a ``dict`` here simply because the AJAX response sent to
        the client has to be JSON serializable. By default python JSON marshallers can only
        encode/decode builtin python primitives. ``pyramid_extdirect`` has a small helper
        though, that checks if an object has a method called ``json_repr()`` (which should
        return a JSON serializable dict/list/string/number/etc.) and if found, this method is
        used to decode an instance to its JSONable version.
        You can define a ``__extdirect_settings__`` property in a class to define a default
        ``action`` and ``permission``, so in the example above we could also just use ``@extdirect_method()``.
        
        Sometimes you need to use the upload features of ExtDirect. Since uploads cannot
        be done using AJAX (through JSON-encoded request body) Ext does a little trick
        by creating a hidden iframe and posting a form within this iframe to the server.
        However, ExtDirect needs to know in advance, that your code might receive uploads.
        In ``pyramid_extdirect`` decorators this is done by adding a ``accepts_files``
        parameter to the ``@extdirect_method`` decorator::
        
            class Users(object):
                ...
                @extdirect_method(accepts_files=True)
                def upload_avatar(self, uploaded_file):
                    # uploaded_file is now a FieldStorage instance
        
        In some situations it is absolutely necessary to access the ``request`` object
        in your functions and you don't want to create an extra class (where the request would be
        passed in to the class constructor) -- this can be achieved by passing ``request_as_last_param`` to the
        decorator::
        
            from pyramid.security import authenticated_userid
        
            @extdirect_method(action='App', request_as_last_param=True):
            def get_current_user(request):
                return authenticated_userid(request)
        
        -- 
        Igor Stroh, <igor.stroh -at- rulim.de>
        
        
        pyramid_extdirect Changelog
        ==============================
        0.6.1
        ----------------
        - Switched to request.has_permission
        
        0.6.0
        ----------------
        - Added metadata support
        
        0.5.2
        ----------------
        - Added error logging and fixed the issue when 'json_encoder'
          wasn't provided in includeme(..) config (thanks Fabian Maier)
        
        0.5.1
        ----------------
        - Added optional json_encoder argument to Extdirect constructor
          to allow for providing a custom JSON serializer (e.g.
          pyramid.renderers.JSON)
        
        0.5.0
        ----------------
        - We're now python3 compliant (thanks Fabien Coronis)
        
        0.4.0
        ----------------
        - Fixed user-defined exfception views handling
        
        0.3.2
        ----------------
        - Added permissions check for extdirect_method decorated functions (vs. methods)
        - Added actions filter for extdirect api route  
        
        0.3.1
        ----------------
        Added pyramid debug toolbar support (thanks github.com/breath)
        
        0.3
        ----------------
        Renamed project to pyramid_extdirect
        
        0.2
        ----------------
        - Fixed form quotes quoting
        - Move package structure from repoze.bfg to pyramid
        
        
        0.1.2
        ----------------
        - Fixed typo in JsonReprEncoder
        
        
        0.1.1
        ----------------
        - Fixed packaging
        - Fixed numargs for methods with request_as_last_param
        
        
        0.1
        ----------------
        
        - Initial release.
        
Keywords: web wsgi javascript pyramid extdirect
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Framework :: Pylons
Classifier: License :: Repoze Public License
