Getting started with Surf

[bandy]

Hi,

We are very keen to use the Surf framework within Alfresco Community, but are having troubles finding definitive information on where to start.

I have read the posts about its current status, could anyone direct me to either the internal documentation or to existing and current documentation on how to get started?

Thanks for your help.

[ddraper]

Hi,

The Surf development documentation does need updating. There is some old documentation at the following locations:
http://wiki.alfresco.com/wiki/Spring_Surf
http://docs.alfresco.com/4.0/index.jsp (search for "Surf" and you'll get lots of results).

I'm aware that the documentation linked might not satisfy your requirements and if you do have specific questions then please ask them here and I (or one of the other community members) will try to answer them. If you could provide some information on what your objectives are then I might be able to suggest some further reading - for example, are you planning on writing a standalone application? a new client for Alfresco? or customizations for Share?

I'd recommend that the best way to start with Surf is by defining new page and template configuration files along with a basic FreeMarker template which you can add to the exploded Share application (so that you avoid needing to do any of your own Surf setup or bootstrapping) and then start investigating binding in WebScript components and experimenting with the various APIs available to you.

As I said, please ask as many questions here as necessary - the more specific the better of course!

Regards,
Dave

[bandy]

Hi Dave,

Thanks for the quick response.

We have found those resources, but part of the trouble we are having is knowing which ones are current and will work - preferably before we spend too much time trying to make it work

Some advice on the correct direction would be fantastic, thanks.

We are interested in building a front end for Afresco Community that will provide a more limited interface for our client.   They will still need much of the existing functionality, but with some specific document management workflows in mind, and some niceties like smart folders based on the document tags and some other things.


It appears as if the best approach may be to use the Surf Spring framework to build a set of new pages, but I and a couple of other developers are now fussing around trying to find a good place to start.

One of the other issues we are having is getting Alfreso Community up and running on AWS - we have found http://blogs.alfresco.com/wp/wabson/alfresco-ec2-images/#comment-4563 which is great, but now that we have an instance up and running it appears not to be accepting connections.

I have also tried using the Linux Quick Install process on a new AWS instance, but unfortunately that appears to trip over at the end when it attempts to create some short cuts.

Alfresco is clearly a fantastic solution, but just trying to get started is proving a challenge

EDIT:  The basic quick installer appears to go well on AWS until near the end where we get a series of:

Please wait while Setup installs Alfresco Community on your computer.

Installing
0% ______________ 50% ______________ 100%
####################################Unable to create symbolic link /opt/alfresco-4.0.d/second/openoffice/basis-link -> basis3.2
Abort, Retry, Ignore ? [A/r/i]R

Unable to create symbolic link /opt/alfresco-4.0.d/second/openoffice/basis-link -> basis3.2
Abort, Retry, Ignore ? [A/r/i]

<snip>

Unable to create symbolic link /opt/alfresco-4.0.d/second/common/lib/libMagick++.so.2 -> libMagick++.so.2.0.0
Abort, Retry, Ignore ? [A/r/i]i

Unable to create symbolic link /opt/alfresco-4.0.d/second/common/lib/libMagickCore.so -> libMagickCore.so.2.0.0
Abort, Retry, Ignore ? [A/r/i]i

Unable to create symbolic link /opt/alfresco-4.0.d/second/common/lib/libMagickCore.so.2 -> libMagickCore.so.2.0.0
Abort, Retry, Ignore ? [A/r/i]i

iWarning: Problem running post-install step. Installation may not complete
correctly
Error creating dynamic link  ja_JP.eucJP /opt/alfresco-4.0.d/second/java/man/ja
Press [Enter] to continue :
Warning: Problem running post-install step. Installation may not complete
correctly
Error creating dynamic link  ja_JP.eucJP /opt/alfresco-4.0.d/second/java/man/ja
Press [Enter] to continue :
Warning: Problem running post-install step. Installation may not complete
correctly
Unknown error while running su postgres -c
'"/opt/alfresco-4.0.d/second/postgresql/bin/pg_ctl" start'
Press [Enter] to continue :

Error: Unknown error while running /opt/alfresco-4.0.d/second/alfresco.sh start
apache & > /dev/null
Press [Enter] to continue :
Warning: Problem running post-install step. Installation may not complete
correctly
Unknown error while running /opt/alfresco-4.0.d/second/java/bin/java -jar
/opt/alfresco-4.0.d/second/bin/alfresco-mmt.jar install
/opt/alfresco-4.0.d/second/amps
/opt/alfresco-4.0.d/second/tomcat/webapps/alfresco.war -directory -nobackup
Press [Enter] to continue :

[ddraper]

Hopefully Will can contribute with respect to your AWS question (that's not something I know anything about unfortunately).

The basic principles of Surf and WebScript development haven't really changed although you should ignore anything you see relating to development tools such as Spring Roo or STS templates. To develop Surf applications you really just need editors for XML (for the config files), FreeMarker (for the templates, there's an Eclipse plugin available) and JavaScript (for the WebScript controllers).

As for getting started writing your own application then it might be worth taking a look at these two blog posts I wrote (http://blogs.alfresco.com/wp/ddraper/2011/11/01/advanced-share-customization-part-1/ & http://blogs.alfresco.com/wp/ddraper/2011/11/03/advanced-share-customization-part-2/) which describe how you can create your new application in a JAR and drop it into the Share lib so that you get all the benefits from Share (security, remote connections, up-to-date Surf libs, etc) without any of the setup overheads.

In terms of learning how to work with the Alfresco repository then a good way to learn is to use FireBug or Web Developer Tools to track the XHR requests that Share makes using the REST API. You can then cross reference these calls back to the list of Web Scripts (by URI) that you can find here: http://<share-server>:<-share-port>/share/page/index/uri/

Also, although Share has been implemented to use WebScript components it is not a necessity - you could just have a single FreeMarker template for each page.

I can't think of any other tips off the top of my head at the moment, but I'd be keen for you to post questions as you go so that we can identify people struggle with when getting started with Surf.

Regards,
Dave

[wabson]

Hi bandy,

Regarding you not being able to connect to your EC2 instance, I replied to the comment that you left on the blog post. Basically, you need to enable inbound TCP/IP connections for your instance, either on port 8080 (direct to Tomcat) or on port 80 (proxied to Tomcat via Apache httpd). The background to this is documented on the EC2 documentation, but there are also a number of other sources of information on the web that I found.

http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/using-network-security.html

If you've set this up and you still have connection problems, then it could mean there is a problem with the start-up of some of the services, but it seems unlikely to me that they would fail to start completely, and it's much more likely that it's a firewall problem.

Cheers,
Will