# Pitchly Proposals Syntax Guide ## 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. {% hint style="info" %} **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. {% endhint %} ## 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. {% hint style="info" %} 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. {% endhint %} ### Single-line text ``` {FIELD_NAME} ``` ### Number ``` {FIELD_NAME} ``` ### Yes/No If you want to show "Yes" if the value in the field is **true**: ``` {#FIELD_NAME}Yes{/FIELD_NAME} ``` If you want to show "No" if the value in the field is **false**: ``` {^FIELD_NAME}No{/FIELD_NAME} ``` {% hint style="info" %} 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". {% endhint %} ### Multi-line text ``` {FIELD_NAME} ``` {% hint style="info" %} The value will retain line breaks {% endhint %} ### Multi-line text, Rollup, Formula (Bulleted List) {#FIELD\_NAME\_BULLET} * **{TEXT}** {/FIELD\_NAME\_BULLET} Using the 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 ``` {FIELD_NAME} ``` ### Dropdown multiple ``` {#FIELD_NAME} • {.} {/FIELD_NAME} ``` {% hint style="info" %} The above renders each value in a bulleted list, but you can separate each value in a comma-separated list by using the syntax below. {% endhint %} {% hint style="info" %} {FIELD\_NAME\_STRING} Above is a simpler way to get a comma delimited list without a trailing. {% endhint %} ### Date ``` {FIELD_NAME} ``` {% hint style="info" %} Will show the date in the format `MM/DD/YYYY` {% endhint %} ### Currency ``` {FIELD_NAME} ``` {% hint style="info" %} Will include the currency symbol before the number {% endhint %} ### Image (attachment) ``` {%FIELD_NAME} ``` {% hint style="warning" %} The value in this attachment field must be an image. {% endhint %} 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. ``` {%FIELD_NAME | size:100:200} ``` 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 ``` {#FIELD_NAME} {REFERENCED_FIELD_1} {REFERENCED_FIELD_2} {REFERENCED_FIELD_3} {/FIELD_NAME} ``` 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: ![](/files/-LypHwd1-q-a8jsyniLR) 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: ``` {#CLIENT} Our client, {NAME}, works in the field of {INDUSTRY}. {/CLIENT} ``` This will display the client's name and industry. To also display information about the **Employee** who manages (or "owns") that client account: ``` {#CLIENT} Our client, {NAME}, works in the field of {INDUSTRY}. {#OWNER} For questions, contact {NAME} at {EMAIL} or via phone at {PHONE}. {/OWNER} {/CLIENT} ``` {% hint style="info" %} 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}` {% endhint %} ### Reference multiple Reference multiple fields behave identically to [References](/proposals/master.md#reference), 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: ``` {#CLIENTS} Our client, {NAME}, works in the field of {INDUSTRY}. {/CLIENTS} ``` Could display as: ``` Our client, Apple, works in the field of Technology. Our client, AT&T, works in the field of Telecommunications. Our client, Farmers Insurance, works in the field of Insurance. ``` The same applies to any nested reference multiple fields. {% hint style="warning" %} **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. {% endhint %} ### 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. ``` {#CLIENT} {%IMAGE} {/CLIENT} ``` Adjustments to the size can still be made, as detailed in the [Image (attachment)](https://docs.pitchly.com/proposals/#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: ``` {%FIELD_NAME | size:100:200} ``` ## Conditional Logic You can hide or show content depending on whether it exists by wrapping it in a conditional block. ``` {#FIELD_NAME} {INNER_FIELD} {/FIELD_NAME} ``` 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](https://docs.pitchly.com/proposals/#image-attachment) as you please. ``` {%TEMPLATE} ``` ## 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](https://pitchly.com/contact). ### uppercase Adding `| uppercase` to a text field will convert the text value to all uppercase letters. ``` {FIELD_NAME | uppercase} ``` ### 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. ``` {~~ DISPLAY_TEXT_FIELD_NAME | hyperlink: URL_FIELD_NAME } ``` 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. ``` {~~ “This text will be linked” | hyperlink: URL_FIELD_NAME } ``` 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. ``` {~~ IMAGE_FIELD_NAME | hyperlink: URL_FIELD_NAME:75:50 } ``` {% hint style="info" %} **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. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pitchly.com/proposals/master.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.