xblocks-core 2.0.0__py3-none-any.whl

xblock_annotatable/.tx/config

@@ -0,0 +1,8 @@
+[main]
+host = https://www.transifex.com
+
+[o:open-edx:p:openedx-translations:r:xblock-annotatable]
+file_filter = conf/locale/<lang>/LC_MESSAGES/text.po
+source_file = conf/locale/en/LC_MESSAGES/text.po
+source_lang = en
+type        = PO

xblock_annotatable/__init__.py

@@ -0,0 +1,5 @@
+"""
+Init for the AnnotatableBlock.
+"""
+
+from .block import AnnotatableBlock as AnnotatableBlock

xblock_annotatable/block.py

@@ -0,0 +1,307 @@
+"""
+AnnotatableXBlock allows instructors to add interactive annotations to course content.
+Annotations can have configurable attributes such as title, body, problem index, and highlight color.
+This block enhances the learning experience by enabling students to view embedded comments, questions, or explanations.
+The block supports internationalization (i18n) for multilingual courses.
+"""
+
+import logging
+import textwrap
+import uuid
+
+import markupsafe
+from django.utils.translation import gettext_noop as _
+from lxml import etree
+from web_fragments.fragment import Fragment
+from xblock.core import XBlock
+from xblock.fields import Scope, String, XMLString
+from xblock.utils.resources import ResourceLoader
+
+from xblocks_core.legacy_utils.xml_utils import LegacyXmlMixin
+
+log = logging.getLogger(__name__)
+
+resource_loader = ResourceLoader(__name__)
+
+
+class SerializationError(Exception):
+    """
+    Thrown when a module cannot be exported to XML
+    """
+
+    def __init__(self, location, msg):
+        super().__init__(msg)
+        self.location = location
+
+
+@XBlock.needs("i18n")
+class AnnotatableBlock(LegacyXmlMixin, XBlock):
+    """
+    AnnotatableXBlock allows instructors to create annotated content that students can view interactively.
+    Annotations can be styled and customized, with internationalization support for multilingual environments.
+    """
+
+    # Indicates that this XBlock has been extracted from edx-platform.
+    is_extracted = True
+
+    display_name = String(
+        display_name=_("Display Name"),
+        help=_("The display name for this component."),
+        scope=Scope.settings,
+        default=_("Annotation"),
+    )
+
+    data = XMLString(
+        help=_("XML data for the annotation"),
+        scope=Scope.content,
+        default=textwrap.dedent(
+            markupsafe.Markup(
+                """
+                <annotatable>
+                    <instructions>
+                        <p>Enter your (optional) instructions for the exercise in HTML format.</p>
+                        <p>Annotations are specified by an <code>{}annotation{}</code> tag which may
+                        may have the following attributes:</p>
+                        <ul class="instructions-template">
+                            <li><code>title</code> (optional). Title of the annotation. Defaults to
+                            <i>Commentary</i> if omitted.</li>
+                            <li><code>body</code> (<b>required</b>). Text of the annotation.</li>
+                            <li><code>problem</code> (optional). Numeric index of the problem
+                            associated with this annotation. This is a zero-based index, so the first
+                            problem on the page would have <code>problem="0"</code>.</li>
+                            <li><code>highlight</code> (optional). Possible values: yellow, red,
+                            orange, green, blue, or purple. Defaults to yellow if this attribute is
+                            omitted.</li>
+                        </ul>
+                    </instructions>
+                    <p>Add your HTML with annotation spans here.</p>
+                    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                    <annotation title="My title" body="My comment" highlight="yellow" problem="0">
+                    Ut sodales laoreet est, egestas gravida felis egestas nec.</annotation> Aenean
+                    at volutpat erat. Cras commodo viverra nibh in aliquam.</p>
+                    <p>Nulla facilisi. <annotation body="Basic annotation example." problem="1">
+                    Pellentesque id vestibulum libero.</annotation> Suspendisse potenti. Morbi
+                    scelerisque nisi vitae felis dictum mattis. Nam sit amet magna elit. Nullam
+                    volutpat cursus est, sit amet sagittis odio vulputate et. Curabitur euismod, orci
+                    in vulputate imperdiet, augue lorem tempor purus, id aliquet augue turpis a est.
+                    Aenean a sagittis libero. Praesent fringilla pretium magna, non condimentum risus
+                    elementum nec. Pellentesque faucibus elementum pharetra. Pellentesque vitae metus
+                    eros.</p>
+                </annotatable>
+                """
+            ).format(markupsafe.escape("<"), markupsafe.escape(">"))
+        ),
+    )
+
+    # List of supported highlight colors for annotations
+    HIGHLIGHT_COLORS = ["yellow", "orange", "purple", "blue", "green"]
+
+    def _get_annotation_class_attr(self, index, el):  # pylint: disable=unused-argument
+        """Returns a dict with the CSS class attribute to set on the annotation
+        and an XML key to delete from the element.
+        """
+
+        attr = {}
+        cls = ["annotatable-span", "highlight"]
+        highlight_key = "highlight"
+        color = el.get(highlight_key)
+
+        if color is not None:
+            if color in self.HIGHLIGHT_COLORS:
+                cls.append("highlight-" + color)
+            attr["_delete"] = highlight_key
+        attr["value"] = " ".join(cls)
+
+        return {"class": attr}
+
+    def _get_annotation_data_attr(self, index, el):  # pylint: disable=unused-argument
+        """Returns a dict in which the keys are the HTML data attributes
+        to set on the annotation element. Each data attribute has a
+        corresponding 'value' and (optional) '_delete' key to specify
+        an XML attribute to delete.
+        """
+
+        data_attrs = {}
+        attrs_map = {
+            "body": "data-comment-body",
+            "title": "data-comment-title",
+            "problem": "data-problem-id",
+        }
+
+        for xml_key, html_key in attrs_map.items():
+            if xml_key in el.attrib:
+                value = el.get(xml_key, "")
+                data_attrs[html_key] = {"value": value, "_delete": xml_key}
+
+        return data_attrs
+
+    def _render_annotation(self, index, el):
+        """Renders an annotation element for HTML output."""
+        attr = {}
+        attr.update(self._get_annotation_class_attr(index, el))
+        attr.update(self._get_annotation_data_attr(index, el))
+
+        el.tag = "span"
+
+        for key, value in attr.items():
+            el.set(key, value["value"])
+            if "_delete" in value and value["_delete"] is not None:
+                delete_key = value["_delete"]
+                del el.attrib[delete_key]
+
+    def _render_content(self):
+        """Renders annotatable content with annotation spans and returns HTML."""
+
+        xmltree = etree.fromstring(self.data)
+        self._extract_instructions(xmltree)
+
+        xmltree.tag = "div"
+        if "display_name" in xmltree.attrib:
+            del xmltree.attrib["display_name"]
+
+        index = 0
+        for el in xmltree.findall(".//annotation"):
+            self._render_annotation(index, el)
+            index += 1
+
+        return etree.tostring(xmltree, encoding="unicode")
+
+    def _extract_instructions(self, xmltree):
+        """Removes <instructions> from the xmltree and returns them as a string, otherwise None."""
+        instructions = xmltree.find("instructions")
+        if instructions is not None:
+            instructions.tag = "div"
+            xmltree.remove(instructions)
+            return etree.tostring(instructions, encoding="unicode")
+        return None
+
+    def get_html(self):
+        """Returns the HTML representation of the XBlock for student view."""
+        return {
+            "element_id": uuid.uuid1(0),
+            "display_name": self.display_name,
+            "instructions_html": self._extract_instructions(etree.fromstring(self.data)),
+            "content_html": self._render_content(),
+        }
+
+    def student_view(self, context=None):  # pylint: disable=unused-argument
+        """Renders the output that a student will see."""
+        frag = Fragment()
+        frag.add_content(
+            resource_loader.render_django_template(
+                "templates/annotatable.html",
+                self.get_html(),
+                i18n_service=self.runtime.service(self, "i18n"),
+            )
+        )
+        frag.add_css(resource_loader.load_unicode("static/css/annotatable.css"))
+        frag.add_javascript(resource_loader.load_unicode("static/js/src/annotatable.js"))
+        frag.initialize_js("Annotatable")
+        return frag
+
+    def studio_view(self, context=None):  # pylint: disable=unused-argument
+        """Return the studio view."""
+        frag = Fragment()
+        frag.add_content(
+            resource_loader.render_django_template(
+                "templates/annotatable_editor.html",
+                {
+                    "data": self.data,
+                },
+                i18n_service=self.runtime.service(self, "i18n"),
+            )
+        )
+
+        frag.add_css(resource_loader.load_unicode("static/css/annotatable_editor.css"))
+        frag.add_javascript(resource_loader.load_unicode("static/js/src/annotatable_editor.js"))
+        frag.initialize_js("XMLEditingDescriptor")
+        return frag
+
+    @XBlock.json_handler
+    def submit_studio_edits(self, data, suffix=""):  # pylint: disable=unused-argument
+        """AJAX handler for saving the studio edits."""
+        display_name = data.get("display_name")
+        xml_data = data.get("data")
+
+        if display_name is not None:
+            self.display_name = display_name
+        if xml_data is not None:
+            self.data = xml_data
+
+        return {"result": "success"}
+
+    @staticmethod
+    def workbench_scenarios():
+        """Defines scenarios for displaying the XBlock in the XBlock workbench."""
+        return [
+            ("AnnotatableXBlock", "<_annotatable_extracted/>"),
+            (
+                "Multiple AnnotatableXBlock",
+                """
+                <vertical_demo>
+                    <_annotatable_extracted/>
+                    <_annotatable_extracted/>
+                    <_annotatable_extracted/>
+                </vertical_demo>
+            """,
+            ),
+        ]
+
+    @classmethod
+    def parse_xml_new_runtime(cls, node, runtime, keys):
+        """
+        Interpret the parsed XML in `node`, creating a new instance of this
+        module.
+        """
+        # In the new/openedx_content-based runtime, XModule parsing (from
+        # XmlMixin) is disabled, so definition_from_xml will not be
+        # called, and instead the "normal" XBlock parse_xml will be used.
+        # However, it's not compatible with RawMixin, so we implement
+        # support here.
+        data_field_value = cls.definition_from_xml(node, None)[0]["data"]
+        for child in node.getchildren():
+            node.remove(child)
+        # Get attributes, if any, via normal parse_xml.
+        try:
+            block = super().parse_xml_new_runtime(node, runtime, keys)
+        except AttributeError:
+            block = super().parse_xml(node, runtime, keys)
+        block.data = data_field_value
+        return block
+
+    @classmethod
+    def definition_from_xml(cls, xml_object, system):
+        if len(xml_object) == 0 and len(list(xml_object.items())) == 0:
+            return {"data": ""}, []
+        return {"data": etree.tostring(xml_object, pretty_print=True, encoding="unicode")}, []
+
+    def definition_to_xml(self, resource_fs):
+        """
+        Return an Element if we've kept the import OLX, or None otherwise.
+        """
+        # If there's no self.data, it means that an XBlock/XModule originally
+        # existed for this data at the time of import/editing, but was later
+        # uninstalled. RawDescriptor therefore never got to preserve the
+        # original OLX that came in, and we have no idea how it should be
+        # serialized for export. It's possible that we could do some smarter
+        # fallback here and attempt to extract the data, but it's reasonable
+        # and simpler to just skip this node altogether.
+        if not self.data:
+            log.warning(
+                "Could not serialize %s: No XBlock installed for '%s' tag.",
+                self.usage_key,
+                self.usage_key.block_type,
+            )
+            return None
+
+        # Normal case: Just echo back the original OLX we saved.
+        try:
+            return etree.fromstring(self.data)
+        except etree.XMLSyntaxError as err:
+            # Can't recover here, so just add some info and
+            # re-raise
+            lines = self.data.split("\n")
+            line, offset = err.position
+            context = lines[line - 1][offset - 40 : offset + 40]
+            msg = f"Unable to create xml for block {self.usage_key}. Context: '{context}'"
+            raise SerializationError(self.usage_key, msg) from err

xblock_annotatable/conf/locale/config.yaml

@@ -0,0 +1,93 @@
+# Configuration for i18n workflow.
+
+locales:
+    - en  # English - Source Language
+    # - am  # Amharic
+    - ar  # Arabic
+    # - az  # Azerbaijani
+    # - bg_BG  # Bulgarian (Bulgaria)
+    # - bn_BD  # Bengali (Bangladesh)
+    # - bn_IN  # Bengali (India)
+    # - bs  # Bosnian
+    # - ca  # Catalan
+    # - ca@valencia  # Catalan (Valencia)
+    # - cs  # Czech
+    # - cy  # Welsh
+    # - da  # Danish
+    # - de_DE  # German (Germany)
+    # - el  # Greek
+    # - en_GB  # English (United Kingdom)
+    # # Don't pull these until we figure out why pages randomly display in these locales,
+    # # when the user's browser is in English and the user is not logged in.
+    # #- en@lolcat  # LOLCAT English
+    # #- en@pirate  # Pirate English
+    - es_419  # Spanish (Latin America)
+    # - es_AR  # Spanish (Argentina)
+    # - es_EC  # Spanish (Ecuador)
+    # - es_ES  # Spanish (Spain)
+    # - es_MX  # Spanish (Mexico)
+    # - es_PE  # Spanish (Peru)
+    # - et_EE  # Estonian (Estonia)
+    # - eu_ES  # Basque (Spain)
+    # - fa  # Persian
+    # - fa_IR  # Persian (Iran)
+    # - fi_FI  # Finnish (Finland)
+    # - fil  # Filipino
+    - fr  # French
+    # - gl  # Galician
+    # - gu  # Gujarati
+    - he  # Hebrew
+    - hi  # Hindi
+    # - hr  # Croatian
+    # - hu  # Hungarian
+    # - hy_AM  # Armenian (Armenia)
+    # - id  # Indonesian
+    # - it_IT  # Italian (Italy)
+    # - ja_JP  # Japanese (Japan)
+    # - kk_KZ  # Kazakh (Kazakhstan)
+    # - km_KH  # Khmer (Cambodia)
+    # - kn  # Kannada
+    - ko_KR  # Korean (Korea)
+    # - lt_LT  # Lithuanian (Lithuania)
+    # - ml  # Malayalam
+    # - mn  # Mongolian
+    # - mr  # Marathi
+    # - ms  # Malay
+    # - nb  # Norwegian Bokmål
+    # - ne  # Nepali
+    # - nl_NL  # Dutch (Netherlands)
+    # - or  # Oriya
+    # - pl  # Polish
+    - pt_BR  # Portuguese (Brazil)
+    # - pt_PT  # Portuguese (Portugal)
+    # - ro  # Romanian
+    - ru  # Russian
+    # - si  # Sinhala
+    # - sk  # Slovak
+    # - sl  # Slovenian
+    # - sq  # Albanian
+    # - sr  # Serbian
+    # - sv  # Swedish
+    # - sw  # Swahili
+    # - ta  # Tamil
+    # - te  # Telugu
+    # - th  # Thai
+    # - tr_TR  # Turkish (Turkey)
+    # - uk  # Ukranian
+    # - ur  # Urdu
+    # - uz  # Uzbek
+    # - vi  # Vietnamese
+    - zh_CN  # Chinese (China)
+    # - zh_HK  # Chinese (Hong Kong)
+    # - zh_TW  # Chinese (Taiwan)
+
+
+# The locales used for fake-accented English, for testing.
+dummy_locales:
+    - eo
+    - rtl  # Fake testing language for Arabic
+
+# Directories we don't search for strings.
+ignore_dirs:
+    - '*/css'
+    - 'public/js/translations'

xblock_annotatable/static/css/annotatable.css

@@ -0,0 +1,188 @@
+@import url("https://fonts.googleapis.com/css?family=Open+Sans:300,400,400i,600,700");
+
+.annotatable-wrapper {
+  position: relative;
+}
+.annotatable-header {
+  margin-bottom: 0.5em;
+}
+.annotatable-section {
+  position: relative;
+  padding: 0.5em 1em;
+  border: 1px solid var(--gray-l3, #c8c8c8);
+  border-radius: 0.5em;
+  margin-bottom: 0.5em;
+}
+.annotatable-section.shaded {
+  background-color: #ededed;
+}
+.annotatable-section .annotatable-section-title {
+  font-weight: bold;
+}
+.annotatable-section .annotatable-section-title a {
+  font-weight: normal;
+}
+.annotatable-section .annotatable-section-body {
+  border-top: 1px solid var(--gray-l3, #c8c8c8);
+  margin-top: 0.5em;
+  padding-top: 0.5em;
+}
+.annotatable-section .annotatable-section-body:after {
+  content: "";
+  display: table;
+  clear: both;
+}
+.annotatable-section ul.instructions-template {
+  list-style: disc;
+  margin-left: 4em;
+}
+.annotatable-section ul.instructions-template b {
+  font-weight: bold;
+}
+.annotatable-section ul.instructions-template i {
+  font-style: italic;
+}
+.annotatable-section ul.instructions-template code {
+  display: inline;
+  white-space: pre;
+  font-family: Courier New, monospace;
+}
+.annotatable-toggle {
+  position: absolute;
+  right: 0;
+  margin: 2px 1em 2px 0;
+}
+.annotatable-toggle.expanded::after {
+  content: " \2191";
+}
+.annotatable-toggle.collapsed::after {
+  content: " \2193";
+}
+.annotatable-span {
+  display: inline;
+}
+.annotatable-span.highlight {
+  background-color: rgba(255, 255, 10, 0.3);
+}
+.annotatable-span.highlight.selected {
+  background-color: rgba(255, 255, 10, 0.9);
+}
+.annotatable-span.highlight-yellow {
+  background-color: rgba(255, 255, 10, 0.3);
+}
+.annotatable-span.highlight-yellow.selected {
+  background-color: rgba(255, 255, 10, 0.9);
+}
+.annotatable-span.highlight-red {
+  background-color: rgba(178, 19, 16, 0.3);
+}
+.annotatable-span.highlight-red.selected {
+  background-color: rgba(178, 19, 16, 0.9);
+}
+.annotatable-span.highlight-orange {
+  background-color: rgba(255, 165, 0, 0.3);
+}
+.annotatable-span.highlight-orange.selected {
+  background-color: rgba(255, 165, 0, 0.9);
+}
+.annotatable-span.highlight-green {
+  background-color: rgba(25, 255, 132, 0.3);
+}
+.annotatable-span.highlight-green.selected {
+  background-color: rgba(25, 255, 132, 0.9);
+}
+.annotatable-span.highlight-blue {
+  background-color: rgba(35, 163, 255, 0.3);
+}
+.annotatable-span.highlight-blue.selected {
+  background-color: rgba(35, 163, 255, 0.9);
+}
+.annotatable-span.highlight-purple {
+  background-color: rgba(115, 9, 178, 0.3);
+}
+.annotatable-span.highlight-purple.selected {
+  background-color: rgba(115, 9, 178, 0.9);
+}
+.annotatable-span.hide {
+  cursor: none;
+  background-color: inherit;
+}
+.annotatable-span.hide .annotatable-icon {
+  display: none;
+}
+.annotatable-span .annotatable-comment {
+  display: none;
+}
+.ui-tooltip.qtip.ui-tooltip {
+  font-size: 0.875em;
+  border: 1px solid #333;
+  border-radius: 1em;
+  background-color: rgba(0, 0, 0, 0.85);
+  color: var(--white, #fff);
+  -webkit-font-smoothing: antialiased;
+}
+.ui-tooltip.qtip.ui-tooltip .ui-tooltip-titlebar {
+  font-size: 1em;
+  color: inherit;
+  background-color: transparent;
+  padding: calc((var(--baseline, 20px) / 4)) calc((var(--baseline, 20px) / 2));
+  border: none;
+}
+.ui-tooltip.qtip.ui-tooltip .ui-tooltip-titlebar .ui-tooltip-title {
+  padding: calc((var(--baseline, 20px) / 4)) 0;
+  border-bottom: 2px solid #333;
+  font-weight: bold;
+}
+.ui-tooltip.qtip.ui-tooltip .ui-tooltip-titlebar .ui-tooltip-icon {
+  right: 10px;
+  background: #333;
+}
+.ui-tooltip.qtip.ui-tooltip .ui-tooltip-titlebar .ui-state-hover {
+  color: inherit;
+  border: 1px solid var(--gray-l3, #c8c8c8);
+}
+.ui-tooltip.qtip.ui-tooltip .ui-tooltip-content {
+  color: inherit;
+  font-size: 0.875em;
+  text-align: left;
+  font-weight: 400;
+  padding: 0 calc((var(--baseline, 20px) / 2)) calc((var(--baseline, 20px) / 2)) calc((var(--baseline, 20px) / 2));
+  background-color: transparent;
+  border-color: transparent;
+}
+.ui-tooltip.qtip.ui-tooltip p {
+  color: inherit;
+  line-height: normal;
+}
+.ui-tooltip.qtip.ui-tooltip-annotatable {
+  max-width: 375px;
+}
+.ui-tooltip.qtip.ui-tooltip-annotatable .ui-tooltip-content {
+  padding: 0 calc((var(--baseline, 20px) / 2));
+}
+.ui-tooltip.qtip.ui-tooltip-annotatable .ui-tooltip-content .annotatable-comment {
+  display: block;
+  margin: 0 0 calc((var(--baseline, 20px) / 2)) 0;
+  max-height: 225px;
+  overflow: auto;
+  line-height: normal;
+}
+.ui-tooltip.qtip.ui-tooltip-annotatable .ui-tooltip-content .annotatable-reply {
+  display: block;
+  border-top: 2px solid #333;
+  padding: calc((var(--baseline, 20px) / 4)) 0;
+  margin: 0;
+  text-align: center;
+}
+.ui-tooltip.qtip.ui-tooltip-annotatable::after {
+  content: '';
+  display: inline-block;
+  position: absolute;
+  bottom: -20px;
+  left: 50%;
+  height: 0;
+  width: 0;
+  margin-left: calc(-1 * (var(--baseline, 20px) / 4));
+  border: 10px solid transparent;
+  border-top-color: rgba(0, 0, 0, 0.85);
+}

xblock_annotatable/static/css/annotatable_editor.css

@@ -0,0 +1,12 @@
+.wrapper-comp-editor {
+    display: block;
+}
+.wrapper-comp-editor.is-inactive {
+    display: none;
+}
+.wrapper-comp-editor.latex-problem {
+    margin-top: 50px;
+}
+div.wrapper-comp-editor.is-inactive ~ div.launch-latex-compiler {
+    display: none;
+}