CookBook

Last Updated:11/2011

ME

SYSTEMS

LLC

COOKBOOK: SOLUTIONS, CODE SAMPLES

AND BEST PRACTICES

S-Docs CookBook

WELCOME

If you‟ve been waiting for a native document generator for Salesforce.com, we have good news:

Your wait is over - S-Docs is here!

You‟re already using Salesforce.com, so you understand the benefits of cloud computing. S-

Docs extends your investment by leveraging the Salesforce.com platform and pushing benefits

even further. There are countless things you can do with S-Docs to improve your business –

we provide a few here along with some best practices.

What you won‟t find are instructions on how to install connectors or plug-ins; S-Docs doesn‟t

use any. You also won‟t find any information related to network configurations or setting

trusted server IPs; S-Docs runs entirely within your existing Salesforce platform.

Once you‟ve started working with S-Docs, we think you‟ll agree that S-Docs is quite novel and

incredibly flexible. You will often find multiple solutions and discover clever ways to meet

requirements (usually by leveraging existing Salesforce.com features).

We‟re excited about this product and welcome your questions, suggestions and feedback.

-TJ

[email protected]

INTENDED AUDIENCE

This guide provides solutions and ideas to help organizations get the most from S-Docs. It is

intended for users already familiar with Salesforce administration and configuration

techniques. Knowledge of HTML is also useful in creating the highest quality documents. We

encourage you to visit our website: http://www.mesystemsllc.com for template samples and

help.

mailto:[email protected]

http://www.mesystemsllc.com/

S-Docs CookBook

TABLE OF CONTENTS

GENERAL SOLUTIONS

1. Conditionally show a field value on a document

2. Use S-Docs with your custom object

3. Link one document to many objects

4. Saving S-Docs as attachments

5. Append Terms and Conditions to your contract

6. Use your own stylesheet or CSS

7. Change page size and orientation (landscape, A4, legal, mailing label)

8. Add line items (related lists) to your documents

9. Filtering, sorting and grouping your related list

10. Using S-Docs Direct SOQL feature for related list

11. Access other fields not visible from the Insert Field button

12. Include billing and shipping contacts on a quote

BEST PRACTICES

13. Updating templates without affecting previously created documents

14. Using S-Docs with Salesforce Chatter

15. Choosing between PDF, HTML, MS Word or Excel formats

USING IMAGES

16. Embedding static images into your document

17. Adding a dynamic signature image into a contract

18. Embedding Google Charts into your document

19. Displaying checkboxes

ADDITIONAL FORMULAS

20. Formatting Dates

21. Formatting Currencies

S-Docs CookBook

1. Conditionally show a field value on a document

Solution. This is a common request. Perhaps you have a sales quote where you would

like to waive charges for a particular product. To accomplish this you should simply

create a formula field on the Salesforce object that does all the work for you. You then

drop that formula field into your S-Docs template.

For example, you could create the following formula field on your base object:

You would then just insert this new formula field into you S-Docs Template using the

template editor‟s “Insert Field” button.

Alternatively, if your output format is MS Excel, you have the option of using an Excel

Formula. Using Excel formulas within your S-Doc template is described in more detail

in Solution #13 of this documentation.

Discussion. Salesforce‟s formula fields provide a simple, powerful and familiar way

to access and display conditional data within S-Docs without adding any complexity or

having to learn any specialized syntax. You will find several solutions throughout this

document that leverage this feature.

2. Use S-Docs with your custom object

Solution. Yes, S-Docs works great with your custom objects, but there are a few

configuration steps you will need to take.

First, you will need to add a picklist value to “Related to Type” field in the SDOC

Templates object. Be sure to use your object‟s API name (e.g. myObject__c) as the

new picklist value. This step is a critical step, as it allows S-Docs templates to be

associated to your custom object.

Second, you need to create an S-Docs button and place it on your custom object‟s detail

page. We‟ve found that a “Detail Page Button” displayed in the “existing window with

sidebar” works great.

You should create a button link using a URL similar to the following:

IF( Tier__c=’Gold’, 'No Charge', Fee__c)

/apex/SDOC__SDCreate1?id={!myObject__c.Id}&Object=myObject__c

S-Docs CookBook

Lastly, this step allows generated S-Docs to be associated to your custom object and

further allows you to place an S-Docs related list on your custom object‟s detail page

layout. You simply need to add a look-up field to the SDOC Relationship object that

points to your custom object. Note: The “Field Name” of this new lookup field must

match the name of your object (e.g. myObject) without the “__c”.

Detailed step-by-step instructions on how to configure S-Docs with your custom object

is available on our website at:

http://www.mesystemsllc.com/resource/1319927036000/CustomDoc

Discussion. When using S-Docs with custom objects, the field template designer will

automatically correct and append your related object fields with a “__r”. If you are

comfortable creating your templates in the source code, be sure to use the standard

Salesforce conventions and dot notation and be mindful of capitalization differences.

3. Link one document to many objects

Solution. You can relate many records to the same S-Doc by leveraging the

SDoc_Relationship__c junction object. By default, one SDoc record can be

simultaneously related to up to 9 distinct standard Salesforce objects (Account, Asset,

Case, Contact, Contract, Lead, Opportunity, Product and Solution). This can be easily

expanded to more standard objects (e.g. Campaign) and custom objects by adding a

lookup field to the SDoc_Relationship__c object. However, if a user wants to

relate one S-Doc to multiple records of the same object type (e.g. one S-Docs Contract

to two Salesforce Accounts), the user simply clicks on the “New SDoc Relationship”

button from the S-Doc related list on the record and then relates it to the S-Doc. One

additional SDoc_Relationship__c record is needed for each records of the same

object type you want to relate to the same S-Doc.

Discussion. The SDoc relationship junction object provides more power and

flexibility in relating S-Docs to your Salesforce objects rather than just linking them

directly. When a document is first generated, one SDoc relationship record is

automatically created and will be linked to up to two objects. This automated

association is driven by the “Related to Type” and “Additional Relationship” fields on

the template setup.

You may also notice that comments field and status field are conveniently located on

the SDocs_Relationship object. S-Docs will automatically synchronize these fields

among all relationships that point to the same generated document. For example, if

you update the status of a Contract that is related to two different Accounts, the

status will be consistent across all views.

S-Docs CookBook

4. Saving S-Docs as attachments

Solution. To create attachments, update each template record and check on the “Auto

Create Attachment” checkbox. When you enable this, attachments will be created in

addition to the S-Doc record for each document that uses that template going forward.

It will not create attachments for previously created documents.

Discussion. There are advantages and disadvantages to using attachments. On one

hand, attachments are more permanent, can be faster to view, and can be exported for

archiving or for legal/compliance purposes. Attachments are also not affected by

future template changes, whereas S-Docs use the template record each time they are

viewed. On the other hand, attachments cannot be easily related to multiple records

and they can consume a significant amount of file storage space within Salesforce.

You also cannot easily report on data located within an attachment. S-Docs lets you

choose whether you want enable attachments or not on a per-template basis.

5. Append Terms and Conditions to your contract

Solution. S-Docs allows you to easily create and append a separate terms and

conditions page (or equivalent) to your documents using the template editor. To use

the terms and conditions feature, open the template detail record and then click on

the template editor button. Next, change the “Field for Edit” picklist value (located at

the top left part of the page) from “Template XML” to “Terms XML”. You can then add

your terms in the editor field. If you want to display varying terms and conditions (e.g.

based on territory or product) for otherwise similar documents, you will need to clone

several templates each having a distinct terms and conditions sections. To improve

how terms and conditions are rendered within your document, a page break is useful

and can be easily inserted in your template by placing the cursor at the beginning of

your terms section and then clicking on the page break icon (last button on the top

row of the of the template editor toolbar.

Note: Both the template source and the terms and condition fields are limited to

32,000 characters each, which is about 10 pages of text.

6. Use your own stylesheet or CSS

Solution. From the template editor, click on the “Source” button. You can then copy

your own <style></style> tags at the start of the page (be sure to use all lower case

S-Docs CookBook

and close your tags). In-line styles also work great and can be used throughout your

template.

Discussion: Not all styles, fonts and borders render precisely in all output formats,

especially PDFs. At this time, you cannot include a separate css file, however, the S-

Docs package does include one stylesheet file as a static resource that you can

leverage.

7. Change page size and orientation (landscape, A4, legal, mailing label)

Solution. Most CSS2 compliant browsers will accept the @page style class. There are

some workarounds for older Internet Explorer versions that can be found on-line.

Working in the template source mode, you can include something similar to the

following at start of your page:

Discussion: Since S-Docs uses standard HTML and CSS, you‟ll find countless online

resources to help resolve any formatting questions. This is a key differentiator that

makes developing S-Docs templates easier and quicker than using a proprietary

design tool.

8. Add line items (related lists) to your documents

Solution. Child or related records will appear as line items in a table within your

document. Since there can be zero or more child records associated to a parent record,

it would not be feasible to map a child field to just one parent field. Therefore, S-Docs

renders child records as rows in a table. You can control the columns displayed, or add

multiple child tables to one document. The simplest way to add a related list is to use

the “Add Related List” button on the template editor page. Using this feature will

allow you to easily select the related objects and columns. If needed, you can then edit

the table header and styles using the template editor.

For even greater control, you can also edit the template source code. Editing the

template source will give you total control of styles and will permit you to drill down

<style>

@page

{

/* use landscape orientation */

size: landscape;

}

</style>

S-Docs CookBook

into one extra level of relationships if needed. Therefore, you can reach fields up to 4

levels removed from the base object. If fields are still further than this, consider using

a formula field to make the value available to your document.

If you edit the template source for custom objects, be sure to use the correct “child

relationship name” in between the ListName tags (e.g.

<ListName>myRelatedObject__r</ListName>). This name does not always match

the object name, as Salesforce can automatically change this value to avoid collisions,

so be sure to verify this value from the custom field definition page within Salesforce.

Example: Template Source for Opportunity Line Items. In the template editor, click

on the “Source” button, and then place the following snippet into a <table> element.

You should create the first header row with column header values. Then place the

LineItems tag as shown below as you would normally use a <tr> element. When

rendered, this code will replaced as a table rows <tr> within the table, and include the

related list field values you specified for columns.

The following snippet will render as a <tr> element. It should therefore be placed

within your <table> element:

Be sure to use include the HTML comment tags () exactly as shown in the

snippet above. While the line items won‟t appear on the template editors WYSIWYG

view, they will render when the document is generated.

NOTE: Since S-Docs is a Native Force.com app, it is subject to Salesforce‟s governor

limits. The complexity of your objects will determine the maximum number of related

lists and the maximum number of line items that you can include in your document

before reaching these limits. We are continually working on improving this limit. For

more information visit

http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_gov_limits.htm.



http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_gov_limits.htm

S-Docs CookBook

9. Filtering, sorting and grouping your related list

Solution. There are several advanced features you can add to your related list using

css and tags. You would need to edit your template source. The example below shows

a combination of features:

1- Leverage CSS to indicate table style, width and alignment of columns

2- Formats numbers and adds prefixes

3- <where> clause used to filter records

4- <orderby> used to sort by a particular column(s)

5- <groupby> used to “break” the table for different sets of values

6- <groupbyheader> needed to specify repeating column names

7- <groupbysum> used to insert running subtotals of each group

<style type="text/css">

table.table1 {border:solid black 1px;border-collapse: collapse;border-

spacing:0px;font-family: verdana; font-size: 10pt; width:100% }

.table1header {text-align:center;font-weight:bold;border:solid black

1px;}

.table1footer {text-align:right;font-weight:bold;border:solid black

0px;}

.table1col0 {font-weight:bold;text-align:left; border:solid black 1px;}

.table1col1 {text-align:left; width:20%;border:solid black 1px;}

.table1col2{text-align:left; width:40%;border:solid black 1px;}

.table1col3{text-align:right;width:10%;border:solid black 1px;}

.table1col4,.table1col5{text-align:right;width:15%;border:solid black

1px;} </style>

... your template HTML here...

<table class="table1">

 </table>

S-Docs CookBook

10. Using S-Docs Direct SOQL feature for related list

Solution. S-Docs Direct SOQL feature is a valuable option when you standard

related list option still do not meet your requirements.

The following are use cases where Direct SOQL may useful:

1- The related list you want to include is not related to (no linked relationships exist)

to your underlying record. The underlying record is the value in the "related to type"

field on the template record. For example, if you wanted to include a related list of

similar Accounts (perhaps in the same industry) in your Account document.

2- You have has more than 100 records in the related list that you want to merge into

your document. Direct SOQL is able to work with more records before hitting any

governor limits.

3- You want your related list to refresh with the latest data every time the S-Doc is

VIEWED from the S-Docs related list. This is a critical distinction, as the document

can change over time without being regenerated. If you want a point-in-time

snapshot, you should also use the “additionally save an attachment” feature.

4- You want to use very specific or advanced SOQL statements they may include

features such as aggregates

5- You want to include the same related object multiple times in your template and

but have each occurrence use a different filter criteria or display different columns.

While you can use the groupby in the standard related list feature to break a table by

a data column, you have more control with Direct SOQL.

Direct SOQL key differences:

- Uses <lineItemsSOQL> instead of <LineItems>

- The <listname> should be set to the object API name not the relationship name. This

means that your should use Opportunity not Opportunities, or OpportunityLineItem

not OpportunityLineItems, or for custom objects you should use CustomObj__c not

CustomObj__r.

- Direct SOQL data is not saved with the S-Doc snapshot record. This means that each

time the s-doc is viewed within salesforce, it is regenerated and therefore it executes

the query and retrieves the latest data. If you email your document, or save it as an

attachment, then that document is unaltered because it is saved as a physical pdf or

Word file. However, if you click on the view button with the S-Docs related list, the

related list data is queried again, and may have changed since the document was

originally generated. Therefore, we strongly recommend you check "also create

attachment" in the template editor in order to keep a hard copy of your document.

To use Direct SOQL:

Open your template, click on the template editor button and then click on the "Source"

button. You will need to add a snippet similar to below where you want the related list

table of data to be inserted. The example below shows how you could select all

opportunities that match a particular criteria and would include the selected records

into a table within your document. You can use this snippet with any template

S-Docs CookBook

because it runs as an independent SOQL query that returns the same data set

regardless of what record or object was used to generate it. In this example, the query

runs irrespective of your base record (that you used to generate the S-Doc from) or

whether your record is linked to these opportunities returned in the query or not.

- If you want to limit the related list items to only those records linked to your specific

record, then you would need to expand the <where> condition and specify the those

line items have a lookup value equal to your specific record ID. For example, if you

want to include only opportunities linked to your account record you would need to

include a condition to filter Opportunity.AccountID value equal to your record

Account.ID. Obviously there needs to be some linked relationship field for this to

work. To do this in the template, you need to specifically use the syntax '{!ObjectID}'

that is dynamically replace the records salesforce id value. In our example, you would

add the following: <where>AccountId='{!ObjectID15}'</where>

Advanced SOQL: If you want even more control, you can type the exact SOQL

statement you want executed by adding a <SOQL> tag.

<table>

<tr><td>stage</td><td>name</td><td>Acct</td><td>amount</td></tr>



</table>

S-Docs CookBook

Adding the following into your template source ( it assumes your base object is

opportunity) will sum your quantity and totals per product and return just one line by

leveraging SOQL aggregate functionality to remove duplicates. You will note how the

<SOQL> statement is used with an alias, and then matched to the columns.

The results from the soql query will be matched to the column names. Here we used

aliases tp and tq that mapped to columns. You don't need to map all columns. If you

use this option, you need to correctly create the soql query to include required where,

group by and order by syntax.

Final note: All SOQL runs as the running user. This prevents any user from viewing

any information that they are not entitled to through salesforce permissions (object

level, record level and field level).

11. Access other fields not visible from the Insert Field Picker button

Solution. The “Insert Field” button in the template editor will allow you to easily

insert fields from related object. However, S-Docs can access related fields using

standard “dot” notation that can reach fields up to 4 relationships removed if you

manually edit the template source. For example, you could include the following in

you template:

Note: Due to Salesforce‟s governor limits, S-Docs may not validate after the second

“dot”. This means users will not receive any warning messages (during document

creation) that a referenced field is invalid. If you find yourself needing to extend to

{{!Opportunity.Account.ParentAccount.Owner.Name}}

<table border="0" class="table1" width="100%">

<tbody>

<tr>

<td class="table1header">

Product</td>

<td class="table1header">

Quantity</td>

<td align="right" class="table1header">

Total Price</td>

</tr>



</tbody>

</table>

S-Docs CookBook

this level, be sure to use the correct relationship name and notation. If you choose to

map fields manually and do not correctly specify objects and fields, the user may

receive an system error during document creation.

Discussion: If you find yourself needing to extend to a far removed field value, we

recommend creating a formula field on the base object. In the example above, you

could easily add a formula field on the Opportunity labeled PAowner_name__c and set

its value to the field referenced above. Then, you could use this field in your S-Docs

template.

12. Include shipping and billing contacts on a quote

Solution. You may find it necessary to include contact names on an invoice, packing

slip, quote or contract. To accomplish this, you can add the following to any template

whose based object is either Opportunity or Account.

If you include the above snippet in your S-Docs template, the user will be prompted to

choose a billing and shipping contact following the document selection step. The

available Contact picklist is populated from the Contact Roles – so, you need to

associate Contacts to the Account or Opportunity in order to use this template.

Optionally, you can include a generic contact record by using the syntax below. This

may be more appropriate for Custom Objects. If you include the following, it will look

for any link from your object to the Contact object and include those matching records.

Bill To Contact: {{!picklist.billingcontact.name}}

Billing Email: {{!picklist.billingcontact.email}}

Ship To Contact: {{!picklist.shippingingcontact.name}}

Shipping Email: {{!picklist.shippingcontact.email}}

Record Contact: {{!picklist.recordcontact.name}}

Record Email: {{!picklist.recordcontact.email}}

S-Docs CookBook

Discussion: Salesforce uses a standard a “contact roles” object to relate contacts to

Accounts and Opportunities. S-Docs leverages this existing functionality. If you need

to specify an individual for other objects, you can extend the object with a custom

field.

BEST PRACTICES

13. Updating templates without affecting previously created documents

Solution. It is important to understand that once a template has been used to create

the first „real‟ document you should refrain from making ANY updates to the

template. This is because the S-Docs template record is used both during document

creation AND during each subsequent view of an S-Doc. Each S-Doc stores the

template used to create it. If you attempt to open an S-Doc where the template used to

create it has been deleted, you will receive an error. The diagram below illustrates

this relationship.

S-Docs CookBook

If you want to make changes after you have completed your design work, it will affect

how PREVIOUSLY generated documents are rendered. Therefore, if you need to

make changes, you should CLONE the template and make modifications to the newly

cloned record. You then uncheck “Active” on the original template to ensure no new

document can be created using it. Previously generated documents will continue to

use the original template (therefore rendering unchanged), and new documents will

use the newly activated template.

Discussion. To maintain flexibility during the iterative process of template design,

and to allow for mass changes to previously created documents, it is advantageous for

some to be able to edit templates after first use. However, for many organizations, it is

equally important that documents are not changed once created. For example, a

contract created a year ago, should not be affected if you updated the Terms section of

the S-Docs template record. If you follow the technique described above, you can

ensure that your documents maintain an unalterable point-in-time record.

S-Docs CookBook

Alternatively, you can also use the „Additionally Create Attachment‟ option (see

Solution #4). This is particularly useful for orgs that are restricted to 5 templates,

have a need to change templates often, and still requiring past documents to remain

unaffected by future template changes. Attachments allow you to store a copy of the

document that cannot be affected by template changes and do not require the S-Docs

template record to view.

14. Using S-Docs with Salesforce Chatter

Solution: Since S-Docs is a Native Force.com app, it integrates seamlessly with

Salesforce Chatter. Enabling Chatter on S-Docs will allow users to comment

(Chatter) on specific S-Docs, and notify any user „following‟ and S-Docs of changes. For

general information on how to configure Chatter, please start with this tutorial: http://wiki.developerforce.com/index.php/An_Introduction_to_Salesforce_Chatter

S-Docs uses a junction object (S-Docs Relationships) to relate generated S-Docs to

your Salesforce records. As explained in Solution #3, this provides much more

flexibility. When enabling S-Docs for Chatter, we recommend enabling the Chatter

feed on the S-Docs Relationship object, not on the S-Doc object itself.

First, go to Setup>Customize>Chatter>Settings and make sure the Chatter

feature is enabled for your org. Next, go to Setup>Chatter>Settings>Feed

Tracking. From here, select the “SDOC Relationship” object, as shown below:

http://wiki.developerforce.com/index.php/An_Introduction_to_Salesforce_Chatter

S-Docs CookBook

Typically, customers will want to track just the “Status” and “Comment” fields, as

these are the fields that are most meaningful to track. If you integrate S-Docs with a

electronic signature solution, users could be notified, via the Chatter feed, that

documents have been executed by the customer.

Now that you have Chatter enabled and Feed Tracking set, you will need to make one

additional change. You will need to create a hyperlink on the S-Docs related list that

can take the user to the S-Docs Relationship record detail page. This is the only page

where users can click on the “Follow” button located on the Chatter toolbar.

You will need to create this hyperlink using a custom formula field on the

SDOC_Relationship__c object. You will then add this field to the related list view.

By using the formula below, you could include a new column that replaces “Document

Number” with the same value but that is a hyperlink to the S-Doc Relationship

record. (For comparison only, both columns are included in the related list shown

below)

HYPERLINK('/'+ Id , SDOC__SDoc__r.SDOC__Document_Number__c, "_self" )

Background: By default, there is no such hyperlink on the S-Docs related list, and this was done

intentionally. While S-Docs related list includes a column labeled “Document Number”, this field is

a plain text field (not a hyperlink). If this field were a hyperlink, the user might expect this to open

the S-Doc itself – not the S-Doc Relationship record. To eliminate any confusion, the hyperlink was

intentionally removed.

However, for Chatter, we do need to get to the S-Docs Relationship record in order to allow users to

click on the Chatter “Follow” button. Unfortunately, the first column in the related list (“Edit” link)

won‟t work either. While this link does take the user to the S-Docs Relationships page, it is

rendered in edit-mode, and the Chatter toolbar does not render for records in edit mode.

So, you will need to add a new column to your S-Docs related list view that will take the user to the

S-Docs Relationships record detail page. While you might first consider using the Relationship ID

field as an easier approach, this ID value would display the S-Doc Relationship ID, not the S-Doc

ID, which again, may confuse users. A formula field rendered as a hyperlink is the best solution.

Since each org will have its own preference on how this related list column should appear, we have

not included this formula field in the core S-Docs package, but rather leave it to the Salesforce

Admins to implement.

S-Docs CookBook

The table below describes the intended behavior we are seeking:

Column Click Action

Column 1 (Edit link) Open S-Docs Relationship record in edit

mode. User can add/edit comments or

change S-Doc status.

Column 3 (Excel icon) Opens the actual S-Doc in new window

(e.g. launches MS Excel)

Column 5 (S-Doc Link) Opens S-Doc Relationship detail in same

window. Users could then click on the

“Follow” icon from the Chatter toolbar.

The example below uses an alternative link. The following formula will create a “Set Chatter Prefs”

link field, that you then add to the related list layout.

Once you‟ve added the link to the relationship object, the user simple opens the record

and then clicks on the follow icon.

HYPERLINK('/'+ Id , “Set Chatter Prefs”, "_self" )

S-Docs CookBook

15. Choosing between PDF, HTML, MS Word or Excel formats

Solution. Some document formats are better suited for certain documents types. For

example, PDFs typically work best for contracts since you do not expect users or

clients to edit after generating. As an administrator, you should select the right

format based on how you expect the document to be viewed, used and distributed.

You must select one output format for each template. If you want to give your users

control of the format, you can simply clone your template and save each version

choosing a different output format. If all the versions are made active, the user could

then choose the template with their desired output format.

PDF –

PDF documents created with S-Docs are self-contained. By this, we mean that the

complete content is stored within the document rather than using links that retrieve

content when the document is opened. Therefore, internet connectivity is not needed

to view any embedded images and using relative links do not pose a problem. Since

the PDF is viewed using a Reader, the output is very consistent and predictable even

across mobile clients. Editing PDFs is not trivial, so it is a good choice when you do

not want the user to edit the document after it has been generated. Therefore, this

output is well suited for documents like quotes, contracts or product information

sheets.

S-Docs CookBook

However, rendering in PDF does have some design considerations. Specifically, not all

fonts are supported, nor are all CSS styles. To get the desired result, you may need

additional editing time or are afforded some leeway on the final output.

If you have existing company PDFs that you would like to use with S-Docs, you will

need to first convert the PDF to HTML, so that it can be saved as an S-Docs template.

Adobe provides free automatic conversion tools that can be found here:

http://www.adobe.com/products/acrobat/access_onlinetools.html. Again, you may need

to edit the template after conversion in order to make it appear as the original.

MS Word –

This is often the best choice for rendering form letters, especially when the message

needs to be tailored for each document, such as customer service letters or meeting

follow-ups. You can still embed company logos, rep signature images and

automatically insert needed Salesforce.com data fields. This format is often used when

there is a need to uniquely edit or personalize each document after it has been

created.

When you select MS Word as the template output type, you will see a “Set advanced

Microsoft Properties” button. You can use this feature to set margins, headers and

footers. The following special S-Docs syntax can be used in your template: ##TERMS## - can be used to insert a terms and conditions section elsewhere than end of document

##PAGEBREAK## - a manual page break is forced

##TOCSTART## and ##TOCEND## - used to insert a table of content

You don‟t need to configure a connector, plug-in or any macros. S-Docs uses the

template definition you provide and creates a new MS Word file. This means you

cannot use an existing MS Word template (.dot file). After generating the document,

the user can then leverage all the features of MS Word to further tailor the content of

each message.

MS Excel –

For large related lists, you may want to render you document using MS Excel. After a

user creates the S-Doc, they can update the spreadsheet as usual.

Note: Similar to how S-Docs generates an MS Word document, S-Docs does not

populate an existing .xls file with data, but rather generates a new .xls file. This

means that you do not need to create and share a template .xls file. All definitions and

formulas should be defined in either Salesforce formula fields, or alternatively, using

the S-Docs template editor. If you have existing xls documents you want to use with S-

Docs, you will need to save them as HTML and use the HTML output as the basis for

your S-Docs template. You may need to remove some special formatting Microsoft

http://www.adobe.com/products/acrobat/access_onlinetools.html

S-Docs CookBook

automatically adds to the document that prevents non-Microsoft browsers from

rendering the document correctly. There are also tools available online for converting

Excel to HTML.

Tip: Since it is often difficult to predict a particular cell location that your S-Docs field

will render to in MS Excel, and since many formulas require cell locations, it is often

easier to create formulas using a two step process. First, you create your fields and

render the document without any formulas. Then, once you have identified all your

target cell locations, you can add your excel formulas using the S-Docs Template

Editor.

For example, typing the following text into the S-Docs template editor that will sum

the values of the values of rows 4 through 8 in Column A.

You can also use a VLookup function to help locate values you want to update with

Salesforce data. Here is a useful resource for creating Excel formulas:

http://www.mrexcel.com/archive/Formulas/index.html

HTML –

HTML is the most flexible of the output formats. HTML docs can even contain editable text areas.

This is the format of choice if you wish to send an in-line document via email. However, you

should note that images are retrieved when the document is viewed. For this reason, we do not

consider the document „self-contained‟. This means users need to not only be connected to the

internet to view your document appropriately, but also have access to the embedded images. While

embedded images can be useful for tracking, rendering consistent HTML on a variety of devices,

browsers and email clients can also be challenging.

Note: If a user emails an HTML S-Doc during the last step of generation, S-Docs will

automatically include the document in-line as HTML in the email body.

USING IMAGES

If you are looking to embed images into your S-Doc, you have several options; each

offers some advantage. Please also see Solution #13 - Based on the document format

(e.g. PDF, MS Word) you want to produce, one of the options may be better suited.

=SUM(A4:A8)

http://www.mrexcel.com/archive/Formulas/index.html

S-Docs CookBook

16. Embedding static images into your document

Solution. For static images, like a company logo, you can simply use an image tag

similar to the following in your S-Docs template source.

This may be the simplest approach if you are emailing HTML content or wish to

embed an image pixel for email tracking. But, keep in mind that if this image is not

stored in your Salesforce org or if the host server is not under your control, the linked

image may change and therefore is not guaranteed to work.

You can also embed images that are stored as Salesforce documents. You can use the

“Add Image” button on the template editor toolbar to search and add the desired

image from your Salesforce documents folder.

If you intend to send a document externally that requires access to the image at view-

time (e.g. HTML S-Doc), be sure that the Salesforce document record, which contains

the image, is set for public visibility. Checking this box will make the image visible on

the public internet.

<image src=”http://publicsite/imagename.png” />

S-Docs CookBook

If you want this image to be visible externally (such as including it in an email sent to

your customers), you must use the full path when referencing the image in your S-

Docs template. To do this, use the source button in the template editor toolbar to

toggle to source view, find the image, and then edit the image src value with the full

url path (adding the underlined portion shown below that corresponds to your

Salesforce instance):

17. Adding a dynamic signature image into a contract

Solution. While the previous solution shows how to insert static images, S-Docs can

also insert dynamic images. For example, say you want to create a letter that includes

an image of the representative‟s signature at the bottom of a page. Or similarly, you

may want to include an image of your product on a Product Specifications PDF.

Rather than cloning the same template many times (once for each unique image), you

would rather have just one template that dynamically includes the right image. You

can also accomplish this in several ways.

Option 1 – Use a rich text field

This is perhaps the easiest method. You first upload your image into a standard

Salesforce.com rich text field on your record detail page. Then, open the template

where in which you want to add the image, click on the „Template Editor‟ button, click

on the “Insert Field” button, select the rich text field, click on the “Contains Rich Text”

checkbox, and finally click on the “insert” button. Your documents will now render the

rich text content for that record wherever you placed this field.

Note: This option is only available for PDF and HTML formatted documents. If your

rich text contains many items or elements, it may not render precisely. This is

because Salesforce uses a rich-text editor that auto-formats rich text content and this

formatting cannot be overridden through a source editor. It is a better practice to use

the S-Docs editor to control document layout rather than inserting a complex rich-text

field into a template. By doing so, you also maintain template formatting in a central

location (the S-Docs template) versus fragmented design elements located in rich text

fields throughout individual records.

Option 2 – Use a standard text field that contains the entire image markup.

You can also use a standard Salesforce.com text field whose value contains the

complete image element tag that you want to include. Each record would potentially

contain a different link that corresponds to the applicable image.

For example, set the value of a ProductImage__c field on a Product record to:

<image

src="https://na1.salesforce.com/servlet/servlet.ImageServer?id=..."/>

S-Docs CookBook

Then, using the S-Docs template editor, click on the “Insert Field” button, select the

field, and then be sure to click on the “Contains Rich Text” checkbox.

This is a simple approach but has limited usage. It is useful for images such as

representative signatures, where they are centrally controlled by an administrator,

they do not change frequently and the user would not normally need to view them in

the Salesforce user interface along with the record. Since this is a text field, if you

were to include this field on a page layout, it would not render as an image – users

would only see the text shown above when viewing the record detail in the Salesforce

UI. Therefore, it would not be appropriate for end-users who upload their own images

frequently (e.g. scanned photograph of a damage claim) or wanted to view the actual

image in Salesforce within the record detail page.

Option 3 – Use a formula field to display an image.

Building on option 2, you can leverage a Salesforce formula field to create the image

path and also display the image within the Salesforce record detail. You would then

drop the formula field into your S-Docs template with the “Contains Rich Text” option

checked (as described in the previous option). The formula field would contain

something similar to the following:

This option requires some planning so that the image field name can be

programmatically derived.

Option 4 – Build an image URL within the S-Docs template

This is a combination of option 2 and 3, but would not require a formula field. You can

use a record‟s existing field value to help build the correct image path but you create

the full path value within the S-Docs template, not in the salesforce field.

For example, to include a dynamic product image or agents signature, you can use

something similar to the following in your document template source:

lt#img src=quot#http://intranet/{{!Product2.ProductPath__c}}.png quot#

/gt#

lt#img src=quot#{{!Opportunity.Owner.SignatureURL__c}}quot# /gt#

PRODUCT IMAGE:<br><img scr=”/host/Product123Image.png” />

IMAGE("/CompanyIntranet/Products”+ myObject__c.ProductID__c + “.png")

S-Docs CookBook

The field value should be a URL that points to either an image in your Salesforce documents

folder or an external image hosted on the public internet. In the second example, the field

should contain the entire path including the „http://‟ prefix.

Since the image path is text (not markup) it should only be surrounded by double brackets, as

shown above. The special notation for <, >, and quotes, using lt#, gt#, quot# respectively, is

used to instruct S-Docs that this markup needs to be evaluated rather than rendered literally.

Having this flexibility gives you total control of how you want a field interpreted within the S-

Docs template.

In order to compensate for relative URLs (e.g src=“/servlets/…”) that Salesforce

automatically generates, S-Docs will automatically replace the relative path with the

complete path, including the correct Salesforce.com instance (e.g.

src=”https://na1.salesforce.com/servlets/...”). Doing this ensures your

embedded images render correctly when viewed by others. If you wish to override this

behavior and use a relative URL, you should specify the path to include the “http”

(e.g. src=”http://servlet/”).

Discussion:

Once you have inserted a marked-up field into your template, you will notice three

sets of brackets that surround your field, for example:

The extra pair of brackets instructs S-Docs to interpret this field rather than just

displaying the stored value. Without this, S-Docs would not know whether a field

containing the value “<img src=“//host/Product123Image.png” />” should be displayed

as the text quoted or substituted with the actual image when rendered. Whenever you

add a field using the template editor and click on the “Contains Rich Text” checkbox,

S-Docs will evaluate the value regardless of the actual Salesforce field type (Rich Text

or otherwise).

18. Embedding Google Charts into your document

Solution. Leveraging Google Charts API provides a great way to include dynamic

charts in your S-Docs.

You can find more information here on Google charts here:

http://code.google.com/apis/chart/

{{{!Product2.ProductImage__c}}}

http://code.google.com/apis/chart/

S-Docs CookBook

Here are a few examples of Google charts:

The charts work by passing the Salesforce data to the Google API, which in turn

dynamically builds and returns the chart as a PNG image.

Security Note. Unlike S-Docs, which works entirely within the Salesforce.com

platform, Google Google charts are hosted remotely. Depending on the chart, your

data is passed from Salesforce to Google. Your security team would need to determine

if this is an acceptable practice.

Images are rendered by using one URL request per chart. For example, you can

manipulate the values in the following URL to render a different pie chart:

The link above will return the following image:

http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Jan|Feb

S-Docs CookBook

As you may begin to see, using Google Charts API is all about creating these URLs

where you pass in the data points, legends and chart options. Depending on the chart,

some of these URLs can be long and a bit complex.

Rather than building complex logic within S-Docs to create these URLs, we again

leverage Salesforce formula fields to do the heavy lifting.

Here is a great tutorial from Salesforce on how to create Google Charts using a

formula field:

http://wiki.developerforce.com/index.php/Using_Formulas_and_Google_Charts_to_Vis

ualize_Data

The above tutorial will walk through how to build the following formula field to

display a Won/Loss pie chart:

Then, we simply drop this formula field into our S-Doc template (be sure to check

“Contains Rich Text” box).

While more complex, another approach is to build the Google Chart API URL in your

S-Doc Template and then mix in field values. This may offer you greater control.

Using syntax similar to the following, you could add the image, where

ChartLegend__c would just contain the value “Jan|Feb”.

Improving performance on pages with many Google charts:

The Google documentation offers a good performance tip if you plan to embed 5 or more charts.

By appending a 1-9 before the “chart.apis.google.com” you can have the browser load the charts

simultaneously. For example,

http://0.chart.apis.google.com/chart?cht=...



Note: S-Docs does not support the Google Visualization API.

lt#img src=

quot#http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl= {{!MyObject__c.ChartLegend__c}}quot# /gt#

IMAGE("http://chart.apis.google.com/chart?cht=p3&chd=t:" &

Text(Won__c/(Won__c + Lost__c)) & "," &

Text(Lost__c/(Won__c + Lost__c)) &

"&chs=275x100&chf=bg,s,F3F3EC&chl=Won|Lost&chco=5555ff",

"chart text")

http://wiki.developerforce.com/index.php/Using_Formulas_and_Google_Charts_to_Visualize_Data

http://wiki.developerforce.com/index.php/Using_Formulas_and_Google_Charts_to_Visualize_Data

S-Docs CookBook

19. Displaying checkboxes

Solution: If you want to create a document that contains checkbox images such as

rather than “True” or “False” values, you can do so by leveraging a formula

field.

By adding the following formula fields to your object, you can easily leverage them to

place checkbox images into your S-Docs. (You do not need to add these fields to the

page layout)

20. Formatting Dates

Solution: If you want to create a dated letter with the text “September 1, 2010”

rather than the Salesforce formatted date-time, you can do so using S-Docs formatting

syntax or using a salesforce formula field. We recommend the first option where

possible because it doesn‟t require any salesforce configuration changes.

To use S-Docs formatting, you would need to edit the template source. Click the source

button, and then locate the date field within your template. You then need to replace

the syntax to match the following:

If the date field is located in a related list column use the following:

The format-date can accept a wide range of values. You can add minutes, timezones

etc. Pay attention to caps as mm in minute, where as MM is month.

Use this reference to view all date formatting options:

http://download.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html

IMAGE(

CASE(MyObject__c.IsValid,

"True", "/img/checkbox_checked.gif",

"/img/checkbox_unchecked.gif"),

'CheckBox'))

{{!**Quote.createdDate}}

<column format-date="MM/dd/yyyy">createddate</column>

http://download.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html

S-Docs CookBook

The second option to formatting dates within your document is to leverage Salesforce

formula fields. By adding the following formula field to your object, you can leverage

built-in Salesforce functionality. You would need to substitute your field name. You do

not need to add these fields to any page layout. If you are working with a Date Field

(not a DateTime field), see the next example for slight modifications needed.

Similarly, you could use the pattern below to modify a Date field for differing Locales.

This formula returns European date formatting (DD/MM/YYYY)

21. Formatting Currencies (UPATED)

Solution: If you would like to display “$235,000.00” as the Opportunity amount in

your document rather than “235000”, which is the default formatting for the currency

field, then you should leverage a formula field. You can do this in one of two ways. The

first option is to use S-Docs formatting, and the second is to use a salesforce formula

field.

To use S-Docs number formatting, you would need to edit the template source. Click

the source button, and then locate the number/currency field within your template.

You then need to replace the syntax to match the following:

If the number/currency field is located in a related list column use the following:

CASE( MONTH( DATEVALUE(LastModifiedDate) ), 1, "January", 2,

"February", 3, "March", 4, "April", 5, "May", 6, "June", 7, "July", 8,

"August", 9, "September", 10, "October", 11, "November", 12, "December",

"-" )

+ ' ' + TEXT(DAY( DATEVALUE(LastModifiedDate))) + ', ' + TEXT(YEAR(

DATEVALUE(LastModifiedDate)))

TEXT(DAY( CloseDate)) +'/'+ TEXT(MONTH( CloseDate)) +'/'+ TEXT(YEAR(

CloseDate))

${{!**Contract.Total_Amount__c}}

<column format-number="#,###">quantity</column>

<column format-number="#,###.##" prefix="$">unitprice</column>

<column format-number="#.###,##" postfix="€">euro_price__c</column>

S-Docs CookBook

These are the three supported formatting options. For others, you can use a formula

field described below.

The following section outlines how to leverage a salesforce formula field to format

currency data within your document.

By adding the following formula field to your object, you leverage built-in Salesforce

functionality. You would need to substitute your field name into the formula below (in

place of “Amount”), and then drop the formula field into your S-Docs template. You do

not need to add any of these fields to any page layout. You can add the dollar sign ($)

to either the start of the formula or within the template design document proceeding

your field.

NOTE: This solution formats only the given value, it does not consider currency

exchange rates. In such cases, you could use a combination of formulas. One to convert

the currency based on the exchange rate, and another to format it correctly for your

document.

IF(

Amount >= 1000000,

TEXT(FLOOR(Amount / 1000000)) & ",",

"") &

IF(

Amount >= 1000,

RIGHT(TEXT(FLOOR(Amount / 1000)), 3) & ",",

"") &

RIGHT(TEXT(FLOOR(Amount)), 3) & "." &

IF(

MOD(Amount , 1) * 100 < 10,

"0" & TEXT(ROUND(MOD(Amount , 1), 2) * 100),

TEXT(MIN(ROUND(MOD(Amount , 1), 2) * 100, 99))

)

AUTHOR CREDIT: By searching the internet, you can find many other solutions. This

particular solution was found online at: http://techblog.appirio.com/2010/02/displaying-currencies-in-sfdc-email.html

http://techblog.appirio.com/2010/02/displaying-currencies-in-sfdc-email.html

http://techblog.appirio.com/2010/02/displaying-currencies-in-sfdc-email.html

CookBook

Documents

Transcript of CookBook