16. Working With Pages

Pages are mostly what the name implies: web pages. However, they are only accessible to users who are logged in to your Polarion system. Pages differ from Documents in that they do not contain Work Items (requirements, test cases, etc.) However, Pages can show information about Work Items, and other artifacts in your projects and repository.

When you create a new Page, you have the choice of 2 types:

The main difference in these types is in the page layout. You can use Widgets in both types. Some page features, such as the ability to extend Widgets with scripting or create reports, may be limited or unavailable with some product licenses.

When creating a new Page, the Classic Wiki Page option is also offered. These pages use the product's original Wiki technology. It is recommended that you use LiveReport and Info Pages for new reports and informational pages. For information on working with existing Classic Wiki pages, see User Guide: Appendix: Using Classic Wiki.

Page Basics

This section introduces and explains the main features and tasks common to both types of Pages (LiveReport and Info). For information specific to LiveReport Pages, see Building Reports. The main topics in this section are:

Creating New Pages

The ability to create new Pages is controlled by user permissions settings in global and project Administration. You must be granted "Permission to CREATE NEW" and "Permission to MODIFY" for Pages in all projects in which you want to create new Pages.

Pages exist within spaces. You can create new pages in any space. There are several access points where you an begin creating a new Page:

  • Index page of any space. Click on the icon on the toolbar. (Tooltip: Create New)

  • Page toolbar. Actions Menu menu: Create New, when Page is in view mode. Click Expand Tools to reveal.

  • Documents and Pages toolbar. Select this topic in Navigation, then click on the icon on the page toolbar.

Figure 16.1. New Page Access Points

New Page Access Points

Create a new page from any of several access points.

To create a new Page:

  1. Launch the Create New dialog.

  2. Click on LiveReport Page or Info Page, depending on the type of new page you want to create.

  3. In the next dialog, enter the title of the new page (any character set), the system identifier in the Name (ID) field (ASCII only), and optionally select a different Space or Subspace to store the page. Note that the Title appears in Navigation, search results, links, and other user interface components that show the Page.

  4. Click OK to finish and create the Page. The new Page opens in edit mode, ready for you to add content.

Figure 16.2. Create New Dialog

Create New Dialog

Create or import new portal content in the Create New dialog

Accessing Existing Pages

The ability to view Pages is controlled by user permissions settings in global and project Administration. You must be granted "Permission to READ" for Pages in all projects in which you want to view Pages.

There are 2 basic ways to access existing Pages: browse or search. These work the same way for Pages as for other types of content.

Browsing for Pages

You can browse for Pages in Navigation. Expand the Documents and Pages node, then expand the node of any space. The Documents and Pages in the space are listed in alphabetical order and the content type is indicated by the icons (see figure of the Create New dialog, above).

If there are too many items to show in Navigation, a message appears in the panel under the space name. You can either use Search, or click on the message to load the space Index page, where you can browse the Pages and Documents in the selected space.

Searching for Pages

The Search field of Navigation enables you to search your project or your entire portal for all types of content, including Pages. For more information, see User Guide: Searching the Portal.

Deleting Pages

The ability to delete Pages is controlled by user permissions settings in global and project Administration. You must be granted "Permission to DELETE" for Pages in all projects from which you want to delete Pages.

To delete a Page:

  1. Locate the Page by browsing or searching to determine the space where it is stored.

  2. Open the space Index page: expand the space name in Navigation and click Index. If you see a message that there are too many items to show, click to message to load the space Index page.

  3. In the space Index page, check the box on the row of all Pages you want to delete and click the Delete button.

Editing Pages

The ability to edit Pages is controlled by user permissions settings in global and project Administration. You must be granted Permission to MODIFY for Pages in all projects in which you want to edit Pages. This section covers the editing features common to both LiveReport and Info type Pages. Information about editing features for developing reports are covered in the Building Reports topic.

To begin editing a Page:

  1. Locate the page using browse or search, and open it for viewing.

  2. At the top of the page, click Expand Tools.

  3. On the Page toolbar that is now visible, click the Edit button to open the Page Designer.

Modifying Page Layout

A Page is composed of one or more regions. Regions are simply containers for Page content. You can modify the default layout of a Page to have whatever regions you need to show your content the way you want it. This section covers:

Selecting a Layout

Each Page type has a default layout:

  • Info Page has one region occupying the full width of the Page.

  • LiveReport Page has three regions: one occupying the full width of the Page, and two occupying half the width of the page.

When you first create a new page, you may want a layout different from the default. Several pre-defined Page layouts are available, which may provide the layout you want, or at least a good starting point for your custom layout. You can also apply one of the pre-defined layouts to an existing page. The Page content is preserved, but it may not appear where you want it in the changed layout. You can either copy content to a different region, or use the Undo button to revert the change. (Redo is available as well.)

You can access the pre-defined layout selectors in the Layout section of the Page Properties sidebar. The options are:

  • 3 regions: top one at 100% of page width, two below at 75% and 25% of page width.

  • 3 regions: top one at 100% of page width, two below at 50% of page width.

  • 3 regions: top one at 100% of page width, three below at approximately 33% of page width.

  • 1 region at 100% of page width.

You can also specify the minimum width of the Page in this sidebar. The width is in pixels, and the default value is 1000. In view mode in a browser, it sets the minimum width of the Page. If there is some wide content such as an image that cannot be scaled, this setting can increase minimum Page width so that the content is completely visible in the parent region.

In PDF export, the Minimal Width value is used to define page width of the PDF document, providing the possibility to preserve the layout. If wide content is included in an insufficiently wide page, it will be scaled (zoomed out).

Adding or Removing Regions

You can add a region to the page by placing a new one, or splitting an existing one, using the following commands on the header of an existing region:

  • Add Region Above: adds a new region above the current region.

  • Add Region Below: adds a new region below the current region.

  • Split Region: splits the current region into two, moving the current region, including its content, to the left and adding a new empty region to the right. Content of the original region may be scaled to fit the changed width.

You can remove a region from the page using the Remove Region command on the drop-down menu of the region's header.

Resizing a Region

If you have multiple regions next to each other in a column-like arrangement, you can reside them horizontally by dragged the separator that appears in the space between the regions. Vertical size of regions is determined by their content and cannot be changed manually.

Formatting Text

Pages support basic rich-text formatting. If you have used a desktop or online word processing application, the rich text tools of the Page Designer will seem quite familiar and work as you expect. If you have worked with Documents, the same text formatting tools are present on the toolbar when editing a Page. The following text formatting options are available:

  • Paragraph, title, and heading level formats.

  • Bold, Italic, underline, strike-through, subscript, superscript, text color, and text background color.

  • Font family and font size.

  • Numbered list and bullet list

  • Indent and outdent

  • Paragraph alignment: left, center, right.

Figure 16.3. Page Designer Text Formatting

Page Designer Text Formatting

Main text formatting available for text in Pages

Change the Ordered List Style

Administrators can change the ordered list style by adding or editing the com.siemens.polarion.document.listStyle= X property to the polarion.properties file.

(Where “X” can be a series of up to 9 values representing each tier of a Multilevel List.)

e.g com.siemens.polarion.document.listStyle= 1ai

The above example is Polarion’s default setting. (Even without the property present.)

Figure 16.4. Default Numbered Multilevel List

Default Numbered Multilevel List
  • "1" for decimal numbers "1,2,3"

  • "a" for lowercase letters "a,b,c"

  • "A" for uppercase letters "A,B,C"

  • "i" for lowercase Roman numbers "i,ii,iii"

  • "I" for uppercase Roman numbers "I,II,III"

Enabling Outline Numbering

Outline numbering of headings in Pages is disabled by default. To enable it:

  1. Open the page for editing in the Page Designer.

  2. Open the Page Properties sidebar (Show Sidebar > Page Properties).

  3. In the Outline Numbering section, click on the ON button.

  4. Save the Page.

Outline numbers for headings are not visible in the Page Designer while editing a Page. They appear only in view mode. Outline numbers are only applied to headings specified in the user interface. Headings created via a script (using e.g. <H2>) will not have outline numbering applied.

Copy and Paste

Copying and pasting text within a Page is similar to other applications you have probably used. There are several things applicable with Pages that may be worthwhile to note:

Copying Work Items Within the Same Document

When On-demand Work Item Loading is turned ON, make sure that all the Work Items you wish to copy have finished loading before pasting them somewhere else within the same document.

(This limitation does not apply when copying them to a different document.)

  • Within the same page you can:

    • copy-paste a block of text to the same or a different region

    • copy-paste a chart or table widget to the same or a different region

    • copy-paste links to a different region (relative links remain relative)

    • copy-paste an entire region to another region

  • Between different Pages you can:

    • copy-paste blocks of text

    • copy-paste chart or table widgets

    • copy-paste links (relative links remain relative)

    • copy-paste an entire region

  • From an external application to a Page you can:

    • copy-paste a block of text

    • copy-paste links

  • From a Page to an external application you can:

    • copy-paste a block of text

    • copy-paste links

    • copy-paste widgets (if text and widget is pasted to an external page, only text will be pasted)

Inserting Content

In addition to text, you can insert several other types of content into any region of a Page:

Insert Image or Attachment Preview

The button is available on the toolbars found on Pages, LiveDocs and Rich text Work Item fields. It launches the “Insert Image or Attachment Preview” dialog.

The dialog initially displays previews of images and attachments that are already attached.

It's also where new images or attachments with previews can be added.

Attachment Previews for File Types other than Images

Polarion supports image and attachment previews for all common image formats. To view previews for Visio files and the popular document formats (pdf, docx, xlsx etc.) described below, Teamcenter Visualization Convert & Print Setup must be installed.

(See the "Polarion Preview Generator" chapter in the Windows installation document or the "Configure attachment preview generator" chapter in the Linux installation document for details.)

To Add a New Image or Attachment
  1. Click on the toolbar.

  2. When you have images or attachments on a page (like a LiveReport page), only the images and attachments on the page itself appear.

    (Not images or attachments within the Work Items that appear in the page's widgets.)

    When you have images or attachments in both a LiveDoc and Work Item and the Insert Image or Attachment Preview dialog is opened inside a Work Item, both sections appear.

    When you have images or attachments in both a LiveDoc and Work Item and the Insert Image or Attachment Preview dialog is opened from inside the LiveDoc, only the Document's images and attachments appear.

    Note

    Hover over an image or attachment preview in the Insert Image or Attachment Preview dialog to see its filename and title (if any).

  3. Click Select File….

  4. Select one or more images or files to attach and click Insert.

    Hold down Shift or Ctrl, then select the files to Insert multiple files at once.

  5. If items with the same filenames already exist, you will be prompted with the following message:

    (When uploading a file with the same name as one already saved within a Work Item, the Revert option is not available and both files will be saved with the same name.)

  6. Click Revert to revert to the original files. Click Insert to add the ones you selected and confirm the overwrite.

  7. Selected items are added and their previews appear in the Rich Page, Live Document or Work Item.

    Images and Visio diagrams with a width larger than 750px are resized, with their aspect ratio maintained, to a width of 750px.

    (The width of the page when inserted into a Live Document.)

    The previews of common document formats (.docx, .pdf, .xlsx, .txt etc.) are resized to a width of 250px and take up 1/3 of a Live Document page's width.

    For less common file types, where previews cannot be generated, an icon is added instead. (See the image below.)

    The Attachments are added to the Attachments sidebar and their previews are also visible when the document is Exported to PDF.

    They appear even when the images or attachments themselves have not yet loaded, if On-demand Work Item Loading is ON.

  8. (Optional) Filter the dialog with the Filter field.

    With Polarion Diagrams

    You cannot insert a Polarion diagram itself (the .mxg file) via the Insert Image or Attachment Preview dialog. Instead a preview of the diagram will be added and the original .mxg file will be listed in the Attachments sidebar.

Resize

To resize an image click on it and click Resize.

Fit To Width: Resizes the image width to the document width. (Not available for Work Item Rich Text fields.)

Reset Size: Resets the image size to its original dimensions.

Keep Aspect Ratio: Active by default. Ensures that the height and width maintain the same ratio when resized.

Preview

  • For a full screen preview of resized images or attachment previews in Edit mode, click on them and click Preview.

    (Or double-click on the image or attachment preview.)

  • When NOT in Edit mode, a single click will launch a full screen preview.

  • Click "ESC" to exit the full screen preview screen.

View: Launches the object in its own browser window or the default program configured by the OS to open the selected file type.

Download: Downloads the object to the browser's download folder.

Update: Upload an updated version of the previewed object. (Is disabled for read-only documents or for users with read-only permissions.)

Close: Closes the preview window. (ESC will also close the window.)

Inserted images, diagrams or files become attachments of the Page, and remain attached even if visually removed from the Page content. To delete an image attachment completely, see the Deleting Attachments section below.

(Adding URL links to images is not supported.)

Pasting Images

CTRL +V or Command +V can be used for images within the document, but if they are used for an image in a Work Item within the document, its thumbnail will NOT appear in the Attachments sidebar.

Inserting Attachments

Rich pages, Live documents and Work Item rich text fields can have almost any type of file as an attachment. Once an attachment has been uploaded, a link to it or a preview of it can be inserted directly into the document. Or it can simply be appended to the document by leaving it in the "Attachments" section of the Attachment sidebar.

(See Managing Attachments below for details.)

Managing Attachments

Managing Attachments in a document is done using the Attachment sidebar.

Access Attachments via the Attachment Sidebar

To open the Attachments sidebar:

  1. Locate the desired Page by browsing or searching.

  2. Click on at the top right and click Attachments.

  3. The Attachment sidebar appears listing the "Attachments" currently attached to the document and the "Attachments Visible in Document".

Add a New Attachment
  1. Open the Attachment Sidebar.

  2. Click Upload New Attachment, select the file to attach and click "Open".

  3. The selected attachment appears under the Attachments section of the Attachment sidebar.

  4. Save the document.

  5. If the attachment is an image, Visio diagram or popular document format, a preview will also appear within the Attachment sidebar. (An icon will appear for less common formats.)

  6. (Optional) To insert a preview of the attachment into the document, place the curser at the desired spot within the document and click Insert Preview.

    See theAdd a New Image or Attachment section for details on how images and attachment previews appear.

Updating an Existing Attachment

Suppose you have a PDF file attached to a Page, and at some point you find there is an updated version of the same document, with changed content. You can upload the updated version to replace the existing attachment. The uploaded file must be of the same type, and have exactly the same file name and extension.

To update an existing attachment:

  1. Open the Attachment Sidebar.

  2. Locate the attachment you want to update. If there are many attachments, or some attachments are hidden, use the sidebar's search field.

  3. Hover your pointer over the attachment you want to update. It will highlight, and expose several icons.

  4. Click the Update icon. Your operating system's file selection dialog appears.

  5. Select the file in your local file system and click the button that confirms the selection. Wait while the file uploads.

  6. When the upload is complete, save the page to finish updating the attachment. It is now available to users viewing the page.

Deleting Attachments

If you find some attachment is outdated or no longer needed, you can delete it from the Attachments sidebar. Keep in mind that if you have any links to the attachment file, you will need to remove them the Page from the Page content.

To delete an existing attachment:

  1. Locate the desired Page by browsing or searching, and open it for editing in the Page Designer.

  2. On the Page Designer toolbar, click the Show Sidebar button and select Attachments to reveal the Attachments sidebar.

  3. Locate the attachment you want to update. If there are many attachments, or some attachments are hidden, use the search field of the sidebar.

  4. Hover your pointer over the attachment you want to update. It will highlight, and expose several icons.

  5. Click the (Delete) icon. The attachment no longer appears in the Attachments sidebar.

  6. Save the page to finalize deletion of the attachment. Remember that any links to the deleted file will not work, so be sure to review the page content.

Inserting Tables

The Insert Table button on the Page Designer toolbar launches a dialog in which you can specify the basic properties of the new table: number of rows and columns, width, alignments, border, header, etc. Tables can be inserted into any region of a Page. Locate the insertion cursor in the region at the point where you want to insert a table, and then invoke Insert Table.

After a table has been inserted, whenever your cursor is in a table cell, the Table menu is available on the Page Designer toolbar. It contains a number of items that enable you to modify the table. You can:

  • Insert new rows and columns.

  • Move columns and rows.

  • Delete rows, columns, or the entire table.

  • Set the text alignment for the table.

  • View and modify the table properties.

  • Merge cells. (And unmerge previously merged cells.)

Compare Historical Changes after using Merge

See Comparing table changes when cells have been merged for details on comparing historical changes and how merging tables affects it.

If you split a region that contains tables, the tables will be automatically resized. You may want to review them and make adjustments such as resizing the columns. You can resize columns by dragging a vertical border to the left or right.

Inserting Links

Your can insert text hyperlinks into any region of a Page. The Insert Link button on the Page Designer toolbar launches a dialog in which you can specify the target URL, and optionally the link text of the hyperlink. If you don't change the Label field, the URL appears as the link text.

Three types of links are recognized: links to Polarion items (represented by the item type icon and its ID/Title), internal portal links, represented by internal URL link text, and external links, represented as external URL link text.

Place the insertion cursor at the point in the region where you want to create a link, and click the Insert Link button.

TIP

You can also create a link by pasting a URL into the Page text. Be sure to leave a space before and after the URL, otherwise it will not be recognized as a link. The link text will include all characters in the URL. After a link is created, the link itself can be copied and pasted. A pasted link is processed and recognized according whether it is a link to a Polarion item, an internal portal link, or an external link.

Inserting a Table of Contents

You can insert a automated table of contents into Page. Although it is possible to insert this into any place in any region of a Page, the most common practice is to insert it at the beginning of the topmost region. A Page only accepts one Table of Contents. If you try to insert another one, you will see an error message.

Table of Contents entries do not appear in the Page Designer, even after you save changes. They are generated only after closing the designer and returning to view mode. If the Page does not contain any Table of Contents elements, a message to that affect appears when the page is viewed. The TOC cannot be copied/pasted.

You can delete the Table of Contents from a Page by clicking on it in the Page Designer, and pressing your keyboard's Delete key.

Inserting Widgets

Note

Users of a Polarion PRO license cannot insert Widgets.

Widgets retrieve and format project data from your Polarion portal for reporting purposes. Normally, you use them only in LiveReport type pages, as described in the Introduction to Pages. However, it is possible to use them in any page of either type. If you decide you want to show some chart on project Work Items in an Info Pages, you can.

The Widgets sidebar is shown by default when you are editing any Page, and you can optionally insert Widgets into any region. The distinction between Info and LiveReport pages is made purely to generalize different use cases. The page types use different layout templates but are otherwise essentially the same.

Saving Changes

When editing a Page, changes to text appear in the Page Designer as you work, but are not visible to other users viewing the Page until you save the changes. In LiveReport Pages, charts and other Widget content in the Page Designer do not reflect changes made to their parameters until you save the Page.

To save changes, click the Save button on the Page Designer toolbar. Other users viewing the Page can then see the changes. The Page Designer remains open until you click the Back button on the toolbar. You are then viewing the page as a report user.

Handling Conflicting Changes

If you attempt to edit a Page that another user is already editing, a pop-up message informs you who is editing the Page, and for how long. If you save changes to the page, the other user sees a message when attempting to save their changes. The message informs them about who else is editing the Page and what options are available.

Neither user is prevented from saving changes. The dialogs provide information about overwrite options and the possibility that some changes may be lost. Clicking the Back button frees the Page for editing by other users.

Working With Page History

As with other artifacts, Polarion automatically tracks every change made to Pages and maintains a complete change history. Pages are included in Baselines.

To access a Page's history:

  1. Find the page by browsing or searching and open in for viewing.

  2. At the top of the Page, click Expand Tools.

  3. On the Page toolbar, click the History button.

    The history page opens, listing all Page revisions and baselines, if any, in chronological order with the most recent at the top.

In the history page you can:

  • See the number, author, age, and date of every revision.

  • Click on the number of any revision to view the state of the Page at the time the revision was committed to the repository.

  • Use icons in the page toolbar to select a revision to view by date or by Baseline.

When viewing a historical revision of a Page, you can:

  • Export the Page revision to PDF or send it to a printer.

  • Download the Page revision as a zip archive.

  • Pick a different historical revision to view.

  • Access the attachments that were present at the time of the revision, if any.

  • Open the Create New dialog.

  • Change page parameters, if any, to see different data according to the function of the parameters.

TIP

You cannot modify the page when viewing a historical revision.

Exporting and Printing Pages

You can export Pages to PDF, or print them on a printer. When exporting or Printing, you can optionally hide some types of Page content.

Embedded image or attachment previews are preserved when a document is exported to PDF or Printed.

To export to PDF, or print a Page:

  1. Open the Page after locating it by browsing or searching.

  2. At the top of the Page, click Expand Tools. The page toolbar appears.

  3. Click on the Actions Menu and choose the desired operation on the drop-down menu.

TIP

When exporting to PDF, you can optionally customize the header and footer of the exported document in the export dialog. PDF export headers and footers are also configurable by administrators, globally or for projects. See: Administration Reference: PDF Export Header/Footer Properties

Controlling Exported Content

You can optionally exclude any region in a Page from appearing in PDF or printed output. You do this in the Page Designer, so you must have permission to modify pages in the project.

To hide a region for PDF export or printing:

  1. Open the Page in the Page Designer (Expand Tools > Edit).

  2. On the header of any region, click the Actions Menu button to show the drop-down menu.

  3. In the menu, check Hide on Print to hide the region in printed output, and/or check Hide in PDF to hide the region in PDF output. You can check one of these options or both options.

  4. Save your changes. If you are finished editing, close the Page Designer.

TIP

In LiveReport Pages, don't confuse region headers (light gray) with Widget headers (light blue, light yellow on hover). You can only hide the region that contains Widgets, not Widgets themselves.

Downloading and Reusing Pages

You can download a Page as a zip archive. You can import a previously downloaded Page to create a new, duplicate Page. Reusing Pages this way can be useful if, for example, you have built a report and need a similar report in a different project, or in the same or a different space in the same project. You can download the completed Page, import the downloaded Zip file to any project and space to which you have access, and then modify the page as needed.

To download a Page:

  1. Open the Page after locating it by browsing or searching.

  2. At the top of the Page, click Expand Tools. The page toolbar appears.

  3. Click (Actions) and choose the Download on the drop-down menu.

  4. Select the location where you want to store the Page archive. The suggested archive file name includes the revision number of the page you are downloading.

To import a previously downloaded Page archive:

  1. Open the project into which you want to import the Page archive to create a new Page.

  2. Open the Index page of any space in the project. It will save a little effort if you open the Index page of the destination space.

  3. On the Index page toolbar, click the Create New button to launch the Create New dialog.

  4. In the Import section of the dialog, click Page Archive. The Import Page dialog appears.

  5. In the dialog, specify the Title and Name of the new Page to be created from the imported Page archive. The Name (ID) must be unique to the space into which you are importing. (This is especially important if you are importing to the same project and space from which the page archive was downloaded.)

  6. If you want to change the target space, select the desired one in the Space field. (The current space is selected by default.)

  7. Click the Choose File button, then browser your local system to select the Page archive file you want to import. (This file must be one previously downloaded from an existing Page).

  8. Click OK to complete the import operation and create a new Page from the imported Page archive.

    You can open the page in the Page Designer and modify it as needed.