RIFE : Paged navigation builder

The PagedNavigation class provides utility methods to generate navigation for paged lists.

The generation of the navigation depends on a collection of block and value IDs that should be defined in a template. Following is a table of all the IDs and their purpose:

Description

<!--B 'NAV:FIRSTRANGE'--><!--/B-->

Provides the content that will be used to jump to the first range. This block has to contain an EXIT:QUERY value that will be replaced with the actual URL that will trigger the paging behaviour.

<!--B 'NAV:FIRSTRANGE:DISABLED'--><!--/B-->

Provides the content that will be used when jumping to the first range is not appropriate, for instance when the first range is already the current offset.

<!--B 'NAV:PREVIOUSRANGE'--><!--/B-->

Provides the content that will be used to jump to the previous range according to the current offset. This block has to contain an EXIT:QUERY value that will be replaced with the actual URL that will trigger the paging behaviour.

<!--B 'NAV:PREVIOUSRANGE:DISABLED'--><!--/B-->

Provides the content that will be used when jumping to the previous range is not appropriate, for instance when the first range is the current offset.

<!--B 'NAV:ABSOLUTERANGE'--><!--/B-->

Provides the content that will be used to jump directly to each individual range. This block has to contain an EXIT:QUERY value that will be replaced with the actual URL that will trigger the paging behaviour.

<!--B 'NAV:ABSOLUTERANGE:DISABLED'--><!--/B-->

Provides the content that will be used when jumping directly to a specific individual range is not appropriate, for instance when that range corresponds to the current offset.

<!--B 'NAV:NEXTRANGE'--><!--/B-->

Provides the content that will be used to jump to the next range according to the current offset. This block has to contain an EXIT:QUERY value that will be replaced with the actual URL that will trigger the paging behaviour.

<!--B 'NAV:NEXTRANGE:DISABLED'--><!--/B-->

Provides the content that will be used when jumping to the next range is not appropriate, for instance when the last range is the current offset.

<!--B 'NAV:LASTRANGE'--><!--/B-->

Provides the content that will be used to the last range. This block has to contain an EXIT:QUERY value that will be replaced with the actual URL that will trigger the paging behaviour.

<!--B 'NAV:LASTRANGE:DISABLED'--><!--/B-->

Provides the content that will be used when jumping to the last range is not appropriate, for instance when the last range is already the current offset.

<!--V 'NAV:RANGECOUNT'/-->

Will contain the number of ranges that are needed to display all the information that is paged. This value is optional.

<!--V 'NAV:FIRSTRANGE'/-->

Will contain the content that allows to jump to the first range. This corresponds to the beginning of the paged data.

<!--V 'NAV:PREVIOUSRANGE'/-->

Will contain the content that allows to jump to the previous range according to the current offset.

<!--V 'NAV:ABSOLUTERANGES'/-->

Will contain the content that allows to jump directly to each individual range that is available.

<!--V 'NAV:NEXTRANGE'/-->

Will contain the content that allows to jump to the next range according to the current offset.

<!--V 'NAV:LASTRANGE'/-->

Will contain the content that allows to jump to the last range. This corresponds to the end of the paged data.

In addition to these template conventions, you must also provide one exit and one output that will be used to create the links that will perform the actual paging behaviour of the navigation. By default, the change_offset exit and the offset output will be used. It is up to you to create the datalink and flowlink and to correctly handle the offset value when it changes.

<!--B 'NAV:FIRSTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&lt;&lt;</a><!--/B-->
<!--B 'NAV:FIRSTRANGE:DISABLED'-->&lt;&lt;<!--/B-->
<!--B 'NAV:PREVIOUSRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&lt;</a><!--/B-->
<!--B 'NAV:PREVIOUSRANGE:DISABLED'-->&lt;<!--/B-->
<!--B 'NAV:ABSOLUTERANGE'-->&nbsp;<a href="[!V 'EXIT:QUERY:change_offset'/]"><!--V 'ABSOLUTERANGE_TEXT'/--></a>&nbsp;<!--/B-->
<!--B 'NAV:ABSOLUTERANGE:DISABLED'-->&nbsp;<!--V 'ABSOLUTERANGE_TEXT'/-->&nbsp;<!--/B-->
<!--B 'NAV:NEXTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&gt;</a><!--/B-->
<!--B 'NAV:NEXTRANGE:DISABLED'-->&gt;<!--/B-->
<!--B 'NAV:LASTRANGE'--><a href="[!V 'EXIT:QUERY:change_offset'/]">&gt;&gt;</a><!--/B-->
<!--B 'NAV:LASTRANGE:DISABLED'-->&gt;&gt;<!--/B-->

Pages: <!--V 'NAV:RANGECOUNT'/--> ( <!--V 'NAV:FIRSTRANGE'/-->
       <!--V 'NAV:PREVIOUSRANGE'/--> <!--V 'NAV:NEXTRANGE'/-->
       <!--V 'NAV:LASTRANGE'/--> | <!--V 'NAV:ABSOLUTERANGES'/--> )

This templating could result in the following output, where all the underlined parts are clickable and will trigger the change_offset exit and provide a new corresponding value for the offset output:

The element that displays the list and calls the navigation generation method could for example be like this:

@Elem(inputs={@Input(name=List.INPUT_OFFSET)})
public class List extends Element
{
    public final static int LIMIT = 10;
    public final static int SPAN = 5;

    /* The name of the input that holds the list offset. */    
    public static final String INPUT_OFFSET = "offset";

    /* Declares a flowlink back to this element that's used when the
       user clicks on a navigation link. */
    @FlowlinkExitField(destClass=List.class, datalinks={
        @Datalink(srcOutput=INPUT_OFFSET, destInput=INPUT_OFFSET)})
    public static final String EXIT_CHANGE_OFFSET = "change_offset";

    public void processElement()
    {
        Template t = getHtmlTemplate("article.list");
        DatabaseArticles manager = DatabaseArticlesFactory.getInstance();
        
        int count = manager.countArticles();
        if (0 == count) t.setBlock("content", "noarticles");
        else
        {
            int offset = getInputInt(INPUT_OFFSET, 0);
            
            PagedNavigation.generateNavigation(this, t, count, LIMIT, offset, SPAN);
            
            Collection<Article> articles = manager.listArticles(LIMIT, offset);
            for (Article article : articles)
            {
                t.setBean(article);
                t.appendBlock("articles", "article");
            }
        }
        
        print(t);
    }
}