Reports and Documents Generator for SharePoint ver.: 2.2 User Guide Version 2.2
Contents 1. Overview... 3 2. Licensing... 4 3. Installation instructions... 4 3.1. Requirements... 4 3.2. Installation... 4 3.3. Creating custom actions to call generator... 5 a) Create custom action by provided dialog... 5 b) Add custom action using SharePoint Designer... 6 c) Add custom action using Edit Control Block... 7 d) Using SharePoint SDK Custom actions features... 10 4. Preparing templates for generator... 10 5. Template tags reference... 15 5.1.Field tag... 15 5.2.Repeat tag... 15 6. Tutorial... 15 www.sharepointdrive.com Reports and Documents Generator v.2.2 2 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 3 P a g e
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. www.sharepointdrive.com Reports and Documents Generator v.2.2 4 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 5 P a g e
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. www.sharepointdrive.com Reports and Documents Generator v.2.2 6 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 7 P a g e
Modify the Content Editor Web Part : Open Source Editor : www.sharepointdrive.com Reports and Documents Generator v.2.2 8 P a g e
And copy - paste the following code to it: <script type="text/javascript" language="javascript"> function Custom_AddListMenuItems(m, ctx) { 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 doclib docname suffix 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. Document library where document content type set by contype parameter is defined. The name of the generated document. 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. www.sharepointdrive.com Reports and Documents Generator v.2.2 9 P a g e
returnfile listname itemid output 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. 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 [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"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <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: www.sharepointdrive.com Reports and Documents Generator v.2.2 10 P a g e
You will see Reports and Documents GeneratorAdd-In task pane opened on the right: To work with content controls you need to enable Developer tab in Word. Open Word Options dialog: Select Show Developer tab in the Ribbon: www.sharepointdrive.com Reports and Documents Generator v.2.2 11 P a g e
Click OK. To insert data placeholder simply put Rich Text Content Control: [PRO] If you want to insert value of the picture field (i.e. image itself) you should use Picture Content Control: www.sharepointdrive.com Reports and Documents Generator v.2.2 12 P a g e
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. www.sharepointdrive.com Reports and Documents Generator v.2.2 13 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 14 P a g e
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) lookuplistfield Column name of the current context list item. 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) view ignoreparent 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. This attribute can be set to view name. If view name is set, then only items from this view is taken. 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: www.sharepointdrive.com Reports and Documents Generator v.2.2 15 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 16 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 17 P a g e
14. Enter Company value for Name attribute. 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): www.sharepointdrive.com Reports and Documents Generator v.2.2 18 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 19 P a g e
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: www.sharepointdrive.com Reports and Documents Generator v.2.2 20 P a g e
24. To insert custom action use steps explained in Creating custom actions to call generator an use the following JavaScript: <script type="text/javascript" language="javascript"> function Custom_AddListMenuItems(m, ctx) { 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: www.sharepointdrive.com Reports and Documents Generator v.2.2 21 P a g e