{"id":13772844,"url":"https://github.com/TelescopeSt/TelescopeCytoscape","last_synced_at":"2025-05-11T05:33:45.848Z","repository":{"id":41756304,"uuid":"131391759","full_name":"TelescopeSt/TelescopeCytoscape","owner":"TelescopeSt","description":"TelescopeCytoscape is a connector to render Telescope visualization on web via Seaside","archived":false,"fork":false,"pushed_at":"2022-07-07T13:09:28.000Z","size":10065,"stargazers_count":8,"open_issues_count":18,"forks_count":1,"subscribers_count":2,"default_branch":"development","last_synced_at":"2025-04-11T18:38:34.319Z","etag":null,"topics":["connector","pharo","seaside","smalltalk","telescope","visualisation","visualization","webapplication"],"latest_commit_sha":null,"homepage":"https://demos.ferlicot.fr/TelescopeDemo","language":"Smalltalk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TelescopeSt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-28T08:49:04.000Z","updated_at":"2022-01-07T10:27:34.000Z","dependencies_parsed_at":"2022-07-12T23:30:34.477Z","dependency_job_id":null,"html_url":"https://github.com/TelescopeSt/TelescopeCytoscape","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelescopeSt%2FTelescopeCytoscape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelescopeSt%2FTelescopeCytoscape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelescopeSt%2FTelescopeCytoscape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelescopeSt%2FTelescopeCytoscape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TelescopeSt","download_url":"https://codeload.github.com/TelescopeSt/TelescopeCytoscape/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253523689,"owners_count":21921815,"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":["connector","pharo","seaside","smalltalk","telescope","visualisation","visualization","webapplication"],"created_at":"2024-08-03T17:01:08.429Z","updated_at":"2025-05-11T05:33:45.376Z","avatar_url":"https://github.com/TelescopeSt.png","language":"Smalltalk","funding_links":[],"categories":["Web"],"sub_categories":[],"readme":"# TelescopeCytoscape\n\nTelescopeCytoscape is a connector to render [Telescope](https://github.com/TelescopeSt/Telescope) visualization on web via [Seaside](https://github.com/SeasideSt/Seaside).\n\nIt uses [CytoscapeJs](http://js.cytoscape.org/) library and websockets to render and update the visualization.\n\n\u003cimg src=\"https://raw.githubusercontent.com/TelescopeSt/TelescopeCytoscape/development/resources/cytoscape.gif\"\u003e\n\n# Documentation\n\n## Version management \n\nThis project use semantic versionning to define the releases. This mean that each stable release of the project will get associate a version number of the form `vX.Y.Z`. \n\n- **X** define the major version number\n- **Y** define the minor version number \n- **Z** define the patch version number\n\nWhen a release contains only bug fixes, the patch number increase. When the release contains new features backward compatibles, the minor version increase. When the release contains breaking changes, the major version increase. \n\nThus, it should be safe to depend on a fixed major version and moving minor version of this project.\n\n## Install TelescopeCytoscape\n\nTo install TelescopeCytoscape on your Pharo image you can just execute the following script:\n\n```Smalltalk\n    Metacello new\n    \tgithubUser: 'TelescopeSt' project: 'TelescopeCytoscape' commitish: 'v2.x.x' path: 'src';\n    \tbaseline: 'TelescopeCytoscape';\n    \tonWarningLog;\n\tonUpgrade: [ :e | e useIncoming ];\n    \tload\n```\n\nTo add TelescopeCytoscape to your baseline just add this:\n\n```Smalltalk\n    spec\n    \tbaseline: 'TelescopeCytoscape'\n    \twith: [ spec repository: 'github://TelescopeSt/TelescopeCytoscape:v2.x.x/src' ]\n```\n\nNote that you can replace the v1.x.x tag by a branch as #master or #development or a tag as #v1.0.0, #v1.? or #v1.0.x or a commit SHA.\n\n## Getting started\n\n### Open a simple visualization\n\nIf you wish to use TelescopeCytoscape only to create a see a visualization, you can create you visualization and send `open` or `openOnWeb` to it. \n\n```Smalltalk\n\t| visualization |\n\tvisualization := TLVisualization fromEntities: (0 to: 359).\n\tvisualization layout: ((TLLinearLayout maximumDimension: 300) angle: 360 atRandom).\n\tvisualization styleSheet backgroundColor: ((MDLColor red property: #yourself gradientAt: 0) to: MDLColor yellow at: 360).\n\tvisualization addInteraction: (TLCustomAction block: [ :node | visualization layout angle: node entity. visualization requireLayoutApplication ]) onClick.\n\tvisualization addInteraction: (TLPopUpAction text: [ :e | 'Turn to an angle of ', e asString , '°' ]) onMouseOver.\n\tvisualization open\n```\n\nThis will use the first `ZincServerAdaptor` it found (if none it will open one on the port 8085) and open the visualization in an already defined Seaside application.\n\n\u003e Note: If your visualization does not work, verify that the port 8085 and 1701 are free. You can find bellow documentation to know how to change the port 1701 for the websocket. For the seaside adapter, open `World menu \u003e Tools \u003e Seaside Control Panel` and add and start an appropropriate `ZnZincServerAdaptor`\n\n### Use TelescopeCytoscape in your Seaside application\n\nThe first thing to do in order to use TelescopeCytoscape with your Seaside application is to add its `FileLibrary` to it.\n\n```Smalltalk\n\t(WAAdmin register: self asApplicationAt: 'myApplication')\n\t\taddLibrary: JQDeploymentLibrary;\n\t\taddLibrary: CYSFileLibrary\n```\n\n### Optional: Set the ports for the websocket \n\nIt is possible to change the port the Cytoscape client and Telescope server will use.\n\nThe server port will be 1701 by default. It is possible to specify another port with this command:\n\n```Smalltalk\nTLCytoscapeWebSocketDelegate serverPort: 1701.\n```\n\nThe client will by default use same port as the server. But it is possible to specify another port with this command:\n\n```Smalltalk\nTLCytoscapeWebSocketDelegate clientPort: 1701.\n```\n\nChanging the client port should be needed only in the case where you deploy an application over TLS and need to manage the encrypted communication via a reverse proxy such as nginx.\n\n### Render a visualization in Seaside \n\nOnce your Seaside application is setup you just need to use TLCytoscapeComponent to render a visualization.\n\n**Example:**\n\n```Smalltalk\nrenderContentOn: html\n\t| visu |\n\t(visu := TLVisualization fromEntities: (1 to: 40)) nodeLabel: #asString.\n\t(visu styleSheet \u003e #connectDemo) color: Color orange; width: 2.\n\tvisu addInteraction: ((TLConnectAction property: [ :n | (1 to: 40) copyWithout: n ] context: visu allNodes) connectToOrigin: #even; connectionStyle: #connectDemo; yourself) onMouseOver.\n\thtml render: (TLCytoscapeComponent visualization: visu)\n```\n\n## Deploy an application using TelescopeCytoscape\n\nDeploying a Seaside application with TelescopeCytoscape can be a little tricky because it uses WebSockets.\n\nIn order to help you with that we will give an example of nginx configuration.\n\n### Deploy without certificate\n\nDeploying without certificate is pretty easy since the websocket used will not be secured (`ws://`).\n\nHere is an example of a nginx configuration:\n\n```yalm\nserver {\n  listen 80; #Since it's a web application, listen port 80\n  listen [::]:80; #Same for IPv6\n  server_name {Domaine name. Example mysite.com}; #Set your domaine name\n  server_tokens off;  #Do not display nginx version for security reasons\n\n  access_log /var/log/nginx/{log name}.log; #loging\n  error_log /var/log/nginx/{error log name}.log; #error loging\n\n  root {Path to the root. For example /srv/myApp/};\n\n  location = / {\n    try_files $uri $uri/index.html @proxy;\n  }\n\n  #use a proxy for your seaside application\n  location @proxy {\n    rewrite ^ /{Seaside application name. For example TelescopeDemo}$1 last;\n  }\n\n  location /{Seaside application name. For example TelescopeDemo} {\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};\n  }\n\n  # This is for the file libraries\n  location /files {\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};\n  }\n\n}\n```\n\n### Deploy with certificate\n\nWhen you deploy with a TLS certificate, you need to use a secure websocket (`wss://`) and the communication needs to be managed with you TLS certificate.\n\nThe easiest way to do that is to use a reverse proxy for the `WSS:// -\u003e WS://` as we do for `HTTPS:// -\u003e HTTP://`.\n\nFirst we need to define a different port between the client and server side of the websocket. We can execute something like this in the Seaside application:\n\n```Smalltalk\nTLCytoscapeWebSocketDelegate \n\tclientPort: 28341;\n\tserverPort: 28340\n```\n\nThen we need to configure nginx:\n\n\n```yalm \nserver {\n  listen 80; #Since it's a web application, listen port 80\n  listen [::]:80; #Same for IPv6\n  server_name {Domaine name. Example mysite.com}; #Set your domaine name\n  server_tokens off;  #Do not display nginx version for security reasons\n  return 301 https://$server_name$request_uri; #Redirect HTTP -\u003e HTTPS\n}\n\nserver {\n  listen 443 ssl http2; #Listen to port 443 for HTTPS\n  listen [::]:443 ssl http2; #Same for IPv6\n  server_name {Domaine name. Example mysite.com}; #Set your domaine name\n  server_tokens off;  #Do not display nginx version for security reasons\n  ssl_certificate {path to your public certificate key}.pem;\n  ssl_certificate_key {path to your private certificate key}.pem;\n\n  access_log /var/log/nginx/{log name}.log; #loging\n  error_log /var/log/nginx/{error log name}.log; #error loging\n\n  root {Path to the root. For example /srv/myApp/};\n\n  location = / {\n    try_files $uri $uri/index.html @proxy;\n  }\n\n  #use a proxy for your seaside application\n  location @proxy {\n    rewrite ^ /{Seaside application name. For example TelescopeDemo}$1 last;\n  }\n\n  location /{Seaside application name. For example TelescopeDemo} {\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};\n  }\n\n  # This is for the file libraries\n  location /files {\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_pass http://127.0.0.1:{Port on which your ZincServerAdaptor listen. For example 8080};\n  }\n\n}\n\nserver {\n  listen 28341 ssl; #Listen on the client websocket port\n  listen [::]:28341 ssl;\n  server_name {domaine name};\n  server_tokens off;\n  ssl_certificate {path to your public certificate key}.pem;\n  ssl_certificate_key {path to your private certificate key}.pem;\n\n  location / {\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection \"Upgrade\";\n    proxy_pass http://127.0.0.1:28340; #Redirect to the server port. This will manage the TLS.\n  }\n}\n```\n\n## Examples\n\nYou can find multiple examples when the application will be installed at the url: [http://localhost:8080/TelescopeDemo](http://localhost:8080/TelescopeDemo)\n\nWhen you install in a plain Pharo image you need to start the seaside server first by opening `World menu \u003e Tools \u003e Seaside Control Panel` and adding and starting an appropropriate `ZnZincServerAdaptor`. If you do not use port 8080, change the port in the URL.\n\nYou can find a demo at: [https://demos.ferlicot.fr/TelescopeDemo](https://demos.ferlicot.fr/TelescopeDemo)\n\n\n## Latest supported Dependencies\n\n- [CytoscapeJS v3.14.0](https://github.com/cytoscape/cytoscape.js/releases/tag/v3.14.0)\n- [Cytoscape QTip v2.8.0](https://github.com/cytoscape/cytoscape.js-qtip/releases/tag/2.8.0)\n\n\n## Smalltalk versions compatibility\n\n| TelescopeCytoscape version \t| Compatible Pharo versions \t|\n|---------------------------\t|---------------------------\t|\n| v1.x.x                | Pharo 61, 70                  |\n| v2.x.x                | Pharo 61, 70, 80, 90, 10                  |\n| development           | Pharo 61, 70, 80, 90, 10               \t|\n\n## Contact\n\nIf you have any question or problem do not hesitate to open an issue or contact cyril (a) ferlicot.me or guillaume.larcheveque (a) gmail.com\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTelescopeSt%2FTelescopeCytoscape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTelescopeSt%2FTelescopeCytoscape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTelescopeSt%2FTelescopeCytoscape/lists"}