Pitchly Proposals Syntax Guide
How to use syntax inside of the Pitchly Proposals app for Word
Introduction
Using the Pitchly Proposals app, you can insert variable data into existing Microsoft Word documents. This allows you to generate hundreds or thousands of documents easily with certain changing data between them.
All that's required to get started using the Proposals app is to upload a Word document which will serve as your template. Before you upload your template, however, you will need to include the placeholders for where you want your data to go. This guide will assume you already have a database in Pitchly set up and that you have fields you would like to reference.
After your template is uploaded, you can export documents (complete with data) by selecting a row from the database and clicking Export in the Proposals app for the document you wish to export.
Note: Each exported document in Proposals will use exactly one row of data from the database row you select prior to export. In situations where you would like to iterate on a list of information inside of a document, to generate a bulleted list for example, you can do so by using Reference Multiple fields inside your database. Syntax for that can be found below.
Placeholders
When creating a template in Word, it's important to keep in mind the data you will be including in your template. Since each document will correlate to exactly one row of data, you would want to upload the document template to the table that contains the root of all the information you need.
For example, if you're generating a proposal for a new project, you would probably want to upload your template to the Projects table. Within the template, you will reference data by the Field Name so that each placeholder will be filled with the value in the selected row for that named field.
The placeholder syntax for each field type is below.
Note: When putting field names in placeholders, the field name must always be capitalized and surrounded by curly brackets. Spaces and non-alphanumeric characters must also be replaced with an underscore (_).
Example: The field name "My Field #5" would become {MY_FIELD__5} if used in a placeholder.
Single-line text
Number
Yes/No
If you want to show "Yes" if the value in the field is true:
If you want to show "No" if the value in the field is false:
The ^ symbol acts as the inverse to #. If you want to show either Yes or No depending on whether the value is true or false, you can simply put the two lines directly next to each other on the same line. The content in the true block will be shown, while a false block will not.
Using {FIELD_NAME} by itself on a yes/no value will show either "true" or "false".
Multi-line text
The value will retain line breaks
Multi-line text (Bulleted List)
{#FIELD_NAME_BULLET}
{TEXT}
{/FIELD_NAME_BULLET}
Using the Multi-line text field, the above renders each line of data as a bulleted list. You can separate each value in Pitchly by listing out the text into new lines in the Multi-line text box. Make sure that you include “_BULLET” at the end of your field name in your syntax so your document knows to add bullets.
Dropdown
Dropdown multiple
The above renders each value in a bulleted list, but you can separate each value however you wish. A comma-separated list, for example, would consist of putting the syntax on one line with a comma after each value.
{#FIELD_NAME}{.}, {/FIELD_NAME}
Date
Will show the date in the format MM/DD/YYYY
Currency
Will include the currency symbol before the number
Image (attachment)
The value in this attachment field must be an image.
By default, an image in the attachment field will be shown at its original size, but you can change the size using the size parameter.
The first value in the size parameter indicates width in pixels, while the other indicates height in pixels. Both values are required.
When both size values are greater than 0, the size of the image will be stretched to fit those dimensions. If one of them is set to 0, the image will be scaled to fit the other given dimension but maintain the original aspect ratio.
For example, {%FIELD_NAME | size:100:0} for an image that is 200px wide and 300px high will show an image with a width of 100px and a calculated height of 150px.
Reference
References can be a little tricky to understand at first, but when used in a document template, they can be extremely powerful ways to iterate over data.
The best way to describe how to use references is with an example. Imagine you have three tables:
Imagine you are generating a proposal for a new Project. Inside of that proposal, you want to include information about the client and the account "owner" who manages that client account.
To show just the information about the Client, you can do this:
This will display the client's name and industry.
To also display information about the Employee who manages (or "owns") that client account:
If you want to quickly reference nested values in a reference without the ceremony of nesting content blocks, you can also refer to a single value like this (note that this does not work for reference multiple field types):
{CLIENT.OWNER.NAME}
Reference multiple
Reference multiple fields behave identically to References, except that the iterative block will loop over each value.
Using the example above, imagine a Project can instead have multiple Clients, and this new Clients field is a reference multiple. The following:
Could display as:
The same applies to any nested reference multiple fields.
Note: References can be nested up to 5 times. Tables with many references can increase the load time of an export exponentially, so be careful when using many references or your exports may become very slow.
Reference image
Proposal Application: To use an attachment image from a referenced field when using the Proposals Application, nest the image field inside a content block as follows.
Adjustments to the size can still be made, as detailed in the Image (attachment) section, by adding the desired width and height parameters, however, the field should still be nested in one of the above types of content blocks based on the application being used. For example:
Conditional Logic
You can hide or show content depending on whether it exists by wrapping it in a conditional block.
If the value of FIELD_NAME is either false or empty, the content inside the block will not be shown.
Inserting design assets
Placing the syntax, {%TEMPLATE}, in the Word Doc pulls in an image of the design asset in it's default template of the corresponding record. Appending size parameters to the syntax allows you to resize the image as you please.
Helpers
There are also helper functions available to help you transform values before showing them in your page.
We currently support two, the uppercase function and the hyperlink function, but we can add more upon request.
uppercase
Adding | uppercase to a text field will convert the text value to all uppercase letters.
hyperlink
Live hyperlinks can be exported to Word Documents using the Proposals App. To do so, use any of the four options listed below.
Using a URL stored in the database to hyperlink text stored in the database. This method requires two text fields. One field to store the text you wish to display in the document and one field to store the URL for the hyperlink.
Using a URL stored in the database to hyperlink text stored within the Word document. This method requires one text field to store the URL. Enclose the text you would like to hyperlink within the syntax as displayed in the below example.
Images will export at their original size by default, however, you can change the size using the size parameters to specify a width and height, as seen below with 75:50. The first value in the size parameter indicates the width in pixels, while the other indicates the height in pixels.
Please note: Hyperlink syntax will only work if the syntax is on its own line. If other syntax is in the same line, the hyperlink will not render properly.
Last updated
