CMSList+ Rollup

About

1. Roll-up is a CMSList+ extension that's used to for quickly capturing information without having to worry about typesetting and text formatting. It provides the ability to quickly structure data, specify target audience and publish simply by providing the information in a plain text file.
2. Roll-up data are searchable from standard WordPress search. Roll-up also includes administration tools to help manage search integration and data clean-up.
3. Roll-up doesn't create any WordPress posts or taxonomies, nor does it touch any of the WordPress database and query mechanisms. The feature is available on CMSList+ since version 0.1.98, 0.0.53.

Data Organization

1. Storage

   1. Roll-up files must be stored under the UPLOADS directory.

   2. Files can be organized in sub-directories.

      1. Sub-directories should be hyperlink-friendly, short, descriptive, and use small caps.
      2. Use the sub-directory structure to logically group the files.

2. Files

   1. Roll-up files use the extension ".static".
   2. Roll-up files are called static files.

   3. For ease of access reasons, it is recommended that roll-up files should be hyperlink-friendly, short, descriptive, and use small caps.

      1. Examples:
          main.static
          download.static
          world-news.static
          recipe.static
          traning.static
   4. Where appropriate, create a static index file (e.g. main.static) when creating a logical group of static files, to serve as its table of contents.

Navigation

1. Browsing

   1. Static files are accessed through a browser using the link format:

      <website root>/cmslist/[<path>/]<static-file>

      Where:
        <website root> - is the website home link.
        cmslist - indicates the rollup is being accessed, and is required.
        <path> - is the sub-directory structure where the static file is found. Omit if on the top of the UPLOADS path.
        <static-file> - is the static file being accessed without the extension.
      
      Examples:
       Given a file named, "main.static" stored under UPLOADS and a site home http://acme.com, the link to main.static will be:

        http://acme.com/cmslist/main

       Given the file "onboarding.static", stored under directory "help" in UPLOADS, the link will be:

        http://acme.com/cmslist/help/onboarding

2. User Interface

   1. Roll-up is made up of lists which it expands one at a time.

      1. If another list is opened, the rest are rolled up.
      2. This is the default behaviour, but can be changed using Roll-up directives.

   2. A list can be expanded by tapping on the label.

      1. If the label is a link (dotted underline) then tap on a space anywhere on the line, otherwise you'll be activating the link which will take you to the location it's pointing to.

   3. A dot () indicates the line has a sub-list.

      1. A grey square (■) -a tap spot- will also appear at the end of a list item indicating it can be expanded.
   4. A circle () indicates the end of the list.
   5. An link (dotted underline) with italicized font indicates a link to another roll-up file on the site.
   6. A link (dotted underline) with normal font indicates an external link that will take you to another site.
   7. If a return link was indicated in the static file, a RETURN button will become available below the page title. Clicking it will take you to the parent list.

3. Navigation Bar

   1. Roll-up Navigation Bar is located between the roll-up description (or title) and the top of the list.

   2. The bar currently has two functions:

      1. List expand and collapse button: + =to expand, - =to collapse.

      2. In-page search activate button: lens button.

         1. Tapping it will open the in-page search bar located on the to of the page.
         2. The navigation bar is disabled while in-page search bar is active.

4. In-Page Search Bar

   1. In-Page Search is a similar function to a browser's find in page feature --which is activated by Ctrl+F keys on Desktops-- which allows you to search for items on the active page.
   2. In-page search is activated by tapping on the lense button on the roll-up navigation bar. Once activated, the roll-up list will be expanded.

Composition

1. Static Files

   1. Static files are plain text files. You can use your favorite text editor to compose it.
   2. Below is an example of a static file, named "trips.static", and it's resulting roll-up page:
      
      (Tap on the image to zoom.)
      

   3. Static file structure is as follows:

      1. Roll-up title is any title you want for the file, and ends with a semi-colon.

      2. Return-path is the link to the parent file, any. It's the directory path from the UPLOADS and the static file. Example:

         1. main - is a return link to the main.static file stored directly under UPLOADS.
         2. help/intro - is a return link to the intro.static file stored under UPLOADS/help directory.
      3. Directives - are any one of available roll-up directives.
      4. Start: - indicates the start of the list.

      5. #Section# - indicates the top of the list, with Section being the label.

         1. Sections must start on the first tab from the left.
         2. Sections must be wrapped by the # sign.

      6. List item, sub-list - are TAB indented lines that forms the list below a section.

         1. List items must start one tab after the section above it.
         2. Sub-items are a tab deeper from the list item above it.
   4. Other than the directives, anything written between the first line and Start: are ignored.

2. Sections

   1. Sections forms the main list grouping. You can think of it as chapters in a book.
   2. A static file can have any number of sections.
   3. Sections are separated by an empty line.
   4. List items in a section must not have an empty line, otherwise the line following it will be discarded.

3. Markup

   1. Line formatting

      1. Sections, list items and Rollup-About directive allows HTML markup.

      2. Links are automatically converted to clickable links. But if this isn't the desire outcome, simply use HTML entities to alter the link format,

         1. e.g. replace "http://" with "http:&#47;&#47;" with &#47; being the HTML entity code for /.

   2. Roll-up Markups

      1. Roll-up markups are special formatting codes to make roll-up coding easier, and are converted to their actual HTML markups once the page is rendered.
      2. Link markup ( [<text>; <url>] ) will be rendered as clickable link with <text> being the label and <url> being the link.
      3. Superscript buttons ( [<SUP><text></SUP>; <url>] ) text wrapped with SUP are rendered as a small button, e.g. ¹, ^CNN.

      4. Substitutions are tags replaced with actual value once the page is rendered, making static files portable.

         1. #HOME# - is the substitution for the site's home link,

            1. Examples:

               1. #HOME#/cmslist/main - will be converted to the actual hyperlink of the main static file for the hosting website.
               2. [Operator's Manual;  #HOME#/cmslist/ops/main] - given the site, acme.com, the markup will be converted to a link with the label "Operator's Manual" that points to the hyperlink http://acme.com/cmslist/ops/main.

      5. Numbered List are list item enumeration using numbers instead of bullets.

         1. Prefix the first list sub-item with "{step}" to indicate the item and its siblings will use numbers instead of bullets.
         2. This markup only applies to the immediate list items, it doesn't cascade down to lower level lists. To use numbers on lower-level lists, repeat the procedure above.
         3. This markup has no effect on the top-level list.

4. Escaping

   1. There are times when characters that serves a special function in roll-up are needed in the actual static text. Replacing the character with their HTML entity equivalent will solve it.
   2. "#" character is used as section wrappers. To use the literal character, replace it with the HTML entity: &num;
   3. Other HTML entity replacements:

      ( ( 
      ) )
      [ [
      ] ]
      TAB  
      / /

Directives

1. Directives are special roll-up instructions that changes how the static file is rendered.
2. Show-Nav:<yes|no> - enables or disables the roll-up navigation bar above the list. Default is "yes".
3. Rollup-About:<text> - where text is the single line description which, if specified, will be placed above the list. HTML markups are allowed.
4. Rollup-Depth:<depth> - controls the depth of sub-list to roll-up, where <depth> is greater than 1. If specified, individual sub-list will roll-up between list items within the parent list.
5. Rollup-Expand:<depth> - initially expands the list from the second level (sub-items) to the depth indicated. Depth must be greater than 1.

6. Rollup-Audience:<user roles list> - where 'user roles list' is a comma-delimited list of WordPress user roles.

   1. Only users having roles that match the given audience will be able to open the roll-up file.
   2. If not specified, the file will be accessible to all roles with read permission.

   3. Examples:

      1. Rollup-Audience: contributor - will be available only to site contributors.
      2. Rollup-Audience: visitor, contributor, author, administrator - will be available only users assigned any of the roles.
      3. Rollup-Audience: visitor - will be available only to site visitors.

7. Note:

   1. If both Rollup-Depth and Rollup-Expand are used, and with depth greater or equal to expand, during initial view, the expand and collapse state of sub-items between sections are preserved as long as none of the sections are closed. This means, you can view multiple sub-items at the same time until you collapse a section - then it's back to the default behaviour.

Search

1. Static files are included in the standard WordPress search, and will appear on the first page under the category "Roll-up".

   1. This category is only for visual classification and is not a real WordPress taxonomy.

2. A lookup table is maintained for all the static files.

   1. This table is automatically updated and doesn't require user intervetion, except for instances where it needs to be wiped clean.
   2. The table is updated whenever the file is changed or deleted.

Tips

1. There are no set rules in organizing static files. It all depends on the information being captured.
2. If a static file is discussing more than one topic in greater detail, it is best to split the content in different static files and create an index file for the new files.
3. A static file that serves as an index (or table of contents) is named "main.static". A main static file can be created for each sub-directory grouping for uniformity.
4. Files referenced by an index should include a return link pointing to the index. Although, the return link can point anywhere, even omitted.