Proposal: extension instructions -> methods

Printer Friendly Version Attach Files

wdavatar?user=leiger
leiger
18 Mar 2011 02:29. Edited 2 times. (Edit, Permalink)

Summary: Essentially, all this means is that I want to change the name of existing instructions/methods (and add many new ones!). An example is input-boolean being renamed to message.get.boolean. What I've written below is mainly there to explain why I've chosen these new names, and what some of the new methods are supposed to do.

Note: There is a lot of reading involved here. If you don't have much time, you might want to read this later.

I'm considering changing a few things in regards to how extensions work. Note that backwards compatibility will not be kept, but I will use the API to automatically update all existing extensions in the gallery so that they work with the new syntax (if this goes ahead). You will need to manually update any developer-mode extensions.

What I want to know from you (after reading):

  • Are there any changes that you would suggest? Or are there any extra methods that I didn't mention here, that you want?
  • Is it easy to understand? Do you think it would be easy for new STE users to understand if they want to make extensions?
  • Overall, are you happy with this proposal? Are you happy with how extensions currently work? Which is best, the current way or the new way?

I'd like to change the term "instructions" to be "methods" - because it sounds better, and because it better fits the new system I am proposing here. So whenever I say 'methods' below, think 'instructions'. They are the same thing.

Except for comments (i.e. [!-- comment --]), this proposal says that all other instructions/methods should be scrapped and no longer supported. Instead, the new ones will be supported (some which do the exact same thing as the existing instructions/methods, and others that give new functionality).

Proposed methods:

Everything should be put into a separate namespace.

So to append text to the document you would say "content" -> "append". This means: find the current page's content (the text in the main text area), and append something to the end of it.

How you currently do it:

append text-to-append

New method:

content.append text-to-append

Now, here's the full list that I'd like to implement and have working. With these, extensions should become far more powerful than they are now: (if you have more suggestions, let me know!)

The set methods allow you to input something, e.g. text. The get methods allow you to specify the name of a variable (which you can use later), and STE will put something into that variable. To help explain… I'll give some code examples after the list. And please ask if you don't understand any of this, or let me know if you think it's going to be too complicated for new users to learn.

  • content
    • set (usage: content.set … new)
    • get (usage: content.get … new)
    • prepend (usage: content.prepend … new)
    • append (usage: content.append … replaces append TEXT)
    • delete (usage: content.delete … replaces delete TEXT)
    • replace (usage: content.replace … new)
  • title
    • set (usage: title.set … new)
    • get (usage: title.get … new)
  • parent
    • set (usage: parent.set … new)
    • get (usage: parent.get … new)
  • tags
    • set (usage: tags.set … new)
    • get (usage: tags.get … new)
  • site
    • set (usage: site.set … new)
    • get (usage: site.get … new)
  • fullname
    • set (usage: fullname.set … new)
    • get (usage: fullname.get … new)
  • document
    • export (usage: document.export … replaces export SITE:PAGE from 3.26 dev)
    • import (usage: document.import … new)
    • new (usage: document.new … new)
  • message
    • get
      • boolean (usage: message.get.boolean … replaces input-boolean VARIABLE)
      • int (usage: message.get.int … replaces input-int VARIABLE)
      • string (usage: message.get.string … replaces input VARIABLE)
    • show (usage: message.show … new)

How this works:

Here's a quick example, to aid understanding. Line numbers added for reference and won't be needed in real code.

I want my extension to change the 'start' page on a site that the user chooses. It might work something like this:

1. EXTENSION ChangeStart
2. CREATOR leiger
3. document.new Home
4. title.set Home
5. content.set Welcome! This is the home page for my site.
6. content.append And this is the second line of my page!
7. message.get.string Name of site
8. document.export :{$Name of site}:start
9. message.show Thanks for using my extension! ;-)

Line-by-line breakdown:

  1. Same as it is now - declare extension name, to be used in STE
  2. Same as it is now - declare extension creator/s, to be used in STE
  3. Closes the current document (asking user if they want to save first). Not using this means your extension will modify the currently-open document instead. You must specify a title for the page when you do this, in this case it is "Home"
  4. Another way to set a title, e.g. for modifying existing documents
  5. Completely replaces any text in the editor with the line you specify. In this case, there wouldn't have been anything in the editor anyway as we started a new document.
  6. To add extra lines, you need to append them to the end. I could have used 'content.append' for line 5 as well, it would have done the same thing.
  7. Asking the user for input works the same was as it did before, but you type 'message.get.string' instead of 'input'
  8. Exports the current document (including the title and content we gave it earlier) to :site:category:page - in this case, 'category:page' is 'start', and the site is whatever the user typed in on step 7.
  9. Displays a message to the user if you wanted to do that. In this example I'm just thanking them for using the extension.

Included page "inc:signature" does not exist (create it now)

wdavatar?user=franknarf
Franknarf

19 Mar 2011 01:49. Edited 0 times. (Edit, Permalink)
Your example code made sense to me without reading your line-by-line comments, and I've only taken a couple CS courses. So I'd say it's appropriate for new STE users that can already handle wikidot.

Other uninformed comments:

  • It looks like your inputted variables are named after the question asked to the user. You probably already have some way of using shorter variable names?
  • It would be convenient (for users) if there were some way to take several inputs at once (in one dialog box) instead of sequentially.

Included page "inc:signature" does not exist (create it now)

wdavatar?user=leiger
leiger

20 Mar 2011 00:55. Edited 0 times. (Edit, Permalink)

  • It looks like your inputted variables are named after the question asked to the user. You probably already have some way of using shorter variable names?

Yes, that is how it would work (and how it already works). I'd like to eventually separate the question and the variable name, but at this stage for simplicity they are the same.

  • It would be convenient (for users) if there were some way to take several inputs at once (in one dialog box) instead of sequentially.

I agree - this is something else that I plan to implement in the future. I'm thinking that the syntax won't change at all - if you ask for several inputs on consecutive lines, they should probably be combined into one modal dialog automatically.

Included page "inc:signature" does not exist (create it now)

Post Reply

Add reply on "Proposal: extension instructions -> methods"

Printer Friendly Version Attach Files

CSS Theme, Images and Code on this website are © Shane Smith 2010-2012. All forum posts by users and documentation licensed under Creative Commons BY-NC-SA 3.0 License.