Metadata-Version: 1.1
Name: django-screamshot
Version: 0.4.0
Summary: Web pages capture using Django & CasperJS
Home-page: https://github.com/makinacorpus/django-screamshot
Author: Mathieu Leplatre
Author-email: mathieu.leplatre@makina-corpus.com
License: LPGL, see LICENSE file.
Description: *django-screamshot* is a **very naive** implementation of Web pages capture
        with `CasperJS <http://casperjs.org>`_ (*aaAAaah!*, `phantomjs <http://phantomjs.org>`_:))
        
        (*See the issues pages for more details about what remains to be done.*)
        
        Checkout `screamshotter <https://github.com/makinacorpus/django-screamshot/tree/screamshotter>`_,
        the simplest Django project powered by *django-screamshot*.
        
        
        =======
        INSTALL
        =======
        
        First make sure you have the ``casperjs`` command in your ``PATH``, using
        related `installation instructions <http://casperjs.org>`_.
        
        Then install the egg :
        
        ::
        
            pip install django-screamshot
        
        
        =====
        USAGE
        =====
        
        * Add ``screamshot`` to your ``INSTALLED_APPS``
        
        
        As a screenshot Web API
        -----------------------
        
        Add it to your project URLs :
        
        ::
        
            urlpatterns = patterns('',
                ...
                url(r'^capture/$',  include('screamshot.urls', namespace='screamshot', app_name='screamshot')),
            )
        
        You can then obtain a screenshot using the following GET parameters :
        
        url
          The website URL to capture. This can be a fully qualified URL, or the
          name of a URL to be reversed in your Django project. Note: do not forget to
          encode the url.
        
        selector
          CSS3 selector. It will restrict the screenshot to the selected element.
        
        method
          HTTP method to be used (*default:* ``GET``)
        
        width
          Viewport width (*default:* ``1400``)
        
        height
          Viewport height (*default:* ``900``)
        
        data
          HTTP data to be posted (*default:* ``{}``)
        
        waitfor
          CSS3 selector. The screenshot will be performed only once this selector is
          satisfied. Typical usage: if your page contains a heavy javascript processing,
          you can add a CSS class on an element when the processing is finished to make
          sure the screenshot will get the page properly rendered.
        
        render
          If render=html, it will return an HTML page containing the image and where the
          print diaplo box will be automatically opened.
        
        size
          Resize image (width x height, e.g: ``500x500``), need install ``PIL`` or ``Pillow``.
        
        crop
          If ``true``, then resulting image is cropped to match specified size.
        
        For example : http://server/capture/?url=http://django-fr.org&selector=body&width=1024&height=768&size=500x500
        
        
        
        As a template tag
        -----------------
        
        You can include screenshots in your pages using a template tag. It will
        perform the capture and return the base64 version of the resulting image.
        
        This is very useful if you don't want to expose the capture API publicly.
        
        ::
        
            {% base64capture URL SELECTOR %}
        
        
        For example, in a SVG template :
        
        ::
        
            {% load screamshot %}
            ...
            
            <image
               y="200"
               x="300"
               id="imagemap"
               xlink:href="data:{% base64capture "company:map" "#map" %}"
               width="640" />
        
        
        If you run the capture server on a different instance, you can specify the 
        root url for reversing (*default is local*) :
        
        ::
        
            SCREAMSHOT_CONFIG = {
                'CAPTURE_ROOT_URL': 'http://127.0.0.1:8001',
            }
        
        Customizing the page rendering
        ------------------------------
        
        The CasperJS script appends the `screamshot` CSS class on the `body` element.
        You can easily customize the rendering for printing using this CSS marker in
        your CSS stylesheet:
        
        ::
        
          .screamshot #navigation {
            display: none;
          }
          .screamshot #main {
            margin: 2em;
          }
        
        Capture views with authentication
        ---------------------------------
        
        You can use Basic HTTP authentication in your Django project, create a dedicated
        user for screenshots and capture the full URL with credentials (``http://user:password@host/page/``).
        
        Alternatively, you can use a specific view decorator.
        
        Define the authorized IP to capture your pages in your settings :
        
        ::
        
            SCREAMSHOT_CONFIG = {
                'CAPTURE_ALLOWED_IPS': ('127.0.0.1',),
            }
        
        And use the provided decorator : 
        
        ::
        
            from screamshot.decorators import login_required_capturable
        
        
            @login_required_capturable
            def your_view(request):
                ...
        
        
        CasperJS command and CLI arguments
        ----------------------------------
        
        By default, we look for thr CasperJS binary in the ``PATH``
        environment variable (like ``which``), but you can bypass this:
        
        ::
        
            SCREAMSHOT_CONFIG = {
                'CASPERJS_CMD': '/home/you/Downloads/apps/capserjs',
            }
        
        
        You can also specify PhantomJS/CasperJS extra-args, such as
         ``--disk-cache=true`` with the ``CLI_ARGS`` setting :
        
        ::
        
            SCREAMSHOT_CONFIG = {
                'CLI_ARGS': ['--disk-cache=true', '--max-disk-cache-size=30000']
            }
        
        See related documentation on PhantomJS and CasperJS homepages.
        
        
        Notes about runserver
        ---------------------
        
        If you want to test it using ``manage.py runserver``, you won't be able
        to capture pages coming from the same instance.
        
        Run it twice (on two ports) and configure ``CAPTURE_ROOT_URL``.
        
        
        =======
        AUTHORS
        =======
        
            * Mathieu Leplatre <mathieu.leplatre@makina-corpus.com>
            * mozillag
            * dynamicguy
            * Eric Brehault <eric.brehault@makina-corpus.com>
        
        |makinacom|_
        
        .. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
        .. _makinacom:  http://www.makina-corpus.com
        
        =======
        LICENSE
        =======
        
            * Lesser GNU Public License
        
        
        =========
        CHANGELOG
        =========
        
        0.4.0 (2014-03-19)
        ==================
        
        * If URL not provided, use request's host (by Mozillag)
        * Allow to provide a custom PhantomJS command (by mo-mughrabi)
        * Improved logging
        * Added some minimalistic unit tests
        
        
        0.3.1 (2014-01-31)
        ==================
        
        * Fix requirement spelling
        
        
        0.3.0 (2013-09-05)
        ==================
        
        * Return appropriate HTTP responses on parameter errors (400)
        * Better processing of capture errors, not for remote JS yet. (ref #1)
        * Save temporary file step is specified output for ``casperjs_capture`` is a filepath
        * Add a *screamshotter* orphan branch, as a demo Django project
        * Ability to control image format (other than ``png`` or ``html``)
        
        
        0.2.0 (2013-08-18)
        ==================
        
        * CASPERJS_CMD setting to bypass PATH lookup
        * Query ``crop`` parameter to control resize
        * Query ``size`` parameter to control image size
        * Query ``render`` parameter to control output format
        * Remove ``remote.message`` loging
        * Query ``waitFor`` parameter to control capture timing
        * Inject *screamshot* class on *body* to allow capture styling
        * Use capture instead of captureSelector if no selector provided
        * Query parameters to control viewport size
        * Ability to add extra command-line arguments
        * Updated CasperJS CLI status code
        * Detect forwarded IP address in login decorator
        
        0.1.1 (2012-04-17)
        ==================
        
        * Include package data
        
        0.1.0 (2012-04-17)
        ==================
        
        * Initial working version
        
Platform: UNKNOWN
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 2.7
