Description

The EDU Plugin used by the NeuroTechEDU website to integrate different services from third-party APIs into wordpress. It is managed as if it was a single plugin but is really multiple plugins providing different types of integration with wordpress (Github, Meetup, ...).

Installation

Method 1: From the Admin Page

To install the plugin:

1. ZIP the content of this repository.
2. From the Admin page, go to the plugin tab and select Add New.
3. Click on the Upload Plugin button and select the ZIP file.
4. Activate the plugin.

Alternative Method

1. On your host, create a new folder (ideally named after the plugin) in the wp-content/plugins directory.
2. Manually copy the files of this repository to the new folder. e.g. Through ftp, scp, ...
3. Activate the plugin via the Admin page.

Extending the EDUPlugin with new plugins

The EDUPlugin is just a loader used to load the plugins in the includes/ directory, including the admin settings page. By convention, the plugins in includes/ are named _Plugin.php_ (such files are "php included" automatically).

To write additional plugins, the callbacks are wrapped in a class to allow different configurations through the class's member attributes.

The class contains two methods:

• The constructor
• The callback
• The shortcode method

The class constructor is used to set the states of the plugin. The callback is the function that gets called when the wordpress hook gets triggered. The shortcode method is the function that generates the page's content. See includes/GithubReadmePlugin.php as an example.

The plugin is then loaded in EDU_Plugin.php . To load a plugin, instantiate an instance of that plugin in the run_EDUPlugin() function of the EDU_Plugin.php file, along with the necessary parameters that the class constructor requires.

Depending on the plugin's use case, call add_action or add_filter member method of the EDUPlugin instance, passing the hook, and an array containing an instance of the plugin and the name of the callback.

For plugins involving generating content in a page or post, it is preferable and more flexible to use the shortcode api. In this case, instead of a callback function in the plugin class, we use a function to generate the desired output and use the add_shortcode() interface. See https://codex.wordpress.org/Shortcode_API

e.g.

$ghplugin = new GithubReadmePlugin( $gh, $owner, $repo, $page_ids, "html" );
$EDUPlugin->add_filter( 'the_content',
                        array( $ghplugin, 'callback_github_readme' ) );
add_shortcode( 'github_readme',
               array( $ghplugin, 'generate_shortcode' ) );                       

To add additional options to the plugin's admin page, add the settings' section and field in the EDUPlugin_page_init callback of the EDUPluginAdmin class in EDUPluginAdmin.php.

See:

• https://codex.wordpress.org/Function_Reference/add_settings_section
• https://codex.wordpress.org/Function_Reference/add_settings_field

Plugins

GithubReadmePlugin

The GithubReadmePlugin set the content of a post (post or page) to the content of a Github Repo's readme.

The parameters that must be set from the settings page are:

• User accessing Github's API
• User token
• Repo owner
• Repo name

To use the plugin, add the content to a post using the following shortcode: [github_readme class="foo"] where:

• class will set the class of the div that wraps the content of the readme.

MeetupEventPlugin

The MeetupEventPlugin set the content of a post (post or page) to a list of Meetup events.

The parameters that must be set from the settings page are:

• API key
• Event groups

To use the plugin, add the content to a post using the following shortcode: [meetup_events class="foo"] where:

• class will set the class of the div that wraps each items of the list of events.

EventbriteEventPlugin

The EventbriteEventPlugin set the content of a post (post or page) to a list of Eventbrite events.

The parameters that must be set from the settings page are:

• API key
• A list of comma separated organizer ids to get the events from

To use the plugin, add the content to a post using the following shortcode: [eventbrite_events class="foo"] where:

• class will set the class of the div that wraps each items of the list of events.

AllEventsPlugin

The AllEventsPlugin set the content of a post (post or page) to a list of all events (Meetup U Evenbrite).

This plugin can also be used to draw a map (Google Maps) with markers.

To use the plugin, add the content to a post using the following shortcode: [all_events class="foo" upto="+2 months"] where:

• class will set the class of the div that wraps each items of the list of events,
• upto limits the events from not up to the given time. e.g. upto="+2 months" will only give the events between now and 2 months from now.

It is also possible to add text input elements on the same page as the above shortcode to allow filtering by city and/or date range. To do so, add an input element on the same page as the above shortcode with id="eventFilterTextInput": <input type="text" placeholder="City" id="eventFilterTextInput">.

This will add the possibility to filter the events by its city's name.

To allow filtering by a date range, add two input elements with type="date" wrapped in a form element with the following attributes:

<form action="#" class="ws-validate">
    <input data-dependent-validation='{"from": "eventFilterToDateInput", "prop": "max"}'
           type="date"
           placeholder="From"
           id="eventFilterFromDateInput"
           style="float:left;">
    <input data-dependent-validation='{"from": "eventFilterFromDateInput", "prop": "min"}'
           type="date"
           placeholder="To"
           id="eventFilterToDateInput"
           style="float:left;">
</form>

NOTE: We use webshim to customize and add extra functionalities (such as client-side validation on HTML5's date input element). See https://afarkas.github.io/webshim/demos/

To add a map of events: [event_map id="foo" scrollWheel="true"] where:

• id is the id of the div where the map will be drawn,
• scrollWheel to enable scroll wheel scaling on the map. (Disabled by default.)

Since Meetup and Eventbrite have similar, but still different representations of an event, we need to aggregate the data from both source into a common format. We use the following standard:

[
    {
        'epoch': $epoch,
        'datetime': $datetime,
        'link': $link,
        'title': $title,
        'description': $description,
        'organizer_name': $organizer_name,
        'organizer_link': $organizer_url,
        'lat': $lat,
        'lng': $lng,
        'address': $address,
        'city': $city
    },
    .
    .
    .
]

Resources

Some useful resources to write plugins:

• Introduction to Plugin Development
• Writing a Plugin
• Plugin API
• Shortcode API
• Creating Option Pages
• Useful references:
  • Filter Reference
  • Action Reference
  • Function Reference