osCommerce France : Accueil Forum Portail osCommerce France Réponses aux questions Foire aux contributions

Bienvenue invité ( Connexion | Inscription )

 
Reply to this topicStart new topic
> [preview]FoxP2 Projects - une documentation riche et dynamique, propulsée par Symfony 2.3.3 & look and feel Windows 8
FoxP2
posté 11 Aug 2013, 10:28
Message #1


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



Préambule :

Les méthodes de publication de documentation relative aux différents scripts osCommerce usitées par Harald Ponce De Leon me sidèrent.
La documentation est statique, codée en dur, à travers des fichiers langues (exemple : new intallation ) mélangeant allègrement le code html, les images, les liens externes ainsi que les extraits de code.
Le tout étant parsé par le moteur de template interne d'osCommerce 3.
A chaque modification de la documentation, il vous faut retrouver le bon fichier si vous avez ajouter / modifier /supprimer des informations relatives à la page.
Ce type d'architecture est juste un enfer pour la maintenance de la dite doc, mais également extrêmement chronophage pour sa création ainsi que pour la traduction.
Ne parlons même pas d'un moteur de recherche (somme toute, option plutôt basique pour retrouver la bonne information dans une documentation pléthorique) qui reste de l'ordre du fantasme puisque hdpl ne l'a même pas pris en compte au moment où il a structuré son site http://library.oscommerce.com/ , un comble !

Une autre vision :

Diamétralement en opposition avec lui, j'ai bâti un site web dynamique, en m'appuyant sur le framework php Symfony 2.3.3.

D'une part,
  • la documentation est stockée en base de données (à l'aide de l'orm Doctrine, gérant le mapping entre les objets de mon application ainsi que la mise en cache des requêtes)
Dans cette bdd sont persistées différentes informations (titre /sous titre / description / images) dans différentes tables usant des contraintes d'intégrités référentielles et tout le toutim ...
  • les différents codes sources sont chargés à partir du serveur Github.
Entre autre avantage, toute modification du code source publiée sur Github est automatiquement mise à jour dans la documentation

d'autre part, à travers plusieurs Bundles, j'ai enrichi la documentation et ajouter des options pour l'utilisateur.

Voyons ce que cela donne :

Chaque partie de la documentation est rangée par catégories, incluant des articles, eux mêmes incluant des articles fils.

Une page article s'affichera ainsi :


articlewizard par foxp2projects, sur Flickr

comme vous pouvez le voir, le code est mise en lumière (highlight) pour en faciliter sa lecture, mais en plus, le code source est enrichi en ajoutant les liens directs pour chaque fonctions natives vers la documentation officielle du langage (facilement identifiable avec une police de caractères surlignée de couleur orange ) :


external-link-documentation par foxp2projects, sur Flickr

l'exemple ci dessus montre que lors du clic sur la fonction native file_exists() une nouvelle fenêtre s'ouvre vers la documentation officielle de php

Les options pour l'utilisateur :

Lors d'un clic droit dans la fenêtre, une app bar apparait en bas de page, donnant différentes actions possibles :


app-bar par foxp2projects, sur Flickr

  • source : permet de télécharger tous les codes sources référencés dans l'article hébergés sur le serveur Github
  • code : permet d'accéder aux codes sources hébergés sur le serveur Github
  • pdf : permet de télécharger l'article au format pdf pour une lecture en mode déconnecté.
  • partager & commenter seront expliqués plus tard.

A propos des pdf :

Les pdf de chaque article sont créés à la volée (ibm dirait On-Demand).
Techniquement, j'ai ajouter le Bundle KnpSnappyBundle à mon application et installé le shell static wkhtmltopdf sur mon serveur.
Chaque pdf est mise en cache sur le serveur et ne sont recréés que si la base de données a été modifiée ou le(s) code(s) source(s) changés sur le serveur Github.

screenshot d'un pdf :


article-pdf par foxp2projects, sur Flickr


Vous pouvez télécharger directement le pdf
(notez au passage que l'ensemble des liens inclus dans les codes sources menant vers les documentations afférentes aux langages usités sont conservés)

Pour conclure :

en choisissant le framework ad hoc (en l’occurrence ici Symfony - et surtout pas osCommerce 3 qui est tout sauf un framework), on peut produire une documentation riche, dynamique, toujours à jour et cela en très peu de ligne de code.
Go to the top of the page
 
Gnidhal
posté 11 Aug 2013, 19:22
Message #2


5eme dan OSC
Icône de groupe

Groupe : Administrateur
Messages : 9221
Inscrit : 4-March 03
Lieu : Pau
Membre no 927



Nice job man !


--------------------
Tout d'abord : - Ni Hotline ni Service Après Vente, ces forums sont un lieu d'échange. BIEN POSER SA QUESTION (généralités)
Les "Informations Importantes" que vous devez ABSOLUMENT avoir lues :
Règlement, Bien poser sa question dans ces forums et Bien utiliser les Forums.
Les raccourcis pour gagner du temps : la FAQ, les PDF de la Doc (MS2-fr): PDF-V1 et PDF-V2, le moteur de Recherche sur les forums , la Liste des Contributions de Corbin.

----------------------------- Quelques sites de référence ---------------------------
PHP: Le site du Zéro et PHP Débutant avec la DOC en français -- HTML: Self HTML - WebProgrammation -- CSS: OpenWeb - AlsaCréations - CSS/Edge -- Autres ressources: - XajaX - highslide js
Les bons outils : EasyPHP - WAMP-5 - - Notepad++ - Firefox et son extension WebDeveloper
Le gène idéal c'est le gène original. Le génie des halles est un Génie des Alpages qui tente d'être à la page. (Merci f'murrr pour les cours de philosophie de chien)
Go to the top of the page
 
FoxP2
posté 12 Aug 2013, 07:56
Message #3


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



Ce dont vous avez toujours rêvez de faire avec osCommerce et que vous ne pourrez jamais faire :

Étendre Symfony grâce aux bundles :

si je devais faire une comparaison grossière, je dirais que les bundles sont les add-ons de Symfony. Mais la comparaison s'arrête là.
alors qu'il vous faut de plusieurs minutes à quelques heures, voir plusieurs jours lors de fulgurants télescopages entres différentes versions et interactions entres add-on à déboguer au sein du script osCommerce, Symfony lui fonctionne différemment et surtout intelligemment.

Gestion des dépendances.
Comme sur Linux, lorsque vous installez un bundle, une extension PHP nommé Composer se charge de vérifier si :
- le bundle est compatible avec votre version de symfony
- si le bundle dépend d'autres bundles (au quel cas, il les installe pour vous au sein de votre application)

Une installation en 2 lignes et 1 commande :

préambule indispensable :

Localement, j'ai ajouté les chemins d'accès aux programmes dans les variables système:
- git
- php
- composer


path par foxp2projects, sur Flickr


ce qui me permet d'utiliser le terminal Win (invite de commandes)

et maintenant, vous pouvez sortir les mouchoirs tellement vous allez pleurez devant tant de facilités pour installer un bundle.

au sein de symfony, dans chaque bundle il y a un fichier composer.json, c'est là qu'on ajoute une ligne de code pour installer 1 bundle.
(dans cet exemple, je vais ajouter le bundle ckeditor - pour mettre en page mes descriptions d'articles)

Code
   "egeloen/ckeditor-bundle": "2.*"



composer.json par foxp2projects, sur Flickr

maintenant, 1 ligne de commande pour installer :

Code
   composer update



composer-command-line par foxp2projects, sur Flickr

et maintenant, dernière ligne de code php : (dans le fichier app/AppKernel.php)

Code
new Ivory\CKEditorBundle\IvoryCKEditorBundle(),


terminé !

évidemment, ensuite il faut lire la doc pour savoir comment on utilise ce bundle dans un projet Symfony, pas de soucis, le développeur a écrit une doc pour ça : https://github.com/egeloen/IvoryCKEditorBun...es/doc/usage.md

un site de référence pour trouvez les bundles destinés à Symfony : http://knpbundles.com/

A savoir :
Sachez que j'ai eu l'occasion, par le passé, de discuter avec HPDL d'architecture et structure, et de lui proposer de nombreuses idées, et celle entre autre, d'utiliser composer pour maintenir le Core d'osCommerce 3, mais également d'être une option d'installation pour les nouveaux add-ons développés pour cette version.
Autant vous dire que si j'avais chanté un hymne punk anti poutine dans une église orthodoxe à Moscou en string léopard, j'aurai eu de meilleures oreilles attentives ...
J'ai rarement rencontré un développeur aussi fermé.
D'où le titre un peu provoc (mais tellement vrai) "Ce dont vous avez toujours rêvez de faire avec osCommerce et que vous ne pourrez jamais faire"
Go to the top of the page
 
FoxP2
posté 7 Sep 2013, 14:06
Message #4


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



après le front office, je viens de finaliser la première partie du back office:

page d'identification :


login par foxp2projects, sur Flickr

page d’accueil :


accueil par foxp2projects, sur Flickr

page de création d'un article :


creation d'un article par foxp2projects, sur Flickr
Go to the top of the page
 
FoxP2
posté 9 Sep 2013, 10:58
Message #5


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



le code est accessible sur github : foxp2 / projects

5204 lignes ! 80% générées automatiquement en quelques lignes de commande, en somme toute la puissance du framework Symfony.

étant donné que j'ai programmé un firewall à plusieurs niveaux, vous aurez bientôt la possibilité de tester en "live".
nota bene : l'ajout / la mise à jour / la suppression de données sera impossible, mais l'ensemble des formulaires restera quand même accessible.
Go to the top of the page
 
FoxP2
posté 9 Sep 2013, 20:30
Message #6


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



La démo est en ligne : http://foxp2projects.fr.nf
Les identifiants d'accès sont indiqués dans les champs.
à visiter avec ie 9 (et +), chrome, opera (certains bugs récalcitrants encore sous firefox)
Go to the top of the page
 
FoxP2
posté 14 Sep 2013, 08:14
Message #7


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



behind the hood* :

L'interface continue de s'enrichir en très peu de ligne de code.


Visualisation d'une catégorie par foxp2projects, sur Flickr

Pour chaque catégorie, les sous catégories & articles liés à celle ci sont aisément accessibles sans aucune requête sql supplémentaires.
En effet, c'est doctrine qui se charge de faire l'auto-jointure sur la table catégories et la jointure externe sur la table articles.
C'est le travail d'un orm, faire le mapping entre la base de données et les objets de mon application.

autojointure sur l'entité categories :
https://github.com/foxp2/projects/blob/mast...egories.php#L30
https://github.com/foxp2/projects/blob/mast...egories.php#L37
jointure externe sur l'entité categories :
https://github.com/foxp2/projects/blob/mast...egories.php#L98

et son inverse sur l'entité articles :
https://github.com/foxp2/projects/blob/mast...rticles.php#L28


ensuite, c'est dans la vue que l'on affiche ces données :
https://github.com/foxp2/projects/blob/mast...w.html.twig#L74
https://github.com/foxp2/projects/blob/mast....html.twig#L100

A propos de Twig
C'est le moteur de template utilisé dans mon application.
C'est une des briques du framework Symfony, il n'y a aucune obligation à l'utiliser (vous pouvez encore écrire vos vues en PHP, mais c'est stupide)
D'ailleurs, l'ensemble des développeurs de la communauté Symfony l'ont adopté et les Bundles produits s'appuient toujours sur ce moteur



A propos de Doctrine

En apparté : lorsque je lis ce genre de ce sujet (ORM or not ORM faut-il les utiliser ?) sur developpez.com, je trouve ce type de test extrêmement réducteur, et surtout en dehors de la réalité. D'une part,les test de montée en charge d'une application sont bien plus complexes à mettre en oeuvre et d'autre part, lorsque l'on maîtrise correctement un orm, le temps gagné sur le développement est souvent important.

Les nombreux avanatages de l'orm doctrine :
  • de part sa généricité, il y a une désolidarisation du sgbd : cela facilite la migration d'un sgbd à un autre.
  • tous les CRUD basiques sont assurés en interne, aucun ordre SQL n'est à écrire.
  • quand il est nécessaire, on peut écrire ses propres requêtes en langage DQL ou SQL native, dans les repositories ( exemple : https://github.com/foxp2/projects/blob/mast...sRepository.php )
    Il convient de préférer le DQL qui permet un portage des requêtes d'un sgbd à un autre.


Notez bien que tous les ORM fonctionnent de la même manière, lorsque vous apprenez à vous servir d'un, la courbe d'apprentissage sur les suivants est plus aisée.


*sous le capot
Go to the top of the page
 
FoxP2
posté 14 Sep 2013, 09:02
Message #8


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



Behind the hood : le cas particulier des gist

Chaque article est lié (ou pas, c'est optionnel) à un gist (hébergé sur les serveurs Github, comprennant de 1 à n fichiers), et un gist n'appartient qu'à 1 et 1 seul article. (dans une entité, on appellerait cela une relation one-to-one)

Côté interface, lors de la création d'un article, c'est un menu déroulant qui liste l'ensemble des gist disponible sur mon compte github. (https://gist.github.com/foxp2 )


édition d'un article par foxp2projects, sur Flickr

La liste est la jointure des données externes (provenant du serveur github ) moins celles venant de la base de données (dans la table articles, une colonne référençant le numéro de gist.
(les données de github passe par l'API github : http://developer.github.com/v3/gists/#list-gists)
C'est la méthode privée getListofGist qui fait le job : https://github.com/foxp2/projects/blob/mast...roller.php#L334

Bien, mais en terme d'expérience utilisateur, une liste de numéro, c'est pas très parlant, même pour moi qui est le codeur de chaque gist.
C'est pourquoi j'ai ajouté un bouton "info", qui appelle en ajax, des informations détaillées sur chaque gist qui s'affiche via une fenêtre modale dans la page.

Avec Symfony,c'est simple de faire de l'asynchrone :
la méthode dans le contrôleur :
https://github.com/foxp2/projects/blob/mast...roller.php#L294
la fonction js dans la vue :
https://github.com/foxp2/projects/blob/mast...t.html.twig#L77

Rappel sur les données en provenance de Github :
C'est le bundle KnpLabs / php-github-api qui se charge de faire le pont entre mon serveur et celui de github.
Chaque requête est mis en cache. tant que les données sur le serveur github ne sont pas modifiées, l'application lit les fichiers mis en cache.
On le voit d'ailleurs sur le screenshot suivant :


cache-github par foxp2projects, sur Flickr

Cela permet de réduire les aller retours entre les serveurs et rendre d'autant plus véloce l'application.
Go to the top of the page
 
FoxP2
posté 25 Sep 2013, 22:15
Message #9


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



Ce que je n'aime pas dans l'api github :

- l'incohérence des données, obligeant à multiplier le contrôle des données renvoyées, tel démontré dans cet exemple
hallucinant, des clés peuvent être absente de la réponse, d'autres renvoyées null, évidemment, en aucun cas la doc le mentionne.

- en parlant de doc, celle sur les activités est un must du genre !
ils nous disent :
Citation
All Events have the same response format

mon c.l, c'est du poulet aussi !
-> gnffrr
une fois de plus, faut switcher dans le controller pour s'assurer que les données sont présentes, tel démontré dans cet exemple

Ce que je n'aime pas dans le Bundle KnpLabs/php-github-api :

La gestion du cache un peu trop simpliste.

C'est la méthode de classe request de la classe CachedHttpClient qui se charge de faire le job : -> gnfrrr
elle contrôle que le statut renvoyé par le header de la requête est égale à 304 pour lire le fichier en cache, sinon elle écrit ce fichier.
sauf que, de temps en temps, l'api github renvoie un 503 car les serveurs sont tombés.
résultat : bah l'application retourne une erreur 500.
la logique voudrait que :
si la réponse == 503
si le fichier cache existe, je renvoie la réponse du cache (en omettant pas d'ajouter un message indiquant que l'application n'est plus à jour par rapport au serveur github)
si le fichier cache n'existe pas,je renvoie une exception

si la réponse == 304
si le fichier cache existe, je renvoie la réponse du cache , sinon je créé le fichier et je renvoie la réponse


évidemment, aucune donnée n'est filtrée, la méthode de classe set de la classe FilesystemCache est plus que minimaliste, gnfrrr
on sérialise les données, et roule ma poule ... pas très optimisé tout ça.


Bref, après débogage, la page profil de l'application fonctionne : http://foxp2projects.fr.nf/backoffice/profil/

elle tourne avec une seule classe controller et une seule vue
l'ensemble des données sont appelées de manière asynchrone (ajax) par 500 lignes de code javascript (inclues dans la vue)

une vidéo est dispo sur youtube démontrant la vélocité de cette partie de l'application : http://www.youtube.com/watch?v=9zXZYZJqESg&hd=1
Go to the top of the page
 
FoxP2
posté 26 Oct 2013, 12:00
Message #10


Ceinture marron OSC
Icône de groupe

Groupe : Membres
Messages : 1665
Inscrit : 3-June 09
Membre no 25501



Le module Profil de l'application est devenu plus générique : http://foxp2projects.fr.nf/fr/backoffice/profil/

à l'initialisation de la page, c'est mon profil qui est affiché.

un moteur de recherche requêtant sur les serveurs Github permet d'accéder aux mêmes informations sur l'ensemble des profils.

le moteur, via un menu déroulant, affiche au minimum les 100 premières suggestions, sinon matche la recherche au plus approchant tel que nous le voyons ci dessous :


profil-search-engine par foxp2projects, sur Flickr

Les onglets Codeurs suivis & Codeurs suivants permettent également de consulter les profils via la bar d'application en cliquant sur View this profil (qui soumet le formulaire via js )

Code
$('#app-bar a').click(function(){
    $("#search" ).val(profil);
    $('#profil_search').attr('action', '{{ path('profil_index') }}').unbind('submit').submit();  
});



profil-search-engine-with-app-bar par foxp2projects, sur Flickr

incidence négative sur mon serveur :

les résultats des requêtes en provenance des serveurs de Github pourraient assez rapidement saturer le disque en cas d'accès important.

un nettoyage s'impose donc. peu de ligne de code pour ça, car Symfony possède les bons outils : le composant Finder qui utilise la SPL de php, et en particulier la SplFileInfo

ce sont des classes internes à PHP facilitant la POO.

Code
        // clean up cache
        
            $cache = $this->container->get('kernel')->getCacheDir() . '/githubapi';


            $finder = new Finder();


            $finder->files()->in($cache);


            $finder->size('> 10K')->date('until 1 days ago')->getIterator();


            foreach($finder as $file) {        


               unlink($file);  


            }

en résumé, je demande à l'application de supprimer tous les fichiers de plus de 10Ko datant de plus d'un jour.
la classe finder permet d'enchainer les méthodes jusqu'à retourner un tableau via la méthode getIterator.
simple.efficace.
une raison de plus d'avoir choisi ce framework depuis sa première version.
Go to the top of the page
 

Reply to this topicStart new topic
1 utilisateur(s) sur ce sujet (1 invité(s) et 0 utilisateur(s) anonyme(s))
0 membre(s) :

 



RSS Version bas débit Nous sommes le : 28th March 2024 - 22:19
Ce site est déclaré auprès de la commision Nationale
de l'Informatique et des Libertés (déclaration n°: 1043896)