Skip to content

Latest commit

 

History

History
380 lines (193 loc) · 15.2 KB

demo-script.md

File metadata and controls

380 lines (193 loc) · 15.2 KB

Simple demonstration/evaluation scripts

The following introductory screencast videos can be downloaded from annalist.net:

  1. Initializing Annalist site data (1m47s) - shows the procedure for first-time initialization of new Annalist site data using the annalist-manager utility.
  2. Log in and and create first collection (3m32s) - steps through an initial login using the admin user created previously, create a new collection and create permissions for a Google-authenticated user to modify that collection.
  3. Initial entry of data in a new collection (3m32s) - covers adding data to a new collection, and adding data record fields beyond the initial default fields.
  4. Configure types and record views in a data collection (3m46s) - customize a collectionto reflect the data it contains through the addition of record types and record views.
  5. Configure list view and default display (3m51s) - customize collection content listings and defaults to simplify the entry of new data.
  6. Using multiple record types (@@TODO)

Scripts for the above demonstration sequences, to allow the operations shown to be performed locally, can be found below.

The original 6 minute demonstration screencast can also be downloaded, but this is based on earlier software and differs in several ways from the current software.

Initializing Annalist site data

annalist-site-setup.mp4 - (3m19s)

This demonstration starts with a fresh Annalist software installation. It introduces the annalist-manager command line tool, and then covers its use to initialize Annalist site data, create an initial administrative user, and specify default user permissions.

  1. The annalist-manager command line tool is provided to perform a range of Annalist system administration activities. To show list of annalist_manager command options, type:

    annalist-manager help

    To show more information about a specific command:

    annalist-manager createsite

  2. Examine the location where annalist site data will be created. (The location is determined by a configuration file installed as part of the Annalist software, and may be changed by editing the configuration file. In his case, we shall use the default "personal" configuration, which creates site data in subdirectory annalist_site the current user's home directory Initially, the directory does not exist.

    annalist-manager sitedirectory

ls /Users/graham/annalist_site

  3. Create new Annalist site structure:

     annalist-manager createsite

 ls /Users/graham/annalist_site

  4. Initialize the web site management database:

    annalist-manager initialize

  5. Create an initial admin user (with user-id admin) with a supplied password:

    annalist-manager defaultadminuser

  6. Set default permissions to allow any logged-in user to create a new data collection:

    annalist-manager setdefaultpermissions "VIEW CREATE_COLLECTION"

  7. Start the Annalist web site server:

    annalist-manager runserver

At this point, you should be able to browse to http://localhost:8000, and be presented with the initial annalist site.

With the Annalist server running, the next demo will show how to log in to the web site and create a first data collection.

Log in and and create first collection

annalist-login-create-collection.mp4 - (3m32s)

This demonstration provides a first view of the Annalist web site interface, and shows the initial steps followed to log in and create a data collection. It starts with a running Annalist server and newly initialized site data and (see previous demo). It also assumes the server is configured to accept OpenID Connect user credentials from Google.

  1. Start a web browser on the same computer that is running an Annalist server, and browse to localhost:8000.

  2. Select "Login" from the top menu bar, and enter "admin" into the User ID field, and click on the Local username button.

  3. Enter the admin password specified when setting up the Annalist installation using annalist-manager defaultadminuser.

  4. Select "Home" from the top menu bar: an empty list of data collections is presented, along with controls to create a new collection.

  5. Enter details for a new collection, and click New collection.

  6. The new collection now shows in the list; click on the link to view the new collection. A single record is shown for the admin user.

  7. Click on the admin user link, and note the permissions shown. Whenever a new collection is created, the creator (in this case, user admin) is automatically given full permissions over that collection.

  8. Click "Close" to return to the collection default display.

  9. We will create a new non-admin user with full permissions over this new collection. In the List drop-down, select User permissions then click on the List button.

  10. A page titled "User permissions" is displayed. Click on the "New" button.

  11. Enter details for a Google-authenticated user, click "Save". The user id must match a value that will be used later for login, and the URI must be a mailto: URI matching the email address of the user's Google account. For full access to the collection, the permissions should be specified as "VIEW CREATE UPDATE DELETE CONFIG ADMIN".

  12. Click "Close" to return to the site front page view (list of collections)

  13. Click "Logout"

  14. Enter the user ID value for the new user just added to the new collection. Then click on the button labeled "Google".

  15. At this point, prompts may be issued to enter Google account and password details. If the user is already logged in to Google, the login may proceed without further user input.

  16. Assuming the credentials are all good, Annalist login completes and brief information about the user is displayed.

  17. Click on Continue to proceed (or on Home in the menu). The list of collections is displayed again.

  18. Click on the link for the new collection created just now.

  19. Click on the link for the new user just added, and note that the they have permissions to create and edit collection content.

This completes the demo. The next demo will show population of a new collection with simple data records.

Initial entry of data in a new collection

annalist-create-configure-data-records.mp4 - (3m26s)

This demo creates a new collection and populates it with a couple of simple desctriptions of musical instruments. It shows that new fields can be added to presented data records as needs are identified.

The demo sequence starts with an empty Annalist site, and a logged in user with permissions to create a new collection.

  1. Create new collection "MusicalInstruments"

  2. Clock on "MusicalInstruments" collection link to view the new collection

  3. Click "New"

  4. Enter values:

    Id: "guitar"

    Label: "Guitar (accoustic)"

    Comment: "String instrument with 6 strings, a fretted neck and a sound box."

  5. Next, we shall add a field indicating the class of instrument. Click on 'New field'.

  6. Enter values:

    id: "InstrumentType"

    Field value type: "annal:Text"

    Field render type "Text"

    Label: "Instrument type"

    Description: "Keyword indicating broad class of instrument (e.g. string. wind, brass, etc.)"

    Placeholder: "(Type of instrument; e.g. string. wind, brass, etc.)"

    property: "micat:instrument_type"

    size/position: "small:0,12; medium:0,6"

    Leave remaining fields untouched.

  7. Click "Save". The 'guitar' record is displayed again.

  8. Click "Add field". Towards the bottom of the page is a list of fields. In the last entry, change values thus:

Field id: "InstrumentType"

Size/position: "small:0,12;medium:0,6"

  1. Click "Save". The guitar record is redisplayed with a new field "Instrument type". Enter "string" into this field.

  2. Click "Save". The collection now shows new entries for "InstrumentType", "Default_view" and "guitar"

  3. Click "New" again.

  4. Enter: Id: "trumpet" Type: "Default_type" Label: "Trumpet" Comment: "Brass instrument with folded tube and three valves." Instrument type: "brass"

  5. Click "Save". Observe both "guitar" and "trumpet" appear in the list.

This concludes the demonstration of simple data entry and adding new fields to a data entry form. In the next demo, we shall see how to customize the presentation of data in a collection to focus on the actual data it contains.

Configure types and record views in a data collection

annalist-configure-type-view-records.mp4 - (3m46s)

This sequence shows how a collection can be configured to reflect the data it contains, through the addition of customized types and record views. It starts with the simple musical instruments catalogue created in the previous demonstration.

  1. View the Musical Instruments data collection.

    Note that the musical instruments are shows as "Default_type", and that other records present are described as "_field, "_user" and "_view" values.

  2. Click on "Customize"

    Columns are displayed for Record types, List views and Record views. A single record view "Default_view" is shown. (This was created previously when a new field was added to the default record view.)

    To customize the collection for musical instrument data, we shall create new a record type and rename Default_view to reflect its use to display musical instrument records.

  3. Click on "New" in the record types column. Fill in the fields displayed:

    Id: MusicalInstrument

    Label: Musical instrument

    Comment: Record type for musical instrument description

    URI: micat:MusicalInstrument

    Click "Save", leaving remaining fields as they are for now.

  4. "MusicalInstrument" now appears in the record type column.

  5. In the Record views column, select Default_view and click on "edit"

  6. Change field values:

    Id: Instrument_view

    Label: Musical instrument view

    Help: View musical instrument description

    Record type: micat:MusicalInstrument

    Click "Save" leaving other fields unchanged. Note that the Record views column now contains an entry Instrument_view.

  7. Clock "Close", then click on the link for guitar.

    Note that the view now does not displkay the instrument type field added previously.

    In the "Choose view" field select Instrument_view, then click "Show view".

    The instrument type is now shown.

  8. In the "Type" field select MusicalInstrument and click on "Save".

    The "Guitar" record now displays with type "MusicalInstrument".

  9. Click on "Customize" again.

    In the record types column select MusicalInstrument and click "Edit"

    In field "Default view" select Instrument_view, and click "Save".

    Click "Close" to return to the collection display.

  10. Click on the guitar link.

    Note that it now displays by default with Instrument_view, showing the instrument type field.

    Click "Cancel"

  11. Click on the trumpet link.

    Note that it shows as Default_type using Default_view.

    From the "Type" field, select MusicalInstrument, then click "Save".

  12. Again, Click on the trumpet link.

    This time it displays as a MusicalInstrument using the Instrument_view form.

    Click "Cancel"

This demonstration has shown how the presentation of data records can be changed through the definition of customized types and views. It also shows how these changes can be made post hoc: existing data records and views can be updated to reflect changes to the data.

In practice, I would recommend to define an appropriate (non-default) type for data records before creating the data. The record type is mainly a convenient label, and does not impose any structural constraints on the data.

The next demonstration will continue customizing the musical instruments catalogue to make data entry and display proceed more smoothly.

Configure list view and default display

annalist-configure-default-list-record.mp4 - (3m51s)

Starting with the customized musical instruments catalogue from the previous Annalist demonstration, this demonstration sequence shows how a collection can be further configured to reflect the data it contains through the addition of customized list views.

  1. View the Musical Instruments data collection.

    Following the previous demo, the guitar and trumpet records are shown as having type "MusicalInstrument".

    We shall proceed to create a customized list view for musical instruments.

  2. Click on "Customize"

  3. In the List views column, click on "New"

    Fill in the fields thus:

    Id: Instrument_list

    Label: Musical instrumemnts

    Help: Listing of musical instruments

    Record type: MusicalInstrument

    View: Instrument_view

    Selector: micat:MusicalInstrument in [@type]

    Record type URI: micat:MusicalInstrument

  4. Add an instrument type field to the listing

    Because there is currently no facility to reorder defined fields, we need to delete an existing field and redefine fields in the desired order.)

    Select the check box by Field id Entity label, then click on "Remove selected field(s)".

    Click on "Add field" and enter details "InstrumentType" and "small:3,3".

    Click on "Add field" again and enter details "Entity_label" and "small:6,6".

    Click "Save".

  5. Click "Close", returning to the main collection display.

  6. In field "List view" select Instrument_list and click "View"

    The display changes to a list of Musical instruments, with a column for instrument type.

  7. To make this display default for the collection, click on "Set default".

    To see the effect of this, click on "Home" inthe top menu bar, then on the "MusicalInstrument" collection link.

  8. To complete the customization, make the new list default for type "MusicalInstrument":

    Click on "Customize"

    In the Record type column, select MusicalInstrument and click on "Edit"

    In field "Default list" select Instrument_list, and click "Save"

    Click "Close"

  9. Create another musical instrument record:

    Click on "New:". Note that the type is pre-selected as MusicalInstrument, and the view is Instrument_view (showing the instrument type field).

    Enter new values:

    Id: violin

    Label: Standard violin

    Comment: An instrument with 4 strings, a neck without frets and a sound box.

    Instrument type: string

    Click on "Save".

  10. Home page

    Click on MusicalInstruments link

    Note that the display comes up with the customized list of musical instruments.

The musical instrument catalogue has now been customized to display a list of musical instruments as its default front-page display, and to use appropriate defaults when creating and displaying new data records.

The next demonstration will introduce a second record type into a collection, and show how links can be created between records.

Next demo:

Add musicians to catalogue, and cross-link

@@TODO