Routing and configuration

bnsf uses router-base internally.

Difference between App routing and API routing

There are two routing files:

• desktop.bundles/index/index.routing.yml
• desktop.bundles/index/index.api.routing.yml

each contains routes in the following format:

- id: page-index
  path: /

Routes from index.routing.yml are available both on the client and on the server, it's the routing of your application.

Routes from index.api.routing.yml are available only on the server, it's the routing of your API server(s).

There is a description of all possible routes parameters.

Examples

How you can use parameters in the routes

- id: page-2
  path: /another-page/file.{format}
  method: GET
  defaults: {format: json}
  requirements: {format: json|html}

Placeholders

In order to avoid duplication in routing configuration files, there is possibility to use %placeholders%:

- id: view
  path: /{projectId}/index.html
  host: %sub_domain%.%host%
  requirements: {projectId: '[\w-]+'}

To use them you'll need to create desktop.bundles/index/index.parameters.dist.yml:

host: example.dev
sub_domain: sub

How to adjust parameters for environment

index.parameters.dist.yml should contain parameters, convenient for all developers.

If somebody wants to use another parameters (host, for example, or you need different hosts for different environments, such as development and production), you can create index.parameters.yml:

host: example.com
sub_domain: sub

Note: index.parameters.yml must be in your .gitignore file.

Custom URL for API and static servers

There is also possibility to change port of the application (default is 3000) and host of the static server (default is localhost:8080). You should create desktop.bundles/index/index.config.node.yml with the following content:

app-kernel: // name of a block you want to configure
  port: %port% // parameters for the block
  staticHost: %static_host%

Of course, you'll need to add appropriate lines to the index.parameters.dist.yml:

port: 3000
static_host: localhost:8080

Note: after creating desktop.bundles/index/index.config.node.yml you'll need to clean the cache of bem-tools: bem make -m clean && bem make or, if you use gulpfile, generated with generator-bnsf: gulp clean && gulp.

How to generate URL from BEMTREE

Query to API

The first thing you should always remember is you should not use any URLs. If you just want to get some data from API it's enough to pass only route and parameters to get function provided by bnsf like this:

block('user').content()(function () {
    return this.get('login', {
        some: 'login params'
    }, function (data) {
        // do something great
    });
});

where login is a route id described in desktop.bundles/index/index.routing.yml as mentioned above and hash {some: 'login params'} is parameters for URL generation.

URL for link

Another useful thing is if you want to generate an URL you can use path function. For example let's create a link to main page:

block('logo').content()(function(){
  return {
    block: 'link',
    url: path('page-main'),
    content: 'My awesome service'
  };
})

you can pass parameters for route as second argument for path function as well.

How to generate URL from JavaScript

Sometimes you need an URL in JavaScript. You can generate it using the app-router-base block which is provide an instance of router-base. Let's write a piece of client JavaScript for user block in the file user.browser.js

modules.define('user', ['jquery', 'app-router-base'] function (provide, $, router) {
  provide({
    create: function () {
      $.ajax(router.generate('create-user', {
        userName: 'Andrew'
      }), ...);
    }
  });
});