Skip to main content

Web pages capture using Django & CasperJS

Project 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.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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-screamshot-0.3.1.zip (22.2 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page