Sharing Engine/Technical workflow & business logic

This page describes the workflows and processes from a technical standpoint. It is designed to help a developer get to the area of the system quickly, and understand the relationships between the data, Drupal's content system, theme and the custom Transition PSE module that drives the Project Sharing Widget. It is broken into key areas as follows...

See documentation for the custom theme, feature and module that makes it all work.

Principles, core features and background

• Submissions are kept separate from the rest of the system in their own content type.
• All forms shown to the end user (submitting a Project) are kept as simple as possible.
• Only users who are entered as the Web Point of Contact for an Initiative Profile are able to start the 'Get the Widget' process.
• All logic for this PSE system is encapsulated by a custom module and a exported Feature.
• Drupal 6 best practices have been followed where possible, though there are a few areas where the code could use a little tidying up -- but that's for another day when the Beta is tested and ready for the final version.
• WebForm was considered to be used to manage the the PSE submissions, but since it has less flexibility and moderation options, it was cleaner just to have our own content type to store the submission temporarily.
• Originally we tried to use the pre-existing Project Profile content type, but unfortunately it became too complex to strip out all the fields from the forms it generated, change the access based on a new field for 'moderation status' and prevent our other modules trying to do things during form build and submission. It was simpler to just have our own clean form, map that to a temporary content type, then (only when accepted by a moderator) copy that information to the final Project Profile node.
• Any questions, please contact me, Jim Kirkpatrick.

Generation & rendering the Widget

NOTE Most code relating to the process of a user getting (and the system rendering) a widget are in the transition_pse.widget.inc file -- please review that file for further information.

Getting/generating a widget

1. The user must be a 'Web Point of Contact' for at least one initiative on the Transition Network site. The function transition_pse_web_point_of_contact_initiatives_access() and transition_pse_web_point_of_contact_initiatives() handle this check in transition_pse.module.
2. Users who are not Web PoC this will get a message generated by transition_pse_widget_get() in transition_pse.widget.inc
3. When a user is a Web PoC, if they do not already have the 'Widget Owner' role they get a 'sign up' page generated by transition_pse_widget_owner_signup_form() where they have the option of signing up to the Widget Owners Newsletter (via MailChimp integration, only if they're not already signed up). They also MUST agree to the terms and conditions.
4. When they agree to the terms and submit, they gain the 'Widget Owner' role, which allows access to the widget generation page.
5. The widget generation page is created by transition_pse_widget_generate() and allows a user to choose 'button', 'sidebar' and 'full' versions of the widget. They must then choose the appropriate initiative and submit.
6. The widget is rendered by transition_pse_widget_generate() and various theme() functions in transition_pse.widget.inc in a box rendered by the Web Widgets module. This appears together with the options to sign up to the newsletter (if they haven't already) and a note on how the moderation works.

Viewing the widget

Once on a site, the widget has 3 parts

1. Chrome (widget outer HTML) -- is a set of simple divs that are styled by the CSS and JS found in the widget directory of the transition_pse module. This is what is generated by the above process and pasted into a website by a webmaster.
2. View widget -- This contains either a view of the projects near to the related initiative (sidebar widget), or some QuickTabs for view, find and about pages (full widget). The 'button' widget does not have a view area. See transition_pse_view_sidebar() and transition_pse_view_full() for the theme() and views calls.
3. Entry widget -- This is covered by Entry widget section, below.

Entry widget: Register/login & submission entry workflow

The 'entry widget' describes the process from the point the user clicks the 'Add your Project' button on the main 'view widget', all the way through to successful submission of the project. Most of this code is found in the https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.pages.inc transition_pse.pages.inc] file.

1. User clicks the 'Add your Project' button on the main 'view widget', popping up a modal div containing an iFrame onto the 'pse/entry/add-project/[participant_uid]/[initiative_nid]' page.
2. The module first checks the user and initiative passed in are valid and have the permissions/setup in _transition_pse_participants_load() and a warning is shown if there's a problem by _transition_pse_invalid_participants_warning(). A flag is set so the system knows a valid PSE operation is occurring.
3. The transition_pse_entry_form_steps() callback handles the page to be displayed: login/register or 'add project'.
4. If the user is not logged in, a combined login/register page is displayed with a toggle to quickly switch between them - see transition_pse_unified_login_page()
5. The login page is the standard Drupal login form.
6. The registration page is also the standard Drupal login form BUT it has all non-required fields removed by transition_pse_form_alter() in the main .module file. A custom submit handler transition_pse_user_register_submit() ensures a unique username in the form of '[firstname] [lastname]' is created.
7. If a user registers via the widget, the Rule PSE: Add 'widget' to user adds the 'Widget user' role to the user so we can see who came in via the widget.
8. When the registration/login is complete, transition_pse_entry_page() outputs the 'Add your project' form created by transition_pse_entry_form() which is a simple 'bare bones' form that uses MaxLength, CCK and Location module calls.
9. When submitted, the transition_pse_entry_form_submit() creates a new 'PSE Project Submission' node, maps the fields entered, and saves it. Two emails are sent, one to the submitter and one to the wiget owner using drupal_mail() which calls our transition_pse_mail() mail hook. These in turn call transition_pse_submitter_mail_text() and transition_pse_webmaster_mail_text() in transition_pse.moderation.inc.
10. Finally, the 'Thank you' page is output using transition_pse_entry_thanks() and the appropriate theme() functions.

Moderation workflow

Most of the code, views, rules, assets and other logic is found in the https://github.com/transitionnetwork/transition_pse_widget transition_pse_widget] feature, and the transition_pse.moderation.inc file.

1. When the PSE Project Submission widget node is created during submission, it becomes available for review to the Web Point of Contact for the related initiative via the 'Project Moderation' (/user/[user id]/widget-moderation) tab on their homepage. That page contains two views with sub-tabs...
2. The 'Needing moderation' tab (default) lists the submissions for which the current user is the web contact for. There is a table of submissions and a 'Review' button.
3. When 'Review'ing the submission, the display uses a Panels node_view override for a nice layout, with two buttons: "Accept: add to the Projects Directory", and "Reject: DELETE this submission". # Accepting the submission calls transition_pse_submission_accept(), which maps the submission fields on to a 'proper' Project Profile node, saves the new node, deletes the submission, and sends an accept email using transition_pse_submitter_mail_text().
4. Rejecting the suibmission calls transition_pse_submission_reject() simply deletes the submission node and reject email using transition_pse_submitter_mail_text().
5. Accepted submissions then go to the second tab on the user's Project Moderation page, "Accepted projects" (user/[user id]/widget-moderation/accepted) as long as the user remains the web point of contact for the project.