FlexibleSiteIndex

What Does it Do?

Flexible Site Index allows you to create a site index that is hierarchical, customizable, stylable, and (X)HTML compliant. You can add multiple entries for any given page/URL/document/website/resource, categorized in any way you see fit. It creates a hierarchy -- a taxonomy -- of topics, organized alphabetically. You can include pages in your site as well as pages or web sites outside of the scope of your web site. You can create any kind of hierarchical list, really, and make the links say whatever you want. With the configurable custom CSS classes, you can add styles to the end result to make it look however you want it to look.

Here's an example. People looking for information about law courses may want to look for the information under "law," or "courses," or "academics," or some other heading. You may want to make entries in the site index along these lines:

Courses > Law Courses

Law > Courses

Academics > Courses > Law Courses

Academics > Law > Courses

Other headings or structures may be appropriate too. The Flexible Site Index can take all of these into account and automatically generate a hierarchical list based on this information.

This script relies on two template variables. One template variable lets you choose whether to have the site index terms show up in the site index or not. The other template variable stores the site index terms.

1. Create the "FlexibleSiteIndex" snippet

• Create a new snippet called "FlexibleSiteIndex" (in the MODx manager under Resources > Snippets)

• Paste in the content from the "FlexibleSiteIndex.snippet.php" file.

• Modify any configuration settings that you want to modify (see the tables of configuration settings at the bottom of this page).

• Place the "flexiblesiteindex" folder (with the FlexibleSiteIndex.class.php file) in your assets/snippets folder.

• If you customize the name of the folder or file at all, make sure the path to your folder is set in the snippet parameters base_dir, snippets_dir, and fsi_dir

2. Set up the first template variable

• Create a new template variable (in the MODx manager under Resources > Template Variables)

• Give it a name (e.g. "site_index_show")

• Give it a caption (e.g. "Show in Site Index?")

• Choose "Radio Options" from the list of options under "Input Type."

• Enter this for the Input Option Values (without the quotes): "Yes==1||No==0"
  Note: The snippet does not check the default value of the template variable, so leave it blank. Setting the default to "1" will NOT automatically include every page in the site index. To include all pages, set scope_of_site_index = 1 (for universal inclusion) or scope_of_site_index = 2 (for limited exclusion of the files that you mark as "No").

• Check the checkbox(es) next to the template(s) used on your site (or at least the ones associated with documents that you want to include in the site index). If you create templates later, you will need to add this template variable to the new templates too.

3. Set up the second template variable

• Create a new template variable (in the MODx manager under Resources > Template Variables)

• Give it a name (e.g. "site_index_terms")

• Give it a caption (e.g. "Site Index Term(s)")

• Choose "Textarea" from the list of options under "Input Type."

• Check the checkbox(es) next to the template(s) used on your site (or at least the ones associated with documents that you want to include in the site index). If you create templates later, you will need to add this template variable to the new templates too.

4. Choose which pages to Include in the Site Index

• First, decide which method you want to use for including pages in the site index. You have three options, which you can set with the scope_of_site_index parameter:
  0 = Limited inclusion: Include only the documents marked for inclusion according to the include_in_index_tmplvar_id template variable (subject to restrictions specified by the include_unpublished and include_deleted settings)
  1 = Universal inclusion: Ignore the include_in_index_tmplvar_id template variable. Include all documents on the site (subject to restrictions specified by the include_unpublished and include_deleted settings)
  2 = Limited exclusion: Include all documents in the site except the ones marked for exclusion with the include_in_index_tmplvar_id template variable. (subject to restrictions specified by the include_unpublished and include_deleted settings)

• If you're going to use option 1 (universal inclusion) you don't have to do anything else.

• To use option 0 (limited inclusion), go to a page in the MODx manager and go into the edit mode, then for all of the pages that you want to INCLUDE in the site index, select the "Yes" option for the "Show in Site Index?" template variable.

• To use option 2 (limited exclusion), go to a page in the MODx manager and go into the edit mode, then for all of the pages that you want to EXCLUDE in the site index, select the "No" option for the "Show in Site Index?" template variable.

5. Populate the Site Index Terms

• For all pages where "Show in Site Index" is set to "Yes," the script will use the site index terms you create, or else the "menutitle," "pagetitle," or "longtitle," in that order, depending on which values are not empty.

• To create your own site index terms and hierarchy, enter in the site index terms in the "Site Index Term(s)" field as you want them to appear in the site index. You must put each term on its own line.

• If you want to create a hierarchical structure, use the "greater than" symbol (>, with spaces on both sides) to show the hierarchical relationship (or, if you've changed the hierarchy delimiter, use that delimiter instead). Enter all of the levels of the hierarchy on the same line.

NOTE: As of version 2.0, the snippet supports a hierarchy up to 10 levels deep.

6. Create a Chunk for Terms and Links Outside of the MODx Document Structure

• If you want to add external websites/documents/resources (or resources in MODx that aren't in the MODx document tree) to your site index, create a new chunk.

• The default name is "site_index_external_links," but you can give it any name you like, as long as you specify the name in the configuration settings or in the parameters when calling the snippet.

• Add each link on a separate line

• The structure is the same as when adding terms in the template variables, except that you need to put the web address at the end of the terms (it must start with "http"), preceded by two underscores, like this:
  Google__http://www.google.com
  Microsoft__http://www.microsoft.com
  Software Giants > Google__http://www.google.com
  Software Giants > Microsoft__http://www.microsoft.com
  ... and so on

• It's okay to insert blank lines as a way to organize the information. They will be ignored.

• You may insert code comments by placing a pound sign (#) at the very beginning of the line (it must be the first character, with no preceding spaces). For example:
  This line > will create > a site index entry
  # This line is a comment and will be ignored

NOTE: As of version 2.0, the snippet supports a hierarchy up to 10 levels deep.

7. Insert a Call to the FlexibleSiteIndex Snippet in a Document

• Call the snippet with this code:
  [[FlexibleSiteIndex]]

• If you want to set some parameters in the snippet call, you may do so. For example:
  [[FlexibleSiteIndex? &div_wrap_everything=`0` &strong_level_1=`0`]]

Pagination

If you want to have the terms for only one letter at a time show on a page, set the pagination parameter to '1'. The default page is the letter "A," but you can change this by setting a different value for the pagination_start_letter parameter.

IMPORTANT: If you turn pagination on, either the snippet or the page must be uncached. To set the snippet to uncached, use exclamation points in the snippet call:

[!FlexibleSiteIndex!]

[!FlexibleSiteIndex? &div_wrap_everything=`0` &strong_level_1=`0`!]

Configuration Settings

All of these settings can be set either in the snippet's default values, or in calls to the snippet.

• index_text_tmplvar_id
  • Options: [integer]
  • Default Value: [NULL]
  • Explanation: Optional. The id of the template variable that you are using to mark pages for inclusion in the site index. (Using the ID rather than the name [see next row below] may improve performance very slightly, because it eliminates one of the queries.)
• index_text_tmplvar_name
  • Options: [string]
  • Default Value: site_index_terms
  • Explanation: The name of the template variable mentioned above. Use this if you don't know the numerical ID of the template variable.
• include_in_index_tmplvar_id
  • Options: [integer]
  • Default Value: [NULL]
  • Explanation: Optional. The id of the template variable that stores terms used in the site index. (Using the ID rather than the name [see next row below] may improve performance very slightly, because it eliminates one of the queries.)
• include_in_index_tmplvar_name
  • Options: [string]
  • Default Value: site_index_show
  • Explanation: The name of the template variable mentioned above. Use this if you don't know the numerical ID of the template variable.
• include_yes
  • Options: [string]
  • Default Value: 1
  • Explanation: This is the value in the template variable that means "yes, include this page in the site index." If you follow the instructions above when creating the template variables (by setting the Input Option Values to "Yes==1||No==0"), a value of "1" causes a page to be included. A value of "0" will cause it to be excluded. You can change the values in your template variable -- for example, you could store "yes" and "no," but if you do, you will have to set the "include_yes" value to "yes" so that the script can find the pages with this value.
• pagination
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; Put each alphabetical section on its own page or not
• pagination_start_letter
  • Options: [string]
  • Default Value: A
  • Explanation: When in pagination mode, the first page to go to
• alpha_links
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; If set to yes, a list of alphabetical characters will appear at the top of the site index, with links to the corresponding alphabetical headings below
• alpha_links_only
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; If set to yes, ONLY thelist of alphabetical characters will appear; no site index terms. This can be useful if you want to have two calls to the snippet, for example to separate the links from the lists
• alpha_links_bottom
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; If set to yes, a copy of the alphabetical links will appear at the bottom of the list, in addition to the alphabetical links at the top.
• alpha_links_span
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; Whether to surround the links in the list of alphabetical character links at the top with <span> elements or not. It may be useful for styling purposes, but is otherwise unnecessary.
• alpha_links_container
  • Options: [string]
  • Default Value: div
  • Explanation: The element to surround the list of alphabetical character links at the top
• alpha_headings_level
  • Options: [string]
  • Default Value: h2
  • Explanation: The snippet generates headings for each letter of the alphabet that has related links. What level of heading do you want to use? It can be any element (even div, p, etc.) but headings are recommended (h1, h2, h3, h4, h5, or h6)
• alpha_headings_id_prefix
  • Options: [string]
  • Default Value: site_index_
  • Explanation: The prefix at the beginning of the "id" in the headings, used as an anchor (link destination) for the alphabetical links at the top. The resulting id for heading "A" will look something like this: id="site_index_A"
• hierarchy_delimiter
  • Options: [string]
  • Default Value: ' > ' (the "greater than" symbol, surrounded by spaces)
  • Explanation: The character(s) to use to show the hierarchical structure, e.g.: Academics > Courses > Law Courses
• external_links_chunk
  • Options: [string]
  • Default Value: site_index_external_links
  • Explanation: The chunk that contains terms and links to external web sites to be included in the site index.
• modx_table_prefix
  • Options: [string]
  • Default Value: modx_
  • Explanation: The prefix for the database tables
• print_new_line_return
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; Printing a line return in the source code makes the source easier to read, but leaving it off may improve performance slightly, especially for long site indexes.
• new_line_return_code
  • Options: [string]
  • Default Value: \n
  • Explanation: The PHP code to use for the "new line" return.
• include_unpublished
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; Include unpublished pages in the site index?
• include_deleted
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; Include deleted pages in the site index?
• include_privateweb
  • Options: 1 || 0
  • Default Value: 0
  • Explanation: 1 = "yes", 0 = "no"; Include restricted (possibly password-protected) pages in the site index?
• div_wrap_everything
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; Wrap the entire site index and alphabetical list at the top in a <div>?
• div_wrap_heading_sections
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; Wrap each heading with its associated list in a <div> container?
• strong_level_1
  • Options: 1 || 0
  • Default Value: 1
  • Explanation: 1 = "yes", 0 = "no"; Put <strong> tags around the top level entries in the site index lists to make them stand out more?
• scope_of_site_index
  • Options: 0 || 1 || 2
  • Default Value: 0
  • Explanation:
    0 = Limited inclusion: Include only the documents marked for inclusion according to the include_in_index_tmplvar_id template variable (subject to restrictions specified by the include_unpublished and include_deleted settings)
    1 = Universal inclusion: Ignore the include_in_index_tmplvar_id template variable. Include all documents on the site (subject to restrictions specified by the include_unpublished and include_deleted settings)
    2 = Limited exclusion: Include all documents in the site except the ones marked for exclusion with the include_in_index_tmplvar_id template variable. (subject to restrictions specified by the include_unpublished and include_deleted settings)
• num_heading
  • Options: [string]
  • Default Value: 0-9
  • Explanation: The text for the heading for numbered terms
• set_placeholders
  • Options:
  • Default Value:
  • Explanation: NOT YET FUNCTIONAL
• alpha_links_placeholder
  • Options:
  • Default Value:
  • Explanation: NOT YET FUNCTIONAL
• site_index_placeholder
  • Options:
  • Default Value:
  • Explanation: NOT YET FUNCTIONAL
• base_dir
  • Options: [string]
  • Default Value: $modx->config['rb_base_dir']
  • Explanation: The base directory of the assets folder
• snippets_dir
  • Options: [string]
  • Default Value: snippets/
  • Explanation: The snippets folder name: slash at end is REQUIRED; No slash at beginning
• fsi_dir
  • Options: [string]
  • Default Value: flexiblesiteindex/
  • Explanation: The flexiblesiteindex folder name: slash at end is REQUIRED; No slash at beginning

CSS Configuration Settings

All of these settings can be set either in the snippet's default values, or in calls to the snippet.

• alpha_links_container_class
  • Default Value site_index_alphalinks
  • Code <div class="site_index_alphalinks">
• alpha_links_class
  • Default Value [NULL]
  • Code <a class="your_value_here">
• alpha_links_bottom_class
  • Default Value alpha_bottom
  • Code <div class="alpha_bottom">
  • Notes This is an extra div surrounding the bottom alphabetical links, if present
• alpha_links_span_class
  • Default Value site_index_alpha_link
  • Code <span class="site_index_alpha_link"> <a href="...
• headings_class
  • Default Value site_index_heading
  • Code <h2 class="site_index_heading">
• list_class
  • Default Value list_level
  • Code <ul class="list_level_2">
  • Notes The level number will be appended to the end of the class
• li_class
  • Default Value li_level
  • Code <li class="li_level_2">
  • Notes The level number will be appended to the end of the class
• li_link_class
  • Default Value [NULL]
  • Code <a class="your_value_here">
• div_wrap_everything_class
  • Default Value site_index_wrapper
  • Code <div class="site_index_wrapper">
• div_wrap_heading_sections_class
  • Default Value heading_section_wrapper
  • Code <div class="heading_section_wrapper"> <h2>...

Advanced Uses

Multiple Indexes, Different Terms

You can create multiple kinds of indexes on your site by creating template variables for each different index. For example, you might have a general site index, plus you may have an index just for keeping track of your blog post topics. To set up the two indexes, create two sets of template variables. When calling the snippet, specify which template variables you want to use. Calling the general site index might look like this (assuming you leave the default snippet names in place):

[[FlexibleSiteIndex]]

The snippet call for your blog posts might look something like this:

[[FlexibleSiteIndex? &include_in_index_tmplvar_name=`blog_index_show` &index_text_tmplvar_name=`blog_index_terms`]]

Multiple Site Indexes, Same Terms

It is even possible to share the same template variable for the terms, but have two different template variables that decide whether to include those terms in two different site indexes. This might come in handy if you need a full site index plus a limited version of the same site index. The snippet call for the full site index might look like this: [[FlexibleSiteIndex]]

The snippet call for the limited site index might look something like this:

[[FlexibleSiteIndex? &include_in_index_tmplvar_name=`site_index_show_limited`]]

Filtering Ditto Results by Your Site Index Terms

You can retrieve documents from your site using Ditto, filtering the results with your site index terms. Refer to the Ditto documentation about filtering for detailed instructions. A couple of examples are shown below.

Example 1: Retrieve only the documents that have "Courses > 2008" in the site index terms: [[Ditto? &parents=`0` &depth=`0` &filter=`site_index_terms,Courses > 2008,7`]]

Example 2: Exclude documents with "Courses > 2008" in the site index terms:

[[Ditto? &parents=`0` &depth=`0` &filter=`site_index_terms,Courses > 2008,8`]]

Note: You will need to think through the filtering options carefully. Depending on how you set things up, you may or may not get the results you want. For example, if the phrase "Courses > 2008" shows up in more than one part of the taxonomy (e.g. "Academics > Courses > 2008" and "Law > Courses > 2008"), this may thwart your filtering plans.