The Details screen allows you to configure various settings including what types of assets to list, the Status of the assets to list and where to find the assets to list.

For more information about the Status, Future Status,Thumbnail and Details sections, refer to the Details Screen chapter in the Asset Screens manual.

Asset Selection

This section allows you to define which asset types to show and what their Status must be to be included in the list.

The fields that are available in this section are as follows:

• Asset Types to List: select the types of assets to list on the page. To select more than one asset type, click on the More... button. An additional list will appear on the screen. You can also check the inherit box to specify that the Asset Listing should include all child types of the selected asset type.
• Asset Statuses to List: select the Status the asset must be to be included in the Asset Listing. For example, if you want to show all assets that are Under Construction and Live in the list, select both of these Statuses. To select multiple Statuses, hold down the Ctrl key on the keyword and click on the Status in the list.

  If no Statuses are selected, the asset listing will work out which assets to show based on the permissions of the user viewing the page. For example, if a public user is viewing the page they will only be able to see the Live assets that have Public Read Permission granted.

  By not selecting anything in the Asset Statuses to List field you can improve the performance of the Asset Listing. If no Statuses are selected, the Asset Listing will only have to filer the list based on permissions and will not have to perform a second filter on the Status of the asset.

• Asset Access to List: select what permission the user must have on the asset for it to be included in the list. For example, if you select Write, it will only show the assets that the user has Write Permission for. Include effective permissions allows you to select whether or not the user only sees the assets if they have that specific permission. For example, if you select Write and select Include effective permissions, it will show the assets that the user has Write and Admin Permission on. If you deselect this option, it will only show the assets the user has Write Permission on.
• Exclude Assets: select which assets from the Asset Map to exclude in the Asset Listing. For example, if you do not want to show the Home page in the list, select it from the Asset Map in this field.
• Exclude Root Node: select which root nodes to be excluded from the Asset Listing. For example, if you do not want to show the files in the Documents Folder in the list, select it from the Asset Map in this field.
• Exclude This Asset: select whether or not to list the asset that is currently being viewed. For example, if the Asset Listing Page is nested in the Site design, it will not list an asset if the user is currently viewing it.

Asset Locations

This section allows you to define where to find the assets to show on the Asset Listing page.

The fields that are available in this section are as follows:

• Root Nodes: select which section of the system to show in on the Asset Listing page. For example, if you want to list all of the PDF Files under your Site, select your Site asset in this field. To select another Root Node, click the More... button. An additional field will appear on the screen. To remove a Root Node, click the Clear button and click Commit.
• Root Node Logic: select whether the asset must be a child of all root nodes or at least one root node. For example, if you have selected the Documents Folder and News Items Folder in the Root Nodes, select whether the asset must be a child of both Folders or at least one Folder. This will only come into affect if more than two root nodes are selected in the field above.

• 
  An example Site

  Direct Links Only: select Yes to only show assets that are direct child assets of the root node. These are the assets that are directly linked to the root node. For example, in the figure shown to the right, if the Root Node was the SquizSite and Direct Links Only was set to Yes, it will only show the Home page and the Matrix page. If this is set to No, all assets that are above or below the root node will be shown. In other words it will show the Home page, the Matrix page and the Modules page.
• Lookup Direction: select Up the tree to list assets above the root node, or Down the tree to list assets below the root node.

• 
  An example Site structure

  Minimum Depth/Height: enter the minimum level from which to list assets. For example, in the figure shown to the right, if Squiz was the root node and this field was set to 2, the Asset Listing will include Modules (level 2), CMS (level 3), Search (level 3) and Training (level 2) assets. It will not print the Home and Matrix assets as they are level 1 assets. This option is only used if Direct Links Only is set to No.

• 
  An example Site structure

  Maximum Depth/Height: enter the maximum level from which to list assets. For example, in the figure shown to the right, if Squiz was the root node, Minimum Depth/Height field was set to 1 and this field was set to 2, the Asset Listing will include Home (level 1),Matrix (level 1), Modules (level 2) and Training (level 2) assets. If does not include the CMS and Search assets as they are level 3 assets. This option is only used if Direct Links Only is set to No.
  
  
  
  
  

  By setting the Minimum Depth/Height field to 0, the assets selected in the Root Node field will be shown in the Asset Listing. When the Maximum Depth/Height field is also set to 0, only the assets selected in the Root Node field will be shown. By doing this, you can show a set list of assets. For example, if you only want to show the Home page, Search page and Site Map, select these three assets in the Root Node field and set the minimum and maximum depth/height field to 0. Only these three assets will be shown.

• Link Types: select the type of link the assets must be to be included on the Asset Listing page. The default value for this field is TYPE_1 and TYPE_2. This setting only applies if the Direct Links Only field is turned on. To select multiple link types from the list hold down the Ctrl key on the keyboard and click on the link type.
• Link Value: enter a value to filter the listed assets by. This value will be checked against the Value entered on the Linking screen of an asset based on the selected Link Value Filtering Logic. For this to work, the field Enable Link Value Filtering needs to be set to Yes.
• Link Value Filtering Logic: select if the listed assets should have link values that are equal or different to the Link Value. The values available in this field are Match and Does not Match. For example, if you enter a value of landscape or portrait on the Linking screen of each Image in your Site, you can create an Asset Listing that will only show landscape images by using landscape as the Link Value and having the Link Value Filtering Logic set to Match. If the Link Value Filtering Logic were set to Does not Match, the Asset Listing would only show portrait images. By default, this field is set to Match.
• Enable Link Value Filtering: select whether or not to enable filtering by the Link Value. If this is set to Yes, only assets that have the link value which meets the Link Value and Link Value Filtering Logic criteria will be returned.

List Formatting

This section allows you to change the format of the Asset Listing page.

The fields that are available for this section are as follows:

• List Format: this option allows you to change the format of the list. The options that are available in this list are as follows:
  • Standard List: this format allows you to display the list on a single page, or broken up across multiple pages, for example 10 assets per page.
  • A-Z: this format displays the list grouped by the first character of the assets short name. If you select this option, you need to add the keyword replacement Page List on the Page Contents Bodycopy. This will show a hyperlink to each character in the alphabet. When you click on the hyperlink, it will list the assets that start with that character. Assets that start with numbers or other characters will be listed under a hyperlink called [Other]. You can change the wording of this hyperlink in the Non A-Z page text field, outlined below.
    An A-Z listing can also be created on a Single Page by configuring the A-Z Listing Style and A-Z Letter Format fields, outlined below.
    For more information on this format, refer to the A-Z Listing chapter in this manual.
  • Custom Grouping: this format displays assets grouped by the grouping conditions set up on the Asset Grouping screen. For more information about this screen, refer to the Asset Grouping Screen chapter in this manual.
  • Random: this format randomly displays results from the list. For more information about setting up a random list, refer to the Random Listing chapter in this manual.
• Assets Per Page: enter the number of assets to show on a page. You can use this field to restrict the number of assets that are seen on the page or break up the assets into a number of pages. To do this, add the keyword replacements Previous Page Link and Next Page Link to the Page Contents Bodycopy so that the user can navigate to the next page of asset. Keyword replacements can also be used within this field to dynamically set the number of assets per page.
  

  If you try and list more than 1000 assets on a single page, Matrix will throw a performance warning saying that the listing is exceeding the performance threshold. However, Matrix will allow you to list as many assets as the PHP Web Memory limit will alllow. It is therefore recommended to stay under the 1000 threshold.

• Start Position: this preference allows you to specify an asset position to start the listing at. By default, this field is set to 0, meaning that this option is disabled and the listing will list the assets as normal. Setting this field to 5, for example, will start the listing from the fifth asset and list the remaining assets from that position, as shown in the figure below.

  
  An example of the Start Position preference (right)

  When using custom groupings, this setting will apply to the individual group listings.
• A-Z Listing Style: this preference allows you to determine whether to list assets on a single page or on multiple pages when using the A-Z list format. By default, this preference will be set to Multiple Pages. This means that users will be able to navigate through pages of assets, with each page representing a different letter. A Single Page A-Z listing will list all these assets on the one page, categorised under letter headings. Clicking a letter on the page list at the top of the screen will automatically take you to the corresponding section of the page. For more information on the A-Z list format, refer to the A-Z Listing chapter in this manual.
• A-Z Letter Format: this preference allows you to format the letter headings on an A-Z listing using Multiple Pages. This format uses the keyword replacement %letter_group% to display the letters in the headings. For more information on the A-Z list format, refer to the A-Z Listing chapter in this manual.
• Previous Link: enter the text that will be used for the hyperlink to the previous results page. This will be shown when you add the keyword replacement Previous Page Link to the Page Contents Bodycopy. By default this is set to Previous.
• Next Link: enter the text that will be used for the hyperlink to the next results page. This will be shown when you add the keyword replacement Next Page Link to the Page Contents Bodycopy. By default this is to Next.
• Non A-Z page text: by default, this field will only appear on the Details screen when the List Format has been set to A-Z listing. It allows you to change the wording for the hyperlink [Other]. This hyperlink will display the assets that start with numbers or special characters. For more information on the A-Z listing, refer to the A-Z Listing chapter in this manual.
• Page Link Format: this format defines the individual layout of items on the listing's linked page list when you are listing results over multiple pages. If you are using the A-Z list format, this will define the individual layout of items on the linked character list.
• Current Page Format: this format defines the layout of the current page number on the listing's linked page list when you are listing results over multiple pages. If you are using the A-Z listing format, this will define the layout of an item in the linked character list when no results are found under that particular letter.
• Hide Unlinked Navigation Text: this option allows you to hide any unlinked navigation text on the search results when you are listing results over multiple pages, i.e the Previous Page link will not appear on the first page of the results and the Next Page link will not appear on the last page of the results.

Customise Bodycopies

This section allows you to specify whether or not the Asset Listing should use the Page Contents (No Results) Bodycopy.

By default, the Customise No Results Bodycopy will be set to Yes. This means that the Asset Listing will use the contents that have been specified in the Page Contents (No Results) Bodycopy. Set this field to No if you do not want to use this Bodycopy.

List Position Settings

This section allows you to specify that a particular asset be displayed in a particular position in the list. For example, if you want the Home page to always appear as the first asset in the list, you would specify an asset position of 1 for the Home page.

By default, no positions have been set, as shown in the figure above. To set a position, in the New Asset Position field, enter the number of the position in the first box and select the asset in the second box. The position setting will appear in the Asset Positions list, as shown in the figure below.

The Asset Positions list

To change the asset that has been selected in a position, click the Change button. To remove a list position setting, click the Delete box and click Commit. To add additional position settings, use the fields available in the New Asset Position field.

Dynamic Parameters

This section allows you to specify an alternate root node for the Asset Listing based on GET, POST or SESSION variables, current asset, current user, current site, set value or any global value. Any dynamic root node passed to the Asset Listing must be located under the asset(s) specified in the Root Node field on the Details screen.

The fields that are available in this section are as follows.

• Parameter: Select the parameter to replace in this field. The options available include: Replacement Root node for the listing or Array of specific asset IDs or selection group.
  • Replacement Root node for the listing: This will allow you to supply one or more asset IDs as the root nodes to use for the Asset Listing.
    

    To pass multiple root nodes, use a comma separated list, eg. "1111,2222,3333".

  • Array of specific asset IDs or selection group: This will allow you to supply one or more asset IDs as the specific assets to list.
    

    Multiple Specific IDs for the Array of specific asset IDs option can be entered as a Set Value, delimited by commas or semicolons. The value can also be written as an array eg. "[1234 , 5678]".

• Source: Select where the Asset Listing should source the alternate root node. You can select one of the following options:
  • GET Variable Name: This allows you to enter a GET parameter. You can set a link on another page to call this page with the appropriate GET parameter. Alternatively, this can be used in conjunction with the Structured Root Selector Options to set the root node to an asset the user selects from a list on the page. For more information on setting up the structured root selector, refer to the Structured Root Selector chapter in this manual.
  • POST Variable Name: This allows you to enter a POST parameter.
  • SESSION Variable Name: This allows you to enter a SESSION parameter.

    Use the list_current_asset_id session variable on a nested Asset Listing Page to display additional information from the children of listed assets. For more information, refer to the List Current Asset ID chapter in this manual.

  • Current Asset: This allows you to set the root node of the Asset Listing according to the asset the user is viewing. For example, say you have an ArticleFolder in your Site. Under that Folder, there are a number of topic pages with articles for that topic stored beneath it in the hierarchy. When a user is viewing a topic page, you want to display the articles for that page in the sidebar of the design. In this case you would nest an Asset Listing in your Design and set the root node for the Asset Listing in the Dynamic Parameters section to be the Current Asset. The Asset Listing will then list the articles for the topic the user is currently looking at.
  • Current User: This allows you to set the root node of the Asset Listing to the user who is currently viewing the page. This can be a logged in user.
  • Current Site: This allows you to set the root node of the Asset Listing to the Site the user is currently viewing.
  • Set Value: This allows you to enter a static value. You can set multiple root nodes using this source type by entering a comma-separated list of asset IDs, e.g. 2000,2001,2005.
  • Any Global Value: This allows you to enter a value for any of the major super global arrays. The SESSION, POST and GET variables will be checked in succession until a value is found.
• If dynamic root not found: Specify the action to take when no dynamic root is returned from the configured Dynamic Parameter. The options available are:
  • Use static root node: Reverts back to the Asset Listing Page's static root node settings. This will either be an asset(s) configured in the Root Nodes field or the Asset Listing Page, itself.
  • Return empty result: Returns no results on the Asset Listing Page. This is the default value for this field.
• If asset selection not specified: Specify the action to take when no asset selection is returned from the configured Dynamic Parameter. The options available are:
  • Use static root node: Reverts back to the Asset Listing Page's static root node settings. This will either be an asset(s) configured in the Root Nodes field or the Asset Listing Page, itself.
  • Return empty result: Returns no results on the Asset Listing Page.

To set up a dynamic parameter, select the parameter you want to use from the first list, select a Source from the second list and click Commit. An additional field will appear in the Dynamic Parameter section, as shown in the figure below.

An example Dynamic Parameter

Enter the value for the source into the field. To delete a dynamic parameter, click the Delete box and click Commit.

Using Multiple Sources

If you use multiple Sources , only the first one that returns a non-empty value will be used.

Consider the following example:

Here we have 3 different GET sources. Matrix will first check the first source, root-a, and if it contains a value, it will use that as the root node and ignore all the other sources.

If root-a returns an empty string, then Matrix will proceed to check the next value which is root-b, and so on.

If you add an Array of specific asset IDs parameter source, it will always overwrite any Replacement Root node parameter sources you might have already added. Even if the array returns an empty value, it will NOT proceed to then check the Replacement Root nodes. In summary, only one method can be used at any time.

Structured Root Selector Options

This section allows you to set up a list of root nodes that the user can select from on the page to use as a base for the listing.

The fields that are available in this section are as follows.

• Name: enter the name for the structured root selector. The name you enter into this field must be the same as the name you use for the GET Variable Name parameter in Dynamic Parameters section.
• Root Node: select the parent asset for the list of assets.
• Depth: enter the number of levels of assets to include in the list. For example, if you only want to shown the assets under the root node, enter 1 into this field. If you enter 0, it will show all assets of the specified type under the root node.
• Asset Types: select which asset types to show in the list. For example, if you only want to show the folders under the root node in the list, select Folder. You can also check the inherit box to specify that the list should include all child types of the selected asset type. To add additional asset types, click the More... button. An additional field will appear on the screen. To delete an asset type from the list, click the Clear button.
• Style: select the style of list to show on the Asset Listing page. You can select Drop-down List, Radio Buttons or Check Boxes.
• Width: enter the width of the list. If you leave this as 0, the list will automatically resize to the longest name in the list.
• Height: enter the height of the list.
• Separator: enter the separator character to use in the list to show the hierarchy of the assets. By default this is set to -.

For more information on how to set up the structured root node list, refer to the Structured Root Selector chapter in this manual.

Button Text

This section allows you to change the wording of the buttons for the Asset Listing page.

The fields that are available in this section are as follows:

• Submit Button Text: enter the text to show on the submit button. By default, this text is Submit. This button is shown when the keyword replacement Submit Button is used on the Page Contents Bodycopy.
• Reset Button Text: enter the text to show on the reset button. By default, this text is Reset. This button is shown when the keyword replacement Reset Button is used on the Page Contents Bodycopy.