BOM : Bills-of-materials

This add-on collects components across the entire org buffer (even in drawers), making it easy to retrieve and sort data. It uses the column special name as a landmark. We will refer to them as 'Keywords'. The keywords are searched using a string-match function, which gives the ability to have multiple column with the same functionality, but also to use the column name as we would usually with org-mode. For example, we can have 'tag' and 'tag2', both are recognized by the BOM add-on and can be used in a spreadsheet-like formula without any confusion. The keywords are also case-insensitive. 'Component' and 'component' will work in the same way.

The BOM is usually used with a dynamic block. (You can use the different functions in emacs-lisp code, but this is beyond the purpose of this tutorial.) Here is the basic dynamic block:

#+BEGIN: bom
#+END:

And here is what we obtain at this point:

 #+BEGIN: bom
| Section | Tag | Component | Quantity |
|---------+-----+-----------+----------|
 #+END:

The table is empty, because we have to either:

1. Add keywords in a table;
2. Add a line-component.

It is possible to rename the BOM columns with the following parameters:

• col-name-component
• col-name-section
• col-name-quantity
• col-name-tag
• col-name-description
• col-name-price

This is how our renamed BOM would look like:

 #+BEGIN: bom :col-name-section For :col-name-tag Need :col-name-component Stuff :col-name-quantity Qty
| For    | Need               | Stuff    | Qty |
|--------+--------------------+----------+-----|
| Friend | Dinosaurs pictures | Keyboard |   1 |
| Me     | Matching colors    | Keyboard |   2 |
 #+END:  

There is two way to add components in a section. Either by adding other rows with the same section's name, or by adding other columns. Both have their uses and they should come to you quite naturally. In our example, we want more stuff.

|   | For     | Material  | Personal | Gift | Need               | Stuff     | More stuff | Much more stuff | How many |
| ! | Section | Component |      Qty | Qty2 | Tag                | Component | Component  | Component       | Qty      |
|---+---------+-----------+----------+------+--------------------+-----------+------------+-----------------+----------|
|   | Me      | Keyboard  |        1 | 1    | Matching colors    | Mouse     | Headset    | USB flash drive | 23       |
|   | Friend  | Keyboard  |        1 |      | Dinosaurs pictures |           |            |                 |          |
|   | Friend  |           |          |      |                    |           |            | CDs             | 50       |
|   | Friend  | Mouse     |        1 |      |                    |           |            |                 |          |

This is beginning to get interesting. Note that even if we can name the additional columns 'Component2' or 'ComponentAAA', there's no use to do it if no table-formula uses the column names.

Now suppose we want to get OUR to-buy list. Simply specify the section's parameter :section Me:

 #+BEGIN: bom :section Me
| Tag             | Component       | Quantity |
|-----------------+-----------------+----------|
|                 | Headset         |        1 |
| Matching colors | Keyboard        |        2 |
|                 | Mouse           |        1 |
|                 | USB flash drive |       23 |
 #+END:  

Wait, where's the section column? Well we don't need it anymore, as we specified one.

A '+' sign will specify we want more than a single section. :section Me+Friend will select both section, and add the quantity and tags for each component.

 #+BEGIN: bom :section Me+Friend
| Tag                                 | Component       | Quantity |
|-------------------------------------+-----------------+----------|
|                                     | CDs             |       50 |
|                                     | Headset         |        1 |
| Dinosaurs pictures, Matching colors | Keyboard        |        3 |
|                                     | Mouse           |        2 |
|                                     | USB flash drive |       23 |
 #+END:

Do not put a whitespace between the section name and the '+' sign. Speaking of whitespace, if you need one in a section name, simply put it in a string:

#+BEGIN: bom :section "Section with whitespace"

We can also return every section that matches at least what we provide. To activate this, use :part-match t. With this, if we write "fr", the Friend section is returned. If we had another section named "Frosting", than Friend and Frosting would have been merged and we would have a total for both section.

 #+BEGIN: bom :section fr :part-match t
| Tag                | Component | Quantity |
|--------------------+-----------+----------|
|                    | CDs       |       50 |
| Dinosaurs pictures | Keyboard  |        1 |
|                    | Mouse     |        1 |
 #+END:

It is also possible to specify that we don't want any section containing "fr". For this, use the parameter :remove t.

 #+BEGIN: bom :section fr :part-match t :remove t
| Tag             | Component       | Quantity |
|-----------------+-----------------+----------|
|                 | Headset         |        1 |
| Matching colors | Keyboard        |        2 |
|                 | Mouse           |        1 |
|                 | USB flash drive |       23 |
 #+END:

In this case, getting all sections not containing "fr" is the equivalent of choosing the section "Me".

If you simply want the components from the current heading, use the parameter :local-only t. This will return components with the current heading as their section, which is the default of every component if no section is provided. If a section has been provided to a component (and is not exactly equal to the heading), the component will not be returned.

Here, we don't have any component under this heading:

 #+BEGIN: bom :local-only t
| Tag | Component | Quantity |
|-----+-----------+----------|
 #+END:

This is all really interesting, but when we're in a shop, we want to know how many of each item we have to buy, we need a total. For this, simply add the :total t parameter. We will also remove the tags once again by using :no-tag t.

 #+BEGIN: bom :total t :no-tag t
| Component       | Quantity |
|-----------------+----------|
| CDs             |       50 |
| Headset         |        1 |
| Keyboard        |        3 |
| Mouse           |        2 |
| USB flash drive |       23 |
 #+END:

This is the equivalent of merging every sections together.

There is another option you might need. If you ever want to add a component without a table, use the #+BOM commentary. As any other org-mode commentary, this one won't appear when exported to another document (pdf, html, docbook..). It will, however, enable you to add a single component in the bill-of-materials. Here is an example:

#+BOM: Keyboard :section Need :tag "Matching colors"

As with the table components, you can simply give a component name if you desire. If no section is given, it will be inherited as an ordinary component in a table: a section property or the current heading.

There is two way to add details to a BOM. The first one is to setq `org-bom-details' with a plist containing, depending on your needs, :description, :datasheet-pdf and :price. You must, however, at least have the component name in the :name property. Here is an example on how to set this variable:

(setq org-bom-details '((:name "Keyboard" :description
                          "Something" :price "40") 
                          (:name "CDs" :description "Not
                          DVDs" :datasheet-pdf "CD.pdf")))

Please note that the price is a string.

The other method, valid for the current buffer only, is to give one or more bom-details table. It is recognized when a table is named as such:

#+TBLNAME: bom-details

Once again, the column names are used. Contrary to the normal BOM keywords however, these are case-sensitive and must be written exactly as their property name. For example, the column of the property ':name' must be 'name'.

 #+TBLNAME: bom-details
| ! | name     | description  | price |
|---+----------+--------------+-------|
|   | Keyboard | Used to type |    40 |
|   | CDs      |              |       |

Any bom-details table will temporarily overshadow the `org-bom-details' variable, but won't erase or modify it. This means you can safely use a bom-details table if you need to change some local buffer description, while using `org-bom-details' in multiple buffer.

Look at the CDs description. When a field is empty, it is not used and BOM falls back to the property in the `org-bom-details' variable.

Here is a list of all the parameters usable in a BOM dynamic block, as seen throughout this tutorial:

no-tag

Remove the tags column

section

Select this section (or more if there's a + sign)

part-match

Select every section with at least the string provided for the section parameter

remove

Select every sections except the one(s) provided

descripton

Add the description column

price

Add the price column and a total row at the bottom of the table

col-name-*

Rename the associated column