From 774970ec46ed9ae19752f85944ebcade5eef8f68 Mon Sep 17 00:00:00 2001 From: Joost Cassee Date: Thu, 27 Jan 2011 12:51:29 +0100 Subject: [PATCH] Refactor KISSinsights module into its own app This commit has not been tested. --- analytical/kiss_insights/__init__.py | 133 ++++++++++++++++++ .../kiss_insights/templatetags/__init__.py | 0 .../templatetags}/kiss_insights.py | 36 +++-- analytical/templatetags/analytical.py | 2 +- docs/services/kiss_insights.rst | 36 +---- 5 files changed, 164 insertions(+), 43 deletions(-) create mode 100644 analytical/kiss_insights/__init__.py create mode 100644 analytical/kiss_insights/templatetags/__init__.py rename analytical/{services => kiss_insights/templatetags}/kiss_insights.py (56%) diff --git a/analytical/kiss_insights/__init__.py b/analytical/kiss_insights/__init__.py new file mode 100644 index 0000000..81627f2 --- /dev/null +++ b/analytical/kiss_insights/__init__.py @@ -0,0 +1,133 @@ +""" +================================ +KISSinsights -- feedback surveys +================================ + +KISSinsights_ provides unobtrusive surveys that pop up from the bottom +right-hand corner of your website. Asking specific questions gets you +the targeted, actionable feedback you need to make your site better. + +.. _KISSinsights: http://www.kissinsights.com/ + + +.. kiss-insights-installation: + +Installation +============ + +You only need to do perform these steps if you are not using the +generic :ttag:`analytical.*` tags. If you are, skip to +:ref:`kiss-insights-configuration`. + +In order to use the template tag, you need to add +:mod:`analytical.kiss_insights` to the installed applications list in +the project :file:`settings.py` file:: + + INSTALLED_APPS = [ + ... + 'analytical.kiss_insights', + ... + ] + +The KISSinsights survey code is inserted into templates using a template +tag. Load the :mod:`kiss_insights` template tag library and insert the +:ttag:`kiss_insights` tag. Because every page that you want to track +must have the tag, it is useful to add it to your base template. Insert +the tag at the bottom of the HTML body:: + + {% load kiss_insights %} + ... + + + {% kiss_insights %} + ... + + +.. _kiss-insights-configuration: + +Configuration +============= + +Before you can use the KISSinsights integration, you must first set your +account number and site code. + + +.. _kiss-insights-account-number: + +Setting the account number and site code +---------------------------------------- + +In order to install the survey code, you need to set your KISSinsights +account number and website code. The :ttag:`kiss_insights` tag will +include it in the rendered Javascript code. You can find the account +number and website code by visiting the code installation page of the +website you want to place the surveys on. You will see some HTML code +with a Javascript tag with a ``src`` attribute containing +``//s3.amazonaws.com/ki.js/XXXXX/YYY.js``. Here ``XXXXX`` is the +account number and ``YYY`` the website code. Set +:const:`KISS_INSIGHTS_ACCOUNT_NUMBER` and +:const:`KISS_INSIGHTS_WEBSITE_CODE` in the project :file:`settings.py` +file:: + + KISSINSIGHTS_ACCOUNT_NUMBER = 'XXXXX' + KISSINSIGHTS_SITE_CODE = 'XXX' + +If you do not set the account number and website code, the survey code +will not be rendered. + + +.. _kiss-insights-identity-user: + +Identifying authenticated users +------------------------------- + +If your can identify website visitors, you can pass this information +on to KISSinsights so that you can tie survey submissions to customers. +By default, the username of an authenticated user is passed to +KISSinsights automatically. See :data:`ANALYTICAL_AUTO_IDENTIFY` for +important information about detecting authenticated visitors. + +You can also send the identity yourself by adding the +``analytical_identity`` variable to the template context:: + + context = RequestContext({'analytical_identity': identity}) + return some_template.render(context) + +If you can derive the identity from the HTTP request, you can also use +a context processor that you add to the +:data:`TEMPLATE_CONTEXT_PROCESSORS` list in :file:`settings.py`:: + + def identify(request): + try: + return {'analytical_identity': request.user.email} + except AttributeError: + return {} + +Just remember that if you set the same context variable in the +:class:`~django.template.context.RequestContext` constructor and in a +context processor, the latter clobbers the former. + + +.. _kiss-insights-show-survey: + +Showing a specific survey +------------------------- + +KISSinsights can also be told to show a specific survey. You can let +the :ttag:`kiss_insights` tag include the code to select a survey by +passing the survey ID to the template in the +``kiss_insights_show_survey`` context variable:: + + context = RequestContext({'kiss_insights_show_survey': 1234}) + return some_template.render(context) + +For information about how to find the survey ID, see the explanation +on `"How can I show a survey after a custom trigger condition?"`_ on the +KISSinsights help page. + +.. _`"How can I show a survey after a custom trigger condition?"`: http://www.kissinsights.com/help#customer-trigger +""" + +kiss_insights_service = { + 'body_top': 'analytical.kiss_insights.templatetags.kiss_insights.KissInsightsNode', +} diff --git a/analytical/kiss_insights/templatetags/__init__.py b/analytical/kiss_insights/templatetags/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/analytical/services/kiss_insights.py b/analytical/kiss_insights/templatetags/kiss_insights.py similarity index 56% rename from analytical/services/kiss_insights.py rename to analytical/kiss_insights/templatetags/kiss_insights.py index 7143021..79ecbb4 100644 --- a/analytical/services/kiss_insights.py +++ b/analytical/kiss_insights/templatetags/kiss_insights.py @@ -1,14 +1,14 @@ """ -KISSinsights service. +KISSinsights template tags. """ import re -from analytical.services.base import AnalyticalService +from django.template import Library, Node, TemplateSyntaxError -ACCOUNT_NUMBER_RE = re.compile(r'^\d{5}$') -SITE_CODE_RE = re.compile(r'^[\d\w]{3}$') +ACCOUNT_NUMBER_RE = re.compile(r'^\d+$') +SITE_CODE_RE = re.compile(r'^[\w]{3}$') SETUP_CODE = """ @@ -17,15 +17,34 @@ IDENTIFY_CODE = "_kiq.push(['identify', '%s']);" SHOW_SURVEY_CODE = "_kiq.push(['showSurvey', %s]);" SHOW_SURVEY_CONTEXT_KEY = 'kiss_insights_show_survey' -class KissInsightsService(AnalyticalService): + +register = Library() + + +@register.tag +def kiss_insights(parser, token): + """ + KISSinsights set-up template tag. + + Renders Javascript code to set-up surveys. You must supply + your account number and site code in the + ``KISS_INSIGHTS_ACCOUNT_NUMBER`` and ``KISS_INSIGHTS_SITE_CODE`` + settings. + """ + bits = token.split_contents() + if len(bits) > 1: + raise TemplateSyntaxError("'%s' takes no arguments" % bits[0]) + return KissInsightsNode() + +class KissInsightsNode(Node): def __init__(self): self.account_number = self.get_required_setting( 'KISS_INSIGHTS_ACCOUNT_NUMBER', ACCOUNT_NUMBER_RE, - "must be a string containing an five-digit number") + "must be (a string containing) a number") self.site_code = self.get_required_setting('KISS_INSIGHTS_SITE_CODE', SITE_CODE_RE, "must be a string containing three characters") - def render_body_top(self, context): + def render(self, context): commands = [] identity = self.get_identity(context) if identity is not None: @@ -35,5 +54,6 @@ class KissInsightsService(AnalyticalService): % context[SHOW_SURVEY_CONTEXT_KEY]) except KeyError: pass - return SETUP_CODE % {'account_number': self.account_number, + html = SETUP_CODE % {'account_number': self.account_number, 'site_code': self.site_code, 'commands': " ".join(commands)} + return html diff --git a/analytical/templatetags/analytical.py b/analytical/templatetags/analytical.py index 195f5ec..fe58679 100644 --- a/analytical/templatetags/analytical.py +++ b/analytical/templatetags/analytical.py @@ -17,7 +17,7 @@ DEFAULT_SERVICES = [ 'analytical.crazy_egg.crazy_egg_service', 'analytical.google_analytics.google_analytics_service', 'analytical.hubspot.hubspot_service', - 'analytical.kiss_insights.KissInsightsService', + 'analytical.kiss_insights.kiss_insights_service', 'analytical.kiss_metrics.KissMetricsService', 'analytical.mixpanel.MixpanelService', 'analytical.optimizely.OptimizelyService', diff --git a/docs/services/kiss_insights.rst b/docs/services/kiss_insights.rst index 9ddc91f..9f2e105 100644 --- a/docs/services/kiss_insights.rst +++ b/docs/services/kiss_insights.rst @@ -1,35 +1,3 @@ -KISSinsights -- feedback surveys -================================ +.. currentmodule:: analytical.kiss_insights -KISSinsights_ provides unobtrusive surveys that pop up from the bottom -right-hand corner of your website. Asking specific questions gets you -the targeted, actionable feedback you need to make your site better. - -.. _KISSinsights: http://www.kissinsights.com/ - -The code is added to the top of the HTML body. By default, the -username of a logged-in user is passed to KISSinsights. See -:data:`ANALYTICAL_AUTO_IDENTIFY`. - - - -Required settings ------------------ - -.. data:: KISSINSIGHTS_ACCOUNT_NUMBER - - The KISSinsights account number:: - - KISSINSIGHTS_ACCOUNT_NUMBER = '12345' - -.. data:: KISSINSIGHTS_SITE_CODE - - The KISSinsights website code:: - - KISSINSIGHTS_SITE_CODE = 'abc' - -You can find the account number and website code by visiting the code -installation page of the website you want to place the surveys on. You -will see some HTML code with a Javascript tag with a ``src`` attribute -containing ``//s3.amazonaws.com/ki.js/XXXXX/YYY.js``. Here ``XXXXX`` is -the account number and ``YYY`` the website code. +.. automodule:: analytical.kiss_insights