View source for 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 [[Sharing_Engine/Drupal_code:_a_module,_a_feature_and_a_theme|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.
* [http://drupal.org/project/webform 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, [http://i-jk.co.uk/contact 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 [https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.widget.inc transition_pse.widget.inc] file -- please review that file for further information.

=== Getting/generating a widget ===
# 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 [https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.module#L401 transition_pse.module].
# Users who are not Web PoC this will get a message generated by '''transition_pse_widget_get()''' in [https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.widget.inc#L15 transition_pse.widget.inc]
# 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 '''[https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.widget.inc#L73 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.
# When they agree to the terms and submit, they gain the 'Widget Owner' role, which allows access to the widget generation page.
# 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.
# 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
# '''Chrome (widget outer HTML)''' -- is a set of simple divs that are styled by the CSS and JS found in the [https://github.com/transitionnetwork/transition_pse/tree/master/widget widget directory of the transition_pse module]. This is what is generated by the above process and pasted into a website by a webmaster.
# '''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.
# '''Entry widget''' -- This is covered by [[Sharing Engine/Technical_workflow_%26_business_logic#Entry_widget:_Register.2Flogin_.26_submission_entry_workflow| 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.

# 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.
# 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.
# The '''transition_pse_entry_form_steps()''' callback handles the page to be displayed: login/register or 'add project'.
# 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()'''
# The login page is the standard Drupal login form.
# 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.
# 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.
# 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.
# 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 [https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.moderation.inc transition_pse.moderation.inc].
# 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 [https://github.com/transitionnetwork/transition_pse/blob/master/transition_pse.moderation.inc transition_pse.moderation.inc] file.
# 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...
# 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.
# 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()'''.
# Rejecting the suibmission calls '''transition_pse_submission_reject() simply deletes the submission node and reject email using '''transition_pse_submitter_mail_text()'''.
# 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.