{"id":14955712,"url":"https://github.com/sul-dlss/sul-embed","last_synced_at":"2026-01-16T02:34:10.068Z","repository":{"id":21548511,"uuid":"24868135","full_name":"sul-dlss/sul-embed","owner":"sul-dlss","description":"An oEmbed Service for Stanford University Libraries","archived":false,"fork":false,"pushed_at":"2024-10-28T14:56:59.000Z","size":13226,"stargazers_count":19,"open_issues_count":83,"forks_count":6,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-10-29T14:15:29.694Z","etag":null,"topics":["access","application","rails-application"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sul-dlss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-10-06T22:54:10.000Z","updated_at":"2024-10-28T14:52:29.000Z","dependencies_parsed_at":"2024-04-15T13:29:23.719Z","dependency_job_id":"3f30a94e-504d-456e-80c8-75c43d65ff3b","html_url":"https://github.com/sul-dlss/sul-embed","commit_stats":{"total_commits":2155,"total_committers":34,"mean_commits":63.38235294117647,"dds":0.7638051044083527,"last_synced_commit":"5067eeb00a90d3f3fa42f7a79049e86a5c9e22b9"},"previous_names":[],"tags_count":149,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sul-dlss%2Fsul-embed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sul-dlss%2Fsul-embed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sul-dlss%2Fsul-embed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sul-dlss%2Fsul-embed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sul-dlss","download_url":"https://codeload.github.com/sul-dlss/sul-embed/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234808947,"owners_count":18890088,"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":["access","application","rails-application"],"created_at":"2024-09-24T13:11:36.350Z","updated_at":"2026-01-16T02:34:10.061Z","avatar_url":"https://github.com/sul-dlss.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/sul-dlss/sul-embed/actions/workflows/ruby.yml/badge.svg)](https://github.com/sul-dlss/sul-embed/actions/workflows/ruby.yml)\n\n# SUL-Embed\n\nAn [oEmbed](http://oembed.com/) provider for embedding resources from the Stanford University Library.\n\n## Development/Test Sandbox\n\nThere is an embedded static page available at `/pages/sandbox` in your development and test environments. Make sure that you use the same host on the service input (first text field) as you are accessing the site from (e.g. localhost or 127.0.0.1).\n\nTo bring up a dev environment first you'll need to install Ruby and JavaScript dependencies. Note: NodeJS v18 and [yarn](https://yarnpkg.com/) must be installed:\n\n    bundle install\n    yarn install\n\nThen start up the Rails app (web server, debugger, CSS bundler, JS bundler) in one terminal window:\n\n    bin/dev\n\nTo debug, add one or more `debugger` statements to Ruby source code and then attach the debug client:\n\n    bin/rdbg -A\n\nNow visit this URL in your browser!\n\n    http://localhost:3000/pages/sandbox\n\n**NOTE**: If you're doing development on the media player, the above link may get you little more than CORS errors, in which case you likely want to develop against ViewComponent previews:\n\n    http://localhost:3000/rails/view_components/\n\nWhen developing viewers it can sometimes be helpful to load items using files served from the local development server instead of deployed PURL and Stacks servers. To do this you will want to create a `config/settings.local.yml` file with the following contents:\n\n```yaml\npurl_url: 'http://localhost:3000/'\nstacks_url: 'http://localhost:3000/'\n```\n\nThen you will need to place the \"public XML\" metadata for an object in the `public` directory `public/{druid}.xml` and the items stacks files in a directory `public/file/{druid}`. For example, for a druid `bk914zc7842` you would have a `public` directory structure that looks something like:\n\n```\npublic\n├── bk914zc7842.xml\n└── file\n    └── bk914zc7842\n        ├── bk914zc7842_low.glb\n        ├── bk914zc7842_low.mtl\n        ├── bk914zc7842_low.obj\n        └── bk914zc7842_normal_low.jpg\n```\n\n# Notes for developers\n\n## oEmbed specification details\n\nURL scheme: `https://purl.stanford.edu/*`\n\nAPI endpoint: `https://embed.stanford.edu`\n\nExample: `https://embed.stanford.edu/embed.json?url=http://purl.stanford.edu/zw200wd8767`\n\n\n## Linking in viewers\n\nThe rich HTML payload that is supplied via the oEmbed API is an iframe. This means that all consumers will be embedding an iframe into their page. Given this fact, generating links will require explicit targets if they are not intended to internally replace embed content.  Given this, there are two patterns that can be used.  For links intended to download files, a `target=\"_blank\"` can be used (effectively opening a new tab for the download which is immediately closed).  When using `target=\"_blank\"` add `rel=\"noopener noreferrer\"` **particularly** when linking externally (although this should be reserved for linking to internal resources when possible). See [this blog post](https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/) for an explanation. *Note: This does not apply to WebAuth links.*\n\nFor links that are intended to navigate the users browser away from the current page (e.g. the links to Memento/GeoBlacklight/etc.) then `target=\"_parent\"` should be used to give the link the default browser behavior. [More about link targets](http://www.w3schools.com/tags/att_a_target.asp).\n\n\n## Developing the media player locally\n\nFirst, identify an object in production that looks like it will work for your development purposes (e.g., a public video with captions, a Stanford-only audio with a transcript, etc.), and set up a ViewComponent preview for it unless it's already got one. Then we'll pull its files locally, so we don't need to hit a media server or a deployed instance:\n\n```\nbin/rake stackify[gt507vy5436]\n```\n\nThen, make sure you have an updated `stacks` checkout in a sibling directory to your `sul-embed` checkout. To run a local instance of stacks (from the sibling directory) via docker:\n\n```shell\nDOCKER_STACKS=true SETTINGS__STACKS_URL=\"http://localhost:3001\" bin/dev\n```\n\nFinally, use the ViewComponent preview you identified earlier to do your development.\n\nNOTE: We can dispense with the sibling directory jazz if we decide to publish the Stacks docker image.\n\n## Developing the media player locally without running Stacks\n**This will only work for world downloadable items**\n1. Add the lines below\n```\n// you need the setTimeout or it only work about 1/2 the time.\nsetTimeout(function(){\n    window.dispatchEvent(new CustomEvent('auth-success'))\n}, 1000)\n```\n before \nhttps://github.com/sul-dlss/sul-embed/blob/99ac3d3e471f30518e4e28bdd13afc31e7ffa4d1/app/javascript/controllers/media_tag_controller.js#L15 \n\n### When working on transcription sidebar\n1. Add return await this.cuesPromise() here https://github.com/sul-dlss/sul-embed/blob/99ac3d3e471f30518e4e28bdd13afc31e7ffa4d1/app/javascript/controllers/transcript_controller.js#L45\n**Note**: Sometimes the media doesn’t quite load right. You might have to refresh the page a couple times to get this to work.\n\n\n\n## Updating language tags\n\nsul-embed uses the IANA language subtag registry to resolve user-provided file language codes (e.g., 'en-US') onto user-friendly labels (e.g., \"English\"), primarily for captions in the media player. This file lives on the web and changes every so often. We cache this file in `vendor/data/language-subtag-registry`, and it can be updated via `rake update_language_tags`.\n\n## Testing javascript\n\nWe have `vitest` installed for javascript testing. These tests can be viewed in `spec/javascript`. The setup file is `spec/javascript/setupVitest.js`. These tests could be expanded but for now minimally test our customizations/plugins. These tests do not currently run in CI but can be run locally with `npx vitest`. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsul-dlss%2Fsul-embed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsul-dlss%2Fsul-embed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsul-dlss%2Fsul-embed/lists"}