Description of a view

[xethorn]

Each view should have a description file that ocntains the description of the view, the different parameters definition (type, comment), the different allowed api endpoints. This description file will allow to:

• Automate unitests: can the view be rendered for all parameters provided, and with data provided from the API.
• Provide quick documentation on what the view accepts.
• Perform checks: the view should not fetch a non tested, non allowed api endpoint.

Suggestion for the name: ViewName.description.js

Possible structure for the file:

{
    name: 'ViewName',
    description: 'Description of the view.',
    api: [
        {endpoint: '/url/endpoint/', params: {'mandatoryparam': [sampleValues]}}
    ],
    params: {
        'name': {format: (...), sample: [sampleValues]}
    }
}

[xethorn]

Thinking more into this, it might be better to have a yml file. The structure will have 4 main parts:

• name: The name of the view (so we don't need documentation in the js and nunjucks file.)
• description: Short description of what this view does.
• api: the allowed endpoints. Each endpoint can have variables and params. The variables have the value type built in. The params that have for the type a "!" means the value is required.
• params: the params for the view. Same as the params for the api, params can be marked "mandatory".
• tests: light test suite to make sure the view can be rendered.

name: 'AppView'
description: |
    'This is the description of the view and all the different values'
    'this view can have.'

api:
    - /user/activate/<username>/
    - /user/<username>/:
        params:
            name: !userid

params:
    name: format

tests:
    michael:
        api: /user/activate/michael/

    raphael:
        api: /user/activate/raphael/

    new_user:
        params:
            user: michael