Welcome, Guest. Please Login
Tinderbox
  News:
IMPORTANT MESSAGE! This forum has now been replaced by a new forum at http://forum.eastgate.com and no further posting or member registration is allowed. The forum is still accessible via read-only access for reference purposes. If you wish to discuss content here, please use the new forum. N.B. - posting in the new forum requires a fresh registration in the new forum (sorry - member data can't be ported).
  HomeHelpSearchLogin  
 
Pages: 1
Send Topic Print
Exporting to Checkvist (Read 12819 times)
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Exporting to Checkvist
Jun 4th, 2012, 1:57am
 
I've just sent Mark B. a template tbx that exports notes to Checkvist (checkvist.com).

For those of you who don't know Checkvist, I found it to be one of the most workable outliner web apps. Worth checking out. And I think Tinderbox and Checkvist go very well together. So I came up with this template.

Hope you find a good use for it.

for testers, grab a copy https://docs.google.com/open?id=0B_lao0UwomH4YkpUUVg4QWFlV2c (temporary)

Back to top
 
« Last Edit: Jun 04th, 2012, 2:05am by Marcelo Mirage »  
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #1 - Jun 4th, 2012, 5:45am
 
Thanks for sharing. For others, the download fails in Safari but works OK in Chrome (looks like some glitch in the Google docs end).

It looks like Checkvist uses an OPML-based exchange format. Even if one doesn't use Checkvist, the Marcelo's TBX is a nice demo example with instructions etc.  I liked the 'Agency' container (...for storing agents!).
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Paul Walters
Full Member
*
Offline



Posts: 267

Re: Exporting to Checkvist
Reply #2 - Jun 4th, 2012, 5:54am
 
I agree with Mark Anderson that Marcelo's demonstration TBX is excellent.  One of the best I've seen here - and that's a high bar.  Smiley  Thanks, Marcelo, for posting this.
Back to top
 
 
  IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #3 - Jun 4th, 2012, 9:41am
 
I'm truly glad you guys liked it (especially after my last template fiasco, an attempt at getting rid of framesets in my Outline&Text...hehehe... I promise I'll be working on an improved version) Wink
Back to top
 
« Last Edit: Jun 4th, 2012, 3:46pm by Marcelo Mirage »  
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #4 - Jun 4th, 2012, 11:27am
 
OK, on to version 1.1, with a few improvements:
https://docs.google.com/open?id=0B_lao0UwomH4M3ZDczNvMnhiazA

ps. @Mark, Safari is not entirely broken, if you ignore the errors, and download via "file" menu, it works.
Back to top
 
 
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #5 - Jun 4th, 2012, 11:48am
 
Ah, I see. Thanks.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #6 - Jun 6th, 2012, 9:32pm
 
The TBX Checkvist Exporter v1.2 is ready:

https://docs.google.com/open?id=0B_lao0UwomH4WlNXMktPNzFleUE

Ok. This is version 1.2. Now checked items should work like in Checkvist (by checking the parent, all descendants are checked). The export code is working, so everything should be exported as expected. Any bugs, let me know.

Enjoy!
Back to top
 
 
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #7 - Jun 7th, 2012, 4:16am
 
Thanks again. Some observations from looking at the v1.2 TBX...

'Toggle status' agent. I believe this is meant to replicate the "0. Toggle Checked" stamp action. It doesn't but instead merely sets $NameStrike (which the stamp doesn't). IOW, the stamp and agent actions do different facets of the same task. I think your intent was that both methods do the same thing.

Typo? The *entry prototype's $Rule includes the code "$text=$Name".  As no user attribute $text is defined, this might be a typo for system attribute $Text.

Agent efficiency. The Agency container has 4 agents all with the same query scope:
  descendedFrom('Drop here')
It would be more efficient to have one agent with this query (with or without an action). For example, make an agent "Find export notes" and then have the per-task agents use the query:
  inside("Find export notes")
The task agents now don't each poll the whole document but only the contents of the agent "Find export notes" which is much less querying per cycle.

Multiple agents actions - same scope. Keeping the task agents as separate agents allows tasks to be switched on individually but if that isn't a need, and just a by-product of iterative development, I'd roll them together. To make the aggregate action code manageable, add the built-in 'Code' prototype to your TBX and make a note of that type. Copy the actions from all your task agents into it. White space like tabs and line breaks won't affect how the code runs so you can format it for clarity - e.g. insetting if() branches and starting each action expression on a new line. The Code prototype helpfully uses a monospace font which is more appropriate for writing code. Now let's assume you delete the old agents and add a new one "Task Agent". The $Rule of the code note would be $AgentAction("Task Agent")=$Text;. To update the agent action you never edit it via Rename but instead edit the $Text of your code note. Changes to the latter are reflected pretty much instantly, every agent/rule cycle. See more on 'code' notes.

(continued...) If doing major surgery to the agent code it can be useful to turn the target agent off so as to avoid unintended side effects. To avoid having to open the agent's Rename dialog a simple 'remote control' method would be to add $AgentPriority as a key attribute in the code note. Although that attribute is in all notes it has no effect except in agents. Now extend the code note's $Rule by adding the action: $AgentPriority("Task Agent")=$AgentPriority. Now, to turn the agent on/off, you set the key attribute's value to 1 for 'on' (normal operation) or -1 for 'off'.  

(continued...) Note: the reason for naming the agent with Agent in the name is to avoid your agent having a name that might conflict with a name you might give an action note, i.e. avoiding name duplication. Another method is to use a prefix or underscores for spaces - basically naming that you would not use in notes.

HTML export extension agent.  You can get rid of this by adding an extra prototype for the export 'wrapper' container. Indeed this is even more helpful if there might be more than one such exporting section in the document. You set the prototype to use the wrapper export template ('checkvist') and give it '.opml' export extension. The latter is most easily done via the prototype's HTML view. All notes using the prototype then inherit that extension & template assignment. There is next to no overhead in the inheritance involved - certainly compared to an agent searching the whole document all the time.

Do ask if any of this needs more clarification.
Back to top
 
« Last Edit: Jun 7th, 2012, 4:16am by Mark Anderson »  

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #8 - Jun 7th, 2012, 5:40am
 
Digging deeper...

(I should just note here that critiquing someone else's work is much easier than creating the document in the first place. It's kind of Marcelo to share with us.)

'Usage' note, 'Shortcomings' section. I'd rename 'Shortcomings' as 'Tinderbox/checkVist format compatibility issues' and then have

1. Although 'entries' can be converted into 'notes' and vice-versa within Tinderbox, checkVist does not allow notes to be containers. Therefore it is best to follow suit within Tinderbox.

2. In checkVist  string values like "ASAP" are allowed.  However, the Tinderbox attribute used to populate checkvist ($due) is Date-type and so only accepts dates (though Tinderbox's built-in date shortcuts work fine).

'Usage' note, 'Quickstamps' section. The stamps don't change the background colours, they only populate data that will do so in checkVist. However, you could easily do this in Tinderbox by expanding the code to set either/both $TextBackgroundColor or $OutlineBackgroundColor. In either case you might want to use a tint of the colour - especially for text background so that the text/title remains readable.

ASAP dates. Assuming checkVist stores & imports/exports ASAP due dates as a string "ASAP" you could simulate this in TB and export it. Make a Boolean $IsASAP and add it to the *entry prototype. To make a date ASAP for checkVist, set $due to "never" and tick $IsASAP. In your export template you then check for items where $due is "never" AND that $IsASAP is 'true' (ticked). For such items, insert "ASAP" instead of a date string for the 'due' OPML attribute. Unfortunately there's no way to capture ASAP state coming back from OPML import as the 'due' OPML attribute will map to TB's $due and non-date values will be ignored.

(continued...) Not tested, but if you made a $due String attribute, you could then add action code to populate a TB Date-type attribute (if even required) so the latter could do date arithmetic in setting $due whilst not squishing "ASAP" assignments.  Unless you used this interchange a lot, that would probably be overkill. Indeed if you want to do a lot of interchange, checkVist has an API - which might be a better way of synching data (though requiring more formal coding skills - it's certainly not my area of expertise).

Testing due dates. You've hit the dates-in-demo problem in that the user actually needs to reset $due for (some of) the tests. You might want to address that in your instructions. Latter sort of issue and providing workarounds/explanation is part of why writing demos for other less familiar users is more work than assumed!

Styling of checkVist attribute names. It might be worth an explicit mention in your instructions as to why we've so many user attributes that don't use TB's normal naming style ($due vs. $Due, etc.). I assume they are there to match checkVist OPML data import defaults. Given your possible code typo $text/$Text (in my last post above) there is all the more reason to explain why you're using potentially confusing attribute names.

'item' export template. Assuming the attribute order within OPML tags doesn't matter (pretty sure that's true) then you can shift the 'user' and '_user_id'  to the front of the output before you test the $Prototype value as these two OPML attributes are written regardless of whether a TB note is an checkVist entry or a checkVist note.

'item' export template. Current usage for ^if()^ queries is to use $ prefixes for attribute names. For now, legacy support stops old usage failing but at some future point it won't. It's better to start out using current syntax. Therefore, in the template correct the following:
  ^if(Prototype=="*note")^ --> ^if($Prototype=="*note")^
  ^if(due!="never")^ --> ^if($due!="never")^
  ^if(tags)^ --> ^if($tags)^
  ^if(color)^ --> ^if($color)^
  ^if(bgColor)^ --> ^if($bgColor)^
  ^if(ChildCount==0)^ --> ^if($ChildCount==0)^
Back to top
 
« Last Edit: Jun 7th, 2012, 5:41am by Mark Anderson »  

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #9 - Jun 7th, 2012, 10:17am
 
@Mark

Thanks a lot for taking so much time analyzing my template. I think not only for me, but many out there in the community can learn a bit more about Tinderbox by studying the template and reading your comments. I think this post has given us a good learning resource.
I'll make the changes immediately and have the new version 1.3 ready in a moment.
Back to top
 
 
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #10 - Jun 7th, 2012, 10:48am
 
My pleasure - you did all the hard work! Don't feel obliged to follow up absolutely everything suggested - they're just suggestions.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #11 - Jun 7th, 2012, 1:28pm
 
Quote:
'Toggle status' agent. I believe this is meant to replicate the "0. Toggle Checked" stamp action. It doesn't but instead merely sets $NameStrike (which the stamp doesn't). IOW, the stamp and agent actions do different facets of the same task. I think your intent was that both methods do the same thing.

* Ok, every change now will be "hooked" to $Checked status. But I'm keeping the agent, rather than a rule in "*entry", to sync $Checked and $NameStrike.


Quote:
Typo? The *entry prototype's $Rule includes the code "$text=$Name".  As no user attribute $text is defined, this might be a typo for system attribute $Text.

* Ops. A relic from earlier coding, emergent structure's side-effect hehehe... fixed.



Quote:
Agent efficiency. The Agency container has 4 agents all with the same query scope:
 descendedFrom('Drop here')
It would be more efficient to have one agent with this query (with or without an action). For example, make an agent "Find export notes" and then have the per-task agents use the query:
 inside("Find export notes")
The task agents now don't each poll the whole document but only the contents of the agent "Find export notes" which is much less querying per cycle.

* Yeah, I realize that. But I thought this template could be a little more didactic than recommended, for learning purposes, so others can discriminate all actions.

How about we publish two different versions: "Learner's version" and "Optimized version", both functional, but the former's purpose is to provide a good learning framework ; the latter, a 'minified' version, optimized for practical use?

Quote:
Multiple agents actions - same scope. Keeping the task agents as separate agents allows tasks to be switched on individually but if that isn't a need, and just a by-product of iterative development, I'd roll them together. To make the aggregate action code manageable, add the built-in 'Code' prototype to your TBX and make a note of that type. Copy the actions from all your task agents into it. White space like tabs and line breaks won't affect how the code runs so you can format it for clarity - e.g. insetting if() branches and starting each action expression on a new line. The Code prototype helpfully uses a monospace font which is more appropriate for writing code. Now let's assume you delete the old agents and add a new one "Task Agent". The $Rule of the code note would be $AgentAction("Task Agent")=$Text;. To update the agent action you never edit it via Rename but instead edit the $Text of your code note. Changes to the latter are reflected pretty much instantly, every agent/rule cycle. See more on 'code' notes.
If doing major surgery to the agent code it can be useful to turn the target agent off so as to avoid unintended side effects. To avoid having to open the agent's Rename dialog a simple 'remote control' method would be to add $AgentPriority as a key attribute in the code note. Although that attribute is in all notes it has no effect except in agents. Now extend the code note's $Rule by adding the action: $AgentPriority("Task Agent")=$AgentPriority. Now, to turn the agent on/off, you set the key attribute's value to 1 for 'on' (normal operation) or -1 for 'off'.  

Note: the reason for naming the agent with Agent in the name is to avoid your agent having a name that might conflict with a name you might give an action note, i.e. avoiding name duplication. Another method is to use a prefix or underscores for spaces - basically naming that you would not use in notes.

* Hold on, I'll need some time to digest all this.

Quote:
HTML export extension agent.  You can get rid of this by adding an extra prototype for the export 'wrapper' container. Indeed this is even more helpful if there might be more than one such exporting section in the document. You set the prototype to use the wrapper export template ('checkvist') and give it '.opml' export extension. The latter is most easily done via the prototype's HTML view. All notes using the prototype then inherit that extension & template assignment. There is next to no overhead in the inheritance involved - certainly compared to an agent searching the whole document all the time.

* Yes, I tried something similar but, for some reason, it didn't render correctly. I'm not sure what I did wrong, so, if you could help me do that.

Back to top
 
« Last Edit: Jun 7th, 2012, 3:58pm by Marcelo Mirage »  
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #12 - Jun 7th, 2012, 3:01pm
 
Quote:
(I should just note here that critiquing someone else's work is much easier than creating the document in the first place. It's kind of Marcelo to share with us.)

* I think people in this community are smart enough to appreciate the intention and value of a thoughtful critique, especially coming from you, Mark. Wink


Quote:
'Usage' note, 'Shortcomings' section. I'd rename 'Shortcomings' as 'Tinderbox/checkVist format compatibility issues' and then have

1. Although 'entries' can be converted into 'notes' and vice-versa within Tinderbox, checkVist does not allow notes to be containers. Therefore it is best to follow suit within Tinderbox.

2. In checkVist  string values like "ASAP" are allowed.  However, the Tinderbox attribute used to populate checkvist ($due) is Date-type and so only accepts dates (though Tinderbox's built-in date shortcuts work fine).

* Agreed. Changed.


Quote:
'Usage' note, 'Quickstamps' section. The stamps don't change the background colours, they only populate data that will do so in checkVist. However, you could easily do this in Tinderbox by expanding the code to set either/both $TextBackgroundColor or $OutlineBackgroundColor. In either case you might want to use a tint of the colour - especially for text background so that the text/title remains readable.

* Thanks, I'll work on it later. For now, the colored badges stand for background color in Checkvist.


Quote:
ASAP dates. Assuming checkVist stores & imports/exports ASAP due dates as a string "ASAP" you could simulate this in TB and export it. Make a Boolean $IsASAP and add it to the *entry prototype. To make a date ASAP for checkVist, set $due to "never" and tick $IsASAP. In your export template you then check for items where $due is "never" AND that $IsASAP is 'true' (ticked). For such items, insert "ASAP" instead of a date string for the 'due' OPML attribute. Unfortunately there's no way to capture ASAP state coming back from OPML import as the 'due' OPML attribute will map to TB's $due and non-date values will be ignored.

(continued...) Not tested, but if you made a $due String attribute, you could then add action code to populate a TB Date-type attribute (if even required) so the latter could do date arithmetic in setting $due whilst not squishing "ASAP" assignments.  Unless you used this interchange a lot, that would probably be overkill. Indeed if you want to do a lot of interchange, checkVist has an API - which might be a better way of synching data (though requiring more formal coding skills - it's certainly not my area of expertise).

* sorry, man, but I do find this overkill. I think users can do without the "ASAP" tag (it's the only problematic string).

Quote:
Testing due dates. You've hit the dates-in-demo problem in that the user actually needs to reset $due for (some of) the tests. You might want to address that in your instructions. Latter sort of issue and providing workarounds/explanation is part of why writing demos for other less familiar users is more work than assumed!


* Could you help me write the instruction? I don't really know how to make this point clear.
** better still: is there a dedicated topic on how to configure dates in tbx demos? If not, how about one?


Quote:
Styling of checkVist attribute names. It might be worth an explicit mention in your instructions as to why we've so many user attributes that don't use TB's normal naming style ($due vs. $Due, etc.). I assume they are there to match checkVist OPML data import defaults. Given your possible code typo $text/$Text (in my last post above) there is all the more reason to explain why you're using potentially confusing attribute names.

* OK. Adding a caveat.

Quote:
'item' export template. Assuming the attribute order within OPML tags doesn't matter (pretty sure that's true) then you can shift the 'user' and '_user_id'  to the front of the output before you test the $Prototype value as these two OPML attributes are written regardless of whether a TB note is an checkVist entry or a checkVist note.

* OK, done.


Quote:
'item' export template. Current usage for ^if()^ queries is to use $ prefixes for attribute names. For now, legacy support stops old usage failing but at some future point it won't. It's better to start out using current syntax. Therefore, in the template correct the following:
 ^if(Prototype=="*note")^ --> ^if($Prototype=="*note")^
 ^if(due!="never")^ --> ^if($due!="never")^
 ^if(tags)^ --> ^if($tags)^
 ^if(color)^ --> ^if($color)^
 ^if(bgColor)^ --> ^if($bgColor)^
 ^if(ChildCount==0)^ --> ^if($ChildCount==0)^


* Done! However, I took that from OPML built-in template itself:
Quote:
^if(ChildCount)^^indent("\t",^value($OutlineDepth(parent)-1))^<outline^if(Text)^ text="^value(attributeEncode($Name))^" _note="^value(attributeEncode($Text))^"^else^ text="^value(attributeEncode($Name))^"^endIf^^if($Checked)^ _status="checked"^endIf^>
^children(/Templates/OPML/OPML item)^^indent("\t",^value($OutlineDepth(parent)-1))^</outline>
^else^^indent("\t",^value($OutlineDepth(parent)-1))^<outline^if(Text)^ text="^value(attributeEncode($Name))^" _note="^value(attributeEncode($Text))^"^else^ text="^value(attributeEncode($Name))^"^endIf^^if($Checked)^ _status="checked"^endIf^/>
^endIf^


Note that some attributes don't have "$".




Back to top
 
« Last Edit: Jun 7th, 2012, 6:58pm by Marcelo Mirage »  
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Marcelo Mirage
Full Member
*
Offline



Posts: 133
Brazil
Re: Exporting to Checkvist
Reply #13 - Jun 7th, 2012, 3:42pm
 
Back to top
 
« Last Edit: Jun 7th, 2012, 3:49pm by Marcelo Mirage »  
Marcelo Mirage Marcelo Mirage MMUmeda misantropov@yahoo.com   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Exporting to Checkvist
Reply #14 - Jun 8th, 2012, 6:44am
 
Lots of changes, all incorporated in TBX_checkvist_exporter_v1.3-1.tbx. Iv'e added my comments as an extra container in the instructions (ex-inro) section. All my notes are in one container for easy deletion when you've had a chance to read them.  I've tried to use TB links, where pertinent, to point you to relevant notes/changes. Deleting my notes will delete those links so they won't leave a mess behind. A few overview notes:
  • The ASAP thing. Agreed it's overkill - I was just pointing out that there was a possible solution if you - or others - wanted/needed to go further in integration.
  • I've added an agent that finds all entries/notes and that set the other agent to work on that (plus some other polish - seem my notes).
  • I've implemented an example of my code note method for you. Again, I'm not saying it's a must-do. Rather it's a bit of incremental formalisation you might find very useful if/when your action code gets complex and difficult to edit via the box on a Rename dialog.  I hit on the method originally when I found myself editing rule code in a another note's text and then pasting back into the Rename's box.
  • I've added a trivial demo to set $TextBackgroundColor.
  • I've fixed the specimen dates for the date tests but using a rule  and date designators (e.g. $due-date("tomorrow")). That method doesn't work around every demo's problem with specimen test dates but I think it answers yours.
  • Template syntax. Oh bother, I thought that had been fixed. I've reported this to support. It doesn't break anything but this is a good example of exactly why I feel TB built-in examples should use current syntax - so people don't end up learning out-of-date syntax that's already slated as not supported in due course.
As I say, the real detail of my changes is in my uploaded modified version of your last file. Don't feel obliged to use my ideas - they're just suggestions - based mainly on things I've learned from fixing previous problems. I'm not trying to hijack the demo! Do ask if anything doesn't make sense.

BTW, one thing I did learn was that if using your stamp #0 (toggle all checked state stamp), then don't select all items you wish changed. Only select the ancestor in each branch on the outline that you wish to update. Otherwise, nothing breaks but you don't get quite the outcome expected. This is because the code cleverly cascades the change across as descendants.

Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Pages: 1
Send Topic Print