Navigation - AppDaddy-Software-Solutions-Inc/framework-markup-language GitHub Wiki

      App navigation in FML is as easy as using a few events. The stack based navigator allows for simple, single page style applications at its core. As well as allowing for multiwindow/tab style applications using widgets such as TREEVIEW, and overlays using MODAL.

      In FML, navigation is stack based. As a user open()s a page, it is added onto the stack and kept track of until the application is exited. When a user preforms back() or close() on the application, the page is popped off of the top of the stack. Multiple navigation events triggered from the same action will continue to preform even when the first page is exited. For instance, if the event string is onclick="back();back();", two pages will pop in unnoticeable rapid succession. Using the back(), open() and replace() events, a developer can effectively manipulate the users position in the stack as desired. Using the close() event, a developer can close() widgets such as DRAWER or MODAL within the same TEMPLATE.

      The open() event is likely the first event you will use when moving from a single to a multipage application. The open() event adds the given url to the navigation stack. It also allows for us to pass certain parameters that will allow for further manipulation of the navigation experience. The parameters involve in open() are 'url', 'modal', 'transition'. Url is simply the url of the template or external page you are wanting to open. The open url allows for either a relative or absolute url. If the url is relative (existing within the domain your application is hosted on), such as open('templates/new-page.xml'), the open() event will add the page onto the stack. If an absolute url (containing the fully qualified domain name) such as open('http://google.com/'), FML will attempt to open a new tab or browser outside of the current application.

      The open() url can also be used to pass datasources and data forward to templates that are within the application using url parameters added using a question mark. Datasources can be passed using data=_id,_id,_id, with comma seperated strings being each sources id from the current template that is preforming the open() event. Other parameters can be assigned and renamed using _name=value. These can be chained together using & or & for a near unlimited passing of data. For more in depth information on passing data values, you can visit databinding.

** It is recommended that all passed in binding names and id's start with an _.

      The modal parameter on open accepts a boolean value, and dictates if the relative url will be opened and added to the stack, or displayed as a MODAL overlay. In the case of the MODAL widget, id.open() without any parameters will cause the modal to open. In the case where it is desired to open an existing template as a MODAL, the url can pass width= and height= as parameters to the open command.

      Finally, transition dictates the type of transition between the two pages that will happen. It defaults to the type of transition specified by the platforms design standard, such as slide for ios and macos. The options for transition are rotation, scale, slide, slideright, slideleft, linux (fade), windows (fade), android (scale), ios (slide), and macos (slide).

<FML>
    <GET id="_d1" url="api/sample">
    <BOX expand="false">
          <BTN label="Open a new window with an external source" color="green" onclick="open('https://fml.dev/');" />
	  <BTN label="Open as a MODAL" color="green" onclick="open('resources/templates/new.xml', true);" />
	  <BTN label="Open a new template" color="green" onclick="open('resources/templates/new.xml');"/>
	  <BTN label="Open and pass the datasource and a custom value" color="green" onclick="open('resources/templates/new.xml?data=_d1&amp;_newvalue=7');" />
    </BOX>
    <DRAWER id="d1"/>
</FML>

      The back() event can pop items from the stack in any number, navigate backwards through the stack for a specific page, popping until that page, as well as simply pop the current page. If back() is supplied with a relative url, it will search the stack for that url and pop until it reaches that page. If back() is given a number back([#]), it will pop that many pages off of the stack or stop at the first page on the stack. The popuntil function can be useful in single page applications that have a home screen with multiple navigation routes for that home screen.

If a developer wants to prevent a user from going back() after opening a page, the replace('url') event can be used. replace() removes the current page in the stack and opens the intended page in its place.

The close() event will take an to close() specific widgets such as DRAWER, or will walk up the widget tree and close the first widget that accepts close. If this is the outer most [TEMPLATE], the page will be popped off of the stack like back().

<FML>
    <BOX expand="false">
          <BTN label="Go Back 2 Pages" color="green" onclick="back([2]);" />
	  <BTN label="Go Back 1 Pages" color="green" onclick="back();" />
	  <BTN label="Go Back until HOME is hit" color="green" onclick="back('resources/templates/home.xml');"/>
	  <BTN label="Replace this page with NEW page" color="green" onclick="replace('resources/templates/new.xml');" />
          <BTN label="Close the drawer" color="green" onclick="d1.close();" />
    </BOX>
    <DRAWER id="d1"/>
</FML>