Tnv3/IIRS

What is the IIIRS

The International Initiative Registration Service (IIRS) is a web service that enables Transition National Hubs to register, list, map and edit Transition Initiatives in their countries, on their own websites.

There are two options for this service

1. WordPress plugin: installed in the National Hub's own 'WordPress' Content Management System, this enables the national hub to manage the user and initiative data itself.
2. Javascript widget: this is run from the Transitionnetwork.org website (TN.org) via a 'widget' on the national hub's website. The national hub does not manage any of the data itself.

There are two phases to this work

1. Producing V1:
   1. a working version of the Plugin to exist on a national hub's Wordpress site (Transition Portugal). All data will be collected and handled on the hub's site and *not* synched with TN.org.
      1. alpha: working behind the scenes on test sites for sharing with developers and managers
      2. beta: working behind the scenes on national hub website
   2. a working version of the Widget to exist in a drupal module on TN.org. All data will be collected and handled on TN.org.
2. Producing V2:
   1. Synching 1.1 with TN.org

Key features

• Register user (User)
• Register initiative (User)
• Map of initiatives
• List of initiatives
• Edit your initiative
• Edit any initiative (Admin)
• ...

Architecture

We are developing a

• Drupal Module (which will exist only on TN.org currently)
• JavaScript widget (<script src="http://TN.org/IIRS/..."/> that can be placed on another website to dynamically embed a JavaScript version of the IIRS functions).
• WordPress plugin

They all do exactly the same things for the user, that is: registration process, mapping of initiatives, editing, etc. see below for full list of functionality provided.

The Drupal and WordPress code will store that data locally in the system where they are installed. The JavaScript widget will store its data on the website that the widget JavaScript code is accessed from: currently: TransitionNetwork.org.

Because all 3 will do exactly the same things, we have developed the shared code all in PHP/HTML/CSS/JS as framework independent.

The Drupal and WordPress Modules are very thin and only do things like abstracting data storage and retrieval, translation, authentication. And, because the JavaScript widget also does exactly the same thing, its screens are taken from a working installed version of either the WordPress or Drupal Module.

So: if the Drupal Module is installed on TN.org, it will expose http://TN.org/IIRS/registration/widgetloader thus allowing someone to embed the JavaScript widget on their HTML page with <script src="http://TN.org/IIRS/registration/widgetloader"/> which will show exactly the same screen as http://TN.org/IIRS/registration/ shows.

Note that, because the Drupal and WordPress Modules create native content, that content will be editable by the framework directly without using code in the IIRS Module. Thus the IIRS edit, list and search are only being developed so that these functions are directly available through the JavaScript widget.

• 

Use cases

• User lands on a (self hosted) National hub page & wants to register their new Transition town.
• User lands on a page on a National hub page hosted by TN.org & wants to register a Transition town.
• User doesn't know about national hubs and lands on another TI page

Questions and notes

• We need to be able to turn Plugins/widgets OFF if it is hacked/breaks/etc.
  1. A: widgets is easy. they come to us *every* time they want to display. we can return a message instead. no need to implement this now
  2. A: plugins: in order to remotely turn off all plugins installed on other sites we would need to code the plugin so that it requested authorisation from us in order to display each time. OR: we could code a remote control back door that allowed us to turn them off remotely. we will maintain a list of places they are installed anyway so this is quite feasible. note that WordPress and Drupal plugins will inform the Administrator of the website automatically when we release an update
• We need to be able to update Plugins in security issues
  1. A: Drupal and WordPress will automatically inform their administrators when a new version of any Module is released.
• How will this integrate with existing TI profile nodes?
  1. e.g. we deploy the jscript option (#1) on Portugal - how do the exisitng TI profile nodes appear?
     1. A: they appear wherever the jscript map, list or search widget is placed: <script src="http://transitionnetwork.org/IIRS/mapping/widgetloader"></script>
     2. A: they are valid TIs on TN.org so will also appear in all the normal places on TN.org

• Translation not clear to Ed - where and what and how
  • A: native framework translation, e.g. TN.org or WordPress portugal.org. there will be an admin screen, accessible to those with sufficient privileges, where translations can be entered
  • A: the jscript plugin screens come from TN.org Drupal IIRS Module. they will be dynamically translated by TN.org before sending to the jscript plugin

• TI profile node editing not in the workflows above - tbd
• A: this is now in the workflows

1. Deploy Javascript option (#1) for now: best to start with Javascript option as it's the simplest start and best way to consider the workflows without getting into the complexities of sharing data that the plugins (#2) will bring

A: moved priority to WordPress focused for portugal

• Need to be careful about how cool this is, and how much time we use - REMEMBER this is a temporary prototyping experiment for something we will need to deploy on what is likely to be a straightforward (as codeless as possible) site on Drupal or WP
  • A: UID (User Interface Design) is cool though, the flows are highly customised to please the user. that is the main difference between the old form and the new, not just reduced info required...

• Annesley need to check the workflows (esp the URLs which may now be out of relevance)
• How will this affect the registration process elsewhere?
  • A: on TN.org it is additional process that could be used instead of the current, or not. simple to switch on or off either.

Workflows: TN.org (D6)

Note that 'Normal' initiative viewers and all regular visitors will see no changes.

'National Hub' page viewer (D6)

1. Will see a 'National' page at ​http://www.transitionnetwork.org/world/[localised_country_name] (e.g. in native language like /france, /deutschland, /brasil, but not /germany, /brazil etc).
2. Page will consist of standard D6/English TN.org site structure, menus and blocks, but content area will be the language appropriate for the country.
3. The top part of the content area will consist of some translated welcome/info text. The lower part of the page will hold the "Full page widget" section of "Listings IIRS Widget", below.
4. Details of the widget part of the page are below.

Workflows: Widgets

see: JavaScript widget TN.org embedded version

"Full page listings" widget (Custom coded)

1. URL ​http://www.transitionnetwork.org/IIRS/[widget]/widgetloader -- though this not be shown to the user usually except when getting the widget code.
2. The widget will have the following display tabs:
   1. t('Latest') - shows users to see the latest [country] initiatives listed,.
   2. t('Map') - shows all the [country] initiatives on a map.
   3. t('Search') - allows searching of initiatives within [country] by criteria.
3. An t('Add your initiative') button opening the Add widget popup -- for details of this, see next section.
4. An t('Initiative details') page appears within the widget in the widget theme (ie with the tabs) whenever an initiative link is clicked within the widget area. This shows the full node view in [language] for the initiative selected. This also allows users to log in and edit the TI profile if they have a authenticated account with the correct permissions (National Hub administrator or TI profile owner/PPOC)

"Add" widget popup display (Custom coded)

1. User clicks button to t('Add your initiative'), popup opens showing URL ​http://www.transitionnetwork.org/IIRS/registration/widgetloader
2. SCREEN 1: User enters LOCATION (suggested town or area name)
   1. System presents user with choices
      1. list of location names returned from google with radio button for user to select
      2. option to add location again
      3. personal details
         1. email address
         2. name (auto-completed from name in email field)
   2. User chooses radio button location option, adds name and email
      1. System creates Drupal user account and auto-generates password
      2. System emails user with welcome email (tbc) and authentication request
3. SCREEN 2: User enters WEBSITE
   1. System presents user choices
      1. website suggestion options (gleaned from DNS search from location) with radio button for user to select
      2. other website field (empty text field)
   2. User chooses radio button option or fills in website field, OR neither (if they don't know, don't have a website)
4. SCREEN 3: User enters TI summary
   1. System presents user with summary field (pre-filled with summary field from selected website if suitable)
      1. Summary field
   2. User either proceeds with pre-filled summary field or enters other information and submits
   3. System emails user with TI profile addition confirmation email with further information
5. SCREEN 4: Thanks page
   1. Text needs to be editable / translate-able by National Hub admin

"View Detail" widget display (Custom coded)

1. Any link to an initiative within the Listings widgets shows the detail in [language] showing the full node view of the initiative. URL TBC but likely ​http://www.transitionnetwork.org/IIRS/view/[tid]
2. There will be an option to t('Log in to make changes if the user is the owner'), or register and submit their own initiative.
3. If the user is logged in, the t('Edit') tab will be available to users who have permission (editors, admins and the content author).

Language

Widget will display in language used by user’s computer

• Process: if someone German goes to the Portugese widget it will look for German on tn.org, if no German, then Portugese, if no Portugese then default to English.
  • Luis (or National Hub Admin (NHA)) doesn’t need to do any translating, but the translation for script widget exists in tn.org
  • Luis (NHA) log into tn.org and see english terms and add his preference for (t) portugese
• So if the user’s computer has a preference for spanish, Tn.org needs to have spanish (t) translations
• so that portugese users will see it in portugese i.e. translation occurs on tn.org for NHAs.
• Nice to have: if can’t find user’s computer language, or default for NH, then auto-translate
• How does a TI edit its registration?
  • in the modal pop-up for ‘base layer’
  • if TI registree allowed them to edit on tn.org - the base layer will be in local language, and the rest will be in english if using *widget* - they could add extra projects

Why is this custom code?

This is a piece of expert specialist code when we’d rather be doing code less / minimal in the long term - because:

1. D6 is weak particularly on international location, and we’re working on this stuff now
2. we don’t want to be limited by D6
3. this is a prototyping experiment to explore the workflows and user experience and data handling issues that arise
4. we haven’t agreed the future framework for TNv3
5. and this could well be used for different plugins around the LAMP web *WP* Ruby… etc.

Fields

User

Mandatory

Standard Drupal user account fields:

1. t('Email') = (built into Drupal)
2. t('Username') = (built into Drupal) --> will be generated from email 'firstname lastname'
3. t('Password') = (built into Drupal) --> will be generated by drupal and sent in email

Additional fields:

1. t('First name') = field_user_name_first
2. t('Last name') = field_user_name_last
3. Location = (not sure how this will be stored)

Hidden metadata

• UUID = The Universally Unique ID of the user -- system generated, globally shared.
• Uid = The local Drupal user ID -- system generated and not shared outside current site.
• Status = Drupal default 'active/blocked' flag. Allows users to be hidden rather than deleted.

Initiative

• NOTE This content type does not include the old 'Status' field (Muller vs Official) as discussions around this and statuses are ongoing. We are going to have 'registered' and 'active'.
• QUESTION: when will TN move from official/muller to registered/active?
• AGREED: for now: add them as *official* - ED to talk to MikeThomas
• ACTION: Annesley add an example of the xml for reference

Mandatory

1. t('Initiative name') --> set to what they type in to name field
2. t('Initiative location') --> taken from their choice of the google options presented to user from the generic google search (town, county, country, lat/long) and the granularity the user adds

Optional but recommended

1. t('Initiative website') --> offered to them with a DNS search from their location entry probably dependent on performance of search
2. t('Summary') - 255 character simple, punchy 'about this ini' text field

Hidden metadata

• Internationally required for base layer schema requirements:
  • UUID = The Universally Unique ID of the initiative -- system generated, globally shared.
• Locally required for base layer on TN.org
  • Nid = The local Drupal node ID -- system generated and not shared outside current site.
  • Status = Drupal default 'published' flag. Allows initiatives to be hidden rather than deleted.

XML Schema (RFC Request For Comment)

Notes:

xmlns:tn="http://transitionnetwork.org/namespaces/2014/transition"

the top level children of tn:initiative are all primaries. that is further people / web locations / locations should be stored under collections.

• tn:related_resources => other websites, exact PDF URLs
• tn:people => other people e.g. <tn:web-contacts><tn:person>...
• tn:locations => <tn:location type="orchard">...

tn:geokml is the polygon that surrounds the area of the geo-location. this allows analysis of overlap / area responsibilities etc.

• <tn:initiative initnumber="345" status="muller" uuid="21EC2020-3AEA-4069-A2DD-08002B30309D">
  • <tn:data-ownership>
    • <tn:registering-server>transitionportugal.org</tn:registering-server>
  • </tn:data-ownership>
  • <tn:name>Bedford west groovy town</tn:name>
  • <tn:location latitude="53.800651" longitude="-4.064941">
    • <tn:street></tn:street>
    • <tn:town>Bedford</tn:town>
    • <tn:county>Bedfordshire</tn:county>
    • <tn:country>England</tn:country>
    • <tn:geokml>53.800651,-4.064941;53.800651,-4.064941;53.800651,-4.064941;53.800651,-4.064941;53.800651,-4.064941;53.800651,-4.064941;</tn:geokml>
  • </tn:location>
  • <tn:summary>we are the groovy Bedford town dudes</tn:summary>
  • <tn:website>
    • <url>http://transitionbedford.org.uk</url>
  • </tn:website>
  • <tn:person uuid="EC212020-3AEA-4069-A2DD-080029DB3030">
    • <tn:name>Annesley Newholm</tn:name>
    • <tn:email>annesley_newholm@yahoo.it</tn:email>
  • </tn:person>
• </tn:initiative>

Fields on creation of TI node from widget

AGREED: only those added in the widget process

Work to do

user functionality / registration: 1 day

user blocked username = firstname lastname set firstname and lastname fields send password in email* user UUID there? author => primary point of contact

front-end UX: 1 day

take some style CSS out of Drupal plugin in to TN.org

un-check radio buttons if t:other clicked

email address format validation

keycode == 13 for search again

set_message is setting a drupal message which won't appear in the popup

functionality in registration: 2-3 days

for moment: allow user to select granuality -> post analyse initiative type

send through ALL geocode information for setting in the location

DNS lookups performance issues

move to a simple text box entry

is location data county sensitive?*

TIs_nearby() calcs - important to do this for future proofing of concepts*

language:

users computer

default language to the national hub

english

other widgets: 3-6 days

other widgets (see spec at https://www.transitionnetwork.org/blogs/ed-mitchell/2013-08/international-initiative-registration-service-workflows):

map

list

basic editing: javascript HTML dump in*

deployment / testing: 1 day

XML schema

deployment on to live

commenting / code documentation / re-visit

cross browser testing

not included

discussion

project management

maintenance

ranting on trac

TOTAL: 8-12 days

BUDGET @ £150 / day: £1200 - £1800

* - risks / not so sure about timings

Original documentation:

• Please see the original documentation for what data to capture here:
• Please the the original documentation for the workflows here

Timesheets

• See list of Annesley activities in detail on the timesheets page