IIRS Solution Design

Please refer to the IIRS/ArchitectureOptions and principles therein.

Features overview

The IIRS will be an add-on service with its own Drupal 7 install. This install will provide the means to:

1. Initiatives: A slimline Initiative content type, related views and maps etc that are synced with TN.org D6.
2. Users: Allow users to log in (to their accounts on the current D6 site), or register (with the new account synced back from D7 to D6).
3. Widget: Add, Edit (with correct perms), list/map initiatives and view single initiatives via a widget.
4. Sync: post-moderated (pre-accepted) D7 initiatives back to TN.org D6 via a web service, AND from D6 to D7 as edits happen there.
5. Hub: Store 'National Hub profiles' that facilitate the translation and syncing of the UI and data.

Drupal 6 site changes

1. New content type: "Transition Hub" - represents the key information about the hub and widgets that will provide content in that language. Has language, country, translated intro text, points of contact, and remote (D7) path for services.
2. New Panels layout for "Transition Hub" content type: Shows key (translated) text in panels layout, below which is a full-page widget showing lists and maps of Initiatives, with the option to view them IN A POPUP in the Hub language. This panel should ideally pre-display the widget using variables from the Hub profile.
3. Services for syncing user accounts, Transition Hub and Initiative profiles nodes automatically on edit, delete (unpublish) and 'provision' to get the D7 site the content it needs.

Drupal 7 site features

Distribution, Profile, Frameworks

1. Based on ​Panopoly for an excellent editorial experience out of the box. There is a lot of momentum around Panopoly in the Drupal world.
2. Theme based on Twitter's ​Bootstrap (v2.3.2) framework for a cross-browser, responsive, clean and deeply sexy starting point. There's loads of good resources and tools on the web for Bootstrap.
3. Lots of Drupal themes integrate with Bootstrap, but ​Radix is also gaining a lot of traction with distributions and works great with Panopoly, Open Atrium, Open Outreach and others.
4. [​Debut will provide as much base features as possible, to minimise custom code and get a fast start on key features. For now these are not needed for content types, but standardising around other features will make future development and integration with other Drupal sites easier. Recommended for consideration: ​Membership, ​Location, ​Social, ​WYSIWYG
5. Will create a 'Transition National Hub' Drupal install profile to allow this site to be built easily on the Transition Network server, and indeed on other interested parties systems.

Transition-specific custom Features & modules

@todo create a diagram to show what features sit where, and what depends on what...

1. Transition Network Core - D7 - variables in feature wrapping all shared dependencies and extras needed to make the site(s) tick.
2. Transition Initiatives - D7 - a feature wrapping up a content type, some simple list-style views (user-facing and admin) and panels panes.
3. Transition Hub - D6 & D7 - anything specific to national hubs goes here. Each 'Hub' content represents a national hub and has language(s), name, country, website and other data. D6 version provides content type, plus 'country homepage' with translated text and widget embedded panels view. D7 provides content type (and others feature TBC).
4. Transition Users - D7 - a feature wrapping up a basic user account, plus some views (users-facing and admin). Need to decide if this is core D7 accounts, or needs Profile2 etc. Ideally would handle social login/register too.
5. Transition * Services - D6 & D7 - (where * is 'intuitive', 'user' etc.) - a feature for each core piece of data that contains relevant services including CRUD, views/lists and probably authentication.
6. Transition Network Sync - D6 & D7 - a module that uses pluggable services (in the above point; for initiatives, users, projects, hubs etc etc) to sync data back to the 'hub' D6 TN.org site.

Widget design

The widget is to be a more flexible evolution of the work started in Sharing_Engine/Technical_Proposal Project Sharing Engine?. The plan is to build on this base but turn the it into a clear, clean model based on a set of components that can be added, extended and re-used. Since Drupal 7 is not MVC, and neither is Drupal 8, the proposal is to use the ​CTools Plugin architecture (​example here) to allow new Widget components to be added/enabled over time.

Widget modules

1. Widget Core --- a module that holds all the shared variables, admin, functions, permissions and other logic that will drive all widgets and facilitate the rest of the components.
2. Widget Builder -- this is the UI module that will allow a user (with permission) to chose the type of widget, Context (see below) Purpose and style of a Widget and build an instance. The module will take these options and create a 'Widget Recipe' (see Components, below) before generating the themed, styled Widget Chrome (below) for a user to paste into their website.
3. Widget Plugins: Initiatives - D7 - a module providing the widget plugins and logic for adding the Initiatives (converted from the ​D6 PSE project).

Widget components

1. Chrome (output, concept) -- the 'Widget Chrome' is this is the actual HTML and related CSS/JS, built by the Widget Builder (above), that a user cut/pastes into their site in order to display the widget. It's held on the client site and runs via whatever tech drives it (iFrames to start, web services & backbone maybe one day). The chrome used depends the user's choice of
2. Recipe -- When user builds a widget, the relevant context, workflow and purpose of the widget will be stored in a Drupal entity called Widget Recipe. This then allows a user to re-generate the widget at any with different styles/types using this recipe. It also allows a central store of both users and administrators to manage widgets and avoid misuse, and provides a means of recreating any widget in use to provide support and debugging. A Widget Recipe consists of:
   1. Style -- How it will look when the Chrome is built; Options Type (Full screen, sidebar, button options etc), Style (css, colours etc - not planned to be editable initially), and Delivery Framework (iFrame for now, later other options might become available).
   2. Purpose -- what the widget is for, e.g. National Directory (this is all we're building for the IIRS), Projects near Initiative, Single Node (e.g. for embedding a single page for an event, initiative or other content), Newsletter signup etc etc. The purpose wraps up a set of Displays (Views onto Services) inside Workflows (see below).
   3. Target -- the entity target(s) for the widget... For now the only 'target' data will be an 'Initiative' node, but this can be anything once the appropriate widget displays and services plugins are built (see below).
   4. Context -- the language, country, user (owner) and other background information the widget is to be used for. This data will be auto-selected from the user's account, or from another target depending on purpose.
3. Display -- An actual single pane of UI within the widget, either stand-alone or as part of a Workflow. Each 'Display' (effectively a 'View' in MVC) uses the theme layer to render the data provided by a Service that is set by the Recipe's context, target and purpose. However, in Drupal 7 and for the purposes of the IIRS, the Display (UI) and the Service (data/logic) are often provided together by various modules -- e.g. Drupal core's login form... For example, the 'View list of Initiatives' display will provide show the output of a Drupal view that lists the recent initiatives added
4. [NOTE SURE ABOUT THESE with regards to Displays -- TBC] Service -- are little chunks of functionality that deliver data to a View (see below). Ideally the services map directly to real web services, though for now this is not likely to be needed/possible since Drupal provides services and displays together. Examples would be 'List nodes', 'Search nodes', 'View Node', 'Log in', 'Register', 'Add node', 'Edit node', 'Newsletter Signup' etc. In Drupal 7 these are effectively menu callbacks with extra theming. Drupal 8/Symfony makes Services much more powerful however
5. Workflow -- A set of displays that go in sequence. E.g. Login/Register? -> Add [Target] -> Thank you page.

Widget Builder example

1. National Hub user (from France, in French) has permission to create themselves a widget.
2. They go to the Widget Builder and choose the Widget Recipe they want:
   • Purpose: "National Hub Listings"
   • Target: "Initiatives"
   • Style: "Full page", "Standard theme", "iFrame"
   • Title: (auto-generated but editable) t('Initiatives National Hub Listings, full page') = "Initiatives Listes nationales de Hub, complète la page".
3. They click 'Save & Generate' and their Widget Recipe entity is saved, and the context is automatically added:
   • Country: "France" (FR)
   • Language: "Français‎" (fr)
   • Owner: [current user]
   • Status: "Active"
   • Created/Edited?: [date/time today]
4. The page refreshes and their widget is shown in the example area, plus the Chrome (HTML code) in a box to copy/paste.

Widget Plugins needed

Leveraging ​CTools, the following plugins are needed for the IIRS... Note that the code for most of these plugins is already written in Drupal 6. What is required is to convert to a standardised component/plugin architecture:

• Style plugins:
  • Types: "Full page", "Sidebar", "Button only" = Chrome styles we currently have.
  • Style: "Default" = whatever we come up with based on very simple style.
  • Delivery Framework: "IFrame" = shows displays and popups using HTML IFrames.
• Purpose plugin: "National Directory (recent)" which uses:
• Target plugin: "Initiatives" = Provides services for and entity handling for viewing/adding Initiative Nodes.
• Display plugins:
  • "Tabbed National" = Large display with tabs for 'Recent', 'Map', and 'Search'). Uses following displays "Recent Content Listing", "Content Map" and "Content Search". Includes 'help' and 'about' links.
  • "Simple National" = Small display with tabs for 'Recent' [target] nodes. Uses following displays only the "Recent Content Listing" displays. Includes 'help' and 'about' links.
  • "Recent Content Listing" = A list of recently added [target] (initiatives in our case) in [country].
  • "Content Map" = A map of recently added [target] (initiatives in our case) in [country].
  • "Content Search" = A way of searching for [target] by name and location.
  • "View Content" = A popup to display a single [target] Node. Can also show edit options if user has permission. Used for displaying both the Initiative details, and the 'About' and 'Help' pages.
  • "Social Log in/Register" = A unified Login/Register? form display with Social Media connect options.
  • "Create Content" = A form to create [target] content, showing only core/required fields).
• Workflow plugin: "Registered User Create Content" which takes a user though the displays "Social Log in/Register" -> "Create Content" (for Initiative target) -> "View Content" ('About' page for Initiative target).

To do (updated 25 Aug 2013)

• Pin down relationships between views (both Drupal Views and View per MVC), Displays, Workflows and Services. It's almost clear but until development is started and the abilities of CTools are known, this is not easy to fully document at this stage.
• Work out how the 'Target' plugins will provide access to nodes, and what if anything they do to displays and services... Ideally they should extend such displays and make available certain fields that are important (e.g. location for initiatives/projects/events, date for events, type for resources etc).
• NOTE It's likely that Purpose, Workflows and Targets either overlap, need combining or need an intermediary object. Again this will be pinned down as work begins on these parts.

Web services

@todo see what the ​Services module does out the box. Note also D6 Services module is hamstrung by ​https://drupal.org/node/2014573.

Services include:

1. Entity sync for: Users, plus each content type we want to send to/from D6/7.
2. A login/authentication service.
3. Ideally make these resilient with a Queue.