django-screamshot 0.8.0

Web pages capture using Django & CasperJS

===================
django-screamshot
===================

.. image:: https://secure.travis-ci.org/makinacorpus/django-screamshot.svg?branch=master
:alt: Build Status
:target: http://travis-ci.org/makinacorpus/django-screamshot

.. image:: https://img.shields.io/pypi/v/django-screamshot.svg
:alt: Latest PyPI version
:target: https://pypi.python.org/pypi/django-screamshot/

.. image:: https://img.shields.io/pypi/dw/django-screamshot.svg
:alt: Number of PyPI downloads
:target: https://pypi.python.org/pypi/django-screamshot/

.. image:: https://img.shields.io/github/downloads/makinacorpus/django-screamshot/total.svg
:alt: Number of Git Hub downloads
:target: https://github.com/makinacorpus/django-screamshot/archive/master.zip

.. image:: https://img.shields.io/pypi/format/django-screamshot.svg
:alt: Format
:target: https://pypi.python.org/pypi/django-screamshot/

.. image:: https://img.shields.io/pypi/l/django-screamshot.svg
:alt: License
:target: https://raw.githubusercontent.com/makinacorpus/django-screamshot/master/LICENSE


*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 either the ``casperjs`` or ``phantomjs`` command in your ``PATH``, using
related installation instructions:
* `CasperJS <http://casperjs.org>`_.
* `PhantomJS <http://phantomjs.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',
}


As a library - render local Django template
-------------------------------------------
Sometimes, you don't have access to the request object. A typical example would be creating a PDF receipt for a customer and emailing it. Both of these tasks can take a while, so it is natural to push them into some queue (like RabbitMQ). But if your pdf-rendering task get's executed, you don't have access to the request object. Don't worry - you can still use screamshot as a library. Here's how.

::

from screamshot.utils import render_template

# you can either render the template to a TemporaryFile:

with render_template('my-template.html', {'context': 'variables'}) as output:
# do anything you want with the output
# like attach it to email message, etc.
print(output.name)

# or you can specify a path instead:
render_template('my-template.html',
{'context': 'variables'},
output='/home/you/rendering.png',
format='png')


Please note, that in order to load your static files, screamshot will try to replace all STATIC_URL occurence with a local path to your static files (only if they are not hosted via https of course)

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):
...


Renderer command and CLI arguments
----------------------------------
You can specify which renderer you would like to use, by setting the
``CAPTURE_METHOD`` setting. The default value is 'casperjs'. Possible values
are 'casperjs' and 'phantomjs'.

::

SCREAMSHOT_CONFIG = {
'CAPTURE_METHOD': 'phantomjs',
}


By default, we look for thr CasperJS/PhantomJS binary in the ``PATH``
environment variable (like ``which``), but you can bypass this:

::

SCREAMSHOT_CONFIG = {
'CASPERJS_CMD': '/home/you/Downloads/apps/casperjs',
'PHANTOMJS_CMD': '/home/you/Downloads/apps/phantomjs'
}


Please note, that the ``CAPTURE_METHOD`` setting specifies which location would
be evaluated, i.e. if you set ``CAPTURE_METHOD`` to 'phantomjs', ``PHANTOMJS_CMD``
would be evaluated.

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.


You can also override the capture script. A default implementation uses capture
script written for CasperJS. A default capture script for PhantomJS is also provided.

If you have your own script which you would like to use, specify it in
``CAPTURE_SCRIPT`` option.

::

SCREAMSHOT_CONFIG = {
'CAPTURE_SCRIPT': '/home/you/scripts/capture.js',
}


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 <[e-mail]>
* mozillag
* dynamicguy
* Eric Brehault <[e-mail]>

|makinacom|_

.. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
.. _makinacom: http://www.makina-corpus.com

=======
LICENSE
=======

* Lesser GNU Public License


=========
CHANGELOG
=========

0.8.0 (2017-05-05)
==================

* Fix python 3 support
* Add support for Django 1.11
* Drop support for Django <1.8


0.7.0 (2017-10-08)
==================

* Support for rendering PDF
* Python 3 support
* Django 1.8 support
* Add TEST_CAPTURE_SCRIPT setting


0.6.0 (2014-11-27)
==================

* Added support of pure PhantomJS capture, i.e. without CasperJS, without selector (by Mateusz Mikolajczyk)
* Support for capturing locally rendered templates, without external request (by Mateusz Mikolajczyk)


0.5.0 (2014-11-11)
==================

* Added screenshot model and adminsite support (by Luc Milland)
* Allows to wait for a given time (milliseconds) before doing the screenshot (by Florent Lebreton)
* Replace mimetype by content_type in HttpResponse for django1.7 compliance (by Florent Lebreton)


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