GEARS is all about having to do as little as possible when creating a system that matches all needs of the client. Many of those needs can be fullfilled with lists of elements in a collection and the details of one these elements.

Let's try to use this easy way of creating list/detail functionality to create an overview what the customer has ordered and the ability to open up one of those orders to see the ordered products.

1. Table of content

• 1. Table of content
• 2. Specify order list and order details
• 3. Add filters to lists
• 4. Add short cuts (links) to lists and details
• 5. Tidy up and commit/sync your work
• 6. Do it yourself
  • 6.1. Situation: You already have a process to Enlist in special courses
  • 6.2. Assignment: Create a list and detail for this and add a link

2. Specify order list and order details

We can now specifiy a lot of functionality at once, all based on the specifications in the LDM.sn. Let's do that now:

1. In the folder resources create a new folder called defs (short for list and details definitions).
2. In that defs folder create a new file called orders.yml and fill it with the following content:

lists:
  - key:    orders 
    entity: ORDER
    detail: order
    label:  Orders
    fields:
      - key:   modified_at
        path:  modified_at
        label: Changed at
      - key:   delivery_address 
        path:  delivery_address
        label: Delivery address 

details:
  - key:    order 
    label:  Order 
    entity: ORDER
    sections:
      - key:   order_details 
        type:  group
        label: Order details
        fields:
          - key:   modified_at
            path:  modified_at
            label: Changed at
          - key:   delivery_address
            path:  delivery_address
            label: Delivery address
          - key:   modifier_username
            path:  MODIFIER.username
            label: Changed by
      - key:   lines
        type:  list
        label: Order lines
        path:  LINES
        fields:
          - key:   product_name
            path:  PRODUCT.name
            label: Product
          - key:   quantity
            path:  quantity
            label: Quantity

It's all pretty straight forward but some explanation is required:

Line	Explanation
lists:	Start of specifications of lists
- key: orders	Unique name for this item. In this case a unique name for this list. Note that keys for items under fields currently cannot contain periods, so we use underscores.
entity: ORDER	Single name of the entity (as in LDM.sn)
detail: order	A reference to the key of the detail screen that will be opened if the users clicks on a row in this list.
label: Orders	Name of the list as will be shown in the app
fields:	Start of a list of which fields should be shown
path: delivery_address	Which info should be shown. Can be a name of the attribute of the current entity or a path to an attribute you can make from the current entity (as in LDM.sn or as in the default entities and attributes).
details:	Start of specifications of detail screens
sections:	Start of the sections of this detail screen.
type: group	Type of each section can be either group (of fields) or list

Now you have specified an order list as well as an order detail screen. But we also need a way to specify how this list can be shown. That can be done by overriding the default menus in the GEARS created application with a new menu structure. This how you do it:

1. Under folder resources create a file called menu.json and fill it with this content:

[
    {
      "key":  "process.start",
      "ref":  "default:start"
    },
    {
      "key":        "list.orders",
      "ref":        "list:orders",
      "label":      "Orders",
      "icon":       "ShoppingBasketTwoTone",
      "activeIcon": "ShoppingBasket"
    }
]

Of course I will give some explanation here as well:

Line	Explanation
"key": "process.start",	This key is part of the default start functionality and should not be renamed
"ref": "default:start"	This is a reference to this default start functionality
"key": "list.orders",	This key you can name yourself as long as it is unique
"ref": "list:orders",	This is a reference to the list with the key orders (as defined by yourself in the orders.yml file)
"label": "Orders",	Menu name as shown in the application
"icon": "ShoppingBasketTwoTone",	Icon name as can be found under https://mui.com/material-ui/material-icons/. For example: . Click on the icon, then on name of icon to copy it so you can use it here:
"activeIcon": "ShoppingBasket"	Dito. Tip: use an icon that is the same but with a darker filling. For instance like this:

4. Do a GEARS:Copy Resources. A GEARS:Generate is not necessary because you only changed things in the resources folder and that does not require a Generate but only a copy.
5. Do a GEARS:Run Application, GEARS:Load data
6. Open the application. As you can see many of the existing menus such as 'Assigned tasks' until 'Deployments' have gone, but a new one has been added: Orders'

7. Let's first create 2 orders with 2 different delivery addresses.
8. Then click on the new menu Orders. It should look a bit like this:

9. Click on one of the orders to open it. It should look a bit like this:

3. Add filters to lists

You may not have realized the following but the current order list will show all orders anyone has done in the application. Let's first test that this is indeed the case.

1. On the right top of the application click on the account icon and then click on Logout.

2. Login with user admin and password admin.
3. Click on menu Orders

As you can see, the user admin is also able to see the list of all orders. Of course you would want to change that to showing only the orders of the current users of the system. You can achieve that by adding filters to a list. Let's do that now:

4. In orders.yml and menu.json make the following changes so everbody knows that we want this list to be "My orders" of the current user:

file	current text	change it to
orders.yml	key: orders	key: my_orders
orders.yml	label: Orders	label: My orders
menu.json	"key": "list.orders",	"key": "list.my_orders",
menu.json	"ref": "list:orders",	"ref": "list:my_orders",
menu.json	"label": "Orders",	"label": "My orders",

5. In order.yml under label: My orders add the following new line:

    filter: CREATOR == current_user()

This is the first time you are using a "function". In this example the function current_user() . In your requirements files (the specs/*.sn files) you can use many different functions which are described here.

Not all of them are already implemented for these list and detail yml files but we'll add more in the near future. In the rest of this getting started you will learn to use more of these functions.

6. Do a GEARS:Copy Resources, GEARS:Run Application, GEARS:Load data.
7. Open the application and log in as user demo and create 2 orders and click on menu My orders to see the orders this users has just created. This list should contain those 2 orders.
8. Now logoff and relogon as user admin and click on menu My orders again. The list should be empty.

4. Add short cuts (links) to lists and details

In webshops it is common to browse through (the list of) products and start ordering from there. We can do that by adding references to the key of a process. These are called "links". Let's first specify a new list and detail for products and add this link to them.

1. In folder defs create a new file called products.yml and fill it with this content:

lists:
  - key:    products
    entity: PRODUCT
    detail: product
    label:  Products
    search:
      - name
    fields:
      - key:   product_name
        path:  name
        label: Name
      - key:   product_price
        path:  price
        label: Price

details:
  - key:    product
    label:  Product details
    entity: PRODUCT
    sections:
      - key:   product_details
        type:  group
        label: Product details
        fields:
          - key:   product_name
            path:  name
            label: Name
          - key:   product_price
            path:  price
            label: Price
    links:
      - key:    order
        ref:    process:sales.products.order
        label:  Order products
        icon:   AddShoppingCart
        fill:
          deliveryAddress: "'Some example address'"
          lines:
            - product:  "id"
              quantity: "1"
            - product:  "id"
              quantity: "2"

Here is the explanation of the things that are new (the links: part):

Line	Explanation
search:	All paths from this entity to a text field you want to be able to search on. It can be any path even if you did not add it as a field. A search can only be part of lists:
links:	Start of all links. Links can only be part of details:
- key: order	Unique key for this link.
ref: process:sales.products.order	Reference to the key (sales.products.order) of the process you want to start with this link.
label: Order products	Name of the link as will be shown in the app.
fill:	Start of how the first form of the process will be filled.
deliveryAddress: "'Some example address'"	Fills field delivery_address (but in camelCase, so deliveryAddress) with the value that comes forth when executing the SNEL expression that is between double quotes ("..."). In this case a simple text value 'Some example address'.
lines:	fills field LINES in Order products.sn) (but in camel case, so lines).
- product: "id"	Because lines is a list, we can provide a list, so indented one level deeper and starting with a hypen (-) then followed by the name of the attribute to fill. In this case product which in turn is by executing a SNEL expression. In this case id. This id in turn refers to a default attributes that GEARS creates (as described in GS_03_Create_first_working_app). Attributes that result in a drowdown list box in the app, should always be filled with id's.
quantity: "1"	quantity will simply be filled with the value 1.
- product: "id"     quantity: "2"	This will add another entry of the same product but with quantity 2.

SNEL stands for SMART Notation Expression Language. Currently that is a subset SMART notation expressions you can use to specify values with. We'll explain and start using more of that later.

2. In file menu.json add the following between the last } and before the last ]:

    ,
    {
      "key":        "list.products",
      "ref":        "list:products",
      "label":      "Products",
      "icon":       "StorefrontTwoTone",
      "activeIcon": "StorefrontRounded"
    }

This is not very different from adding a new menu item as you did previously for Orders, so this should not require more explanaition.

3. Do a GEARS:Copy Resources, GEARS:Run Application and GEARS:Load data
4. Open the application and log in as user demo and click on the new menu item Products. It should look like this:

5. Right click on one of the products. The following context menu should appear:

This context menu has 3 items you can click on:

• Copy product ID will copy the technical id of this row.
• Show product will open the details of this product (which is the same effect as left-clicking on a row).
• Order products is the link you just specified. When clicked it will start the process you specified (process:sales.products.order).

6. Let's first choose Show product. This will open the detail screen you specified:

As you can see this screen also shows the Order products link to the right of the screen.

7. Click Order products. It should start the first form of the process but now prefilled with the specified values:

8. Simply change these values to your liking and click Submit.

The process is now complete and the data is stored in the database. You can check that if you like.

Congratulations. You have now added a lllllllot of functionality just by adding some .yml files and overriding and changing the menus of your application in menus.json. It has made your application a lot more professional in a very short time. While you were at it, you already used a little bit of SNEL which may come in handy later.

5. Tidy up and commit/sync your work

Same as you did at the end of GS_03_Create_first_working_app but in short:

1. Kill all tasks
2. Give your work a good commit message
3. Click the blue Commit button
4. Click the blue Sync Changes button.

6. Do it yourself

In your school system it is time to add a list and detail screen for Special courses and add a link to it.

6.1. Situation: You already have a process to Enlist in special courses

You should already have a process to enlist in special courses because you made as part of the assignment in GS_05_Create_multiple_results.

6.2. Assignment: Create a list and detail for this and add a link

Go ahead and:

• Create a list of Special courses.
• Also specifify a detail screen for each Special course
• Add a link to the "Enlist in special courses" process