Using the Smashdocs API from Python
-----------------------------------

In order to use Smashdocs from Python you need to obtain the following data from
your Smashdocs provider:

- Partner URL (URL of Smashdocs service)
- Client ID (used for authentication)
- Client Key (used for authentication) 

Creating client handle to Smashdocs
+++++++++++++++++++++++++++++++++++

.. code::

    from zopyx.smashdocs.api import Smashdocs

    # first you need to instantiate a client instance of the `Smashdocs`
    # connector class. The `group_id` is used to group all documents together
    # belong to a particular user group (e.g. a work group working on one or more 
    # document). The `client` is from now on used for all interactions with Smashdocs.

    client = Smashdocs(partner_url, client_id, client_key, group_id)

Upload a DOCX document to Smashdocs
+++++++++++++++++++++++++++++++++++

The following code will upload a given DOCX file from the local filesystem
into Smashdocs and create a document instance inside Smashdocs. The API
call returns all relevant data including the document id of the document inside
Smashdocs and an URL that can be used open the uploaded document inside your browser
for editing.

The `filename` parameter is the path to a locally stored DOCX file. `title`
and `description` are arbitrary unicode strings (metadata length restrictions
apply and are partly checked within the module). 

The `role` parameter is one of the four roles in Smashdocs: 

- `reader`
- `commentator`
- `editor`
- `approver`    

You also need a `user_data` datastructure containing information about the current
user using the Smashdocs API. The fields of the dict structure are obvious. Please
keep in might that Smashdocs does not provide you with an explicit user management.
The `userId` field represents the user within Plone.

.. code::

    user_data = dict(
        email=u'test@foo.com',
        firstname=u'Henry',
        lastname=u'Miller',
        userId=u'testuser',
        company=u'Dummies Ltd')


    result = client.upload_document(
        filename='sample.docx',
        title=u'My document',
        description=u'My description',
        role='editor',
        user_data=user_data)
    
    # preserve the id of the document in Smashdocs for further usage
    document_id = result['documentId']

    # this URL can be used to access the uploaded document through the browser
    document_url = result['documentAccessLink']


Creating a new empty document
+++++++++++++++++++++++++++++

Creating a new empty document works exactly the same way as uploading
a DOCX file except that you do not need any document here.


.. code::    
        
    result = client.new_document(
        title=u'My document',
        description=u'My description',
        role='editor',
        user_data=user_data)
    
    # preserve the id of the document in Smashdocs for further usage
    document_id = result['documentId']

    # this URL can be used to access the uploaded document through the browser
    document_url = result['documentAccessLink']

Open an existing Smashdocs document by its ID
+++++++++++++++++++++++++++++++++++++++++++++

With a given `document_id` you can open (obtain its access URL) using the following code.
In this case we open the document for read-only access (role=reader) with a different
user context.

.. code::

    user_datai2 = dict(
        email=u'mike@foo.com',
        firstname=u'Mike',
        lastname=u'Reader',
        userId=u'mike-reader',
        company=u'Dummies Ltd')

    result = client.open_document(document_id, 'reader', user_data2)

    # this URL can be used to access the uploaded document through the browser
    document_url = result['documentAccessLink']