[Experimental idea] Redesign section naming

[SimonBiggs]

Some section names are don't currently clearly highlight what they actually achieve. I propose changing section names in the following way:

• <section-button> --> <button-trigger>
• <section-live> --> <contents-trigger>
• <section-output> --> <global-trigger>
• <section-filechange> --> <file-trigger>
• <section-start> --> <kernel-start-trigger>

And also the potential implementation of a range of other sections:

• <kernel-stop-trigger>
• <page-load-trigger> with optional flag parameter firstUserOnly
• <page-close-trigger> with optional flag parameter lastUserOnly
• <timeout-trigger> with parameter seconds
• <url-trigger> with parameter url
  • triggers whenever a defined url is called
• <result-trigger> with parameter result -- the design of this one needs further thought
  • triggers whenever a code result (such as a function or variable) changes

I also propose creating a more advanced code trigger component which can be customised to be mixes of the above as required. However this will not replace the above options, instead provide more advanced control as needed:

<multi-trigger triggers="a_python_list" options="a_python_dict">

[SimonBiggs]

@robmarkcole along the same "keeping it simple" vein, does this proposal keep the basics simple do you think? Should I be looking at section naming redesign, or is it okay as is?

[robmarkcole]

I like the existing namings, but that’s just a personal preference as they are a bit more succinct

[SimonBiggs]

@robmarkcole Thanks for the feedback :)

After your response I have done more editing of the top post trying to make the names more succinct.

Is the swap of 'section' for 'trigger' a good one do you think? My aim with using the word 'trigger' is to make it more self explanatory of what it is actually doing. And then also tie in to the 'triggers' parameter within multi-trigger.

By renaming the sections as triggers someone trying out the multi-trigger component will naturally just write 'session-start' for example as one of the triggers since they have got used to using it.

[SimonBiggs]

I don't believe this is name changing for name changing sake. At the beginning I only had start, button and live. The name live was chosen to contrast against button, as in button only runs when you click it, but live live updates. The word section was chosen simply because its what I thought of at the time when I was trying to avoid clashing with the standard html <button> component.

But now that I have output and filechange which are also live update sections. So I believe I need to change live to contents or something of the sort making it clear that live only runs when a variable within it changes.

But I have also often come across cases where I want a section to do two things. So I do also need to build in the ability to customise the sections. Given that I am already changing the name of live it means that the choice of the word section should also be considered to make sure it is the best option.

The section word is saying that, "This is a group of code which all has a similar property". That's all well and good, but I don't know if that idea needs to be portrayed. However the trigger word would say, "Code within here is triggered by such and such thing changing". This makes things like filechange make sense to be shortened, as in with the section word shortening to <section-file> isn't obvious that it runs whenever a file changes, however <file-trigger> can naturally read as "triggers when a file changes" more succinctly.

[robmarkcole]

OK I understand your reasoning. I still find the use of trigger a little confusing, could you update one of the example forms to use the new convention, so I can get a feel for it in context?

Also I am wondering if there are any other projects with a convention we could adopt?

[SimonBiggs]

I haven't even begun implementing the new names. Just thinking about it at the moment.

I personally do like the section word. Maybe if it's not broke don't fix it?

I like your second point. Is there a convention from another project. I'll have a look. If you find something please let me know.

On Sat., 21 Apr. 2018, 5:22 pm Robin, [email protected] wrote:

OK I understand your reasoning. I still find the use of trigger a little confusing, could you update one of the example forms to use the new convention, so I can get a feel for it in context?

Also I am wondering if there are any other projects with a convention we could adopt?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-383274329, or mute the thread https://github.com/notifications/unsubscribe-auth/AGQVe0850XO8SN4DuCM-eGdr76xBt2_Kks5tqt4sgaJpZM4TdPTz .

[SimonBiggs]

To play devils advocate the "section" helps indicate where that element needs to be placed. It helps indicate that it needs to go around the code blocks. "Trigger" doesn't give you a an idea about it needing to surround the cod blocks.

The live name can change to content or something similar. But keep "section" as is?

On Sat., 21 Apr. 2018, 6:23 pm Simon Biggs, [email protected] wrote:

I haven't even begun implementing the new names. Just thinking about it at the moment.

I personally do like the section word. Maybe if it's not broke don't fix it?

I like your second point. Is there a convention from another project. I'll have a look. If you find something please let me know.

On Sat., 21 Apr. 2018, 5:22 pm Robin, [email protected] wrote:

OK I understand your reasoning. I still find the use of trigger a little confusing, could you update one of the example forms to use the new convention, so I can get a feel for it in context?

Also I am wondering if there are any other projects with a convention we could adopt?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-383274329, or mute the thread https://github.com/notifications/unsubscribe-auth/AGQVe0850XO8SN4DuCM-eGdr76xBt2_Kks5tqt4sgaJpZM4TdPTz .

[SimonBiggs]

@robmarkcole

Here's another thought. Go back to just <section-start>, <section-button>, and <section-live>. Remove filechange and output. And instead have a trigger parameter on <section-live>.

The trigger parameter on the live section would default to trigger="['content']", but could be replaced with options such as trigger="['global']" or trigger="['file']". So its default if no trigger parameter was provided would be to do what it does currently, but the live section can be extended with more triggers as need be.

[SimonBiggs]

or what if the parameter was instead addTriggers which indicated that it would always keep the content but could have others included. And make it so that the addTriggers parameter is available on all sections.

This would mean that <section-start addTriggers="['content']"> would actually be equivalent to <section-live addTriggers="['start']">

[SimonBiggs]

Hmm, different word altogether. Inspired by RxJS (http://reactivex.io/documentation/operators/subscribe.html)

What about:

• <observe-files>
• <observe-all-variables>
• <observe-content-variables>
• <observe-code-result>
• <observe-session-start>
• <observe-page-load>
• <observe-button>

And finally

• <observe-custom subscriptions="['content-variables', 'button']">

This is especially poignant because that is exactly what the underlying code is doing. It is using the RxJs library to observe changes in those respective things.

[robmarkcole]

@SimonBiggs I like that formalism

[SimonBiggs]

Woo hoo! :) we have a winner!

Okay, back up a sec, why do you like it? (I don't want to race ahead with the idea unless we're sure that we're sure).

[SimonBiggs]

I envisage usage of the above observe elements to look like the following:

<observe-session-start>

```python
file_names = ['a_file_name.csv', 'another_file_name.py']

x = 1
y = 2


def a_function():
    return x + y


def is_disabled():
    return x == 1


def some_code():
    print('boo')
```

</observe-session-start>

<observe-session-start runCode="some_code()"></observe-session-start>


<observe-page-load runCode="some_code()"></observe-page-load>


<observe-all-variables runCode="some_code()"></observe-all-variables>

<variable-slider>x</variable-slider>

<observe-content-variables runCode="some_code()">
  <variable-number disabled="is_disabled()">y</variable-number>
</observe-content-variables>


<observe-button value="a_button_name" runCode="some_code()" disabled="is_disabled()">
<observe-button>


<observe-files files="file_names" runCode="some_code()" disabled="is_disabled()">
</observe-files>


<observe-code-result observeCode="a_function()" runCode="some_code()" disabled="is_disabled()">
</observe-code-result>

<observe-code-result observeCode="[x, y]" runCode="some_code()">
</observe-code-result>

<observe-code-result observeCode="x" runCode="some_code()">
</observe-code-result>


<observe-session-start>

```python
# can use a list when no options are needed
subscriptions_with_no_options = [
    'content-variables', 'page-load'
]

# when options are needed use a dict
# pass None if that subscription isn't being passed an option
subscriptions_with_options = {
    'files': file_names,
    'button': {
        'value': 'a_button_name',
        'colour': 'red'
    },
    'content-variables': None,
    'page-load': None,
    'code-result': 'is_disabled()'
}
```

</observe-session-start>

<observe-custom subscriptions="subscriptions_with_no_options" runCode="some_code()">
</observe-custom>

<observe-custom subscriptions="subscriptions_with_options" runCode="some_code()" disabled="is_disabled()">
</observe-custom>

[SimonBiggs]

@OxygenLithium do you have any preferences/ideas/recommendations regarding https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-384922733 and https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-384926107

[SimonBiggs]

I think I have managed to convince myself. Managing to convince you @robmarkcole so quickly probably helped sell the idea to myself.

[SimonBiggs]

So, unless there are any objections I will begin implementing this formalism in parallel. The old method will hang around. Once the new method is complete the old method will get deprecation notices.

I will keep the old method around for quite a while though to make the transition smooth.

The new interactive docs will only make mention from the get go this new syntax.

---

... time to sleep on it me-thinks.

[SimonBiggs]

@robmarkcole do you have any thoughts about the parameter design?

[robmarkcole]

@SimonBiggs could you clarify with a single example to choose between?

[SimonBiggs]

For example:

• changing conditional to disabled, resulting in being more aligned to standard html
• In observe code result, trying to make it clear which is the code being run and which code is being watched
• Change the parameter code parameter from code to runCode, primarily to facilitate the point above
• If options are wanted on the observe custom, pass a dictionary. The keys of that dictionary will be used to work out what subscriptions are needed.

[robmarkcole]

@SimonBiggs

• Consistency with standard HTML recommended
• Clarifying watched vs. run code is necessary
• runCode is useful
• Dict is a good approach

[SimonBiggs]

Thanks Robin. Let me know if I've been sending too many pings your way.

[robmarkcole]

No way, keep them coming :-)

[SimonBiggs]

Cheers. Thanks for the help by the way. I'm glad I didn't get stuck with "trigger".

[SimonBiggs]

@robmarkcole another question, could I get away with:

<observe-code-result code="a_function()" runCode="some_code()"></observe-code-result>

As in if code to be run is always called "runCode" is it obvious enough to use "code" instead of "observeCode" on the observe-code-result section?

[SimonBiggs]

@robmarkcole and please let me know if you can think of ways to shorten any of the names and still make it clear what they mean.

[robmarkcole]

Hi @SimonBiggs I think if you are using runCode then you should also use observeCode : explicit is better than implicit :)

[SimonBiggs]

Kk :) sounds good. Explicit is definitely better than implicit. Thanks Robin.

On Mon., 30 Apr. 2018, 4:14 pm Robin, [email protected] wrote:

Hi @SimonBiggs https://github.com/SimonBiggs I think if you are using runCode then you should also use observeCode : explicit is better than implicit :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-385319895, or mute the thread https://github.com/notifications/unsubscribe-auth/AGQVew3ChAAEWbsir8OTdEUeKAwl-vlLks5ttqvcgaJpZM4TdPTz .

[SimonBiggs]

@robmarkcole here's a project that is very very similar in syntax. It's designed to produce static documents, but the syntax has been well thought out and the same syntax could achieve the same ends here.

https://rmarkdown.rstudio.com/lesson-3.html

Essentially don't have sections at all. Instead define how each code block interacts in the header of the code block.

```{python button}
print('hello world')
```

I'm not sold on the idea. But thought the idea needed to be raised seeing that r markdown is achieving a very similar aim with a very similar syntax.

[robmarkcole]

@simonbiggs as someone with no web dev experience but plenty of python experience, that syntax does have a ‘familiar look and feel’. I’ve been working out how to best implement some syntax in my own project recently and the tricky part is establishing the best structural relationships between syntax. If that package has those relationships figured out already you could just adopt their structure but change the precise syntax.

[SimonBiggs]

Interesting. I'll think more about it. I'm not really sold on it...

If you could think of some ways the parameters could be neatly put in there that would help. I can't picture how to get a similar level of flexibility...

On Sun., 13 May 2018, 3:59 pm Robin, [email protected] wrote:

@SimonBiggs https://github.com/SimonBiggs as someone with no web dev experience but plenty of python experience, that syntax does have a ‘familiar look and feel’. I’ve been working out how to best implement some syntax in my own project recently and the tricky part is establishing the best structural relationships between syntax. If that package has those relationships figured out already you could just adopt their structure but change the precise syntax.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/SimonBiggs/scriptedforms/issues/247#issuecomment-388603712, or mute the thread https://github.com/notifications/unsubscribe-auth/AGQVe-iAHfXnakqhV7HNUNAgKgNAN9sGks5tx8vTgaJpZM4TdPTz .