Skip to content

Commit

Permalink
Updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@sanosom
sanosom committed Jul 31, 2017
1 parent 3448a42 commit f2c6f64
Showing 1 changed file with 74 additions and 88 deletions.
162 changes: 74 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,57 @@

[![Status](https://travis-ci.org/prexview/prexview-python.svg?branch=master)](https://travis-ci.org/prexview/prexview-python)

A pip library to use PrexView a fast, scalable and very friendly service for programatic HTML, PDF, PNG or JPG generation using JSON or XML data.
A Python package to use [PrexView][1], a fast, scalable and friendly service for programatic HTML, PDF, PNG or JPG generation using JSON or XML data.

*See [PrexView](https://prexview.com) for more information about the service.*
*See [PrexView][1] for more information about the service.*


## Install pip
## Installation

#### PyPI - Python Package Index

```
pip install prexview
```

## Usage
## Getting started

#### Get your API Key

You can get an API Key from [PrexView][1]

###### Set up the PXV_API_KEY as an environment variable
#### Set up your API Key

If you can setup enviroment variables

```
export PXV_API_KEY="API_KEY"
export PXV_API_KEY="YOUR_API_KEY"
```

If you can't setup the environment variable, create the PrexView object like this
If you can't setup environment variables, create the PrexView object with your API Key as argument

```python
pxv = PrexView('your_token_here')
pxv = PrexView('YOUR_API_KEY')
```

You can get an API Key by downloading PrexView Studio from [PrexView](https://prexview.com).
#### Include the library

###### Sending XML
##### PyPI installation

```python
# coding: utf-8
from prexview import Prexview
from prexview import PrexView
```

#### Sending an XML

pxv = Prexview()
options = dict(design='custom-invoice', output='pdf')
To send an XML string use ```pxv.sendXML(xml, options)``` method, this method will return a [Response object][3] on success or thrown an error.

##### Example

```python
pxv = PrexView();

options = dict(template='supported_languages', output='pdf')

xml = '''<?xml version="1.0" encoding="UTF-8"?>
<languages>
Expand All @@ -59,24 +75,24 @@ except Exception as e:
print e
```

###### Sending JSON
#### Sending a JSON

To send a JSON string or dictionary object use ```pxv.sendJSON(json, options)``` method, this method will return a [Response object][3] on success or thrown an error.

You can pass the json param as a valid json string or as a standard object
##### Example

```python
# coding: utf-8
from prexview import Prexview
pxv = PrexView();

pxv = Prexview()
options = {'design': 'custom-invoice', 'output': 'pdf'}
options = {'template': 'supported_languages', 'output': 'pdf'}

json = '''{
"languages": [
{"code": "en", "name": "English"},
{"code": "es", "name": "Español"},
{"code": "fr", "name": "Française"}
json = {
'languages': [
{'code': 'en', 'name': 'English'},
{'code': 'es', 'name': 'Español'},
{'code': 'fr', 'name': 'Française'}
]
}'''
}

file = 'test.pdf'

Expand All @@ -92,88 +108,58 @@ except Exception as e:
print e
```

## API

### sendXML(xml, options)

Send data as a XML string

### sendJSON(json, options)

Send data as a JSON string, it can also be can be a valid JSON string or a dictionary object
##### Response object

#### Options
|Property|Type|Description|
|--------|:--:|-----------|
|id|`string`|Transaction ID.|
|file|`binary`|Document created by the service.|
|responseTime|`int`|Response time from service.|
|rateLimit|`int`|Maximum number of calls to the service.|
|rateLimitReset|`int`|Seconds to reset the rate limit.|
|rateRemaining|`int`|Number of remaining call to the service.|

##### -\-format
##### Options

###### Type: `string` **Required: Yes**
|Name|Type|Required|Description|
|----|:--:|:------:|-----------|
|template|`string`|Yes|Template's name to be used to document creation, you can use [dynamic values][2].|
|output|`string`|Yes|Type of document that will be created by PrexView service, it must be **html**, **pdf**, **png** or **jpg**.|
|note|`string`|No|Custom information to be added to the document's metadata, it's limit up to 500 characters and you can use [dynamic values][2].|
|format|`string`|No|Type of data used to the document creation, it must be **xml** or **json**, this should be inferred from library methods.|
|templateBackup|`string`|No|Template's name to use to be used if the option **template** is not available in the service.|

Data to use for the document creation, must be xml or json.
##### Dynamic values

##### -\-design
In **template** or **note** options you can use JSON sintax to access data and have dynamic values, for instance having the following JSON data:

###### Type: `string` **Required: Yes**

Design's name to use.

You can use json sintax here to access data and have dynamic design names
```json
{
"Data": {
"customer": "123"
}
}
```
Design name can use any data attribute or text node
```
invoice-customer-{{Data.customer}}
```
We will translate that to the following
```
invoice-customer-123
```

And finally the service will try to find the design **invoice-customer-123** in order to transform the data and generate the document.

##### -\-output

###### Type: `string` **Required: Yes**

Document response type from the service, it can be **html**, **pdf**, **png** or **jpg**.

##### -\-design-backup

###### Type: `string`
Your **template** or **note** can use any data attribute or text node, for instance:

Design's name to use to be used if the option **design** is not available in the service.

##### -\-note

###### Type: `string`

Custom note that can be used to add any information, it's limit up to 500 chars. This is useful if you want to add metadata such as document, transaction or customer ID.

You can use json syntax to access data and get dynamic notes.

```json
{
"Data": {
"customer": "123"
}
}
```
Notes can use any data attribute or text
'invoice-customer-{{Data.customer}}'
```
Document: Invoice
Customer: {{Data.customer}}
```
We will translate that to the following

Then we will translate that to the following:

```
Document: Invoice
Customer: 123
'invoice-customer-123'
```

And finally the service will try to find the **template** or **note** ```invoice-customer-123``` in order to transform the data and generate the document.

## License

MIT © [PrexView](https://prexview.com)
MIT © [PrexView][1]

[1]: https://prexview.com
[2]: #dynamic-values
[3]: #response-object

0 comments on commit f2c6f64

Please sign in to comment.