SAM can turn almost any kind of static webpage structure into a custom adaptive menu, in a few lines of code only. It comes with the following features:
- Abstraction of webpage menus, easily built using JQuery selectors.
- Continuous logging of user interactions, entirely local to the web browser of each user.
- Popular adaptation techniques, split between target policies (what to adapt in a menu) and adaptation styles (how to adapt the target items).
You can find more details about the framework in the following IUI19 paper.
Running SAM (for end-users)
Since SAM is entirely client-side, it can be injected in any webpage. This process allows to adapt the menu of many websites, even though they were not built using SAM.
- Open the Code Injector panel (click the icon).
- Create a global rule (common to all URLs) to inject SAM on every website you visit. If you prefer, you can also use more restrictive rules to only inject SAM on certain websites.
- Add specific rules to initialise SAM on each website containing menus you wish to adapt. Let's take Wikipedia as an example, and add a new rule in Code Injector:
- URL pattern:
- URL pattern:
Building SAM (for developers)
If you want to build SAM on your machine, you must start by installing all the dependencies using npm. It is shipped along with Node.js, that you can install with one of the following ways:
- Using nvm (Unix & OSX):
nvm install node
- Using Homebrew (OSX):
brew install node
- See other alternatives on npmjs.com
Once this is done, open a terminal and run the following commands:
git clone https://github.com/aalto-ui/sam.gitto clone this repository.
cd samto change you working directory to the clone you just made.
npm install -g grunt-clito install the CLI of Grunt, the build system we use.
npm installto install all the other dependencies (listed in
gruntto finally build SAM.
build folder will contain your own build of SAM. You can also generate your own documentation by running
Note on the
Extending SAM (for researchers)
In SAM, each adaptation technique is a combination of a policy and a style. While the code of SAM can be extended in various ways, one of the most interesting kind of extension is the addition of a new policy or a new style:
- A policy is a metric of importance for all items (or groups of items). It must assign a score to each item (or group of item), and sort them accordingly. It reflects what to adapt in the menus (e.g. the most clicked items).
- A technique is a certain way of updating the webpage menus to adapt them. It must modify the DOM in accordance with the output of the policy, and be able to cancel the changes at any time. It reflects how to adapt the menus (e.g. highlight the top-3 items).
We decided to make adaptation techniques modular in order to encourage researchers to re-use existing pieces of code, and spend more time on trying out new ideas (instead of constantly re-implementing features such as user logging and common metrics). In addition, SAM already provides some popular policies and styles.
Adding a new target policy
In order to add a new target policy, you must first create a new class which implements the
TargetPolicy interface, and give it a unique name.
For more convenience, you may want to extend the
DefaultTargetPolicy class instead. It provides a default implementation of all methods of the interface but
getSortedItemsWithScores, that must return a sorted array of objects containing an item and its score, and that you must implement yourself.
Once your new class fully implements the interface, you must add an instance of your policy in the
AVAILABLE_POLICIES array, and rebuild SAM. It will be available in the adaptation manager by using the name you gave it.
Note on default implementations: if your policy belongs to a specific kind of metric, you may want to check if there is an even more specific abstract class to extend. For instance, all the policies provided by SAM which sort items according to a score related to the page they link to extend the
LinkedPageScorePolicy class instead, which does almost all the work!
Adding a new adaptation style
In order to add a new adaptation style, you must first create a new class which implements the
AdaptationStyle interface, and give it a unique name.
Remember that the scores and/or the order of the items (or group of items) provided by the policy represent the importance of the different items (or groups of items) for the user (i.e. what the adapted menu should highlight).
Once your new class fully implements the interface, you must add an instance of your style in the
AVAILABLE_STYLES array, and rebuild SAM. It will be available in the adaptation manager by using the name you gave it.
Note on composite styles: another way of making it simpler to create new adaptation techniques lies in the notion of style composition: two or more styles can be chained inside a new style (which basically calls the
cancel methods of other styles in the right order). This kind of adaptation style is called a composite style. SAM provides some examples of composite styles.