Best practice for external Javascript framework?

Hi folks,

I need to use an external Javascript framework (Dojo, and would like to try this in conjunction with Outsystems (I'm using the express edition at the moment).

How is this done ... are there best practices for something like this? I would love to integrate Dojo with the application rather than import it from a separate server.
Hi, Stefan. Welcome to our community!

OutSystems StyleGuide (available in the Academy) uses Prototype, along with Scriptaculous, which provides us most of the slick tricks for enabling Rich Web Applications.

Nevertheless, OutSystems platform is not restricted to any 1 Javascript framework. Just use what you prefer.

To use a specific JS framework, just paste its source code into the eSpace Javascript area, accessible through the eSpace properties (just double-click the main tree node in Service Studio).

This source code will be put into an external file, and each eSpace page will be linked to this external resource, through the required markup.

Find more about Adding Javascript in our Online Service Studio Help (also accessible through the search functionality of our community): 
(June 2012 update: this link is no longer available. Please refer to the latest version of the help file)
Hi Stefan,

Welcome to our community.

Since your first question is not a simple one, I'll have to address a complex answer. I'm sorry for that. Here it goes...

Gonçalo suggestion is usually the best way to add external javascript...

Unfortunately, it will not be appropriate for Dojo toolkit.

This has to do with the fact that this toolkit isn't just a bunch of JS files. They're stored within directories and subdirectories... which means that we need to maintain their tree structure when deploying our solution.

1st possible solution:
- Change each .js file to work within one single directory, instead of being organized within subdirs.
This not good at all. We're talking about several files and there could exist files with the same name but within different directories. Besides we would certainly introduce several errors and loose time debugging them.

2nd possible solution:
- Install the toolkit manually within the HTTP server and change our applications to point them.
This is still not quite good, although much better. OutSystems platform gives us the ability to 1-Click-Publish an entire application without having to worry about database scripts, files deployed, file versioning... and now I have to manually deploy files? Of course this a very normal task, but people already familiar with the OS platform know what I mean. Nevertheless this is the most simple solution.

3rd possible solution:
- We can build an extension Dojo.xif (using Integration Studio) and add the Dojo toolkit zipped file as a resource.
- Then we could build an application DojoDeployer.oml (using Service Studio), which will be executed with special credentials (it has to be a user with write privileges within the web server; don't use ASPNET), that will unzip the resource file from that extension and save its directories within the web server. This functionality would be available as a web service.
- Finally our main application XPTO.oml could call that web service from DojoDeployer within the application's setup procedure (bootstrap), and after that our application could be executed with nor problems since all dojo directories would have been copied to our application directory.

Hope it helps.

Feel free to discuss any point that could raise some doubt...

Duarte Gouveia

Thanks, Gonçalo and Duarte, for the prompt feedback!

Solution 2 works fine (found that one on my own already), but as you note it's kind of clunky given that everything else is neatly integrated ...

I'll try out solution 3 ... although it's more work, it's one-time work to set it up and then all my apps can profit :)

Cheers, and I'll surely be back with more questions :)

You have another option.

You can include the .js files in your eSpace as resources mantaining their original directory structure by using OmlResources. That way, when your eSpace is deployed, these files wil be copied to the running application directory with the same directory structure they were imported. For example, if you execute "OmlResources -o eSpace.oml -add dir\file.js", you can then reference the javascript file in your pages as "dir/file.js". To do the include you can add a <script> to your WebScreen using an unescaped expression, or better, in the Preparation of your WebScreen call the Action "AddJavaScriptTag" of the Extension HTTPRequestHandler. This way you'll have an include in the <head> section of the html.

Best Regards,
Gustavo Guerra

Aaaahhh ... THAT is what I've been looking for :) ... sounds very straightforward ... I'll give it a whirl right away.

(any particular reason why this option is only available via command line?)

Thanks a million, Gustavo!
I'm not familiar with the Dojo toolkit, but I've been alerted that it has 1138 files splitted in 233 folders. Taking in consideration that OmlResources doesn't support wildcards, maybe the other alternative will be better :)

Best Regards,
Gustavo Guerra
That's what I have python for :) ... let's see how the Outsystems resource handler scales with that amount of files *grins*.

- Stefan
Hi Stefan,

Just one more note...

If you're going to add, as resources (using python or other scripting language to automate the task), all these files (1138), you'll get a huge oml file (OutSystems eSpace file). This also means that, every time you want to publish a new version, you'll have to wait for the entire upload... which can impact the overall development time.

I suggest that you build a specific eSpace just for storing this Dojo toolkit. Then you could add actions to this eSpace, which would be 'public', that would return the needed information for other consumer applications. This way, you just have to publish once (or at least for every DOJO version...) this application. On the other hand (consumer app point of view), you would be having a nice way to reference this toolkit without having to know too much Javascript (just references to DOJO.oml public actions... and some minor Javascript as well). Maintenance ('built-to-change') and development would most likely benefit from this... (my opinion, of course).

Best regards,

Duarte Gouveia
Thanks for the suggestion! This would also nicely decouple Dojo from the apps ...

The other day I had a similar problem, and chose the one suggested by OutSystems Engineering: including all Javascript framework files and directories in my eSpace through omlresources. This also enforced a more contained approach than having another reference (such as an extension) to deal with it. Also, resources that are included into an extension get their directory structure «flat», meaning they are simply ignored...

Nevertheless, I came across a problem which the omlresources does not cope with: it's not possible to add multiple files with just one command like using wildcards, for instance. You can't do something like omlresources -o MyeSpace.oml -a *.* or even add a recursive parameter to include a set of directories. So what do you do? Especially if you're not a scripting guru? :)

Just go to your command prompt, under your javascript framework root directory, and type:
  • dir /b /s > files.bat This will print a complete list of files and directories into a text file;
  • Open files.bat with your notepad;
  • Replace all absolute paths with a relative one, such as:
    • The string C:\Documents and settings\user\Desktop\scriptaculous\
    • with the string omlresources -o MyeSpace.oml -a .\scriptaculous\
  • Save your file and execute it from your command prompt.

Guess what this will do ;)

Have fun,
Pedro Gonçalves

i was trying to do this for CKEditor, but there is no omlresources.exe file in Service Studio 5.1 directory....

How can i do this?

Best Regards.

Diogo C S Cordeiro
Hi Diogo,

You can either import each file one by one (which should take a long time) or you can download service studio 4.2, create an eSpace only to import the files and follow the procedures above, and then you can merge that eSpace with the one you are working on.

Tiago Simões
Hmmm, and do you know if this is already in Engineering backlog?

Best Regards,

Diogo C S Cordeiro
In, you can use this command line to add a resource:
    ServiceStudio.exe -importResource espace.oml resource_filename [target path]

You can do a similar batch file to import the whole directory

Best Regards,
Gustavo Guerra
Hi Gustavo,

I tried to do something like this from the directory where the OML is and where the resources reside:

"C:\Program Files\OutSystems\Service Studio 5.1\ServiceStudio.exe" -importResource sencha.oml getting-started.html .\sencha
"C:\Program Files\OutSystems\Service Studio 5.1\ServiceStudio.exe" -importResource sencha.oml pkgs\core.js .\pkgs 

However no resources are added to the OML

Any suggestions ??
Hi Joop,

I alos faced that problem recently, but as it turns out, I did not have, but  a previous 5.1 version. Could that be the case?

An alternative - sadly, the one that I used - was to grab my Service Studio 4.2 installation, create a blank eSpace, and using a batch file and omlresources, I added 100+ resources to the eSpace.

The commands using omlresources were

OmlResources.exe -o TestResources.oml -a js\swfobject.js
OmlResources.exe -o TestResources.oml -a js\jquery\jquery.dropdown.js
OmlResources.exe -o TestResources.oml -a js\jquery\jquery.js
OmlResources.exe -o TestResources.oml -a js\mootools\mootools.dropdown.js
OmlResources.exe -o TestResources.oml -a js\scriptaculous\scriptaculous.dropdown.js

Then I upgraded it in 5.1, and all went well.

In your case, you may also have the alternative of adding the resources to an extension, and referencing them.

I hope this helps.


Paulo Tavares
Hi Paulo,

After all it worked out fine with 5.1 ...

Just go to your command prompt, under your javascript framework root directory, and type:
  • dir /b /s > files.bat This will print a complete list of files and directories into a text file;
  • Open files.bat with your notepad;
  • Change the names so it looks like this

"C:\Program Files\OutSystems\Service Studio 5.1\ServiceStudio.exe" -importResource espace.oml resource_filename [target_path]

It took some time to go over all the filenames and add the target path after the DIR command and the replace action mentioned earlier

Do you have a bat file example and where the place to put the oml file?

I tried and it executes but I cannot see the resource in service studio. any way to debug this?

Now you can simply do this with a right click on the Resources folder.

Understand, but I have to upload hundreds of documents, Is there a way to use a batch process to do it. I followed instrucctions and ran the bat file but after sucessful completion nothing was reflected in service studio. I tried reloading oml and nothing. also executed in same folder were I had a backup of the oml and tried to open it to see if any was reflected and nothing. Any idea?