Skip to content

Getting Started Developing with Arethusa

Jump to bottom Edit New page
Bridget Almas edited this page Feb 11, 2016 · 16 revisions

First, when just learning the code, it's best to start with a stable tagged release. The Master branch may contain work that hasn't been fully tested, and some of which might be broken.

Second, essential debugging tips:

  1. Before starting your dev enviroment (with the grunt reloading-server command), do export DEV=1. This causes the non-minified code to be loaded in the browser's debugging console.

  2. You can insert debugger statements into the code to initiate breakpoints when the browser's debugging console is open (but only works if DEV=1 is sent in your environment per previous tip).

  3. To access the state object in the browser console (e.g. at a breakpoint), you can enter the following: angular.element(document.body).injector().get("state")

Next, it's good to understand that all of Arethusa is designed around some key concepts:

  • configurability
  • plugins
  • retrievers
  • persisters
  • state and tokens

One way to understand these without being overwhelmed by complexity is to look at an existing plugin and think about how to use it as a base for another. The Comments Plugin is a relatively simple one to start with.

Configuration

A plugin is added to the Arethusa interface by way of the configuration. The configuration to use when developing with Arethusa in stand-alone mode is the staging.conf.

Open staging.conf

Overall configuration for the app is in the main object

The plugins used in the interface are defined in the main.plugins array and the configuration for each plugin in the plugins object, keyed by plugin name. So, the comments configuration can be found in plugins.comments

From this you can see that the Comments plugin defines a retriever it its configuration, called the Comments.Retriever. And this retriever itself is configured with a resource, called arethusaServerComments.

So where is the arethusaServerComments resources' configuration defined? If we search within perseids.json, we don't find this further. But, we do see an object named resources and that includes an @include property which points at a file path resources/dev.json.

Arethusa configuration is layered, and resources can be included by file or URL.

Opening resources/dev.json we now find an object named arethusaServerComments and it defines a route to retrieve a comments file, at a file path /examples/comments/:doc and a query parameter, doc. If you have imported the example data, you will find some files at that path, named by document id, and you can inspect them to see what a comments document is expected to look like.

Plugin

Plugins are made up of:

  • templates
  • modules
  • services
  • directives

and Arethusa offers alot of common functionality that is available to a plugin:

  • user settings
  • keyboard shortcuts
  • history (undo/redo)
  • ...

Templates

Templates live in app/templates/<pluginname> and provide the skeleton UI for the plugin. The base template for a plugin can be defined in the configuration, although most have a default path configured in the plugin service code in the defaultConf method.

If we look at app/js/arethusa.comments/comments.js we see that is has 2 default templates defined, the base template (templates/arethusa.comments/comments.html and another for the contextMenu, templates/arethusa.comments/context_menu.html). The contextMenu template is optional, and used by plugins that want functionality exposed in the contextMenu for a token.

The other template files in templates/arethusa.comments are templates for specific directives used within the comments plugin.

Modules

The modules in Arethuse are all just thin wrappers that set up the namespace and dependencies for the plugin. All of the business logic code for a plugin resides in the services and directives.

Services

Directives

User Settings

User specific configuration for a plugin is managed via the settings object of the plugin, and should be set using the arethusa.util.commons#setting method.

(Whether or not arethusa will obey this for a plugin is determined by the way the plugin is instantiated - the with-settings attribute on the plugin directive must be set to true, e.g. see arethusa_tabs.html)

e.g.

 this.settings = [
      commons.setting('User Friendly Name', 'internalVariable')
    ];

The arethusa.core.pluginSetting directive is normally responsible for persisting plugin-level setting changes made through the UI to the user preferences stored in the browser cache. The arethusa.core.globalSettings` object is responsible for application-wide settings.

Keyboard Shortcuts

The keyCapture service handles the keyboard shortcuts for Arethusa's plugins. A plugin can add shortcut keys to the application by calling the keyCapture.initCaptures method

keyCapture.initCaptures(function(kC) {
      return {
        myplugin: [
          kC.create('myKeyName', myCallbackFunction, 'ctrl-K')
        ]
      };
    });

The plugin then just needs to define the callback function that responds when the use presses the specified key combination.

Retrievers

retriever and persister concept

Persisters

State and Tokens

Always use state object for CRUD operations on tokens

Resources

Add a custom footer
Add a custom sidebar
Clone this wiki locally