Reports and Documents Generator for SharePoint ver.: 2.2

(1)

Reports and Documents Generator for

SharePoint ver.: 2.2

User Guide

(2)

1. Overview

Reports and Documents Generator is a solution for SharePoint users who want to generate reports and documents using data stored in SharePoint lists.

Reports and Documents Generator uses Microsoft Office Word content controls based templates. By using custom content controls it is possible to preserve data and rich Word formatting capabilities at the same time. One of the main features of Reports and Documents Generator is capability to generate reports or documents from lists that are related to each other by SharePoint lookup columns. So for example if you have Order and Order details list related by lookup column you can prepare template like this:

(4)

And Reports and Documents Generator will generate sales order like this:

2. Licensing

You will find novitas_eula.docx file in downloaded zip file. Also you must accept this EULA when installing SharePoint reports and documents generator. By this EULA you are granted non-transferable and nonexclusive right to use and execute the Reports and Documents Generator on a single computer, without right to

sublicense it. Under no circumstance may you store, use or allow the use of the Reports and Documents Generator in any manner on more than one computer at a time.

3. Installation instructions

3.1. Requirements

Reports and Documents Generatorsupports:

Server SharePoint Foundation 2013 SharePoint Server 2013 SharePoint Foundation 2010 SharePoint Server 2010

Client Microsoft Office Word 2013 Microsoft Office Word 2010 Microsoft Office Word 2007

3.2. Installation

To install Reports and Documents Generator run downloaded executable file and follow onscreen instructions. Also Reports and Documents Generator comes with Word Add-In which is used to prepare templates for Reports and Documents Generator. You need to install it only on computer where you will be preparing templates. To install Reports and Documents Generator Add-In run setup file and follow onscreen instructions.

(5)

3.3. Creating custom actions to call generator

There are several ways how to create custom actions in SharePoint. You can find more information in SharePoint SDK (you can choose different SharePoint version by using Others Versions menu at the top). In this guide you will see how you can quickly add custom actions to item’s Edit Control Block (ECB) menu without the need to access the SharePoint server and how to add custom action using SharePoint Designer:

a)

Create custom action by provided dialog

After installing Documents and Reports generator for SharePoint each lists ribbon action is extended with additional button:

This button will bring you dialog which allows you to create custom actions comfortable:

(6)

b)

Add custom action using SharePoint Designer

In this part we will show how to create the same custom action using SharePoint Designer. At first in SharePoint Designer open your site, and find a list where you want to add custom action (list Orders):

By clicking on list open properties page and find Custom Actions panel:

There press New… button and open Create Custom Action dialog. Enter Name, Description and Action URL.

(7)

If you want to create custom action similar to one in the previous section, URL should look like this:

~site/_layouts/generate.aspx?docLib=Sales documents&conType=Sales invoice&docName=Sales invoice&returnFile=Yes&suffix=Invoice number&listName={ListId}&itemID={ItemId}

c)

Add custom action using Edit Control Block

Open the list page for editing (for example AllItems.aspx) where you want to add custom action:

Add a Content Editor Web Part to the page:

(8)

Modify the Content Editor Web Part :

Open Source Editor :

(9)

{

var url = ctx.HttpRoot +

"/_layouts/generate.aspx?docLib=Sales documents&conType=Sales

invoice&docName=Sales invoice&returnFile=Yes&suffix=Invoice number&listName="+ctx.listName+"&itemID="+currentItemID;

var js = "STSNavigate('" + url + "')";

CAMOpt(m, "Print Sales Invoice", js,

""); CAMSep(m); return false; }

</script>

Main area where you need to concentrate is custom action’s link:

"/_layouts/generate.aspx?docLib=Sales documents&conType=Sales invoice&docName=Sales invoice&returnFile=Yes&suffix=Invoice

number&listName="+ctx.listName+"&itemID="+currentItemID

You MUST pass all the following parameters to the SharePoint reports and documents generator: conType

Reports and Documents Generatoris using document content type templates. You need to set this parameter to the name of document content type you wish to generate.

docLib

Document library where document content type set by conType parameter is defined.

docName The name of the generated document. suffix

You can add a suffix to the name of the generated document. It must be the name of one of the current item columns. For example you may want to add Order Number to the generated document name.

And copy - paste the following code to it:

(10)

returnFile

You can return generated document directly to the browser and open it with Word or save it to the SharePoint document library. Document library set by docLib parameter is used to save generated document.

listName itemID

Reports and Documents Generator must be called from a list item context. It means that you need to pass list and item ID to the generator. You can always pass those parameters by adding following string to the custom actions link:

listName="+ctx.listName+"&itemID="+currentItemID

output [PRO] this parameter allows to change generatef file format. Possible values are: docx(default) pdf xps png jpeg bmp tiff

So in example above you are telling to the generator: generate document using content type’s Sales Invoice template stored in Sales document library. Use Sales invoice name for the generated document by adding Invoice number suffix to it. And please return generated document directly to the browser.

d)

Using SharePoint SDK Custom actions features

Alternatively you can use SharePoint SDK to figure out how to add custom actions using SharePoint features or you can ask to do it your SharePoint system administrator. You can use exactly the same custom action link as in example above:

<?xml version="1.0" encoding="utf-8" ?>

<CustomAction Id="UserInterfaceCustomActions1.DisplayFormToolbar"

RegistrationType="ContentType" RegistrationId="0x01005728C2E9132CA4469E63D58F478E115A" Location="DisplayFormToolbar" Sequence="106" Title="Print Order">

<UrlAction Url="~site/_layouts/generate.aspx?docLib=Sales documents&conType=Sales invoice&docName=Sales invoice&returnFile=Yes&suffix=Invoice

number&listName={ListId}&itemID={ItemId}" />

</CustomAction>

<CustomAction Id="UserInterfaceCustomActions2.DisplayFormToolbar"

RegistrationType="ContentType" RegistrationId="0x01005728C2E9132CA4469E63D58F478E115A" Location="DisplayFormToolbar" Sequence="107" Title="Print Invoice">

<UrlAction Url="~site/_layouts/generate.aspx?docLib=Sales documents&conType=Service invoice&docName=Service invoice&returnFile=No&suffix=Invoice

number&listName={ListId}&itemID={ItemId}" />

</CustomAction> </Elements>

4. Preparing templates for generator

In order to prepare templates for Reports and Documents Generator you don‘t need SharePoint. All you need is to use Word Add-In that is provided with Reports and Documents Generator.

To activate Reports and Documents Generator Add-In click on Add-Ins tab in Word(following steps are for Word 2007) and then click Tags Edtor button:

(11)

You will see Reports and Documents GeneratorAdd-In task pane opened on the right:

To work with content controls you need to enable Developertab in Word. Open Word Options dialog:

Select Show Developer tab in the Ribbon:

(12)

Click OK.

To insert data placeholder simply put Rich Text Content Control:

(13)

The tag in template will look like this:

Ant in the generated document you‘ll will see:

At the moment there are 2 tags that you can insert in to template: Field and Repeat. Field

Field tag is used when you want to insert single column value. If column is a lookup column than you can insert one column value from item to which the lookup column is related.

(14)

Repeat

Repeat tag is used when you want to insert all items from related/child list or just simple list. Child list must have a lookup column to the parent list (the list from which generator was called). After you insert Repeat tag you must insert one Field tag inside Repeat tag for each child‘s list column you want to appear in generated report or document.

For more details how to use tags see the Tutorial and Template tags reference.

After you created template you need to save it as one of your document content type‘s template:

(15)

5. Template tags reference

5.1.Field tag

Field tag is used to insert column value of current context item. All tags that are out of Repeat tag bounds have current item context (item on which custom action was called). All tags that are inside Repeat tag have context of related list set by Repeat tag list attribute.

Attributes

name (required) Column name of the current context list item.

lookupListField If column name set with name attribute is a lookup column you can set this

attribute to the column name (which value you want to appear in report) of related list. Also if column name set with name attribute is Person type you can set

lookupListField to the one of users profile attributes.

5.2.Repeat tag

Repeat tag is used to define how to display items from some list. The items from the list can be taken in two ways (or combination of them):

a) Items can be taken from the list related to the current context item (context item should be set and ignoreParent attribute not set or set to false). E.g. order items that belong to the context of the current order.

b) Items can be taken from the lists view. View attribute must be set to any of the list view names (context item should not be set or ignoreParent attribute should be set to true). E.g. a list of tasks finished this week.

c) Items related to the current context item and contained in some view (context items and view attribute should be set). E.g. current order items currently in stock.

Attributes

list(required) The name of the list to take items from. Reports and Documents

Generatorautomatically will find a lookup field in related list by which the lists are related.

view This attribute can be set to view name. If view name is set, then only items from this view is taken.

ignoreParent If this attribute is set to true, then current context item is ignored and table is created form the list items from the view

Note: to avoid creating tables from big lists – tables will not be created if you set ignoreParent to true and will not give view‘s name. If you really need tables containing all list items, you must provide a view containing all items (e.g. „All Items“).

6. Tutorial

In this tutorial we will use OOTB document library, a couple Contact lists and one Custom list to prepare

template to the Reports and Documents Generatorand later will add custom action to call document generator that will be using this prepared template:

(16)

1. Create a standard document library named Reports. 2. Create a standard Contacts list named Accounts. 3. Create a standard Contacts list named Contacts. 4. Create a custom list Banks (with a single Title column).

5. Create a lookup column in Contacts list named Account and point it to Accounts list. 6. Create a lookup column in Accounts list named Bank and point it to Banks list. 7. Enter a couple of related items in Contacts, Account and Banks lists.

8. Enable content types in the Reports document library:

9. In the Reports document library select Document content type and in Advanced setting click Edit template:

10. Enable Developer tab and Add-In as explained in Preparing templates for generator. 11. Create template like this:

(17)

12. Insert a tag for Account company field. Place a cursor after a colon and insert Rich Text or Text content control (if content controls are disabled try to save document in DOCX format):

13. Click on inserted content control tag (if you can’t see tags enable design mode by clicking on Design Mode in Developer tab) and select Field in Reports and Documents Generatortask pane:

(18)

This tells to the Reports and Documents Generatorto insert a Company column value for the current Account item.

15. Using same technique insert E-Mail and Created By column values:

16. Insert tag for Bank field. But this time we need to lookup value in Banks list item that is related to the current Account. To do this we need to set Name attribute to the “Bank” value and lookupListField to the ” Title” value (related list’s column name that we want to appear in report):

14. Enter “Company” value for Name attribute .

(19)

17. Insert tag for Job Title field. We need a Job Title column value from user’s who created Account profile properties:

To tell that to the generator we need additionally set lookupListField to Job Title:

18. Next step is to prepare a contacts table for the Account. Double click on the first table cell so that entire row gets selected:

(20)

19. While row is selected insert content control.

20. Set the current Repeat tag context to Contacts list by setting List attribute to “Contacts” value:

21. Insert one Field tag for each rows cell in a table and set name attributes to the corresponding column names: Last Name, First Name, Business Phone, Home Phone, E-Mail Address. At the end you will get picture like this:

22. The template is ready. Save it.

23. Now we will need a custom action in the Accounts item’s context menu:

(21)

24. To insert custom action use steps explained in Creating custom actions to call generator an use the following JavaScript:

{

var url = ctx.HttpRoot +

"/_layouts/generate.aspx?docLib=Reports&conType=Document&docName=Account

report&returnFile=Yes&suffix=Company&listName="+ctx.listName+"&itemID="+currentIte mID;

var js = "STSNavigate('" + url + "')"; CAMOpt(m, "Print Account Contacts", js, ""); CAMSep(m); return false;

}

</script>

25. Call generator by selecting just created custom action and see the results:

Reports and Documents Generator for SharePoint ver.: 2.2