{"id":20037858,"url":"https://github.com/openedx/xblock-sdk","last_synced_at":"2025-04-04T07:05:13.678Z","repository":{"id":14770230,"uuid":"17491768","full_name":"openedx/xblock-sdk","owner":"openedx","description":"Workbench and example xblocks","archived":false,"fork":false,"pushed_at":"2025-03-17T05:01:38.000Z","size":1744,"stargazers_count":70,"open_issues_count":12,"forks_count":102,"subscribers_count":123,"default_branch":"master","last_synced_at":"2025-03-21T18:03:15.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openedx.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-06T20:34:41.000Z","updated_at":"2025-03-17T05:01:40.000Z","dependencies_parsed_at":"2023-02-17T10:45:59.817Z","dependency_job_id":"8a5dbd13-7472-45bf-b843-223683117700","html_url":"https://github.com/openedx/xblock-sdk","commit_stats":{"total_commits":884,"total_committers":87,"mean_commits":"10.160919540229886","dds":0.7409502262443439,"last_synced_commit":"f24b8e1c7bad994dc796485323fa0f81554925a3"},"previous_names":["edx/xblock-sdk"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openedx%2Fxblock-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openedx%2Fxblock-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openedx%2Fxblock-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openedx%2Fxblock-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openedx","download_url":"https://codeload.github.com/openedx/xblock-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135141,"owners_count":20889420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T10:23:23.041Z","updated_at":"2025-04-04T07:05:13.652Z","avatar_url":"https://github.com/openedx.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"XBlock SDK\n#############################\n\n.. note::\n\n  This README was auto-generated. Maintainer: please review its contents and\n  update all relevant sections. Instructions to you are marked with\n  \"PLACEHOLDER\" or \"TODO\". Update or remove those sections, and remove this\n  note when you are done.\n\n|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|\n|license-badge| |status-badge|\n\nPurpose\n*******\n\nThis repository consists of three main components to assist in the creation of new XBlocks:\n\n* a template-based generator for new XBlocks (found in the ``prototype`` directory)\n\n* sample XBlocks that can be the basis for new XBlock work (found in the ``sample_xblocks`` directory)\n\n* Workbench runtime, a simple runtime for viewing and testing XBlocks in a browser (found in the ``workbench`` directory)\n\nGetting Started\n***************\n\nDeveloping\n==========\n\nThis code runs on Python 3.11 or newer.\n\nOne Time Setup\n--------------\n.. code-block::\n\n  # Clone the repository\n  git clone git@github.com:openedx/xblock-sdk.git\n  cd xblock-sdk\n\n  # Set up a virtualenv with the same name as the repo and activate it\n  # Here's how you might do that if you have virtualenvwrapper setup.\n  mkvirtualenv -p python3.11 xblock-sdk\n\n  # Install system requirements needed to run this on ubuntu.\n  # Note: Debian 10 needs libjpeg62-turbo-dev instead of libjpeg62-dev.\n  sudo apt-get install python-dev libxml2-dev libxslt-dev lib32z1-dev libjpeg62-dev\n\nEvery time you develop something in this repo\n---------------------------------------------\n\nLocally\n~~~~~~~\n\n#.  Install the requirements and register the XBlock entry points::\n\n    $ make install\n\n#.  Run the Django development server::\n\n    $ python manage.py runserver\n\n#.  Open a web browser to: http://127.0.0.1:8000\n\nTesting\n~~~~~~~\n\nTesting is done via tox to test all supported versions:\n\n#.  Create and activate a virtualenv to work in.\n\n#.  Run just unit tests via tox::\n\n    $ tox\n\nFor each supported version of Django (currently 1.8 and 1.11) this will run:\n\n* Integration tests of XBlocks running within the workbench.\n* Individual tests written for the demo XBlocks\n\nTo run the unit tests in your virtualenv you can use::\n\n    $ make test\n\n\nTo run all tox unit tests and quality checks::\n\n    $ make test-all\n\n\nTo run just the quality checks::\n\n    $ make quality\n\nYou can test XBlocks through a browser using `Selenium`_. We have included an\nexample Selenium test for ``thumbs`` that uses Django's `LiveServerTestCase`_.\nIt runs as part of the test suite as executed by the above command.\n\n.. _Selenium: http://docs.seleniumhq.org/\n.. _LiveServerTestCase: https://docs.djangoproject.com/en/1.11/topics/testing/tools/#django.test.LiveServerTestCase\n\nTo update and view test coverage::\n\n    $ make coverage\n\nSee the `coverage.py`_ docs for more info and options.\n\n.. _coverage.py: http://coverage.readthedocs.org/\n\n\nDeploying\n=========\n\nThis repository is deployed to PyPI.  To deploy a new version.\n\n#. Bump the version of the package in ``workbench/__init__.py``\n\n#. Make a new release in github or push a new tag up to Github.\n\nThe pypi-publish github action should trigger.  It will build and deploy the source and wheel package to PyPI.\n\nGetting Help\n************\n\nDocumentation\n=============\n\nStart by going through `the documentation`_.  If you need more help see below.\n\n.. _the documentation: https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/sdk/get_started_sdk.html\n\nMore Help\n=========\n\nIf you're having trouble, we have discussion forums at\nhttps://discuss.openedx.org where you can connect with others in the\ncommunity.\n\nOur real-time conversations are on Slack. You can request a `Slack\ninvitation`_, then join our `community Slack workspace`_.\n\nFor anything non-trivial, the best path is to open an issue in this\nrepository with as many details about the issue you are facing as you\ncan provide.\n\nhttps://github.com/openedx/xblock-sdk/issues\n\nFor more information about these options, see the `Getting Help`_ page.\n\n.. _Slack invitation: https://openedx.org/slack\n.. _community Slack workspace: https://openedx.slack.com/\n.. _Getting Help: https://openedx.org/getting-help\n\nLicense\n*******\n\nThe code in this repository is licensed under the APACHE 2.0 license unless\notherwise noted.\n\nPlease see `LICENSE.txt \u003cLICENSE.txt\u003e`_ for details.\n\nContributing\n************\n\nContributions are very welcome.\nPlease read `How To Contribute \u003chttps://openedx.org/r/how-to-contribute\u003e`_ for details.\n\nThis project is currently accepting all types of contributions, bug fixes,\nsecurity fixes, maintenance work, or new features.  However, please make sure\nto have a discussion about your new feature idea with the maintainers prior to\nbeginning development to maximize the chances of your change being accepted.\nYou can start a conversation by creating a new issue on this repo summarizing\nyour idea.\n\nThe Open edX Code of Conduct\n****************************\n\nAll community members are expected to follow the `Open edX Code of Conduct`_.\n\n.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/\n\nPeople\n******\n\nThe assigned maintainers for this component and other project details may be\nfound in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml``\nfile in this repo.\n\n.. _Backstage: https://backstage.openedx.org/catalog/default/component/xblock-sdk\n\nReporting Security Issues\n*************************\n\nPlease do not report security issues in public. Please email security@openedx.org.\n\n.. |pypi-badge| image:: https://img.shields.io/pypi/v/xblock-sdk.svg\n    :target: https://pypi.python.org/pypi/xblock-sdk/\n    :alt: PyPI\n\n.. |ci-badge| image:: https://github.com/openedx/xblock-sdk/workflows/Python%20CI/badge.svg?branch=main\n    :target: https://github.com/openedx/xblock-sdk/actions\n    :alt: CI\n\n.. |codecov-badge| image:: https://codecov.io/github/openedx/xblock-sdk/coverage.svg?branch=main\n    :target: https://codecov.io/github/openedx/xblock-sdk?branch=main\n    :alt: Codecov\n\n.. |doc-badge| image:: https://readthedocs.org/projects/xblock-sdk/badge/?version=latest\n    :target: https://docs.openedx.org/projects/xblock-sdk\n    :alt: Documentation\n\n.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/xblock-sdk.svg\n    :target: https://pypi.python.org/pypi/xblock-sdk/\n    :alt: Supported Python versions\n\n.. |license-badge| image:: https://img.shields.io/github/license/openedx/xblock-sdk.svg\n    :target: https://github.com/openedx/xblock-sdk/blob/main/LICENSE.txt\n    :alt: License\n\n.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen\n\n\n\nOther Documentation\n*******************\n\nUsing the workbench\n===================\n\nWhen you open the workbench, you'll see a list of sample XBlock configurations\n(scenarios).  Each will display a page showing the XBlocks composited together,\nalong with internal information like the \"database\" contents.\n\nThe workbench database defaults to a sqlite3 database. If you're using devstack,\nyou may want to set ``WORKBENCH_DATABASES`` to point to your MySQL db.\n\nIf you want to experiment with different students, you can use a URL parameter\nto set the student ID, which defaults to 1::\n\n    http://127.0.0.1:8000/?student=17\n\nDifferent students will see different student state, for example, while seeing\nthe same content.  The default student ID contains only digits but it is not\nnecessary to limit student IDs to digits. Student IDs are represented as\nstrings.\n\n\nMaking your own XBlock\n======================\n\nMaking an XBlock involves creating a Python class that conforms to the XBlock\nspecification. See the ``sample_xblocks`` directory for examples and\n`the XBlock tutorial`_ for a full walk-through.\n\n.. _the XBlock tutorial: https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/index.html\n\nWe provide a script to create a new XBlock project to help you get started.\nRun ``bin/workbench-make-xblock`` in a directory where you want to create your XBlock\nproject.  The script will prompt you for the name of the XBlock, and will\ncreate a minimal working XBlock, ready for you to begin development.\n\nYou can provide scenarios for the workbench to display: see the ``thumbs.py``\nsample for an example, or the ``xblock/problem.py`` file.  The scenarios are\nwritten in a simple XML language.  Note this is not an XML format we are\nproposing as a standard.\n\nOnce you install your XBlock into your virtualenv, the workbench will\nautomatically display its scenarios for you to experiment with.\n\nIf you are interested in making an XBlock to run for your course on edx.org,\nplease get in touch with us as soon as possible -- in the ideation and design\nphase is ideal. See our `XBlock review guidelines`_\nfor more information (note that this is not needed for XBlocks running on your\nown instance of Open edX, or released to the wider community).\n\n.. _XBlock review guidelines: https://openedx.atlassian.net/wiki/display/OPEN/XBlock+review+guidelines\n\n\nExample XBlocks\n===============\n\nIncluded in this repository are some example XBlocks that demonstrate how to use\nvarious aspects of the XBlock SDK. You can see a more detailed description of\nthose examples in `the README`_ located in that repository:\n\nThere is a rich community of XBlock developers that have put together a large\nnumber of XBlocks that have been used in various contexts, mostly on the edx-platform.\nYou can see examples of what that community has done in the `edx-platform wiki`_.\n\n.. _the README: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/README.rst\n.. _edx-platform wiki: https://openedx.atlassian.net/wiki/spaces/COMM/pages/43385346/XBlocks+Directory\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenedx%2Fxblock-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenedx%2Fxblock-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenedx%2Fxblock-sdk/lists"}