Home

Setup

Hey! Welcome!

So you're interested in using this plugin? Great!

Before we start integrating the plugin & the snippet to your Kirby CMS, let me show you the Stack Exchange API Docs.

I'll refer to it during the setup multiple times.

Note: I try hard to make the plugin usage as simple as possible for you with API knowledge on your side as little as possible. But this is a longterm goal due to the complexity of the API and to preserve the flexibility of this plugin. At the moment you may need to take a short look into the docs from time to time.

The setup contains four steps:

Step 1 - Integrate the plugin

First you have to copy the plugin file stackexchange.php to your Kirby CMS plugin directory

Step 2 - Integrate the snippet

Then copy the corresponding snippet stackexchange-snippet.php to your Kirby CMS snippet directory

Step 3 - Template Integration

Integrate the snippet into your template(s).

Simply add the the following code line to your templates.

<?php snippet('stackexchange-snippet'); ?>

That's quite simple, isn't it? Now let's come to the last step where the magic happens.

Step 4 - Page Integration

To use the plugin with the help of the snippet you need to add custom variables to your page where you want to include StackExchange Results.

Which community site?

Each API Request, which will be handled by this plugin, needs at least the Stack Exchange community site you are referring to (e.g. StackOverflow, Super User, Server Fault, Mathematics etc.). Due to the fact, that this plugin has no clue which site you are referring to, you have to specify the site specific name on your markdown coded page.

For example with stackexchangesite:stackoverflow you would refer to the stackoverflow community.

Note: The community site name you have to insert is based on the specific community site url (e.g. for http://gamedev.stackexchange.com/ the name is gamedev, for http://fitness.stackexchange.com/ it's fitness). Hence we could say: You have to insert cname of the community site you want to pull the results from.

What do you want to do?

Next you have to specify which method you want to trigger or more naturally formulated: What do you want to do?

Examples:

• I want to have all answers to a specific question on the fitness site
• Show me all latest asked questions on the Science Fiction and Fantasy site
• Show me this freaking awesome answer on my question by this genius guy which saved me hours on that problem!

All these use cases are possible, but unfortunately the plugin isn't that smart to convert the sentences above into API requests. But maybe in some months ¯\(ツ)/¯

At the moment you have to take a look into the API documentation.

Let's assume the last case. You want to show one or more specific answers. Then the API method specified at https://api.stackexchange.com/docs/answers-by-ids seems to be your best friend. Let's cut out the subpath of the method based on the above URL which is answers-by-ids. This is your answer on the question What do you want to do?.

Hence you answer to the above question with the method subpath in the API documentation url.

Here you have to set on your page:

stackexchangemethod:answers-by-ids

Now the plugin knows "Ah, you want some answers! Ok, but which ones?"

So you need to specify which answers you want to get. Almost every Stack Exchange API object has an ID for referencing. So you have to tell the plugin the ID of the answer(s) you want to show by specifying them in a semicolon separated list.

You can get the IDs by taking a look on the site url of your community question, or by taking a look on the HTML (you can find data attributes there like data-answerid, data-questionid etc.

Or by clicking on the share button under each answer on the Stack Exchange sites. You will get a link and the number at the end of the url is the ID of your object.

Then you have to write the ID list like

stackexchangemethodids:28306

Filters, Filters, Filters

Filters are great! They help us to keep simplicity and hide all unnecessary things we don't need. So it's really cool that the the Stack Exchange API is also based on filters.

But what are filters with concern of the Stack Exchange API?

Filters allow applications to reduce API responses to just the fields they are concerned with, saving bandwidth. With the list of fields an application is actually concerned with, the API can avoid unneccessary queries thereby decreasing response time (and reducing load on our infrastructure). Finally, filters allow us to be more conservative in what the API returns by default without a proliferation of parameters (as was seen with body, answers, and comments in the 1.x API family). Source: https://api.stackexchange.com/docs/filters

This means you can add your own filters to guarantee good response time on your website by only get the data you want. Isn't that a nice feature?

There are four API built-in filters which you can use right away:

default - The API's default filter

withbody - Which is default plus the *.body fields

none - which is almost empty data returning. Only some meta informations

total - which includes just .total

The plugin uses a default filter based on withbody which means all *.body fields (containing all HTML content of an answer, question etc.) are already included by default when you are using the plugin without specifying a specific filter.

But if you don't need any HTML output, but only some meta informations (e.g. date when an answer was posted) then you may specify a custom filter based on your needs (you can create custom filters here. This may speed up the plugin usage a little bit, as said before. So think about your use-case and which data you really need.

To override the plugin's default filter you can add

stackexchangefilter:filtername

to your page.

What do you want to show?

At the end you have to tell the plugin which data fields you want to show.

The plugin will loop through this comma separated list of field names and will show the corresponding data on your webpage.

Let's proceed with the example from the beginning. So you want to get specific answers, based on IDs. Now you have to specify what you want to display to your site visitors. Let's assume you want to show the answer itself, means the answer's body field and some informations about the person who has written the answer, means the owner of the answer. For a complete reference of all answer fields, go to the Stack Exchange Answer Type Site.

For the output specified above, you simply have to type in

stackexchangeoutput: body, owner

And that's it. Then the plugin will fetch your entries and outputs the data you've specified based on the plugin's default layout (see defaultLayout() method in the plugin file).

Note: At the moment you either have to customize the defaultLayout method based on your needs or you can edit the rendering directly in the snippet file where the defaultLayout() method is called. But I try to find a simple and clean way to define custom layouts easily.

Summary

At the moment you can "control" the plugin via Kirby based on five custom variables you can add to your page:

stackexchangesite (mandatory): Defines which StackExchange hosted site(s) content you want to include.

stackexchangemethod (mandatory): Defines which API method(s) you want to use

stackexchangemethodids (mandatory based on chosen method): Semicolon separated list of object IDs you want to show (based on the method you've chosen)

stackexchangefilter (default filter withbody): Here you can add your custom StackExchange API Filter

stackexchangeoutput (mandatory): Here you have to specify which data fields you want to show on your page.

Example Use Case

Let's say you plan a trip to Taipei and you want to know good places to get an internet connection. That's not a joke, but a real example see this posting.

Now you want to show all answers to this question on your Kirby CMS page. After you're finished with step 3 of this plugin setup you only need to set these page variables correctly to get what you want, namely all live answers to this question on your page.

Let's go through the page variables:

So you want to access content from the travel page (travel.stackexchange.com). Hence you have to set stackexchangesite:travel. Quite easy, isn't it? ;-)

Furthermore you want to get all answers posted for a specific question. If you take a look on the methods overview site you can see, that the method described on the url https://api.stackexchange.com/docs/answers-on-questions is what you are searching for.

The last sub-path of the API documentation URL for this method is answers-on-questions. Hence you can set stackexchangemethod to this subpath string:

stackexchangemethod:answers-on-questions

The stackexchangemethodids variable corresponds to the {ids} parameter in the official method documentation. You need to set this value to the Question ID of the question you want to filter/integrate. You can find this question ID in the url of the posting: travel.stackexchange.com/questions/ 7770 /internet-connections-in-taipei.

Hence you have to set stackexchangemethodids:7770

The last mandatory varibale is stackexchangeoutput where you have to specify which content fields you want to display on your page. The answers-on-questions method returns answer objects which have a defined set of content fields to display (see here). Since we want to show the real answer text or body (which is the field name for the raw content within the complete StackExchange API) and the owner of the answer you need to set:

stackexchangeoutput: body, owner

It's really simple, isn't it? Of course there is much room for improvements and user-friendly interaction. But as I said this is a pre-pre-alpha version, so to say.

Note: You don't necessarily need to add a custom filter here, because the plugin's default filter contains answer.body and answer.owner fields. So this example will work without specifying a custom filter. But of course, you can replace default filter by a custom one.

The final page setup looks like this.

At the end you should see the answers on your Kirby CMS Page like this! Yay!

And that's it. Happy coding!