Tag: Documents

In this post, we’ll look at how to create a new document type. Firstly, SAP Enable Now ships with [as of July 2022] ten different output types by default (9 Word documents and 1 PowerPoint presentation). You will find it much, much easier to start from one of these, and customize it, so that’s what we’ll do here. There’s examples of all of the built-in document styles in the SAP Enable Now Development book (along with descriptions of all of the document type macros), or you can just generate each of them yourself, and see which one most matches your requirements. In this example, we’ll start from the Work Document.

Creating the Word template

If you go to Resources | Documentation Settings in Producer, you’ll see a Documentation Settings configuration file for each of the 13 output types. Locate the one you are going to copy, and click on it, to show its properties.

The main thing to note here, is the Template (which in this example is SAP – Single Document). This is the Word template (.dot) on which this document is based. Assuming you only want to change the content of the document, and not its physical layout, you can re-use this as-is for your new document type. However, in this example, we will go ahead and change this. This is because by default these documents are formatted for A4 size paper (SAP is based in Europe), and for the purposes of this exercise, we will assume we are working in the United States, where standard paper is Letter size. Although Word/Acrobat will adjust for this on the fly, it would be ‘cleaner’ if we changed this ourselves in the template itself. Even if you don’t need to change the page size, if you want to change the page margins, or add a custom header or footer (for example, to include your company or project logo or name), this is the best way to do so.

So, if you now go to Resources | Adaptable Resources | Documentation Style, you will see several Word documents. (Note that you may need to select Show Resources from the Filter drop-down in the Template dialog box to be able to locate these.) One of these is SAP – Single Document, which corresponds to the Template property identified for the Work Document, above. So if we want to influence the layout of our document, this is the file to change. You could just edit this file, but a better thing to do is to take a copy of it. That way, if the original file is replaced during an upgrade, you won’t lose your customization. The easiest way to do this, is to open the existing file (SAP – Single Document in our example), use Save As… and save a copy to a temporary location on your PC, change this file as required in Word, and then drag the file from your PC onto the Documentation Style Group in Producer. In the Properties pane for this file, the only thing you can change is the Name. This will default to the file name, but you can change it to something more meaningful if necessary. You now have a Word template that you can use with your new document style.

Creating the Document Type

Now to create the new document type. As noted above, it’s best to start this from an existing style. So return to the Resources | Document Settings group, click on the existing style that you want to copy, and then click on the Duplicate button on the Toolbar (or right-click on it and select Duplicate from the shortcut menu). You’re prompted to enter a New Name, and a New ID. The New Name is important, as this is the name that will be listed in the Generate Document dialog boxes, and will also be the default name for the generated document for a simulation. The value you enter for New ID is less significant as it is largely internal, but it must be unique (across all document IDs). Once created, there are a lot of properties you can specify. Let’s start with the easy ones.

The most important property here is the Template setting. You should change this to specify the Word template (.dot file) you created above.

Another property that is worth looking at here is the Text Style property. This specifies the text style file that will be used to determine the text styles in the document. This file can be found in Resources | Adaptable Resources, and has an Object Type property of text_styles. It is important to re-emphasize that the text styles used in the document are taken from this style file. Any standard Word-defined character, paragraph, or table styles within the template itself are not used. This is an odd design choice of SAP’s, but I’m sure they had their reasons. In the meantime, if you really want to control the text styles used, you can define a new Text Style file (which will be the subject of another post, but as a hint: use Tools | Customization | Edit Text Styles).

Defining the document structure

Now that you have a new document type (based on an existing document type) you can start configuring it to meet your needs. The content is largely controlled internally by Enable Now, but you can change the structure via the document type’s Fragment properties. You can change these either via the Properties pane for the document type in the Workarea, or via menu option Tools | Settings | Documentation Settings | {Document type}.

You can specify up to 11 or 12 ‘fragments’ (depending upon the base document type), which are effectively the ‘building blocks’ that contain the information that is to appear in the document. Because we copied an existing document type, some or all of these will already be specified. The example below shows the default fragments for our new type, which is based on the Working Document document type.

In each of the Fragment x fields, you can select one of the following ‘blocks’ of content:

Defining the document content

Now let’s look at the other settings that you can use to influence the specific content and format of the document. The properties that are available are split over several properties; we’ll look at each of these in turn (because it will be easier to cross-reference them later).

Note that these only apply to ‘single document’ output formats. The Compound Document has its own set categories unique to it. This will be the subject of another article.

Project Content category

The Project Content fragment is used to insert the actual contents of the content object for which you will generate the document. Most often this is a single simulation project, but for Master Documents it could contain multiple simulations, book pages, and other content objects. The properties in the Project Content category therefore influence how (or if) this project content appears within the document. The available properties, and there purpose are:

• Show Bubble Text: Determines whether bubble text is included or not. By default, this is selected, as normally you would want to include bubble text. If you deselect this, then bubble text for interaction macros (such as mouse actions, input text, and keyboard actions) will not be included in the document – but curiously text for Explanation bubbles will. This is a useful option (to deselect) if all you really want is the screenshots.
• Bubble Text from: Choose which texts (Demo text or Practice text) should be used.
• Indent of Cue Table: Specify the number of pixels by which the box for Explanation bubbles should be indented.
• Headings from: By default, a heading (at the level indicated in the Heading Level property – see below) will be inserted for each Step. For this property, the following options are available to influence this:
  • Step titles: This is the default, and will use the Step’s Name property as the heading.
  • Screens: This option will cause the Title property for the Screen Macro to be used as the heading text. Note that any Comments will not influence this (as it does in the Thumbnail View in the Project Editor).
  • None: This option will prevent Step-level headings from being used at all (content from one step will just lead directly into the next).
• Heading Level (Single Document): This property determines the heading level of the Project. By default, the Project has a Level 2 heading (this is to allow for situations where multiple Project-level documents are gathered into a Master Document or Compound Document). The Steps within a Project are then at Level 3. If you know that you will never use this document type within a Compound or Master document, you may want to set a value of 0 for this property. This heading level will also be applied to Book Pages and Text Units used as fragments. (Heading levels are confusing and inconsistent; I’ll add a separate blog post covering these, later.)
• Show Branches: Branches are not handled well in generated documents. By default, the document will just list each ‘branch action’ and destination one after the other (and in the same ‘action step’ list item / table entry), with a dash before each choice. This will be done regardless of this property’s setting. If you select this checkbox then the branch choices will be preceded by a line of bold text stating “Branch – select one of the following actions”, which at least gives the reader an indication that the options that follow are discrete choices. If you use branches in any of your projects I would strongly suggest selecting this option.
• Branch Title as Header: If you choose to include branches, select this property if you want the branch introductory text (of “Branch – select one of the following options”) to be formatted as a heading. This heading will be one level lower than the Step-level heading.

Action Table category

The Action Table category is available for the BPP Document and Audit and Compliance Document types (or documents based on these). The properties in this section determine the layout and content of the Action Tables included in the document (one Action Table is included per Step). The Action Table is used in the Project Content snippet. The following properties are available:

• Heading Level: The ‘heading level’ in Word to use for each Project.
• Hide Screenshots: If you want to include the (cropped) screenshots in the document then make sure this option is not selected. If screenshots aren’t shown then all actions are included in a single Action Table, and a shaded row (with a single, merged cell) is included for each Step/screenshot, showing the screen name.
• Action Table: If you want the actions to be listed in a table (the default) then select defined table. Otherwise, select text only and the actions will be presented in a simple numbered list (with each action being a list item). If you choose the table option, then you can specify the table width and contents via the remaining properties; otherwise these have no effect.
• Table Width: The overall width of the table, in pixels (which isn’t as useful as being able to specify a width- say, of 100%). This defaults to 400, but for Letter-sized paper, a width of 450 is closer to ‘full width’.
• Column {1-5} Content: You can specify up to 5 columns. The content of each column can be one of:
  • Numbering: Sequential number of the action within the Step (or for the entire project if Hide Screenshots is selected).
  • Text from Demo Bubble
  • Text from Practice Bubble
  • Object Name
  • Value: Value of the Input Text property
  • ROC: Value of the Documentation > ROC (Required, Optional, Conditional) property
  • Description: Value of the Documentation > Description property for action macros, or the Demo Text (always, regardless of any Text from… setting elsewhere in the table) for Explanation macros.
  • Result (Heading only – cell is blank)
  • OK (Heading only – cell is blank)
  • Comment (Heading only – cell is blank)
  • Reference (Heading only – cell is blank)
  • Hide Column: In theory this omits the column, but in my experience it is better to set the column’s properties to inactive – having a column active and set to Hide Column seems to have unexpected results (like also hiding other columns).
• Column {1-5} Width: The desired width of the column, as a percentage of the overall table width.

Screenshots category

The properties in the Screenshots category determine how or if screenshots are to be included in the document. The following properties are available: 

• Hide Screenshots: Select this checkbox if you do not want the screenshots (actually, the cropped area of the full screen) to be included in the document.
• Scaling: Documents typically include the ‘cropped’ area of the screenshot (the area bounded by the gray box in the Thumbnail view, and these are scaled (via the Image Size (%) property in the Documentation category for the screenshot in the Project). However, you can use the document’s Scaling property to specify the percentage by which the crop area (not the full screenshot [Page] size) should be scaled.
• Show Captions: Select this option if you want a caption to be shown underneath the screenshot. If you select this option, then select Captions from Screens to use the Title property of the screen macro. If you select Show Captions but deselect Captions from Screens, a caption of “Figure x” will be used.
• Border Width / Border Color: These properties can be used to set the width and color of of the border around the screenshots. It is important to note, however, that the Border Width property will apply only to screenshots for which the Documentation > Border Width property for the Screen macro in the project is inactive. The border Color will be applied to all screenshots for which a positive Border Width property is specified (either in the Project, or via the document Border Width property – but again, only if the Border Width property in the Project is inactive) – which means that if the Border With is activated in the Project but no value is specified, the document setting will not add a border or color it. Yes, it’s confusing!
• Quality in Word/PDF Document / Quality in HTML Document: Select the color mode for the generated document. (Note that this will apply to the entire document, and not just the screenshots.) This setting can be one of:
  • RGB: Standard ‘full color’. This is the default.
  • Indexed Color: Use only 256 colors (the exact colors are determined by the image, and similar colors will be merged if necessary to keep within 256 unique colors only). This will result in a smaller file size, but possibly with some loss of quality. It is not suitable for ‘photo-realistic’ images, but is typically acceptable for most software application interfaces.
  • Grayscale: All screenshot images will be converted to grayscale. This will result in the smallest file size, and may be acceptable if the documents will typically be printed on a black and white printer anyway.

Markers category

‘Markers’ are the call-outs that are placed over the (cropped) screenshot to point to the relevant object for each mouse action or string input action. The numbers used correspond to the numbers shown in the step list below the screenshot.

The following properties are available for markers:

• Highlight Offset: Use this property to define the amount of space that should be left between the screen object (as identified by the Control > Position and size property in the simulation) and the highlight (the colored border around the object). This will override any changes made via the Highlight Position / Size property in the simulation.
• Border: This property controls the width of the the (default red) highlight border, and the (default red) border around the marker circle, and the ‘pointer’ line connecting the two. By default, these are all set to 4pt, but you can specify a different width if necessary. Note that specifying a value of 0 will actually use a width of 1 (just so that there’s something there).
• Color: This property controls the color of the highlight, the border around the marker circle, and the line connecting the two.
• Text Color: This property controls the color of the number inside the marker bubble.
• Background Color: This property controls the color of the fill for the marker circle.
• Arrow Length / Arrow Width: In theory, these properties are used to control the appearance of arrows inserted onto the screenshot via the Arrow macro.

Note that if you set Quality in … Document to Grayscale, then the markers are also shown in grayscale, regardless of your settings here.

Numbering Category

The properties in the Numbering category control the way in which the actions within each Step are numbered (these either appear as a numbered list or a Step/Action table below the screenshot. The properties in the Numbering category control the way in which the actions within each Step are numbered (these either appear as a numbered list or a Step/Action table below the screenshot). The following properties are available:

• Indexing: This determines the overall numbering scheme to use, and can be one of the following:
  • Step – highlights only: Each action within a Step is numbered, and numbering restarts at 1 for each Step.
  • Step – all objects: Each action (including keyboard actions) and each Explanation for which the Icon property is set to None within a Step is numbered, and numbering restarts at 1 for each Step.
  • Global – highlights only: Each action is numbered, but as a single sequence across all Steps within the document (that is, numbering does not restart at 1 for each Step).
  • Global – all objects: Each action and each Explanation for which the Icon property is set to None is numbered, but as a single sequence across all Steps within the document (that is, numbering does not restart at 1 for each Step).
  • None: Actions are not numbered (and just appear as separate paragraphs below the screenshot).
• Style: This defines the numbering style, and can be one of:
  • (1)
  • [2]
  • 3.

Quiz category

The Quiz category of properties determines how Quiz elements (essentially, Questions) that are embedded in the simulation (or in a Group, for Compound documents) are handled. There are only two properties in this category. These are:

• Show Quiz: Select this option to include quiz questions in the document.
• Include solutions: If you selected Show Quiz, then select this option if you also want to include the answers / solutions to the questions.

Input Values category

If you have included the Input Values fragment in your document structure, then the document will include a separate table containing details of every Input Text macro in the simulation. The properties in the Input Values category determine what information is shown for each of these macros. The following properties is available:

• Show Object Name: Include the Field Name property in a column.
• Show Value: Include the Value property in a column.
• Show Bubble Text: Include the bubble text for the Input Text macro (whether this is the Demo text or the Practice text depends upon the document’s Project Content > Bubble Text From property). This appears in a column labeled Instruction, between Value and ROC.
• Show ROC: Include the Documentation > ROC property in a column. This property can take one of three values:
  • Required (R)
  • Optional (O)
  • Conditional (C)
• Show Description: Include the contents of the Documentation > Description property.

An example of an Input Values table (with all properties except Show Bubble Text selected) shown below. Note that there is no document heading included.

As an alternative to including the Input Values table as a Fragment in your document, you can use the Input Values document macro within the project itself. (But you wouldn’t want to do both.)

Revision History category

The properties in the Revision History category determine how the Revision History table appears in the document. This table provides the contents of all of the Revision Entry document macros in the associated project. It is automatically included in the BPP Document and Audit and Compliance Document formats, but can be included as a Fragment in any document type. The following properties are available:

• Hide in Project Content: Revision Entry macros are placed in the simulation project, and can appear within the project in whichever step they appear (typically you’d have them in the Start step, but you can actually put them anywhere – and they will appear in the project wherever you place them). If you include the Revision History as a Fragment in your document type, then you probably don’t want them also appearing within the project itself. So selecting this property will suppress them from appearing in-project.
• Sorting: Adjacent Revision Entry macros in a project will be included in a single Revision History table (either where positioned by its inclusion as a Fragment, or wherever the macros appear in the project). By default, these are sorted in Date order (oldest first). If you want the entries to be left in the order they appear in the project, then set this property to None. This might be a useful option if you want the entries to be listed ‘newest on top’ – assuming that this is the order you have entered them in the project.

Included Objects category

The properties in the Included Objects category control how certain types of (non-project) objects included in the document as Fragments appear. This does not apply to Book Pages or Text Units included within the project itself. The following properties are available:

• Show Title of Text Unit: If a Text Unit is included in the document as a Fragment then include the Title of the Text Unit as a header.
• Show Title of Book Page: If a Book Page is included in the document as a Fragment then include the Title of the Book Page as a header.
• Book Page Format: This property determines how the contents of Book Pages are to be included in the document. Options are:
  • Book Page as Text: Include the text from the Book Page. Note that all text will be included (in Layer order) – regardless of whether this is displayed by default or in response to a timer or other action.
  • Book Page as Image: Insert the entire Book Page, as a static image.
• Book Page Description: If selected, the contents of the Book Page’s Description property are included in the document.

Once you’ve specified all of the properties, save your document type definition and check it in. You will then be able to generate this type of document for your simulation projects.

If you want this document type to be shown in the upper-left corner of the Document drop-down panel in the Project Editor (so it is the first choice), select your new document type, and then click on Set As Default.

And that’s it! That’s all there is to defining a new document type. Actually, there’s a few more things you can do around defining the text styles used in the document, but we’ll cover that next time.