I tried to use the cross-wikia-transclusion trick you used recently and embed an emoticon from w:c:templates. That obviously broke the page. Do you have any idea how to fix this? I'm stumped.
I'm not able to edit your posts, but if you temporarily make me an admin, I could try to see if I can do anything on this end? Other than that, not sure I have any other good ideas.
Okay. Fixed. Do you want to keep the adminship? It may come in handy if we ever continue to work on ThreadTools again. Not that I have an idea when that might be...
Replace All doesn't work -- the replacement doesn't happen, and it says "420 replacements made!" when they aren't anywhere close to 420 matches to begin with...
The UI does really weird things when you move it off the edge of the screen. In Chrome, the UI background becomes transparent and it creates a slider. In Firefox, the buttons get pushed down.
Here's a first demo of automatically converted Jsdoc output. As you can see it looks quite different. It would take quite a bit of doing, but it would be possible to use the same color scheme as in the original files. But it's not really possible to use the same typefaces. Mainly because Wikia does not permit those types of files.
Here's the stylesheet: Jsdoc.css. Feel free to toy with it!
Also, once I complete the next version, I'll try to provide an actual, full copy of my directory -- if that's what you meant -- not just the results of generating documentation. But I can't do that right now because my code is in disarray.
The documentation page itself looks pretty decent, but you've dropped the navigation box thingymajig on the left-hand side. But, I suppose there's not too much of an issue with going back to the Class Index if you want to search a different class.
Keep in mind that with every new version of Railgun, there will be new objects/namespaces. I can't even tell you what the new ones will be with this version because I'm still ironing out... issues...
-sigh- before our discussion over on the Railgun wiki, I knew exactly what I was doing. Now I don't have a damn clue >_<
Ok, I think what the problem is is too much talking and not enough coding. I need to do something exactly when I think of it -- not accumulate a ton of ideas and then try to do everything at once.
Also, I need to stop trying to change my architecture to fit different ideas. Rather, I need to mold the ideas so that they fit my architecture.
"About the folder structure: Why do you see structural changes as a problem?"
I dunno, it's probably not a problem. I'm just saying that new folders will be getting added. In the next version, there will be a Symbols\Railgun.ModuleManager at the very least.
I'm logging off of Wikia and not getting back on until I'm happy with my code. Wikia is too much of a distraction and I can't focus =P
No, I am not okay with that structure. I may wish to change the names of the namespaces. I don't want to be locked in to my current naming convention just yet.
Also ... I'm not done yet. Made good progress, but still banging my head against the wall on a few fine points. Here's one of them:
My code is written to emphasize objects, not functions. Thus, while trying to implement one of your suggestions (that the user provide an init() method to be run later) the following has become a headache for me:
var myObject ={
datum :'blah blah blah',
method :function(){
console.log(this.datum);
console.log(this);}}var differentName = myObject.method;
myObject.method();// prints "blah" and myObject
differentName();// prints "undefined" and Window object
Oh and, before you say it -- no, I can't just put datum as a variable inside the function. I have multiple functions that need to access the same data.
^That basically re-asserts why the way I had it set up before made more sense: user provides an object which contains an init() method (doesn't matter what the object is called, so long as that object has a method named exactly "init()")
... you know, now that I think about it. That's not that far off from your module construction in Wikimarks. To make my code look like yours, all I'd have to do is put all of that stuff into a function so as to not pollute the global namespace... hmmmm...
// namespace
myObject ={};// use a run-immediately, anonymous function to// add properties and methods to the object(function(ns){
ns.datum='blah blah blah';
ns.method=function(){
console.log(ns.datum);}}(window.myObject));var differentName = myObject.method;
myObject.method();// prints "blah blah blah"
differentName();// prints "blah blah blah"
Suddenly the method to the madness is clear.
So, the object-oriented structure really is the same! The only thing that was keeping me from seeing it was that stupid function wrapped around the outside of the code, and the fact that the properties and methods were being added to the object *AFTER* it had been created, not during the creation process.
It's the same. It looks different. But it's really the same.
Don't worry! That structure for the docs doesn't box you in. You are free to remove, rename and add classes etc. at any time. I could either delete obsolete files or place a redirect in their stead. That's no problem at all.
I just thought it would be convenient to store all documentation as subpages of a Docs page. The Docs page itself would be left untouched by the updater to give you a chance to write a quick intro or somesuch.
"This" is a fickle thing in JavaScript. It's always relative to the caller. That can be confusing as hell.
There are a few other ways to deal with it. There's even a built-in method just for that purpose: "apply".
And with jQuery's $.proxy function you can create a whole new function whose "this" is firmly tied to a certain object.
var myObject ={
datum :'blah blah blah',
method :function(){
console.log(this.datum);
console.log(this);}}var differentName = myObject.method;
myObject.method();// prints "blah" and myObject
differentName.apply(myObject);// same herevar anotherName = $.proxy(myObject.method, myObject);
anotherName();// and here as well
About the docs, good to hear. Because I was thinking about renaming the RailgunServer namespace. It doesn't fit into my preferred convention of having all namespaces be subnamespaces of Railgun.
Thanks. Hmmmm, I'd use $.proxy because it looks extremely handy. But in this case, I think that everytime I pass a function as a parameter, I'll just go back and remove any this from the body of the function. That seems to be perfectly safe way to go.
I won't be passing functions as a parameter very often anyway -- it's not a concept I'm used to yet. You can't even do it in Java. In C++, you can create a pointer to a function and then pass the pointer as a parameter. But I only use that construction when I absolutely have to, as a last resort kind of thing.
Hey I saw you're adding lots of pages for the JSDoc stuff. How's that working out?
Wanted to let you know that I'm essentially done with the next version of Railgun. I've caught up with my code and everything makes sense again (yay!). Soooooooo many errors having to do with misusage of the this keyword...
The new API for modules is incorporates some of your suggestions. The end result is that no specific structure is imposed or anything. All you have to do is provide a function and register it so that the framework can call it later. Simple as that.
I'm probably going to release next week just because I don't have much time this weekend. The extra time should hopefully allow me to get my module sorting algorithm in place and tie off some loose ends.
Oh and, there was going to be a question here, but I answered it myself in the process of typing it out =)
A few seconds ago my script completed its first successful run :)
This is how it works: You dump the make.php (and the accompanying files) into a directory where all public files are stored. When you run make.php from the command line, it processes the directory's content by these rules:
files whose modification date is older than the last time you ran make.php are ignored
files in subdirectories of the working directory are ignored
all newer JS, CSS and HTML files in the working directory are uploaded to Wikia
JS and CSS files will be minified.
minified files will be prefixed with a (configurable) comment header
both regular and minified versions will be uploaded
JS files will be run through jsdoc-toolkit
the generated documentation will be reformatted and uploaded as well
missing features + known bugs:
wikia's connection is a bit wonky at times; currently make.php doesn't deal well with unexpected failures...
the CSS needs a bit of fine-tuning; the "method details" and the "field details" areas look a bit messy still; also: I only worked on the stuff that I got to see; you did not e.g. use the @augments tag or the @event tag, etc.; how any of these will look is unknown
default values for fields should be wrapped in nowiki-tags
code-tag for examples needs to be replaced by a source-tag
filter script in the siderail does not work
Apart from that I think we should ditch the source view jsdoc-toolkit produces and link to the actual script files instead. The line numbers are nice of course but everything else is inferior to what the source-tag produces.
So, since make.php generates the documentation -- it sounds like all you need from me are the JS/CSS files themselves?
-D="noGlobal:true"
^Adding that to the command line args when building the documentation causes global to be completely omitted. I've been using that when I build my documentation. Does that solve the bugs with global?
Ditching source view jsdoc-toolkit produces: That's fine. The line numbers are extremely important to me, but I can view them in my IDE anyways so no worries there.
"default values for fields should be wrapped in nowiki-tags"
"code-tag for examples needs to be replaced by a source-tag"
I suppose I *could* change the comments in my JS files to accommodate those. Is that the solution you had in mind, or would some sort of automated Find and Replace work instead?
The stuff I listed in my last post isn't really difficult to solve. They're just things I noticed when I first saw the code in action. That's all.
Kicking out global is not necessary. I just don't like the "_global_" name. I'd rather have "global". A little formatting issue. Same with that empty p tag...
I can also deal with the default values and the example code. It's not difficult. It just takes a little time.
The line numbers are handy. I agree. Everything else is meh at best. I also feel it's a needless duplication to have two versions of the same script. Maybe we should think of a way to add line number to the source-tag instead? That would have uses beyond our documenting project.
And about the script: Actually I was hoping I could make it so maintenance free that I can give you the script - instead of you giving me the files to parse with the script.
It turns out jsdoc-toolkit uses the code-tag for a great many things. There's no way make.php can distinguish example code from everything else and it doesn't seem to be a good idea to replace all uses of the code-tag.
I'm afraid I have to ask you to go back in and add source- or nowiki-tags to example code and default values.
Sorry about the bad news!
I'll upload the script now.
Just so you know:
The script's output is very verbose. It logs every little detail about the communication with the server to stdout. That's probably not particularly useful to you, but it does not indicate a problem.
The script takes a very very long time to execute. That's intentional. I've set the minimum time between uploads to 60 seconds.
I may have found something interesting for your Railgun: Voting. We'd have to find somebody who's been around for a while to know for sure, but it seems that at some point in time Wikia experimented with votes on articles. Maybe the users weren't all that interested in that feature. Maybe it never saw the light of day. I can't tell. Again: We'd have to find a veteran to know for sure. But either way: The mechanism for voting is still around and it appears to still work.
Why is this interesting? First of all a vote is a minor interaction with Wikia's servers. It doesn't cause a lot of traffic or cost a lot of server time. It's not a big deal. That makes it interesting to use it as a Ping of sorts - especially since votes seem to be timestamped automatcially.
And secondly - and most importantly - it does not seem that voting counts as an edit. If that's true than a JavaScript that "votes" in the background, does not pollute anybody's EditCount or any wiki's WikiActivity/RecentChanges/Logs or other important metrics.
All of this is highly speculative, of course, and yes we're most definitely talking about a hack here!
If you're interested, take a look at the [/api.php API] and search for the "wkvoteart" entries. There's four of them under:
action=insert
action=update
action=delete
action=query
The first three are for casting votes and the fourth one retrieves an article's votes.
That is kind of interesting, although I must admit I have at least 2 other features I very much so wish to code next.
One of them is the ability to show/hide the entire siderail (that should be a quickie, the hardest part is figuring out where to put the button -- I should have this feature completed by today).
The second thing I want is up/down arrows on every module, so that you can re-order everything on the siderail at will. E.g. maybe I want the Wiki Activity module at the very top -- simply click a few arrows to move it there. This one is going to be a bit of a challenge, because different modules appear on different pages. The Community Messages module, for example, only appears on Special:WikiActivity. Other than that though, it basically just devolves to sorting an array, saving to localStorage, and some annoying UI work.
I'm kind of hoping to have these 2 features in play before I start writing other modules. I'll be hopefully pushing an update later today that fixes some bugs with the Friend's List module, tweaks the CSS a bit (I've added a stylesheet), and introduces the show/hide sidebar feature.
That being said, if this voting thing interests you a lot more than it does me, I certainly have no problem with you joining and writing that module yourself -- I just have to admit it's not an immediate priority for me. But I will keep this in mind!
Maybe that wasn't clear, but my last post was a reply to your earlier question how you could determine a user's online status. Because it's seems that the voting system with its timestamped pings could be used/abused for just that.
Hmmm, slightly more interested. Although, this would only work for detecting other people that are using my script (use the script to automatically have them vote in the background). I'd like to first consider methods that would detect everybody -- i.e. chat entry point and last entry on Special:Contributions
I haven't. I'm not particularly interested in chat -- that just seems like the easiest way to determine someone's online status. I'm not about to pour a bunch of time into coding this feature just yet. I was merely gathering ideas.
Update: The latest version of Railgun is now available, if you're interested. I've created a wiki for the project at w:c:railgunscript which I'll be working on, the code is now stored there.
New feature: show and hide the siderail by clicking the arrow in your toolbar.
Tweaks:
Friend's List module html updated.
Stylesheet created.
No longer runs on the Wikimarks wiki
Some backend changes to help development going forward, but that won't really affect the end-user experience
There are 2 versions of Railgun with completely separate code bases: the normal version, and the debug version. The debug version has anti-caching built in (you will get non-cached versions of the server.js and the stylesheet.css), and it also will print out some messages to the console for testing purposes. Otherwise, the debug version and the normal version are the same.
The previous version of the script was entirely on my testing wiki -- so any data saved to localStorage was for the mathmagician.wikia.com domain. But now it's a different domain, so any saved data from localStorage did not carry over.
About the menu color, is it too bright? I do like blue, and it seems fine to me...
Hmmm, this is interesting. So I finally got JSDoc-Toolkit to work (it helps when you use the current command line options, not the deprecated ones XD), and I love the documentation -- but 1) I'd have to rewrite some comments (mostly copy/paste work) and
2) ... how the heck am I supposed to make the documentation available on the wiki? As you can see here, it isn't pretty if you copy/paste the HTML and verbatim it.. any ideas?
Hmmm alright I'll tinker around with it a little and let you know if I can get the CSS sort of working. I have a bad feeling about this, but the documentation is so nice to have imo that it's too good of an opportunity to pass up. I will re-write all of my existing code if necessary to fit the documentation pattern.
Hmmm.. I'm thinking now that I'll instead not try to force the documentation onto the wiki. It's just not meant to be. Yes, I have mostly isolated the CSS. But every single link is broken. And all of that fixes stuff would need to be hard coded every single time the documentation got updated.
I'll just zip the documentation folder and throw it up on http://www.mediafire.com/ and then link to the download. Much easier.
From what I've seen, it should be possible to write a script that modifies the doc output to play nice with wikitext. Those kinds of things need to be tried to find out if they're do-able. It's far too early to give up already. That mediafire solution may be easier for the moment, but it will cause us no end of hassle in the long run.
What kind of system do you run btw? Do you have access to PHP?
I don't think I have access to PHP, but I wouldn't know, I've never used PHP before. I run Windows 7 on a PC.
At least for now, I'm going to focus on re-writing my code / comments so that they work with JSDoc-toolkit. Part of it may just be me needing to play around with the tags, but from what I've seen, I get the feeling that my object literal style is hard for JSDoc-toolkit to document. I need to learn more about this and figure out what to do with to actually create the good documentation.
Once I've actually got some real documentation, I'll upload it or email it to you (so that you have a copy) and then we can try and get it onto the wiki. Just let me physically get the documentation first =)
I'm also going to try to use this instead of the default documentation templates.
If this is successful, we could also consider adapting it for ThreadTools and/or Wikimarks. Big projects like these can benefit from good documentation I feel.
Yep, you'll get all of my documentation as well as the doc-commented source code when it's completed. I'm mostly done commenting the server code, but I still have to comment the client code.
Do you need help setting up jsdoc-toolkit? The instructions here explain all of the command line options -- if you're a command line guru, that's probably all you need to know. If not, I can walk you through the process on Windows at least since I just did it.
Oh and, glad you discovered the arrow =). It's a small but important feature of Railgun. Makes reading certain pages much easier.
The arrow is quite possibly the coolest feature. At least right now. :P
One little thing though: It seems to point in the wrong direction. Right now I have the content area maximized - I'm really getting used to that :) - but the arrow points outward instead of inward.
As for jsdoc-toolkit: I don't think finding out if we can make this look good on a wikia page is something we should postpone. I'd very much prefer to test that right now. Getting the CSS should be easy, unwrapping the content should be easy as well. Maybe I'm overly optimistic (and if so I'd rather find out today) but I believe I can write a script that reformats everything automatically. There are also a few goodies I wrote earlier that may come in handy now. I have e.g. a PHP class that generates wikitext tables... or a class that can upload files to Wikia... stuff like that. What I don't have is a docCommented JS file or two I can test my code with. So I was hoping you could supply me with what you got. It does not need to be finished or perfect, mind you!
BTW: Are you familiar with my InfoWidgets? They would be perfect for the siderail. You can use them to display each and every bit of information that can be retrieved via the API. The concept could easily be expanded upon by adding interactive elements. Imagine having small versions of all Special pages, that can be loaded into the siderail. You could e.g. review all external links and find the broken ones, get a list of the last editors, revert the edit with all the broken links and send the person whose edit you just undid a message that explains what you did and why. All from the siderail and all without leaving the page in question...
Can you give me your email address and I'll send the folder to you? There's 2 folders -- 1 for jsdoc's default style templates and 1 for the codeview templates (which I prefer).
Also what file format do you want. .zip okay? I do have 7-zip so I can probably compress it differently if needed.
Also about info widgets -- I'm not familiar with it, but the possibilities you're describing do sound exactly in line with one of the directions I want to take this project -- I'm considering writing a toolbox module with 1-click delete buttons, etc. I'll have to look into this, because the toolbox module was the next thing I had planned.
Edit: About the arrow, it's designed to represent the current state of the content area and siderail, not what will happen when you click it.
I think buttons should show what will happen when you click on them. Adding state information to a button is a delicate business. It's usuallly best to avoid it. In this case it's unnecessary too. I don't need to look at the button to know whether the siderail is collapsed or not. That's perfectly obvious.
Personally I'd recommend to think of your Railgun as a framework and the modules as exchangeable plugins. You've already set up a wiki, so you already have the perfect spot to house an entire zoo of plugins by many different coders.
I see two problems: The fonts - I don't know how or if at all I can upload them to Wikia.
But more importantly: The menu on the left. In your demo it's almost empty, but I imagine it can become very long when you keep adding classes and files...
I think that the guy who wrote codeview forgot that months are zero-based, because the data says "Generated on: 2012-5-19 10:26"
As for the arrows, alright, I'll switch them.
As for the plugin concept -- I like it, but unfortunately, my code is currently not written in a manner that would be friendly towards it.
Basic overview of my code:
1) The RailgunServer.js has a single event handler processRequest(event) for messages. The event handler looks at event.data.instruction, and if it recognizes the instruction, then it delegates the task to another server method and posts the server's response back to the client. But if the server doesn't have code to process the request, it does nothing. I.e. the server must be set up to handle a given instruction -- so if a plugin needed to save to localStorage, the RailgunServer.js would need to be updated.
2) Inside RailgunClient.js, there is a Railgun.Storage namespace. This is a conglomerate namespace which contains all methods that issue requests to the server. The idea is to isolate all communications with the server. An individual plugin or module does not issue requests to the server -- it calls a method within the Storage module to issue a request to the server -- so every new plugin that needs to save to localStorage would require updating the Storage namespace.
3) Inside RailgunClient.js file, each individual module only contains code for handling DOM related stuff (initialization, module states) -- all styling is handled by the RailgunStylesheet.css and any communications with the server must go through the Railgun.Storage namespace.
Create an variable thats []; aka an empty array, and create a function that simply uses the js function push to integrate the new module into the code.
That doesn't solve the structuring issue with my code. The structuring issue is this:
Suppose someone writes a new module and they need to save data to localStorage. Not only do they need to write their module, but they ALSO need update the Storage namespace AND the server code.
What I need to do to support plugins would be to restructure the code so that they JUST need to write a module. I.e. something like the following.
1) Modules need to be able to issue requests to the server without going through the Storage namespace.
2) Modules need to pass a function to the server which the server simply executes without question -- that way the server.js doesn't need to be updated to accomodate a new type of storage request.
3) The server needs to send the entire contents of localStorage to the client upon pageload. (Well, currently it does this, but in a hard coded fashion. It needs to instead loop through every thing localStorage and just send everything.)
Oooh, I just a brilliant idea for how to restructure my server code to accept generic requests to store or retrieve various data types. In other words, rather than thinking about what event the server is reacting to, I'm now thinking about what data types need to be stored or retrieved.
@Pecoes -- because of this realization, I'm going to start on restructuring my server code. In the client, I'm also going to partially nuke my Storage namespace. The result will be a more logical server structure, as well as client support for plugins. However, this means I'm going to put documentation on hold. If I'm going to restructure my code, now (before there's too much) is the best time to do it.
I've completed refactoring the code and just released the new version.
What's new:
switched the left/right arrows
new code structuring is more plugin friendly
JSDoc comments for everything
Complete documentation + source code available here for download.
If you experience any caching related issues while using the script, please purge the source code for the debug version, or import the stable release instead of the debug one:
Hopefully the documentation helps you somehow find a way to put the template docs on a wiki... it would be cool if it were possible, but I've kinda given up on that at least for now.
So is Railgun at a stage now where the API is relatively stable and you could say to a prospective module developer such as myself: Here's the interface, hack away!
If the answer is not "yes", then it's "almost certainly but maybe not quite yes". Give me a day to layout the interface on the railgunscript wiki and reanalyze a couple things. You can help me by answering whether you prefer scenario (1) or scenario (2) below:
There are two big issues related to how Railgun connects with a module, but these issues do not affect how the source code of a module is written.
Issue A) where the source code is located -- (1) should a module be an individual .js file, or (2) should every module's source code be integrated into the same RailgunClient.js file? Railgun is currently not designed for scenario (1), but it shouldn't be too hard to do so if needed... I think...
Issue B) how modules are initialized -- each module needs to have an init() method, plain and simple. But Railgun's initialization sequence is not in its final state yet. It will need to be optimized/customized for performance so that modules users don't want aren't loaded.
A) As a developer I would hate it if I had to embed my code into larger project. I'd rather work on it independently and have my own page. But as a user I would hate it if my browser would load 100 js files of 1KB each. I could probably brew and drink a cup of coffee while the page loads.
You might be able to reconcile these two expectations it you transclude the js files into the main project as if they were templates
B) Not sure if you will find this useful, but I wrote a little bit of code two days ago that I call - for lack of a better word - a Sequencer. The Sequencer has two methods: onload() + loaded():
loaded() is supposed to be called by every module when it is ready to supply other modules with its functionality. The one parameter to loaded() is the module's name.
onload() can be called by any number of modules to execute code that is dependent on another module. onload() has two parameters: the targeted module's name and a callback function that will be executed when the target module calls loaded().
The important thing is that the Sequencer memorizes the loaded() calls. When an onload() is registered after the loaded() was already called, the callback will simply be executed immediately.
Clarification, in case I haven't made this clear enough yet: "module" in the context of Railgun refers to an object in the Railgun namespace which defines states and behaviors associated with a single <section></section> element on the Wikia Rail. "Module" does not refer to the modular programming pattern (e.g. used by Wikimarks) in the context of Railgun.
A) ... transclude the js files into the main project as if they were templates -- you lost me here, what does it mean to "transclude a js file?"
One thing I can guarentee is that it will be fully possible to write a module, say 'myMod', in a separate file from the main script, and then run 'myMod' from the console after Railgun has loaded. So, at least for development purposes, it's possible for the script to be separate.
B) The sequencer sounds nice, but it doesn't seem in line with Railgun's philosophies.
Fact 1: Railgun modules do not depend on one another, every module must be standalone. Module X is not allowed to pass information to Module Y because Module X doesn't know if Module Y even exists.
Fact 2: Modules do not have any control over when they are loaded or in what order they are loaded. A module is not allowed to load itself or any other module. A module simply must provide an init() method (basically, a constructor) that Railgun will call when and if it feels like it. Railgun has absolute central control over the module loading sequence.
Hey, I've started a page at w:c:railgunscript:Developing a Module which will be the central How-To page for developing a module. I'm going to create a bunch of smaller pages describing each individual concept and a navigation template that links between all of these "development" pages.
But in case you were more immediately interested, that page now contains the basic necessary information I think.
Edit: By the way, how can I get syntax highlighting for the sections of code on that page? E.g. like how there's syntax highlighting at ThreadTools.js
Pecoes, can I check out the sequencer? Math, your SDKs and APIs are good, but give me a week or two (I'm on vacation) and I can make some serious improvements.
@Math: That's very nice. I'll think of something to contribute! Is there also some kind of framework in terms of a user interface? What I mean is: Is there a way to switch between modules, to activate or deactivate them? Should I make an icon for my modules? Stuff like that...
@Kangaroo:
I've written it for FindReplace, but here's a stand-alone version. It's short and simple because jQuery's $.Callback supports this kind of functionality out of the box (if you set the memory- and unique-flags):
The What various moving pieces are involved? tells me stuff I don't really need know to write a module. It should be at the end of the article - not at the beginning.
Storage is nice, but it's not on my A-list of functions I'd expect from a siderail framework. How about a "spawnModule" function (with an optional "height" parameter) that spawns a div in the siderail with the correct classes at the correct point in the DOM etc. and returns a jQuery obect?
EDIT: Or a "close" function that removes the module? Or a "back" function that takes the user back from the module to whatever interface you will provide for switching modules?
Pecoes: The "framework" you're talking about is actually the next piece I've been planning. I call it the "Module Manager" -- and it will allow for at least 2 things:
There will be a way for a user to activate/deactivate individual modules.
Users will be able to sort Railgun modules in whichever order they want.
For #2, the caveat is that it won't be possible to sort the default Wikia modules such as Recent Wiki Activity or Chat -- I would very much like to be able to do that, but I've looked into it and it's just not feasible. Instead, users will have a choice to put ALL Railgun modules either above or below the default Wikia modules, but no mixing the two.
I'm about done with the preplanning and I should be writing code for that soon, so expect to see it sometime next week.
Also, the tutorial on the wiki remains a work in progress -- but I feel very confident in the API at this point. Modules won't need icons -- all the Module Manager will need to know is 1) the name of the object, and 2) the CSS class of the section tag. I'll put that "framework" info on the wiki once I've got the Module Manager done.
I'll consider some of those functions you mentioned. I think I won't know if they're needed until I've actually written some more code.
However, a module would not make use of such functions. Modules are not allowed to insert themselves into or remove themselves from the DOM. -- Railgun must have centralized control over managing all modules, it cannot allow a single module to go rogue and insert itself. For that reason, I'm hesitant to add more more public methods. I don't want modules doing things they shouldn't be doing.
All a module is supposed to do is 1) generate its own HTML, 2) manage its various states, 3) save/load information from storage by using the API
That being said, I can certainly provide insert or remove methods for testing purposes only.
That's intended behavior. Links to your own userpages are perhaps the most important ones you could ask for! If you don't want to friend yourself, nobody is forcing you to do so. But it's a convenient feature, so I'm not so fast to remove it.
I really see that module as being wider in scope than the name. For example, an admin could add an IP to their friend's list so that they remember to check in on them later to see if they've stopped vandalizing.
"User List" or a more generic name really would be more appropriate. But "Friend's List" stuck when I was coming up with it, so there you have it.
Math, there should be a easier way to write modules. You should allow only a few subroutines- name, init, version, onload, and the GUI framework. Then. The function to call the module should also be wrapped in an unnamed function so it's impossible for modules toninteractnwith one another. Our code isood, but can you let me join as a Dev? This is one of the most investing code projectsnive heard of in a while, and is right up my alley (code-speak)
Sure, I don't mind if you wanted to join to write a module. But I need more time to get things in place first -- I'm still doing some minor refactoring, but more importantly, adding an essential new feature. And then I need to invest some time to look into this script that Pecoes has been doing for the JSDoc documentation. Please give me at least another week. I'll get back to you when I feel ready to move forward with writing modules.
For now, I'm going to have to say no. The most important thing to me is that the framework be 1) well-documented with JSDoc and 2) written in a uniform style. Having more than one person work on the API is contrary to that goal, so I would like to retain sole authorship of that major portion of the code.
By contrast, per Pecoes suggestions, I've been trying to make it so that modules can be written more free-style.
What I'm saying though is that th should also be a way to have an easy way for beginners to write it and that would mean that the API would have to do significantly more work that it does lalready. And what's up the keys? You realize I could use the push method to make my own to the variable if it's meant to be a precaution? It also kinda stops devs writing modules without your consent for their personal use, something quite annoying.
Yes, I realized that. The keys needing to be recognized is being removed in the next update.
However, it doesn't change the fact that my script is stored in the MediaWiki namespace, which not just anybody can edit. Devs writing modules do need my consent to add them into my script.
It's not supposed to be a complicated thing though. If someone wants to work on the project, I give them admin access to the wiki. Simple as that.
I moved all that CSS into a stylesheet where it belongs. The Stylesheet module is a loader for the CSS file now.
EDIT: And a third thing: I'm starting to like the HTML code in the ThreadTools.js source. It's actually useful that you can link to modules indivdually. I've just modified the HTML bits, so that "edit section" links appear now as well. Because why edit the entire codebase, when you only want to fix a particular module?
EVEN MORE EDIT: And a fourth thing... This is a link to an article about arrays in JavaScript I wanted to give you for days but always forgot. It's quite short, but I'd say it's a must-read.
And while I'm at it: Would you be interested in this?
Looks good so far -- my only concern is that the width of the quoted post is significantly less than the width of the original. Might want to tweak the CSS so that the quoted text isn't so squished.
Alright, I've looked through the stylesheet module and it makes sense to me. I'm curious why you added the code to determine the background color. Why does ThreadTools need to know if the background color is light or dark -- where exactly does that come into play?
Wait so -- the reason my edit section links were globally missing on every page on every wiki was because of ThreadTools? I didn't realize that... been thinking this whole time it was a bug on Wikia's end.
I actually had come to that realization after last time we talked about Arrays -- but thanks for the link =)
This is certainly interesting enough that it warrants a try. Also, it seems very similar to JavaDoc comments, so if that's the case I'll feel very much at home. The template here certainly looks nice.
2.) That background color thing is actually for the quotes. I made two versions: a black and a white one.
3.) I don't know about that. There are two reasons why they didn't work in ThreadTools.js. There was an __NOEDITSECTION__ near the top. And I used <h2> tags instead of wiki-style ==headlines==
4.) Good :)
5.) This one has lots of goodies JavaDoc does not have - like @augments or @function or @namespace etc.
Random question: Javascript is interpreted by whatever browser one is using, right? Say for example I'm using Chrome, and I wish to know how Array.sort() is implemented (I'm curious if it's a quicksort, merge sort, etc. and whether or not it's stable) -- do you know if google provides this kind of information, like the specifics of how the browser interprets Javascript?
3. It's not ThreadTools. My section edit links are missing globally on every page that has <h2> tags (==Header==). In fact it's not anything in my global.js or global.css so far as I can tell. I'm going back to my assumption that it's a Wikia bug.
And yes, the mini editor is horrendous with some of those tags. It eats my <pre> and <nowiki> tags on just about every other occasion.
I'm starting to wonder whether I've made the Wikimarks too complicated. The initial idea was to use regular wikitext because that's what people are familiar with (or should be). Now I'm starting to think that a little bit of custom syntax might make things easier - for noobs as well as for pros. So without further ado, here's the idea:
depth title = link
"depth" is the menu level, so it's either "1", "2" or "3"
"title" is what shows up in the menu
"link" is a wikilink or URL
Here are some examples of relative links:
1 Wiki Activity = Special:WikiActivity
2 Wiki Activity = /wiki/Special:WikiActivity
2 Wiki Activity = /index.php?title=Special:WikiActivity
Note that it's irrelevant, whether you use a wikilink or a URL
Some absolute links:
1 Wiki Activity = w:c:example:Special:WikiActivity
2 Wiki Activity = http://example.wikia.com/index.php?title=Special:WikiActivity
1 Wiki Activity = http://example.wikia.com/wiki/Special:WikiActivity
Again: It's irrelevant what link notation you use
Those were the basics, let's move on to the advanced stuff:
And of course you're not confined to these two JavaScript functions! You can use ANY JavaScript code you like. But you're only allowed to leave out the "javascript:" part, when you use url() or win()
So, what do you think? Personally I think this would be easy to use and easy to learn. It IS however one extra thing one has to memorize.
Hmmm, I'd say go for that simplified syntax if you want. Anyone who knows how to make a link in wiki markup will also be smart enough to learn level title = link. And this format has the advantage of making javascript urls much more simple.
(Also, there was a flaw in the "wiki markup links for Wikimarks is best" argument to begin with. MediaWiki:Wiki-navigation doesn't use the exact same syntax for creating links -- e.g. missing [[ ]]. And then there's the fancy shortcuts for displaying all pages in a category, etc.)
Wikitext is tried and true. Users already are familiar with it and they don't have to learn new things. Plus, wikitext is easier to parse... I think there's an API param for it.
It's not exactly wikitext, is it? If it were wikitext, you could e.g. make the menu titles bold or cursive etc. But you cannot, because the wikitext parser doesn't touch the Wikim*rks. I've written my own parser and it intentionally ignores lots of wikitext markup. And what little I've left of wikitext, I've already modified. There are no local URLs or javascript: URLs in normal wikitext e.g. Yet there are in the Wikim*rks.
Maybe I've already deviated so far from regular wikitext, that deviating a little more would make things a lot clearer... That and the fact that this modified syntax throws a lot of dead weight - like those gazillions of square brackets - overboard.
Forget about the numbers, though. I think I like this better:
* title = link
** title = link
*** title = link
When you use numbers people's first reaction is: "Why only 3? I can count to a lot more than that, sir!" The number of asterisks people are willing to type is reached much more quickly. Besides: When you look at other people's Wikim*rks they'll be rendered in a slightly more meaningful way...
Forget about other people's opinions -- go with what you think will work =). If they don't like it, I'm sure you'll hear about it later. (What I mean to say is, you can only take syntactical theorycrafting so far...)
@Kangaroo: Actually it's "*link|title" in the Wiki-nav - not "*title|link". I do not want that. It should be possible to create a link-less menu entry.
This looks clean to me:
** title =
You'll see that in templates all the time.
This looks messy:
** | title
And I'm not sure I want to allow title-less links. I would have to show the URL in the menu instead and that's practically guaranteed to be too wide.
Looks like I arrived a little late to the party ;) Nonetheless, I'd be inclined to go for the
* title = link
** title = link
*** title = link
style of syntax, although I'm not sure how that affects the current way functions are used, or things like [?action=history]. If you're confident it's a simple thing to get your head around, then I'd go for it.
On the other hand wiki markup of links is one of the fundamental parts of editing every user will know. If this is going to be accessible to as many people as possible, it's best to keep things familiar. As long as this new method keeps things simple for the more... 'complex' links, there shouldn't be any major problems.
That's it. That's all you have to learn/remember, really. The history link would look like this now:
** History = ?action=history
Apart from all the brackets I'm also eliminating the distinction between wikilinks and regular URLs. Feel free to use whatever you like or whatever works best...
EDIT: Oh, about functions... That "Function" pseudo-namespace would be eliminated as well. But you can use regular javascript: URLs instead.
Alright. The syntax has been changed. The info-page is completely outdated now, but everything I wrote in my first post, works now exactly like that (except for the level thing - I went back to the asterisks).
I also took the liberty of converting your Wikim*rks to the new syntax.
Aaaaand there are few other interface changes.... You'll see ;)
And I have to admit I'm cheating a little. I've added all kinds of shortcuts into the code to make sure I would get to see the uncached versions of everything. Your version will update a lot slower. It will probably load a lot faster, though ;)
The manual is updated to the new syntax. I also tried to update the main page but I mostly removed stuff. All that intro text is gone now. Instead it's a bit of a showcase for the Wikim*rks . Not a great showcase, but better than none. As an answer to the question: What are Wikim*rks? it's probably good enough.
Just FYI: Your Railgun displaces the URL preview bar on the right. It's supposed to be directly under the selected menu entry, but the Railgun pushes the submenu preview down and that does mysterious things to the offset. I need to fix that...
Are you talking about what it looks like here: w:c:wikimarks:User:Mathmagician/Wikimarks? I noticed that earlier. I think I'm just going to make the script not run on the wikimarks wiki for compatability -- short term fix.
Edit: Currently, Railgun is coded to prepend new modules into the siderail, so yes, it will push everything else down (except the search form).
@Pecoes that is neither your nor Math's job to fix but rather the job of the end-user. If one of you does have to fix it though, it would be easier for math, as she just run a if then to hide the module on the wikkimarkks editor page
@Kangaroo: No, I do think, I should fix it. You see: There's no logical reason why the submenu preview getting pushed down should push the URL preview almost off-screen. The two should stay in synch regardless of Math' addition. If they do not, then there was something broken to begin with and Math' addition only makes the bug obvious.
That's basically what I'm going to do. It's no problem at all, as I also need to set up ifs so that it doesn't run if skin !== "oasis" or if 0 === $('.WikiaRail').length, so might as well fix that while I'm at it.
I picked one of my favorite anime characters as an avatar, but I'm male. I suppose that can be a bit misleading, but my profile does have a link to my facebook on it which clarifies =P
Well, now you have =P. That show and its currently airing prequel, Fate/zero, sit together at the #3 spot on my top 15 list, out of the 200 or so anime I've seen. It's one of my bigger hobbies, you could say.
I've made the first sketches for my Updater. I will test it with Wikimarks first, but it's supposed to work just as well for ThreadTools. The idea is to "make" the project with a single command.
Minify the JS and CSS files
Add comment header and footer to the minified files
insert headers and a table of contents into the regular JS (like I did just now (by hand))
add version info to the headers of all files
add revision commentary to all files
upload the lot to Wikia
What kind of system do you have? (My guess would be a Mac :) Java is a given it seems, but what about PHP? Is that available on your machine?
What about the changes to ThreadTools.js? Do you like them? I'm having second thoughts. The web presentation looks nicer now, but in my IDE it looks rather ugly. The latter is what counts more, isn't it?
Why Minify? For wikimedia, yes it makes sense, since they support all browsers except those before IE4 i believe. All Wikia Supported Browsers though are more than capable of parsing javascript. If you really insist on doing this, I can give you an already made script which I can modify some to fit your needs
Minifying means throwing out comments and whitespace and replacing names of functions and variables with single letters. The point is to reduce filesize and thus download speed. Anything above a thousand lines of code - and with a lot of comments :) - can profit greatly from minifying. jQuery.min.js e.g. is 50% smaller than jQuery.js.
I'm concerned about the fact that removing all whitespace and comments would obfuscate the code, which is something I'm against. I'm fine with minifying for efficiency purposes during release -- so long as the readable version remains publically available as well, both so that we it can be worked upon easily and so that others can easily and freely read the code if they wish to determine its nature.
As far as your change to ThreadTools.js, I do like the presentation, but at the same time, it's important to me how it looks in my IDE. Using h2 tags etc. makes the presentation look good on the wiki, but it doesn't help in the IDE.
I think that good comment headers solve the code readability issue both in IDE and on the wiki, and so that's the solution I would like to aim for.
Edit: By the way, I run Windows 7 on an HP laptop, and I don't really like macs =P. I'm not sure if I have PHP available. I don't know the second thing about PHP (the first thing, I think, is that it's supposed to be a server-side scripting language used in web development)
Obfuscation increases the compression rate significantly. There's nothing wrong with obfuscation as long as you add a link to the non-obfuscated code. I was planning to do that. That was point 2 actually:
2.) Add comment header and footer to the minified files
That was a bit elliptical. I'll try again: Add a comment header with the project name + a link to the project page + a link to the non-compressed code + copyright notice and then wrap the whole thing in <source> tags
Whoa. I'm shocked! That's 75% comment and 25% code! Are you serious about that?
EDIT: Feel free to remove the HTML tags again, btw!
Alright, I'm happy with minifying as long as there's a link to the readable version =)
And no, the code to comment ratio isn't typically like that. I just haven't written most of the code yet. I've thought up some of the objects I want and how they should interact, drawn a few diagrams on paper, and then put up comment headers ... most of the code isn't written yet. (This is more of an up-front, object-oriented, top-down sort of design.)
But yes, if the ratio actually ended up being 1 line of code for every 3 lines of comments or something like that, I wouldn't mind. Comments are collapsible in pretty much every IDE I've used, so if they're in the way, that's the solution.
The important thing is to make the code make sense to anyone who might want to edit it. (Remember, for all we know, someone new might want to join the project or help maintain it later.)
To me, first and foremost, that means I need to know what objects and functions are meant to do, the properties and methods an object has, and I need to know what parameters a function needs and what that function returns. That's just because I'm an object-oriented thinker. To me, an event handler is merely a function (or something that happens inside of a function).
Of course, if I myself am never going to be using certain functions, objects, modules etc., I don't need to know the specifics, so long as they work and I can guess what they do.
I know you prefer Chrome to Firefox, but today I found a truly awesome plugin for Firebug called Acebug that makes Firefox a serious contender. Check it out! I can't believe I only just now found this. How did I ever get anything done without it? :)
Installed. Very nice, I love the syntax highlighting. I also like how it has a "use spaces instead of tabs" option and allows you to set the tab width. Normally I work with tabs -- but that's extremely inconvenient on MediaWiki pages where the tab width is 8.
If only it had drop down suggestions! That's the #1 reason I love Chrome's console. (e.g. I can type "wg" in the console for this page and a drop menu listing variables such as wgPageName and wgServer will pop up.) Also, the fact that pressing ENTER runs code in Chrome's console -- very convenient for testing, when I just want to copy/paste/run
But, I will definitely be getting more out of Firebug now -- it's just that it has to compete with my pre-existing affinity for Chrome and IDEs. Although, I'm not a huge fan of Eclipse (but I've been using JSDT for Eclipse). I'm one of those weird people who prefer Netbeans.
The weird thing is: When you collapse the input to a single line, it does have autocomplete and it works very well too. But the multiline-field doesn't have that feature. That's really a shame.
Nice as Acebug is, it's certainly no replacement for an IDE of course.
Hey, while I'm at it... These two are also absolute must-haves:
I went to http://robertnyman.com/firefinder/ and watched the demo video. Went to https://www.google.com/, pressed CTRL + SHIFT + V to bring up Firefinder (can also just go to the Firefinder tab in Firebug). Typed in "p a" and "/html/body" into Firefinder just like he did in the video. Pressed the Filter button and absolutely nothing happened. No matter what I type in, clicking the Filter button does absolutely nothing, I can't get any results for anything on any webpage anywhere >_>
