GitHub PullRequestEvent at 2014-07-24 16:11:32
Repository: TiddlyWiki5
Actor: Jermolene
Payload: {"action":"closed","number":680,"pull_request":{"url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680","id":18626183,"html_url":"https://github.com/Jermolene/TiddlyWiki5/pull/680","diff_url":"https://github.com/Jermolene/TiddlyWiki5/pull/680.diff","patch_url":"https://github.com/Jermolene/TiddlyWiki5/pull/680.patch","issue_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/680","number":680,"state":"closed","title":"\"TiddlyWiki Architecture\" needs to go into more depth","user":{"login":"ssokolow","id":46915,"avatar_url":"https://avatars.githubusercontent.com/u/46915?","gravatar_id":"14a5929fe3ec7a450338bde34dea21bd","url":"https://api.github.com/users/ssokolow","html_url":"https://github.com/ssokolow","followers_url":"https://api.github.com/users/ssokolow/followers","following_url":"https://api.github.com/users/ssokolow/following{/other_user}","gists_url":"https://api.github.com/users/ssokolow/gists{/gist_id}","starred_url":"https://api.github.com/users/ssokolow/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ssokolow/subscriptions","organizations_url":"https://api.github.com/users/ssokolow/orgs","repos_url":"https://api.github.com/users/ssokolow/repos","events_url":"https://api.github.com/users/ssokolow/events{/privacy}","received_events_url":"https://api.github.com/users/ssokolow/received_events","type":"User","site_admin":false},"body":"I spent a couple of days twisting my mind in knots because the \"Overview\" diagram in the TiddlyWiki Architecture tiddler didn't go into enough detail, the RefreshMechanism tiddler doesn't exist, and the tiddlers listed in the table of contents didn't have enough cross-references. (The light only came on as a result of a lot of code-diving and some tiddler search results.)\r\n\r\nAside from a few rough spots where I'm not yet certain of how things work, I've assembled an amendment for the [TiddlyWiki Architecture](http://tiddlywiki.com/#TiddlyWiki%20Architecture) tiddler which should really help.\r\n\r\nIf you're receptive, I'm willing to sign the CLA and then convert the non-TODO bits of this into a pull request for a WikiText version.\r\n\r\nThere are probably inaccuracies, but I did the best I could given the current state of TW5's docs and the lack of any kind of API documentation to provide an auto-generated project-wide function/method index.\r\n\r\n----\r\n\r\nWhen programming TiddlyWiki 5 plugins which make changes outside the scope of the included examples, you will need a more in-depth understanding of TiddlyWiki's internal architecture.\r\n\r\n## Model\r\n\r\nTiddlyWiki's data model is a fairly simple key-value store.\r\n\r\n* Each tiddler is simply an object with a `fields` member containing members such as `title`, `text`, `tags` and so on.\r\n* The core `Wiki` class defined in `boot/boot.js` implements simple associative array behaviours like insertion, deletion, iteration, listing keys, and get-by-key.\r\n* The code in `core/modules/wiki.js` then extends the `Wiki` class with functionality such as event dispatch and various cache-backed methods such as `getTiddlersWithTag`.\r\n\r\nThe active tiddler store can be accessed via `$tw.wiki` as in this example:\r\n\r\n```js\r\n$tw.wiki.makeTiddlerIterator($tw.wiki.getTiddlersWithTag('timeline')\r\n    )(function(tiddler, title) {\r\n        // Skip templates\r\n        if (tiddler.fields.tags.indexOf('templates') >= 0) { return; }\r\n\r\n        do_something(tiddler);\r\n});\r\n```\r\n\r\n**TODO:** Find a properly in-depth explanation of what [Naming of System Tiddlers](http://tiddlywiki.com/#Naming%20of%20System%20Tiddlers) is actually saying and extend this explanation. (eg. Is there any special behaviour assigned to slashes in tiddler names? What special behaviours are attached to which names? What's the difference between a `$:/state/*` tiddler and a `$:/temp/*` tiddler? etc.)\r\n\r\n**TODO:** Figure out where the [PermaLinks](http://tiddlywiki.com/#PermaLinks) mechanism is documented and whether it's extensible. (eg. Could an tiddler expand/collapse plugin add its state to the permalink?)\r\n\r\n## View\r\n\r\nTiddlyWiki's view layer has a *lot* in common with desktop widget toolkits and this is the part which is most likely to trip newcomers up. There are two facets to it:\r\n\r\n### Role of the DOM\r\nBecause TiddlyWiki may re-render content, plugins should treat the DOM as write-only.\r\n\r\nIn other words, any state you store in the DOM could vanish at any instant and you need to use TiddlyWiki's internal [StateMechanism](http://tiddlywiki.com/#StateMechanism) instead.\r\n\r\nIn a desktop application, the base widget class defines a method such as `paint(canvas)` which is called in response to `expose` events or \"data has changed\" messages; In TiddlyWiki, the `Widget` class in `core/modules/widgets/widgets.js` defines a `render(parent, nextSibling)` method which TiddlyWiki calls in response to various events such as changes in the model.\r\n\r\n(The potential inefficiency of this approach is mitigated via a `refresh(changedTiddlers)` method which TiddlyWiki calls to ask your widget whether its current rendering is stale.)\r\n\r\n**TODO:** Look up how actual TW5 code binds events.\r\n\r\n### Locus of Control\r\n\r\nWhile TiddlyWiki markup is similar in design to HTML templating languages with logic constructs, you can't just ignore it and assemble all your content in raw Javascript because it is used to define most of TiddlyWiki's UI.\r\n\r\nIn this respect, it's closer to a glue language like Qt Quick or Python with Javascript filling the \"create new components\" role of C/C++ in widget toolkits like Qt and GTK+.\r\n\r\n![tiddlywiki page composition](https://cloud.githubusercontent.com/assets/46915/3560524/30698ea6-0974-11e4-83ad-e3bcc946056a.png)\r\n\r\nTo familiarize yourself with this, read the [Widgets in WikiText](http://tiddlywiki.com/#Widgets%20in%20WikiText) and [Introduction to Filters](http://tiddlywiki.com/#Introduction%20to%20Filters) tiddlers and then examine the internals for a tiddler like [TaskManagementExample](http://tiddlywiki.com/#Introduction%20to%20Filters).\r\n\r\n## Controller\r\n\r\n**TODO:** Figure out what kind of hackery TiddlyWiki allows to be performed on the core itself.","created_at":"2014-07-20T02:52:21Z","updated_at":"2014-07-24T16:11:32Z","closed_at":"2014-07-24T16:11:32Z","merged_at":"2014-07-24T16:11:32Z","merge_commit_sha":"e60646bf2d989f387b6c3e4ed25c4d3328c1a252","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680/commits","review_comments_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680/comments","review_comment_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/comments/{number}","comments_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/680/comments","statuses_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/statuses/1a9f34203ce070e4e9deeb9e5be4fbaa6f27ccef","head":{"label":"ssokolow:issue-680","ref":"issue-680","sha":"1a9f34203ce070e4e9deeb9e5be4fbaa6f27ccef","user":{"login":"ssokolow","id":46915,"avatar_url":"https://avatars.githubusercontent.com/u/46915?","gravatar_id":"14a5929fe3ec7a450338bde34dea21bd","url":"https://api.github.com/users/ssokolow","html_url":"https://github.com/ssokolow","followers_url":"https://api.github.com/users/ssokolow/followers","following_url":"https://api.github.com/users/ssokolow/following{/other_user}","gists_url":"https://api.github.com/users/ssokolow/gists{/gist_id}","starred_url":"https://api.github.com/users/ssokolow/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ssokolow/subscriptions","organizations_url":"https://api.github.com/users/ssokolow/orgs","repos_url":"https://api.github.com/users/ssokolow/repos","events_url":"https://api.github.com/users/ssokolow/events{/privacy}","received_events_url":"https://api.github.com/users/ssokolow/received_events","type":"User","site_admin":false},"repo":{"id":21854696,"name":"TiddlyWiki5","full_name":"ssokolow/TiddlyWiki5","owner":{"login":"ssokolow","id":46915,"avatar_url":"https://avatars.githubusercontent.com/u/46915?","gravatar_id":"14a5929fe3ec7a450338bde34dea21bd","url":"https://api.github.com/users/ssokolow","html_url":"https://github.com/ssokolow","followers_url":"https://api.github.com/users/ssokolow/followers","following_url":"https://api.github.com/users/ssokolow/following{/other_user}","gists_url":"https://api.github.com/users/ssokolow/gists{/gist_id}","starred_url":"https://api.github.com/users/ssokolow/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ssokolow/subscriptions","organizations_url":"https://api.github.com/users/ssokolow/orgs","repos_url":"https://api.github.com/users/ssokolow/repos","events_url":"https://api.github.com/users/ssokolow/events{/privacy}","received_events_url":"https://api.github.com/users/ssokolow/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ssokolow/TiddlyWiki5","description":"A reboot of TiddlyWiki for the next 25 years","fork":true,"url":"https://api.github.com/repos/ssokolow/TiddlyWiki5","forks_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/forks","keys_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/teams","hooks_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/hooks","issue_events_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/issues/events{/number}","events_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/events","assignees_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/assignees{/user}","branches_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/branches{/branch}","tags_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/tags","blobs_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/git/refs{/sha}","trees_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/statuses/{sha}","languages_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/languages","stargazers_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/stargazers","contributors_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/contributors","subscribers_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/subscribers","subscription_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/subscription","commits_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/commits{/sha}","git_commits_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/git/commits{/sha}","comments_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/comments{/number}","issue_comment_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/issues/comments/{number}","contents_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/contents/{+path}","compare_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/merges","archive_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/downloads","issues_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/issues{/number}","pulls_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/pulls{/number}","milestones_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/milestones{/number}","notifications_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/labels{/name}","releases_url":"https://api.github.com/repos/ssokolow/TiddlyWiki5/releases{/id}","created_at":"2014-07-15T09:52:29Z","updated_at":"2014-07-15T09:56:49Z","pushed_at":"2014-07-20T02:49:42Z","git_url":"git://github.com/ssokolow/TiddlyWiki5.git","ssh_url":"git@github.com:ssokolow/TiddlyWiki5.git","clone_url":"https://github.com/ssokolow/TiddlyWiki5.git","svn_url":"https://github.com/ssokolow/TiddlyWiki5","homepage":"http://tiddlywiki.com/","size":14962,"stargazers_count":0,"watchers_count":0,"language":"JavaScript","has_issues":false,"has_downloads":true,"has_wiki":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"Jermolene:master","ref":"master","sha":"e3dc00573d9ea4db61e619b8f101168d1b4920a5","user":{"login":"Jermolene","id":174761,"avatar_url":"https://avatars.githubusercontent.com/u/174761?","gravatar_id":"f10cdf2027f7fd310dff8d5377111088","url":"https://api.github.com/users/Jermolene","html_url":"https://github.com/Jermolene","followers_url":"https://api.github.com/users/Jermolene/followers","following_url":"https://api.github.com/users/Jermolene/following{/other_user}","gists_url":"https://api.github.com/users/Jermolene/gists{/gist_id}","starred_url":"https://api.github.com/users/Jermolene/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Jermolene/subscriptions","organizations_url":"https://api.github.com/users/Jermolene/orgs","repos_url":"https://api.github.com/users/Jermolene/repos","events_url":"https://api.github.com/users/Jermolene/events{/privacy}","received_events_url":"https://api.github.com/users/Jermolene/received_events","type":"User","site_admin":false},"repo":{"id":2828239,"name":"TiddlyWiki5","full_name":"Jermolene/TiddlyWiki5","owner":{"login":"Jermolene","id":174761,"avatar_url":"https://avatars.githubusercontent.com/u/174761?","gravatar_id":"f10cdf2027f7fd310dff8d5377111088","url":"https://api.github.com/users/Jermolene","html_url":"https://github.com/Jermolene","followers_url":"https://api.github.com/users/Jermolene/followers","following_url":"https://api.github.com/users/Jermolene/following{/other_user}","gists_url":"https://api.github.com/users/Jermolene/gists{/gist_id}","starred_url":"https://api.github.com/users/Jermolene/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Jermolene/subscriptions","organizations_url":"https://api.github.com/users/Jermolene/orgs","repos_url":"https://api.github.com/users/Jermolene/repos","events_url":"https://api.github.com/users/Jermolene/events{/privacy}","received_events_url":"https://api.github.com/users/Jermolene/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/Jermolene/TiddlyWiki5","description":"A reboot of TiddlyWiki for the next 25 years","fork":false,"url":"https://api.github.com/repos/Jermolene/TiddlyWiki5","forks_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/forks","keys_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/teams","hooks_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/hooks","issue_events_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/events{/number}","events_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/events","assignees_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/assignees{/user}","branches_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/branches{/branch}","tags_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/tags","blobs_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/git/refs{/sha}","trees_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/statuses/{sha}","languages_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/languages","stargazers_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/stargazers","contributors_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/contributors","subscribers_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/subscribers","subscription_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/subscription","commits_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/commits{/sha}","git_commits_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/git/commits{/sha}","comments_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/comments{/number}","issue_comment_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/comments/{number}","contents_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/contents/{+path}","compare_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/merges","archive_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/downloads","issues_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues{/number}","pulls_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls{/number}","milestones_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/milestones{/number}","notifications_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/labels{/name}","releases_url":"https://api.github.com/repos/Jermolene/TiddlyWiki5/releases{/id}","created_at":"2011-11-22T14:26:07Z","updated_at":"2014-07-23T16:52:58Z","pushed_at":"2014-07-24T16:11:31Z","git_url":"git://github.com/Jermolene/TiddlyWiki5.git","ssh_url":"git@github.com:Jermolene/TiddlyWiki5.git","clone_url":"https://github.com/Jermolene/TiddlyWiki5.git","svn_url":"https://github.com/Jermolene/TiddlyWiki5","homepage":"http://tiddlywiki.com/","size":26163,"stargazers_count":735,"watchers_count":735,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"forks_count":178,"mirror_url":null,"open_issues_count":144,"forks":178,"open_issues":144,"watchers":735,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680"},"html":{"href":"https://github.com/Jermolene/TiddlyWiki5/pull/680"},"issue":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/680"},"comments":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/issues/680/comments"},"review_comments":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680/comments"},"review_comment":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/pulls/680/commits"},"statuses":{"href":"https://api.github.com/repos/Jermolene/TiddlyWiki5/statuses/1a9f34203ce070e4e9deeb9e5be4fbaa6f27ccef"}},"merged":true,"mergeable":null,"mergeable_state":"unknown","merged_by":{"login":"Jermolene","id":174761,"avatar_url":"https://avatars.githubusercontent.com/u/174761?","gravatar_id":"f10cdf2027f7fd310dff8d5377111088","url":"https://api.github.com/users/Jermolene","html_url":"https://github.com/Jermolene","followers_url":"https://api.github.com/users/Jermolene/followers","following_url":"https://api.github.com/users/Jermolene/following{/other_user}","gists_url":"https://api.github.com/users/Jermolene/gists{/gist_id}","starred_url":"https://api.github.com/users/Jermolene/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Jermolene/subscriptions","organizations_url":"https://api.github.com/users/Jermolene/orgs","repos_url":"https://api.github.com/users/Jermolene/repos","events_url":"https://api.github.com/users/Jermolene/events{/privacy}","received_events_url":"https://api.github.com/users/Jermolene/received_events","type":"User","site_admin":false},"comments":6,"review_comments":0,"commits":1,"additions":382,"deletions":0,"changed_files":3}}